public interface DmhClientItf
You will typically setup only one DmhClient connection to a particular DMH server and use it for the lifetime of your application.
The actual network connection is not attempted until init() is called.
Modifier and Type | Field and Description |
---|---|
static int |
STATE_CLOSING |
static int |
STATE_COMM_ERROR |
static int |
STATE_CONNECTED |
static int |
STATE_DISCONNECTED |
static int |
STATE_NAME_RESOLUTION |
static int |
STATE_SETUP_IN_PROGRESS |
static int |
TRACE_ERRS
trace background errors including exceptions thrown by application
message receiving callbacks.
|
static int |
TRACE_LOGIC
trace connection setup and other processing logic
|
static int |
TRACE_READS
trace low level data receiving
|
static int |
TRACE_RECV
trace DMH message receiving
|
static int |
TRACE_SEND
trace DMH message sending
|
static int |
TRACE_WRITES
trace low level data sending
|
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 secondsTimeout)
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 secondsTimeout)
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.
|
String |
serverStatus()
Obtain the current message system status as a text list.
|
int |
setDefaultTimeout(int seconds)
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.
|
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.
|
static final int STATE_CLOSING
static final int STATE_COMM_ERROR
static final int STATE_CONNECTED
static final int STATE_DISCONNECTED
static final int STATE_NAME_RESOLUTION
static final int STATE_SETUP_IN_PROGRESS
static final int TRACE_ERRS
static final int TRACE_LOGIC
static final int TRACE_READS
static final int TRACE_RECV
static final int TRACE_SEND
static final int TRACE_WRITES
void close(String boxname) throws Exception
boxname
- The name of the mailbox that is to be closed.Exception
- if there is no connectionint[] count(String boxname) throws Exception
boxname
- The mailbox name.
Exception
- if there is no connectionvoid disarm() throws Exception
Exception
void disarm(String boxname) throws Exception
boxname
- The name of the mailbox that is serving as the destination for the sender(s) of the message(s).Exception
- if there is no connectionvoid disconnect()
String doXact(String destbox, String msg) throws Exception
destbox
- The mailbox name of the server to which the message is sent.msg
- The message string.Exception
- for improper arguments or a broken connectionString doXact(String destbox, String msg, int secondsTimeout) throws Exception
destbox
- The mailbox name of the server to which the message is sent.msg
- The message string.secondsTimeout
- The maximum time to wait for the reply in seconds.Exception
- for improper arguments or a broken connectionString doXact(String destbox, String msg, String replybox) throws Exception
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.Exception
- for improper arguments or a broken connectionString doXact(String destbox, String msg, String replybox, int secondsTimeout) throws Exception
destbox
- The mailbox name of the server to which the message is sent.msg
- The message string.secondsTimeout
- The maximum time to wait for the reply in seconds.replybox
- A mailbox name specified for receiving the reply message.Exception
- for improper arguments or a broken connectionvoid flush(String boxname) throws Exception
boxname
- The name of the mailbox that is to be emptied.Exception
- if no connection.String getClientID()
int getDefaultTimeout()
String getDescription()
String getGroupname()
String getHostname()
String getMhGroup()
String getProduct()
A proprietary or competitive version of this interface should return a different value.
int getState()
int getTraceBits()
String getVersion()
int groupnamePort(String groupname)
groupname
- String init(String hostname, int port) throws Exception
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 serverException
- if the connection attempt failsString init(String hostname, String groupname) throws Exception
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.Exception
- if the connection attempt failsvoid put(String mailbox, String message) throws Exception
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.Exception
void putr(String destbox, String replybox, String message) throws Exception
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.Exception
String serverStatus() throws Exception
Exception
int setDefaultTimeout(int seconds) throws Exception
seconds
- The default maximum time to wait for reply messages.
The value must be >= 1 and < 86400Exception
void setDescription(String description)
description
- A user supplied description of the application
process.DmhLostServerItf setLostServer(DmhLostServerItf handler)
handler
- An object that implements the DmhLostServerItf interfaceDmhTraceItf setTrace(DmhTraceItf handler)
int setTraceBits(int tracebits)
tracebits
- Treated as a bitfieldString timedReceive(String boxname, int secs_timeout) throws Exception
boxname
- The mailbox name.secs_timeout
- The maximum time to wait in seconds.Exception
void whenMsg(String boxname, DmhReceiveItf handler) throws Exception
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.
boxname
- The name of the mailbox that is serving as the destination for sent messages.handler
- An object that implements the DmhReceiveItf interface.Exception
- if no connectionvoid whenMsgAgain() throws Exception
Exception
String[][] whenMsgDump()