com.interfaceware.chameleon
Class LlpServer

java.lang.Object
  extended by com.interfaceware.chameleon.LlpServer

public class LlpServer
extends java.lang.Object

This object implements a Lower Layer Protocol (LLP) TCP/IP server that listens for connections from clients.

Most of the network events that are raised provide a LlpConnection parameter, which gives methods to interact with the client connection that the event is associated with.

See http://www.interfaceware.com/manual/network_components.html for more information.


Constructor Summary
LlpServer()
           
LlpServer(long Handle)
           
 
Method Summary
 void addListener(LlpServerListener Listener)
          Adds the specified listener so that it receives events from this LlpServer object.
 int countClients()
          Returns the total number of Clients.
 int countConnections()
          Deprecated. This method has been superseded by countClients().
 void disconnectAllClients()
          Stop listening on the port for new connections, and initiate a disconnect on all open connections.
protected  void finalize()
           
 LlpConnection getClient(int ClientIndex)
          Representation of the collection of remote Clients that are connected to this server.
 java.lang.String getHeaderBlock()
          The characters that precede a message in a stream.
 java.lang.String getHost()
          The local interface on which we are listening, used by the next call to the startListen method.
 boolean getIsListening()
          The status of the listening state.
 int getPort()
          The port on which we are listening, set by the startListen method.
 java.lang.String getTrailerBlock()
          The characters that follow a message in a stream.
 java.lang.String makeMessagePrintable(java.lang.String InputString, java.lang.String NewLine, int MaximumLength)
          Make message printable by changing plain carriage return characters "\r" to carriage return and newline characters "\r\n".
 void release()
           
 void removeListener(LlpServerListener Listener)
          Removes the specified listener so that it no longer receives events from this LlpServer object.
static void runMessageLoop()
          On Unix and Linux platforms events are dispatched using a loop based on the ::select function.
 void setHeaderBlock(java.lang.String Value)
          Set method for headerBlock.
 void setHost(java.lang.String Value)
          Set method for host.
 void setTrailerBlock(java.lang.String Value)
          Set method for trailerBlock.
 void startListen(int Port)
          Attempt to listen on the supplied port for incoming client connections.
 void stopListen()
          Stop the component from listening for new connections.
 void stopMessageLoop()
           This will send a quit message to the thread that the networking components are running on.
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

LlpServer

public LlpServer()
          throws ChameleonException
Throws:
ChameleonException

LlpServer

public LlpServer(long Handle)
          throws ChameleonException
Throws:
ChameleonException
Method Detail

release

public void release()
             throws ChameleonException
Throws:
ChameleonException

finalize

protected void finalize()
                 throws ChameleonException
Overrides:
finalize in class java.lang.Object
Throws:
ChameleonException

getPort

public int getPort()
            throws ChameleonException

The port on which we are listening, set by the startListen method.

Throws:
ChameleonException

getHost

public java.lang.String getHost()
                         throws ChameleonException

The local interface on which we are listening, used by the next call to the startListen method.

The default is an empty string, which means the listener will listen on all local interfaces.

It must be in the Internet standard "." (dotted) notation (e.g. 127.0.0.1).

See also the setHost method.

Throws:
ChameleonException

setHost

public void setHost(java.lang.String Value)
             throws ChameleonException

Set method for host.

See Host.

Parameters:
Value - Value to set host to.
Throws:
ChameleonException

getHeaderBlock

public java.lang.String getHeaderBlock()
                                throws ChameleonException

The characters that precede a message in a stream.

The default value for this property is 0x0B as defined by the the LLP protocol.

This property is used both for parsing out the incoming data streams and wrapping outgoing messages.

See also the setHeaderBlock method.

Throws:
ChameleonException

setHeaderBlock

public void setHeaderBlock(java.lang.String Value)
                    throws ChameleonException

Set method for headerBlock.

See HeaderBlock.

Parameters:
Value - Value to set headerBlock to.
Throws:
ChameleonException

getTrailerBlock

public java.lang.String getTrailerBlock()
                                 throws ChameleonException

The characters that follow a message in a stream.

The default value is the character 0x1C followed by 0x0D as defined by the LLP protocol.

This property is used both for parsing out the incoming data streams and wrapping outgoing messages.

See also the setTrailerBlock method.

Throws:
ChameleonException

setTrailerBlock

public void setTrailerBlock(java.lang.String Value)
                     throws ChameleonException

Set method for trailerBlock.

See TrailerBlock.

Parameters:
Value - Value to set trailerBlock to.
Throws:
ChameleonException

getIsListening

public boolean getIsListening()
                       throws ChameleonException

The status of the listening state.

Returns true if the server is currently listening for connections.

Blocking: Function blocks until the listening state is determined.
Events: None.

Throws:
ChameleonException

getClient

public LlpConnection getClient(int ClientIndex)
                        throws ChameleonException

Representation of the collection of remote Clients that are connected to this server.

This list changes in size as connections are received or closed, or if an error occurs on the connection (which implies a close).

Users cannot change the size or append to the contents of this collection since it is managed internally.

References to LlpConnection objects within this collection should not be maintained. Instead, always access LlpConnection objects through this collection interface, or the event to which LlpConnection objects are passed as parameters.

Parameters:
ClientIndex - The index of the Client to return.
Throws:
ChameleonException

countClients

public int countClients()
                 throws ChameleonException

Returns the total number of Clients.

See also the Client property.

Throws:
ChameleonException

stopMessageLoop

public void stopMessageLoop()
                     throws ChameleonException

This will send a quit message to the thread that the networking components are running on.

Under Windows, this is a WM_QUIT message. All the networking components must be created on a single thread with a running message loop. For more information, see the runMessageLoop method.

Throws:
ChameleonException

runMessageLoop

public static void runMessageLoop()
                           throws ChameleonException

On Unix and Linux platforms events are dispatched using a loop based on the ::select function. All POSIX applications require this function to be called in order to start receiving events.

On Windows platforms all events are dispatched using the Windows message loop.

Graphical Windows applications contain a running Windows message loop; therefore, this function will not need to be called. Console applications require this function to be called in order to start receiving events.

Throws: Function will throw an exception only if the operating system reports an error.
Blocking: Function will block until stopMessageLoop is called, or (Windows only) a WM_QUIT message is posted to the message loop on the thread that the networking components are running on.

Throws:
ChameleonException

startListen

public void startListen(int Port)
                 throws ChameleonException

Attempt to listen on the supplied port for incoming client connections.

This function requires a running message loop (see runMessageLoop) in order to receive connections.

Blocking: Function blocks until a port can be successfully listened on or an error occurs.
Throws: Function will throw an exception if the port is in use, or the operating system reports any other error.
Events: None.

By default, the listener will listen on all local interfaces. To make it listen on a specific local interface use the Host property to set the IP address of the interface to use.

Parameters:
Port - Port to listen on.
Throws:
ChameleonException

makeMessagePrintable

public java.lang.String makeMessagePrintable(java.lang.String InputString,
                                             java.lang.String NewLine,
                                             int MaximumLength)
                                      throws ChameleonException

Make message printable by changing plain carriage return characters "\r" to carriage return and newline characters "\r\n".

HL7 messages use the carriage return character "\r" to separate the segments. This makes it difficult to print them out in console windows because the cursor overwrites each previous segment instead of moving on to a newline for each segment. This method is intended to be a simple utility method to make it easier to convert HL7 messages into a printable format. This function also allows the output string to be truncated.

Parameters:
InputString - Input message string.
NewLine - Line feed string.
MaximumLength - Maximum length of the message to print out. Characters after this length will be truncated. If you want to output the whole message, set the length to -1.
Returns:
Printable string, with "\r" characters changed to "\r\n"
Throws:
ChameleonException

stopListen

public void stopListen()
                throws ChameleonException

Stop the component from listening for new connections.

Note that any existing connections that have already been established are NOT closed. In order to properly disconnect existing connections as well as stop listening, use disconnectAllClients.

Blocking: Function blocks until the stop listen succeeds.
Throws: Function does not throw any exceptions.
Events: None.

Throws:
ChameleonException

disconnectAllClients

public void disconnectAllClients()
                          throws ChameleonException

Stop listening on the port for new connections, and initiate a disconnect on all open connections.

This function requires a running message loop (see runMessageLoop).

Blocking: Function blocks until disconnect is called on all open connections. This implies that the connections are not necessarily closed when this function returns.
Events: None.

Throws:
ChameleonException

addListener

public void addListener(LlpServerListener Listener)
                 throws ChameleonException

Adds the specified listener so that it receives events from this LlpServer object.

Throws:
ChameleonException
See Also:
removeListener

removeListener

public void removeListener(LlpServerListener Listener)
                    throws ChameleonException

Removes the specified listener so that it no longer receives events from this LlpServer object.

Throws:
ChameleonException
See Also:
addListener

countConnections

public int countConnections()
                     throws ChameleonException
Deprecated. This method has been superseded by countClients().

Returns the total number of Clients.

Throws:
ChameleonException