com.interfaceware.chameleon
Class LlpClient

java.lang.Object
  com.interfaceware.chameleon.LlpClient

public class LlpClient
extends java.lang.Object

This class can be used to implement a Lower Layer Protocol (LLP) TCP/IP client to connect to an LLP server.

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

Constructor Summary

LlpClient()

LlpClient(long Handle)

Method Summary

void	addListener(LlpClientListener Listener) Adds the specified listener so that it receives events from this LlpClient object.
void	connect(java.lang.String Host, int Port) Connect to the given host and port number.
void	disconnect() Attempt to gracefully disconnect from the server.
protected void	finalize()
java.lang.String	getHeaderBlock() The characters that precede a message in a stream.
boolean	getIsConnected() The status of the connection with the server.
java.lang.String	getTrailerBlock() The characters that follow a message in a stream.
void	hardDisconnect() Ungracefully disconnect without doing TCP/IP handshaking with the server.
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(LlpClientListener Listener) Removes the specified listener so that it no longer receives events from this LlpClient 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	setTrailerBlock(java.lang.String Value) Set method for trailerBlock.
void	stopMessageLoop() Send a quit message to the thread that the networking components are running on.
void	transmitMessage(java.lang.String Message) Send a message to the server, prefixed and postfixed by the current HeaderBlock and TrailerBlock characters.

Methods inherited from class java.lang.Object

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

Constructor Detail

LlpClient

public LlpClient()
          throws ChameleonException

Throws:

ChameleonException

LlpClient

public LlpClient(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

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 stream 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 stream 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

getIsConnected

public boolean getIsConnected()
                       throws ChameleonException

The status of the connection with the server.

Returns true if the client is currently connected with the server.

Throws:

ChameleonException

stopMessageLoop

public void stopMessageLoop()
                     throws ChameleonException

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

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

connect

public void connect(java.lang.String Host,
                    int Port)
             throws ChameleonException

Connect to the given host and port number.

Function requires a running message loop (see runMessageLoop).

Blocking: Function does not block.
Events: If the connection succeeds, a connected event results. If the connection fails, an errorReceived event results, containing the error message indicating why the connect attempt has failed.

Parameters:

Host - Host to connect to.

Port - Port to connect to.

Throws:

ChameleonException

disconnect

public void disconnect()
                throws ChameleonException

Attempt to gracefully disconnect from the server.

A graceful disconnect implies a shutdown to the write end of the connection, and reading all data until the peer issues a close to its write end.

Note that the peer may not actually close the write end of its connection (although this is rare), which results in the connection never receiving the close event to signify that the connection is closed. In this situation, it is recommended that hardDisconnect be called to close the connection.

Function requires a running message loop (see runMessageLoop).

Blocking: Function does not block.
Events: If the close succeeds (the peer closes the connection), a closed event results. If an error occurs during the close operation, an errorReceived event results, containing the error message indicating why the close attempt has failed.

Throws:

ChameleonException

hardDisconnect

public void hardDisconnect()
                    throws ChameleonException

Ungracefully disconnect without doing TCP/IP handshaking with the server.

If there is data pending on the network buffer to be sent, the peer will receive a reset on the connection if it attempts to read or write to the connection.

Blocking: Function blocks; upon returning, the connection is closed.
Events: None.

Throws:

ChameleonException

transmitMessage

public void transmitMessage(java.lang.String Message)
                     throws ChameleonException

Send a message to the server, prefixed and postfixed by the current HeaderBlock and TrailerBlock characters.

The data is not guaranteed to be received after this function is called. All data is buffered internally; completion of this call does not signify reception of data.

Function requires a running message loop (see runMessageLoop).

Blocking: Function does not block.
Events: If an error occurs during the send operation an errorReceived event results, containing the error message indicating why the send attempt has failed.

Parameters:

Message - Message to send to the server.

Throws:

ChameleonException

addListener

public void addListener(LlpClientListener Listener)
                 throws ChameleonException

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

Throws:

ChameleonException

See Also:

removeListener

removeListener

public void removeListener(LlpClientListener Listener)
                    throws ChameleonException

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

Throws:

ChameleonException

See Also:

addListener