ipworks
Class Ipdaemon

java.lang.Object
  |
  +--ipworks.Ipdaemon

public class Ipdaemon

extends java.lang.Object

The IPDaemon bean is used to create TCP/IP servers. The bean handles multiple simultaneous connections on the same TCP/IP port (service port). It is designed to balance the load between connections for a fast, powerful server.

IPDaemon is the server complement of IPPort (which is used to create client applications). They share a common design philosophy and interface. We expect you will find IPDaemon as easy to use as IPPort.

By default, each instance of IPDaemon can handle up to 1000 simultaneous incoming connections (this number may be increased up to 100,000, or decreased to a lower value by using theMaxConnectionsconfiguration setting).

The connections are identified by a ConnectionId (a number between 1 andMaxConnections). Most of IPDaemon's properties are array properties indexed by ConnectionId . IPDaemon's events also have ConnectionId as a parameter to identify the connection they relate to.

Our main goal in designing IPDaemon was to make it easy to use without sacrificing performance. The bean has a minimum of properties, and six events: ConnectionRequest , Connected , DataIn , Disconnected , ReadyToSend , and Error .

IPDaemon can start to listen on a port by setting the Listening property to True. When a remote host asks for a connection, the ConnectionRequest event is fired. At that point, the connection can either be accepted or rejected. If the connection is accepted, a ConnectionId is assigned, and communication can start. From this point on, the operation is very similar to IPPort. Data is sent by assigning the data string to the DataToSend property. The address and port of the incoming connection can be found by querying the RemoteHost and RemotePort properties.

Constructor Summary

Ipdaemon()

Method Summary

void	addIpdaemonEventListener(IpdaemonEventListener l)
java.lang.String	config(java.lang.String configurationString) Sets or retrieves a beanconfiguration setting.
void	disconnect(int connectionId) Disconnect from the remote host.
void	doEvents() Processes events from the internal message queue.
int	getBytesSent(int connectionId) The number of bytes actually sent after an assignment to DataToSend .
int	getConnectionBacklog() The maximum number of pending connections maintained by the TCP/IP subsystem.
int	getConnectionCount() The number of currently connected clients.
byte[]	getEOL(int connectionId) Used to break the incoming data stream into chunks separated by EOL .
java.lang.String	getLocalAddress(int connectionId) The IP address of the interface for ConnectionId in Internet dotted format.
java.lang.String	getLocalHost() The name of the local host or user-assigned IP interface through which connections are initiated or accepted.
int	getLocalPort() The TCP port in the local host where the bean listens.
java.lang.String	getRemoteHost(int connectionId) The IP address of the RemoteHost in Internet dotted format.
int	getRemotePort(int connectionId) The IP port of the RemoteHost for a connection.
boolean	isAcceptData(int connectionId) Enables or disables data reception (the DataIn event).
boolean	isConnected(int connId) Used to disconnect individual connections and/or show their status.
boolean	isKeepAlive() When True, KEEPALIVE packets are enabled (for long connections).
boolean	isLinger() When set to True, connections are terminated gracefully.
boolean	isListening() If True, the bean accepts incoming connections on LocalPort.
boolean	isSingleLineMode(int connectionId) Special mode for line-oriented protocols.
void	removeIpdaemonEventListener(IpdaemonEventListener l)
void	send(int connectionId, byte[] text) Send data to the remote host.
void	sendLine(int connectionId, java.lang.String text) Sends a string followed by a newline.
void	setAcceptData(int connectionId, boolean acceptData) Enables or disables data reception (the DataIn event).
void	setConnected(int connId, boolean connected) Used to disconnect individual connections and/or show their status.
void	setConnectionBacklog(int connectionBacklog) The maximum number of pending connections maintained by the TCP/IP subsystem.
void	setDataToSend(int connectionId, byte[] dataToSend) A string of data to be sent to the remote host.
void	setEOL(int connectionId, byte[] EOL) Used to break the incoming data stream into chunks separated by EOL .
void	setKeepAlive(boolean keepAlive) When True, KEEPALIVE packets are enabled (for long connections).
void	setLinger(boolean linger) When set to True, connections are terminated gracefully.
void	setListening(boolean listening) If True, the bean accepts incoming connections on LocalPort.
void	setLocalHost(java.lang.String localHost) The name of the local host or user-assigned IP interface through which connections are initiated or accepted.
void	setLocalPort(int localPort) The TCP port in the local host where the bean listens.
void	setSingleLineMode(int connectionId, boolean singleLineMode) Special mode for line-oriented protocols.
void	shutdown() Shutdown the server.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Ipdaemon

public Ipdaemon()

Method Detail

isAcceptData

public boolean isAcceptData(int connectionId)
                     throws IPWorksException

Enables or disables data reception (the DataIn event).

Setting the property to False, temporarily disables data reception (and the DataIn event) on the connection specified by ConnectionId . Setting the property to True, reenables data reception.

IPWorksException

setAcceptData

public void setAcceptData(int connectionId,
                          boolean acceptData)
                   throws IPWorksException

Enables or disables data reception (the DataIn event).

Setting the property to False, temporarily disables data reception (and the DataIn event) on the connection specified by ConnectionId . Setting the property to True, reenables data reception.

IPWorksException

getBytesSent

public int getBytesSent(int connectionId)
                 throws IPWorksException

The number of bytes actually sent after an assignment to DataToSend .

The BytesSent property shows how many bytes were sent after the last assignment to DataToSend . Please check the DataToSend property for more information.

IPWorksException

isConnected

public boolean isConnected(int connId)
                    throws IPWorksException

Used to disconnect individual connections and/or show their status.

The Connected property is used to close connections.

Connected also shows the status of a particular connection (connected/disconnected).

How and when the connection is closed is controlled by the Linger property. Please refer to its description for more information.

IPWorksException

setConnected

public void setConnected(int connId,
                         boolean connected)
                  throws IPWorksException

Used to disconnect individual connections and/or show their status.

The Connected property is used to close connections.

Connected also shows the status of a particular connection (connected/disconnected).

How and when the connection is closed is controlled by the Linger property. Please refer to its description for more information.

IPWorksException

getConnectionBacklog

public int getConnectionBacklog()

The maximum number of pending connections maintained by the TCP/IP subsystem.

This value reflects the SOMAXCON option for the main listening socket. The default value for most systems is 5. You may set ConnectionBacklog to a larger value if the server is expected to receive a large number of connections, and queuing them is desirable.

setConnectionBacklog

public void setConnectionBacklog(int connectionBacklog)
                          throws IPWorksException

The maximum number of pending connections maintained by the TCP/IP subsystem.

This value reflects the SOMAXCON option for the main listening socket. The default value for most systems is 5. You may set ConnectionBacklog to a larger value if the server is expected to receive a large number of connections, and queuing them is desirable.

IPWorksException

getConnectionCount

public int getConnectionCount()

The number of currently connected clients.

The value of ConnectionCount automatically increases and decreases as Connected and Disconnected events are fired.

Please note that setting Listening to False, does not actually disconnected connected clients, and ConnectionCount keeps reflecting the number of these active connections. You must use the Connected property to disconnect each client individually.

setDataToSend

public void setDataToSend(int connectionId,
                          byte[] dataToSend)
                   throws IPWorksException

A string of data to be sent to the remote host. Write-only property.

Assigning a string to the DataToSend property makes the bean send the string to the remote host. The Send method provides similar functionality.

If you are sending data to the remote host faster than it can process it, or faster than the network's bandwidth allows, the outgoing queue might fill up. When this happens, DataToSend fails with exception 10035: "[10035] Operation would block" (WSAEWOULDBLOCK). You can check this error, and then try to send the data again. The BytesSent property shows how many bytes were sent (if any). If 0 bytes were sent, then you can wait for the ReadyToSend event before attempting to send data again. (However, please note that ReadyToSend is not fired when part of the data is successfully sent).

IPWorksException

getEOL

public byte[] getEOL(int connectionId)
              throws IPWorksException

Used to break the incoming data stream into chunks separated by EOL .

The EOL property is used to define boundaries in the input stream using the value of the property.

The EOL property is especially useful with ASCII files. Setting it to CRLF ("\\r\\n") enables splitting of the incoming ASCII text stream into lines. In this case, one event is fired for each line received (as well as in packet boundaries). The CRLF ("\\r\\n") . bytes are discarded.

The EOL property is a binary string. In particular, this means that it can be more than one byte long, and it can contain NULL bytes.

IPWorksException

setEOL

public void setEOL(int connectionId,
                   byte[] EOL)
            throws IPWorksException

Used to break the incoming data stream into chunks separated by EOL .

The EOL property is used to define boundaries in the input stream using the value of the property.

The EOL property is especially useful with ASCII files. Setting it to CRLF ("\\r\\n") enables splitting of the incoming ASCII text stream into lines. In this case, one event is fired for each line received (as well as in packet boundaries). The CRLF ("\\r\\n") . bytes are discarded.

The EOL property is a binary string. In particular, this means that it can be more than one byte long, and it can contain NULL bytes.

IPWorksException

isKeepAlive

public boolean isKeepAlive()

When True, KEEPALIVE packets are enabled (for long connections).

The KeepAlive enables the SO_KEEPALIVE option on the incoming connections. This option prevents long connections from timing out in case of inactivity.

Please note that system TCP/IP stack implementations are not required to support SO_KEEPALIVE.

The KeepAlive property is shared among incoming connections. When the property is set, the corresponding value is set for incoming connections as they are accepted. Existing connections are not modified.

setKeepAlive

public void setKeepAlive(boolean keepAlive)
                  throws IPWorksException

When True, KEEPALIVE packets are enabled (for long connections).

The KeepAlive enables the SO_KEEPALIVE option on the incoming connections. This option prevents long connections from timing out in case of inactivity.

Please note that system TCP/IP stack implementations are not required to support SO_KEEPALIVE.

The KeepAlive property is shared among incoming connections. When the property is set, the corresponding value is set for incoming connections as they are accepted. Existing connections are not modified.

IPWorksException

isLinger

public boolean isLinger()

When set to True, connections are terminated gracefully.

The Linger property controls how a connection is closed. The default is True. In this case the connection is closed only after all the data is sent. Setting it to False forces an abrupt (hard) disconnection. Any data that was in the sending queue may be lost.

The default behavior (which is also the default mode for Winsock stream sockets) might result in an indefinite delay in closing the connection. Although the bean returns control immediately, the system might indefinitely hold system resources until all pending data is sent (even after your application closes). This means that valuable system resources might be wasted.

Setting Linger to False forces an immediate disconnection. If you know that the other side has received all the data you had sent (by a client acknowledgment, for example), setting Linger to False might be the appropriate course of action.

The Linger property is shared among incoming connections. When the property is set, the corresponding value is set for incoming connections as they are accepted. Existing connections are not modified.

setLinger

public void setLinger(boolean linger)
               throws IPWorksException

When set to True, connections are terminated gracefully.

The Linger property controls how a connection is closed. The default is True. In this case the connection is closed only after all the data is sent. Setting it to False forces an abrupt (hard) disconnection. Any data that was in the sending queue may be lost.

The default behavior (which is also the default mode for Winsock stream sockets) might result in an indefinite delay in closing the connection. Although the bean returns control immediately, the system might indefinitely hold system resources until all pending data is sent (even after your application closes). This means that valuable system resources might be wasted.

Setting Linger to False forces an immediate disconnection. If you know that the other side has received all the data you had sent (by a client acknowledgment, for example), setting Linger to False might be the appropriate course of action.

The Linger property is shared among incoming connections. When the property is set, the corresponding value is set for incoming connections as they are accepted. Existing connections are not modified.

IPWorksException

isListening

public boolean isListening()

If True, the bean accepts incoming connections on LocalPort.

Use the Listening property to make the bean 'listen' (accept connections) on the port specified by the LocalPort property. Setting Listening to False will make the bean stop listening. (Please note that this does not close any existing connections).

setListening

public void setListening(boolean listening)
                  throws IPWorksException

If True, the bean accepts incoming connections on LocalPort.

Use the Listening property to make the bean 'listen' (accept connections) on the port specified by the LocalPort property. Setting Listening to False will make the bean stop listening. (Please note that this does not close any existing connections).

IPWorksException

getLocalAddress

public java.lang.String getLocalAddress(int connectionId)
                                 throws IPWorksException

The IP address of the interface for ConnectionId in Internet dotted format.

The LocalAddress shows the IP address of the interface through which the connection identified by ConnectionId is passing.

This property is important for multihomed hosts where it can be used to find which particular network interface an individual connection is going through.

IPWorksException

getLocalHost

public java.lang.String getLocalHost()

The name of the local host or user-assigned IP interface through which connections are initiated or accepted.

The LocalHost property contains the name of the local host as obtained by the gethostname() system call, or if the user has assigned an IP address, the value of that address.

In multihomed hosts (machines with more than one IP interface) setting LocalHost to the value of an interface will make the bean initiate connections (or accept in the case of server beans) only through that interface.

If the bean is connected, the LocalHost property shows the IP address of the interface through which the connection is made in internet dotted format (aaa.bbb.ccc.ddd). In most cases, this is the address of the local host, except for multihomed hosts (machines with more than one IP interface).

NOTE: LocalHost is not persistent. You must always set it in code, and never in the property window.

setLocalHost

public void setLocalHost(java.lang.String localHost)
                  throws IPWorksException

The name of the local host or user-assigned IP interface through which connections are initiated or accepted.

The LocalHost property contains the name of the local host as obtained by the gethostname() system call, or if the user has assigned an IP address, the value of that address.

In multihomed hosts (machines with more than one IP interface) setting LocalHost to the value of an interface will make the bean initiate connections (or accept in the case of server beans) only through that interface.

If the bean is connected, the LocalHost property shows the IP address of the interface through which the connection is made in internet dotted format (aaa.bbb.ccc.ddd). In most cases, this is the address of the local host, except for multihomed hosts (machines with more than one IP interface).

NOTE: LocalHost is not persistent. You must always set it in code, and never in the property window.

IPWorksException

getLocalPort

public int getLocalPort()

The TCP port in the local host where the bean listens.

The LocalPort property must be set before IPDaemon starts listening. If its value is 0, then the TCP/IP subsystem picks a port number at random. The port number can be found by checking the value of the LocalPort property after IPDaemon is in listening mode (after successfully assigning True to the Listening property).

The service port is not shared among servers (i.e. there can be only one IPDaemon 'listening' on a particular port at one time).

setLocalPort

public void setLocalPort(int localPort)
                  throws IPWorksException

The TCP port in the local host where the bean listens.

The LocalPort property must be set before IPDaemon starts listening. If its value is 0, then the TCP/IP subsystem picks a port number at random. The port number can be found by checking the value of the LocalPort property after IPDaemon is in listening mode (after successfully assigning True to the Listening property).

The service port is not shared among servers (i.e. there can be only one IPDaemon 'listening' on a particular port at one time).

IPWorksException

getRemoteHost

public java.lang.String getRemoteHost(int connectionId)
                               throws IPWorksException

The IP address of the RemoteHost in Internet dotted format.

The RemoteHost property shows the IP address of the remote host through which the connection specified by ConnectionId is coming.

ConnectionId must indicate a valid connection, or an error will be fired.

If the bean is configured to use a SOCKS firewall, the value assigned to this property may be preceded with a "*". If this is the case, the host name is passed to the firewall unresolved and the firewall performs the DNS resolution.

IPWorksException

getRemotePort

public int getRemotePort(int connectionId)
                  throws IPWorksException

The IP port of the RemoteHost for a connection.

The RemotePort property shows the TCP port on the remote host through which the connection specified by ConnectionId is coming.

ConnectionId must indicate a valid connection, or an error will be fired.

IPWorksException

isSingleLineMode

public boolean isSingleLineMode(int connectionId)
                         throws IPWorksException

Special mode for line-oriented protocols.

When SingleLineMode is True, the bean treats the incoming data stream as lines separated by CRLF, CR, or LF. The EOL property is ignored.

IPWorksException

setSingleLineMode

public void setSingleLineMode(int connectionId,
                              boolean singleLineMode)
                       throws IPWorksException

Special mode for line-oriented protocols.

When SingleLineMode is True, the bean treats the incoming data stream as lines separated by CRLF, CR, or LF. The EOL property is ignored.

IPWorksException

config

public java.lang.String config(java.lang.String configurationString)
                        throws IPWorksException

Sets or retrieves a beanconfiguration setting.

Config is a generic method available in every bean. It is used to set and retrieveconfiguration settingsfor the bean.

Configuration settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the bean, access to these internal properties is provided through the Config method.

To set a configuration setting named PROPERTY , you must call Config("PROPERTY=VALUE") , where VALUE is the value of the setting expressed as a string. For boolean values, use the strings "True", "False", "0", "1", "Yes", or "No" (case does not matter).

To read (query) the value of a configuration setting, you must call Config("PROPERTY") . The value will be returned as a string.

IPWorksException

disconnect

public void disconnect(int connectionId)
                throws IPWorksException

Disconnect from the remote host.

Calling this method is equivalent to setting the Connected property to False.

IPWorksException

doEvents

public void doEvents()
              throws IPWorksException

Processes events from the internal message queue.

When DoEvents is called, the bean processes any available events. If no events are available, it waits for a preset period of time, and then returns.

IPWorksException

send

public void send(int connectionId,
                 byte[] text)
          throws IPWorksException

Send data to the remote host.

Calling this method is equivalent to setting the DataToSend property to Text .

IPWorksException

sendLine

public void sendLine(int connectionId,
                     java.lang.String text)
              throws IPWorksException

Sends a string followed by a newline.

This method is used for sending data with line-oriented protocols. The line is followed by CRLF ("\\r\\n") .

Please refer to the GetLine method and SingleLineMode property for more information.

IPWorksException

shutdown

public void shutdown()
              throws IPWorksException

Shutdown the server.

Calling this method is equivalent to setting Listening to False, and then breaking every client connection by setting Connected to False.

IPWorksException

addIpdaemonEventListener

public void addIpdaemonEventListener(IpdaemonEventListener l)
                              throws java.util.TooManyListenersException

java.util.TooManyListenersException

removeIpdaemonEventListener

public void removeIpdaemonEventListener(IpdaemonEventListener l)