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). 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(ipworks.IpdaemonEventListener l)
java.lang.String	config(java.lang.String configurationString) Sets or retrieves a beanconfiguration setting.
void	disconnect(java.lang.String connectionId) Disconnect from the remote host.
void	doEvents() Processes events from the internal message queue.
int	getConnectionBacklog() The maximum number of pending connections maintained by the TCP/IP subsystem.
ConnectionList	getConnections() A collection of currently connected clients.
byte[]	getDefaultEOL() A default EOL value to be used by incoming connections.
int	getDefaultMaxLineLength() The default maximum line length value for inbound connections.
int	getDefaultTimeout() An initial timeout value to be used by incoming connections.
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.
boolean	isDefaultSingleLineMode() Tells the bean whether or not to treat new connections as line-oriented.
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.
void	removeIpdaemonEventListener(ipworks.IpdaemonEventListener l)
void	send(java.lang.String connectionId, byte[] text) Send data to the remote host.
void	sendFile(java.lang.String connectionId, java.lang.String fileName) Send file to the remote host.
void	sendLine(java.lang.String connectionId, java.lang.String text) Sends a string followed by a newline.
void	setConnectionBacklog(int connectionBacklog) The maximum number of pending connections maintained by the TCP/IP subsystem.
void	setDefaultEOL(byte[] defaultEOL) A default EOL value to be used by incoming connections.
void	setDefaultMaxLineLength(int defaultMaxLineLength) The default maximum line length value for inbound connections.
void	setDefaultSingleLineMode(boolean defaultSingleLineMode) Tells the bean whether or not to treat new connections as line-oriented.
void	setDefaultTimeout(int defaultTimeout) An initial timeout value to be used by incoming connections.
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	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

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 queueing 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 queueing them is desirable.

IPWorksException

getConnections

public ConnectionList getConnections()

A collection of currently connected clients.

This property is a collection of currently connnected clients. All of the connections may be managed using this property. Each connection is described by the different fields of the CONNECTION type.

This collection is a hashtable type of collection, in which the connection Id string is used as the key to the desired connection. You may acquire the key for a given connection through the Connected event.

getDefaultEOL

public byte[] getDefaultEOL()

A default EOL value to be used by incoming connections.

Once the bean accepts and establishes an inbound connection, it will set that connection's EOL to the value in DefaultEOL . By default, this value is empty (""), meaning that data will be fired as it is received.

setDefaultEOL

public void setDefaultEOL(byte[] defaultEOL)
                   throws IPWorksException

A default EOL value to be used by incoming connections.

Once the bean accepts and establishes an inbound connection, it will set that connection's EOL to the value in DefaultEOL . By default, this value is empty (""), meaning that data will be fired as it is received.

IPWorksException

getDefaultMaxLineLength

public int getDefaultMaxLineLength()

The default maximum line length value for inbound connections.

DefaultMaxLineLength controls the default size of an internal buffer which holds received data while waiting for an end-of-line (EOL) string.

The default value is 2048 bytes.

setDefaultMaxLineLength

public void setDefaultMaxLineLength(int defaultMaxLineLength)
                             throws IPWorksException

The default maximum line length value for inbound connections.

DefaultMaxLineLength controls the default size of an internal buffer which holds received data while waiting for an end-of-line (EOL) string.

The default value is 2048 bytes.

IPWorksException

isDefaultSingleLineMode

public boolean isDefaultSingleLineMode()

Tells the bean whether or not to treat new connections as line-oriented.

DefaultSingleLineMode instructs the component whether or not to treat newly established connections as line-oriented protocols. If this value is True, newly accepted connections will read the incoming data stream as lines separated by CRLF, CR, or LF, and will ignore the EOLs.

setDefaultSingleLineMode

public void setDefaultSingleLineMode(boolean defaultSingleLineMode)
                              throws IPWorksException

Tells the bean whether or not to treat new connections as line-oriented.

DefaultSingleLineMode instructs the component whether or not to treat newly established connections as line-oriented protocols. If this value is True, newly accepted connections will read the incoming data stream as lines separated by CRLF, CR, or LF, and will ignore the EOLs.

IPWorksException

getDefaultTimeout

public int getDefaultTimeout()

An initial timeout value to be used by incoming connections.

DefaultTimeout is used by the bean to set the operational timeout value of all inbound connections once they are established. By default, the timeout is 0, meaning that all inbound connections will behave asynchronously.

setDefaultTimeout

public void setDefaultTimeout(int defaultTimeout)
                       throws IPWorksException

An initial timeout value to be used by incoming connections.

DefaultTimeout is used by the bean to set the operational timeout value of all inbound connections once they are established. By default, the timeout is 0, meaning that all inbound connections will behave asynchronously.

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

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

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(java.lang.String 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(java.lang.String connectionId,
                 byte[] text)
          throws IPWorksException

Send data to the remote host.

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

IPWorksException

sendFile

public void sendFile(java.lang.String connectionId,
                     java.lang.String fileName)
              throws IPWorksException

Send file to the remote host.

This method sends the file to the client specified by the ConnectionId .

IPWorksException

sendLine

public void sendLine(java.lang.String 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(ipworks.IpdaemonEventListener l)
                              throws java.util.TooManyListenersException

java.util.TooManyListenersException

removeIpdaemonEventListener

public void removeIpdaemonEventListener(ipworks.IpdaemonEventListener l)