com.hume.DMH

Class DmhClient

Object

com.hume.DMH.DmhClient

All Implemented Interfaces:

DmhClientItf, Runnable

Direct Known Subclasses:

DmhServer

public class DmhClient
extends Object
implements DmhClientItf, Runnable

An implementation of interface DmhClientItf.

Use the class only for a constructor call. Use the interface classname in your application. For example:

     DmhClientItf dmh = new DmhClient();
 

Field Summary

Fields inherited from interface com.hume.DMH.DmhClientItf

STATE_CLOSING, STATE_COMM_ERROR, STATE_CONNECTED, STATE_DISCONNECTED, STATE_NAME_RESOLUTION, STATE_SETUP_IN_PROGRESS

Constructor Summary

Constructors

Constructor and Description
DmhClient() An implementation of interface DmhClientItf.

Method Summary

Methods

Modifier and Type	Method and Description
void	close(String boxname) Stop using a mailbox - disarm receiving if listening, discard any pending messages, and remove from existence if it exists.
int[]	count(String boxname) Obtain mailbox message counts.
void	disarm() Cancel all mailbox receiving for the connection.
void	disarm(String boxname) Un-register the listener from a mailbox.
void	disconnect() Clean-up resources such as network connections that are being used by this interface.
String	doXact(String destbox, String msg) Send a message and wait for a reply.
String	doXact(String destbox, String msg, int secs_timeout) Send a message and wait for a reply.
String	doXact(String destbox, String msg, String replybox) Send a message and wait for a reply.
String	doXact(String destbox, String msg, String replybox, int secs_timeout) Send a message and wait for a reply.
void	flush(String boxname) Empty a mailbox of any pending messages.
String	getClientID() Get the server's unique ID string for the client connection.
int	getDefaultTimeout() Get the current default timeout that is used on DoXact calls.
String	getDescription() returns the client description
String	getGroupname() return the DMH Groupname as provided to the init() method.
String	getHostname() Return the TCP/IP hostname of the local computer
String	getMhGroup() If you have a connection, getMhgroup() returns hostname:port of the DMH server else an empty string
String	getProduct() Obtain the vendor product id.
int	getState() Obtain an integer code representing communication status.
int	getTraceBits() get the trace bitfield settings
String	getVersion() Obtain the DMH compatibility version.
int	groupnamePort(String Groupname) Return the socket port that a DMH groupname is mapped to.
String	init(String hostname, int port) Initialize and connect to a DMH server.
String	init(String hostname, String groupname) Initialize and connect to a DMH server.
void	put(String mailbox, String message) Send a message to a named mailbox.
void	putr(String destbox, String replybox, String message) Send a message to a mailbox with a reply mailbox indicated.
void	run() Run is public for Thread start to call, not for applications to call.
String	serverStatus() Obtain the current message system status as a text list.
int	setDefaultTimeout(int secs_timeout) Set the default timeout that is used on DoXact calls.
void	setDescription(String description) Set the description for the client that is shown by the "Identify" button from the DMH Status window.
DmhLostServerItf	setLostServer(DmhLostServerItf handler) Register a handler that gets called if the connection to the DMH server is lost.
DmhTraceItf	setTrace(DmhTraceItf handler) set the Trace output handler, return the previous value
int	setTraceBits(int tracebits) Control the output of trace information.
String	timedReceive(String boxname, int secs_timeout) Wait for a message to be received.
String	toString()
void	whenMsg(String boxname, DmhReceiveItf handler) Register a callback object to receive the next message available in mailbox boxname.
void	whenMsgAgain() This method is called by the logic of your dmhReceive() method to specify that the current handler object should be used to process the next message received in the same destination mailbox.
String[][]	whenMsgDump() Dump the list of active mailbox listeners.

Methods inherited from class Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

DmhClient

public DmhClient()

An implementation of interface DmhClientItf.

Use the class only for a constructor call. Use the interface classname in your application. For example:

     DmhClientItf dmh = new DmhClient();
 

Method Detail

close

public void close(String boxname)
           throws Exception

Description copied from interface: DmhClientItf

Stop using a mailbox - disarm receiving if listening, discard any pending messages, and remove from existence if it exists.

Specified by:

close in interface DmhClientItf

Parameters:

boxname - The name of the mailbox that is to be closed.

Throws:

Exception - if there is no connection

count

public int[] count(String boxname)
            throws Exception

Description copied from interface: DmhClientItf

Obtain mailbox message counts.

Specified by:

count in interface DmhClientItf

Parameters:

boxname - The mailbox name.

Returns:

A three element array

1. the total count of messages that have been sent to the mailbox,
2. the total count of messages that have been consumed from the mailbox,
3. the count of pending messages.

Throws:

Exception - if there is no connection

disarm

public void disarm()
            throws Exception

Description copied from interface: DmhClientItf

Cancel all mailbox receiving for the connection.

Specified by:

disarm in interface DmhClientItf

Throws:

Exception

disarm

public void disarm(String boxname)
            throws Exception

Description copied from interface: DmhClientItf

Un-register the listener from a mailbox. This call is used to cancel an earlier whenMsg() call.

Specified by:

disarm in interface DmhClientItf

Parameters:

boxname - The name of the mailbox that is serving as the destination for the sender(s) of the message(s).

Throws:

Exception - if there is no connection

disconnect

public void disconnect()

Description copied from interface: DmhClientItf

Clean-up resources such as network connections that are being used by this interface.

Specified by:

disconnect in interface DmhClientItf

doXact

public String doXact(String destbox,
            String msg)
              throws Exception

Description copied from interface: DmhClientItf

Send a message and wait for a reply. The variations of doXact() allow you to let the reply mailbox or the timeout parameter use default values. The default reply mailbox is a unique one that is created, used once, and freed on your behalf. You can set the default timeout value using the setDefaultTimeout() call.

Specified by:

doXact in interface DmhClientItf

Parameters:

destbox - The mailbox name of the server to which the message is sent.

msg - The message string.

Returns:

The reply message string or the literal text "TIMEOUT".

Throws:

Exception - for improper arguments or a broken connection

doXact

public String doXact(String destbox,
            String msg,
            int secs_timeout)
              throws Exception

Description copied from interface: DmhClientItf

Send a message and wait for a reply. The variations of doXact() allow you to let the reply mailbox or the timeout parameter use default values. The default reply mailbox is a unique one that is created, used once, and freed on your behalf.

Specified by:

doXact in interface DmhClientItf

Parameters:

destbox - The mailbox name of the server to which the message is sent.

msg - The message string.

secs_timeout - The maximum time to wait for the reply in seconds.

Returns:

The reply message string or the literal text "TIMEOUT".

Throws:

Exception - for improper arguments or a broken connection

doXact

public String doXact(String destbox,
            String msg,
            String replybox)
              throws Exception

Description copied from interface: DmhClientItf

Send a message and wait for a reply. The variations of doXact() allow you to let the reply mailbox or the timeout parameter use default values. You can set the default timeout value using the setDefaultTimeout() call.

Specified by:

doXact in interface DmhClientItf

Parameters:

destbox - The mailbox name of the server to which the message is sent.

msg - The message string.

replybox - A mailbox name specified for receiving the reply message.

Returns:

The reply message string or the literal text "TIMEOUT".

Throws:

Exception - for improper arguments or a broken connection

doXact

public String doXact(String destbox,
            String msg,
            String replybox,
            int secs_timeout)
              throws Exception

Description copied from interface: DmhClientItf

Send a message and wait for a reply.

Specified by:

doXact in interface DmhClientItf

Parameters:

destbox - The mailbox name of the server to which the message is sent.

msg - The message string.

replybox - A mailbox name specified for receiving the reply message.

secs_timeout - The maximum time to wait for the reply in seconds.

Returns:

The reply message string or the literal text "TIMEOUT".

Throws:

Exception - for improper arguments or a broken connection

flush

public void flush(String boxname)
           throws Exception

Description copied from interface: DmhClientItf

Empty a mailbox of any pending messages. A pending message is one that has been sent to the mailbox but has not been consumed. In other words, a pending message is waiting in a queue associated with the mailbox name. Messages are consumed by reading or flushing.

Specified by:

flush in interface DmhClientItf

Parameters:

boxname - The name of the mailbox that is to be emptied.

Throws:

Exception - if no connection.

getClientID

public String getClientID()

Description copied from interface: DmhClientItf

Get the server's unique ID string for the client connection.

Specified by:

getClientID in interface DmhClientItf

Returns:

The ID string or "" if a connection has not been made.

getDefaultTimeout

public int getDefaultTimeout()

Description copied from interface: DmhClientItf

Get the current default timeout that is used on DoXact calls.

Specified by:

getDefaultTimeout in interface DmhClientItf

Returns:

timeout in seconds

getDescription

public String getDescription()

Description copied from interface: DmhClientItf

returns the client description

Specified by:

getDescription in interface DmhClientItf

Returns:

the client description

getGroupname

public String getGroupname()

Description copied from interface: DmhClientItf

return the DMH Groupname as provided to the init() method.

Specified by:

getGroupname in interface DmhClientItf

Returns:

the DMH Groupname as provided to the init() method.

getHostname

public String getHostname()

Description copied from interface: DmhClientItf

Return the TCP/IP hostname of the local computer

Specified by:

getHostname in interface DmhClientItf

getMhGroup

public String getMhGroup()

Description copied from interface: DmhClientItf

If you have a connection, getMhgroup() returns hostname:port of the DMH server else an empty string

Specified by:

getMhGroup in interface DmhClientItf

Returns:

A string representing the connection to the DMH server as hostname:port. An empty string is returned if no connection exists.

getProduct

public String getProduct()

Description copied from interface: DmhClientItf

Obtain the vendor product id.

A proprietary or competitive version of this interface should return a different value.

Specified by:

getProduct in interface DmhClientItf

Returns:

The Hume version returns the string "DMH" to indicate the vendor branding of this implementation.

getState

public int getState()

Description copied from interface: DmhClientItf

Obtain an integer code representing communication status. Typically you only test to see if the value is STATE_CONNECTED.

Specified by:

getState in interface DmhClientItf

Returns:

state value (see STATE_* constants)

getTraceBits

public int getTraceBits()

Description copied from interface: DmhClientItf

get the trace bitfield settings

Specified by:

getTraceBits in interface DmhClientItf

Returns:

the OR'd combination of TRACE_* bit settings

getVersion

public String getVersion()

Description copied from interface: DmhClientItf

Obtain the DMH compatibility version.

Specified by:

getVersion in interface DmhClientItf

Returns:

Current software returns a string that leads with "1.1" to indicate compatibility with DMH versions 1.1 and earlier, and includes source code version information.

groupnamePort

public int groupnamePort(String Groupname)

Description copied from interface: DmhClientItf

Return the socket port that a DMH groupname is mapped to.

Specified by:

groupnamePort in interface DmhClientItf

Returns:

socket port

init

public String init(String hostname,
          int port)
            throws Exception

Description copied from interface: DmhClientItf

Initialize and connect to a DMH server.

Specified by:

init in interface DmhClientItf

Parameters:

hostname - the TCP/IP hostname of the DMH server, may also be the IP number as a string. May be null to represent your own system.

port - the socket port number for the server

Returns:

the return value is the hostname:port of the server on success. The hostname is the server's preferred TCP/IP hostname and not necessarily the hostname argument you provided.

Throws:

Exception - if the connection attempt fails

init

public String init(String hostname,
          String groupname)
            throws Exception

Description copied from interface: DmhClientItf

Initialize and connect to a DMH server.

Specified by:

init in interface DmhClientItf

Parameters:

hostname - the TCP/IP hostname of the DMH server, may also be the IP number as a string. May be null to represent your own system.

groupname - the name of the DMH message group. Group names are hashed to an integer port number. The init() method can also be called directly with an integer port number.

Returns:

the return value is the hostname:port of the server on success. The hostname is the server's preferred TCP/IP hostname and not necessarily the hostname argument you provided.

Throws:

Exception - if the connection attempt fails

put

public void put(String mailbox,
       String message)
         throws Exception

Description copied from interface: DmhClientItf

Send a message to a named mailbox.

Specified by:

put in interface DmhClientItf

Parameters:

mailbox - The destination mailbox name.

message - The message string. String characters are converted to UTF-8 encoding, so that you can safely send International characters.

Throws:

Exception

putr

public void putr(String destbox,
        String replybox,
        String message)
          throws Exception

Description copied from interface: DmhClientItf

Send a message to a mailbox with a reply mailbox indicated.

Specified by:

putr in interface DmhClientItf

Parameters:

destbox - The destination mailbox name.

replybox - The reply mailbox.

message - The message string. String characters are converted to UTF-8 encoding, so that you can safely send International characters.

Throws:

Exception

run

public void run()

Run is public for Thread start to call, not for applications to call.

Specified by:

run in interface Runnable

serverStatus

public String serverStatus()
                    throws Exception

Description copied from interface: DmhClientItf

Obtain the current message system status as a text list. See the User Guide for details.

Specified by:

serverStatus in interface DmhClientItf

Returns:

a text list containing message system status

Throws:

Exception

setDefaultTimeout

public int setDefaultTimeout(int secs_timeout)
                      throws Exception

Description copied from interface: DmhClientItf

Set the default timeout that is used on DoXact calls. If not set, the value of 30 seconds is used.

Specified by:

setDefaultTimeout in interface DmhClientItf

Parameters:

secs_timeout - The default maximum time to wait for reply messages. The value must be >= 1 and < 86400

Returns:

The value that was defined prior to your call.

Throws:

Exception

setDescription

public void setDescription(String description)

Description copied from interface: DmhClientItf

Set the description for the client that is shown by the "Identify" button from the DMH Status window. The default value is ":java DMH client"

Specified by:

setDescription in interface DmhClientItf

Parameters:

description - A user supplied description of the application process.

setLostServer

public DmhLostServerItf setLostServer(DmhLostServerItf handler)

Description copied from interface: DmhClientItf

Register a handler that gets called if the connection to the DMH server is lost. The handler can try to periodically restore the connection, tell the user to call the system administrator etc. Only a single handler can be registered, newer registrations replace earlier ones.

Specified by:

setLostServer in interface DmhClientItf

Parameters:

handler - An object that implements the DmhLostServerItf interface

setTrace

public DmhTraceItf setTrace(DmhTraceItf handler)

Description copied from interface: DmhClientItf

set the Trace output handler, return the previous value

Specified by:

setTrace in interface DmhClientItf

setTraceBits

public int setTraceBits(int tracebits)

Description copied from interface: DmhClientItf

Control the output of trace information. The output defaults to System.out until the application uses the setTrace() method to install a trace receiving callback. The TRACE_* bit values are defined to control the desired output.

Specified by:

setTraceBits in interface DmhClientItf

Parameters:

tracebits - Treated as a bitfield

timedReceive

public String timedReceive(String boxname,
                  int secs_timeout)
                    throws Exception

Description copied from interface: DmhClientItf

Wait for a message to be received.

Specified by:

timedReceive in interface DmhClientItf

Parameters:

boxname - The mailbox name.

secs_timeout - The maximum time to wait in seconds.

Returns:

The message data or the literal string "TIMEOUT".

Throws:

Exception

toString

public String toString()

Overrides:

toString in class Object

whenMsg

public void whenMsg(String boxname,
           DmhReceiveItf handler)
             throws Exception

Description copied from interface: DmhClientItf

Register a callback object to receive the next message available in mailbox boxname.

An application should insure that the dmhReceive() call completes execution in due course - the application should not try to "live" in a dmhReceive() call.

The message is removed (consumed) from the mailbox by the action of receiving it. There should not be more than one receiver per mailbox.

Specified by:

whenMsg in interface DmhClientItf

Parameters:

boxname - The name of the mailbox that is serving as the destination for sent messages.

handler - An object that implements the DmhReceiveItf interface.

Throws:

Exception - if no connection

whenMsgAgain

public void whenMsgAgain()
                  throws Exception

Description copied from interface: DmhClientItf

This method is called by the logic of your dmhReceive() method to specify that the current handler object should be used to process the next message received in the same destination mailbox. Receiving the next message does occur until the current dmhReceive() call completes. Throws Exception result if no connection.

Specified by:

whenMsgAgain in interface DmhClientItf

Throws:

Exception

whenMsgDump

public String[][] whenMsgDump()

Description copied from interface: DmhClientItf

Dump the list of active mailbox listeners.

Specified by:

whenMsgDump in interface DmhClientItf

Returns:

An array of string pairs (String [N][2]). Each pair consists of [][0] a mailbox name, and [][1] the result of executing the toString value of the DmhReceiveItf object.