com.hume.DMH

Interface DmhServerItf

All Known Implementing Classes:

DmhServer

public interface DmhServerItf

This interface defines the public procedures that a DMH message system server provides.

The class DmhServer implements both the DmhClientItf and the DmhServerItf. So all of the usual DMH message sending, receiving and management methods are provided using the DmhClientItf interface definitions. Here we only see additional methods used to support server-only functions.

Method Summary

Methods

Modifier and Type	Method and Description
void	addAlias(String groupname) Use the uncommon feature of adding a DMH groupname alias so that sending to mailbox@groupname is recognized as sending within the server's own DMH group.
void	clientDisconnect(String id) close the client's socket connection
String	clientIdentify(String id) ask the client to provide his hostname, command line, and DISPLAY name as a String result
void	clientPing(String id) Exercise the network connection which causes an error closure if the client is gone.
void	clientTerminate(String id) tell the client to exit, which is honored by Tcl and Java clients, and by VB clients if the developer codes the Shutdown() callback.
String[]	getAliases() An alias array is used to implement the concept of of virtual DMH groups in a single physical server.
String	getMhMsgs(String boxname) Tcl virtual data mh_msgs.
String	init(int port) Initialize using a specified socket port number.
String	init(String groupname) Initialize the DMH server, usually on the default network interface.
String	lastRead(String boxname) To support debugging, the DMH server keeps a copy of the last message sent to each mailbox.
DmhLostClientItf	setLostClient(DmhLostClientItf dlc) register to receive notification of disconnected clients.
DmhReceiveItf	setTraceMsg(DmhReceiveItf traceReceive) Register to receive the messages that are sent to the TRACE mailbox.
void	shutdown() shutdown the listening socket and close all existing client connections

Method Detail

addAlias

void addAlias(String groupname)

Use the uncommon feature of adding a DMH groupname alias so that sending to mailbox@groupname is recognized as sending within the server's own DMH group.

Parameters:

groupname -

clientDisconnect

void clientDisconnect(String id)

close the client's socket connection

Parameters:

id - the client handle from the serverStatus list

clientIdentify

String clientIdentify(String id)

ask the client to provide his hostname, command line, and DISPLAY name as a String result

Parameters:

id - the client handle from the serverStatus list

clientPing

void clientPing(String id)

Exercise the network connection which causes an error closure if the client is gone.

Parameters:

id - the client handle from the serverStatus list

clientTerminate

void clientTerminate(String id)

tell the client to exit, which is honored by Tcl and Java clients, and by VB clients if the developer codes the Shutdown() callback.

Parameters:

id - the client handle from the serverStatus list

getAliases

String[] getAliases()

An alias array is used to implement the concept of of virtual DMH groups in a single physical server. The most common and desirable benefit of using the indirection of the names in the array, is that the software does not have to include or specify the server hostname when specifying DMH groupnames. This keeps the software simpler and more portable across different hosts. A typical user will not need to use these methods. The present version does not provide gateway forwarding across groups. So the alias definitions should all resolve to the servers own group, DmhClient.getMhGroup().

getMhMsgs

String getMhMsgs(String boxname)

Tcl virtual data mh_msgs. The Tcl DMH server makes it seem like there is a global array mh_msgs which has all of the queued DMH messages. The array does not physically exist as a Tcl array - the read accesses are trapped and the queue data is converted to Tcl variable form on demand. There is risk of the user causing huge amounts of additional memory use by viewing a message queue that has a lot pending message data. This is a documented feature, and an acceptable design, because computing history has shown that what we consider huge today is ordinary and reasonable in two years. So we are supported the equivalent feature, which is used for debugging and diagnosis. The result is a formatted list of pairs, where each pair is a list of the message body and the reply mailbox. If there is no reply mailbox, the second element of the pair is an empty list.

 "{{hello world message} MY_REPLYBOX} {{sent w/o replybox} {}}"
 

init

String init(int port)
            throws Exception

Initialize using a specified socket port number.

Parameters:

port - socket port

Returns:

the return value is the hostname:port of the server on success.

Throws:

Exception - on failure

init

String init(String groupname)
            throws Exception

Initialize the DMH server, usually on the default network interface. The default interface is the one returned by java.net.getLocalHost(). When a host has multiple network interfaces the user can specify which one to serve using forms of Init( ) provided by the DmhClientItf. For these calls, the hostname can be a machine name or a string representing the IP address such as "192.168.2.3"

Parameters:

groupname - the name of the DMH message group. Group names are usually 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.

Throws:

Exception - on failure

lastRead

String lastRead(String boxname)

To support debugging, the DMH server keeps a copy of the last message sent to each mailbox. In the Tcl versions, the global array mh_last_read is used. You can know what mailboxes are in use from the ServerStatus() call. A typical user will not need this method.

setLostClient

DmhLostClientItf setLostClient(DmhLostClientItf dlc)

register to receive notification of disconnected clients.

setTraceMsg

DmhReceiveItf setTraceMsg(DmhReceiveItf traceReceive)

Register to receive the messages that are sent to the TRACE mailbox. The default handler is System.out.println( ) with timestamp decoration. The return value is the previously registered handler. Do not perform any time-consuming manipulation in your logic. Also avoid any method calls involving the dmh instance. You can post work to a queue which is serviced as the application has idle time if you need to perform time consuming processing.

shutdown

void shutdown()

shutdown the listening socket and close all existing client connections