org.jlab.coda.cMsg
Class cMsg

java.lang.Object
  extended by org.jlab.coda.cMsg.cMsg

public class cMsg
extends java.lang.Object

This class is instantiated by a client in order to connect to a cMsg server. The instantiated object will be the main means by which the client will interact with cMsg.

This class acts as a multiplexor to direct a cMsg client to the proper subdomain based on the UDL given.


Constructor Summary
cMsg(java.lang.String UDL, java.lang.String name, java.lang.String description)
          Constructor which automatically tries to connect to the name server specified.
 
Method Summary
 void connect()
          Method to connect to a particular domain server.
 void disconnect()
          Method to close the connection to the domain server.
 void flush(int timeout)
          Method to force cMsg client to send pending communications with domain server.
 java.lang.String getDescription()
          Get the client's description.
 java.lang.String getDomain()
          Get the name of the domain connected to.
 java.lang.String getHost()
          Get the host the client is running on.
 java.lang.String getName()
          Get the name of the client.
 cMsgShutdownHandlerInterface getShutdownHandler()
          Method to get the shutdown handler of the client.
 java.lang.String getString()
          Get a string that the implementation class wants to return up to the top (this) level API.
 java.lang.String getUDL()
          Get the UDL of the client.
 java.lang.String getUDLRemainder()
          Get the UDL remainder (UDL after cMsg:domain:// is stripped off) of the client.
 boolean isConnected()
          Method to determine if this object is still connected to the domain server or not.
 boolean isReceiving()
          Method telling whether callbacks are activated or not.
 cMsgMessage monitor(java.lang.String command)
          This method is a synchronous call to receive a message containing monitoring data which describes the state of the cMsg domain the user is connected to.
 void send(cMsgMessage message)
          Method to send a message to the domain server for further distribution.
 cMsgMessage sendAndGet(cMsgMessage message, int timeout)
          The message is sent as it would be in the send(org.jlab.coda.cMsg.cMsgMessage) method.
 void setShutdownHandler(cMsgShutdownHandlerInterface handler)
          Method to set the shutdown handler of the client.
 void shutdownClients(java.lang.String client, boolean includeMe)
          Method to shutdown the given clients.
 void shutdownServers(java.lang.String server, boolean includeMyServer)
          Method to shutdown the given servers.
 void start()
          Method to start or activate the subscription callbacks.
 void stop()
          Method to stop or deactivate the subscription callbacks.
 java.lang.Object subscribe(java.lang.String subject, java.lang.String type, cMsgCallbackInterface cb, java.lang.Object userObj)
          Method to subscribe to receive messages of a subject and type from the domain server.
 cMsgMessage subscribeAndGet(java.lang.String subject, java.lang.String type, int timeout)
          This method is like a one-time subscribe.
 int syncSend(cMsgMessage message, int timeout)
          Method to send a message to the domain server for further distribution and wait for a response from the subdomain handler that got it.
 void unsubscribe(java.lang.Object obj)
          Method to unsubscribe a previous subscription to receive messages of a subject and type from the domain server.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

cMsg

public cMsg(java.lang.String UDL,
            java.lang.String name,
            java.lang.String description)
     throws cMsgException
Constructor which automatically tries to connect to the name server specified.

Parameters:
UDL - semicolon separated list of Uniform Domain Locators - each of which specifies a server to connect to
name - name of this client which must be unique in this domain
description - description of this client
Throws:
cMsgException - if domain in not implemented; there are problems communicating with the name/domain server; name contains colon; the UDL is invalid; the UDL contains an unreadable file; any of the arguments are null
Method Detail

connect

public void connect()
             throws cMsgException
Method to connect to a particular domain server.

Throws:
cMsgException

disconnect

public void disconnect()
                throws cMsgException
Method to close the connection to the domain server. This method results in this object becoming functionally useless.

Throws:
cMsgException

isConnected

public boolean isConnected()
Method to determine if this object is still connected to the domain server or not.

Returns:
true if connected to domain server, false otherwise

send

public void send(cMsgMessage message)
          throws cMsgException
Method to send a message to the domain server for further distribution.

Parameters:
message - message
Throws:
cMsgException

syncSend

public int syncSend(cMsgMessage message,
                    int timeout)
             throws cMsgException
Method to send a message to the domain server for further distribution and wait for a response from the subdomain handler that got it.

Parameters:
message - message
timeout - time in milliseconds to wait for a response
Returns:
response from subdomain handler
Throws:
cMsgException

flush

public void flush(int timeout)
           throws cMsgException
Method to force cMsg client to send pending communications with domain server.

Parameters:
timeout - time in milliseconds to wait for completion
Throws:
cMsgException

subscribeAndGet

public cMsgMessage subscribeAndGet(java.lang.String subject,
                                   java.lang.String type,
                                   int timeout)
                            throws cMsgException,
                                   java.util.concurrent.TimeoutException
This method is like a one-time subscribe. The server grabs the first incoming message of the requested subject and type and sends that to the caller.

Parameters:
subject - subject of message desired from server
type - type of message desired from server
timeout - time in milliseconds to wait for a message
Returns:
response message
Throws:
cMsgException
java.util.concurrent.TimeoutException - if timeout occurs

sendAndGet

public cMsgMessage sendAndGet(cMsgMessage message,
                              int timeout)
                       throws cMsgException,
                              java.util.concurrent.TimeoutException
The message is sent as it would be in the send(org.jlab.coda.cMsg.cMsgMessage) method. The server notes the fact that a response to it is expected, and sends it to all subscribed to its subject and type. When a marked response is received from a client, it sends that first response back to the original sender regardless of its subject or type. The response may be null.

Parameters:
message - message sent to server
timeout - time in milliseconds to wait for a reponse message
Returns:
response message
Throws:
cMsgException
java.util.concurrent.TimeoutException - if timeout occurs

subscribe

public java.lang.Object subscribe(java.lang.String subject,
                                  java.lang.String type,
                                  cMsgCallbackInterface cb,
                                  java.lang.Object userObj)
                           throws cMsgException
Method to subscribe to receive messages of a subject and type from the domain server. The combination of arguments must be unique. In other words, only 1 subscription is allowed for a given set of subject, type, callback, and userObj.

Parameters:
subject - message subject
type - message type
cb - callback object whose cMsgCallbackInterface.callback(cMsgMessage, Object) method is called upon receiving a message of subject and type
userObj - any user-supplied object to be given to the callback method as an argument
Returns:
handle object to be used for unsubscribing
Throws:
cMsgException

unsubscribe

public void unsubscribe(java.lang.Object obj)
                 throws cMsgException
Method to unsubscribe a previous subscription to receive messages of a subject and type from the domain server.

Parameters:
obj - the object "handle" returned from a subscribe call
Throws:
cMsgException - if there are communication problems with the server

monitor

public cMsgMessage monitor(java.lang.String command)
                    throws cMsgException
This method is a synchronous call to receive a message containing monitoring data which describes the state of the cMsg domain the user is connected to.

Parameters:
command - directive for monitoring process
Returns:
response message containing monitoring information
Throws:
cMsgException

start

public void start()
Method to start or activate the subscription callbacks.


stop

public void stop()
Method to stop or deactivate the subscription callbacks.


shutdownClients

public void shutdownClients(java.lang.String client,
                            boolean includeMe)
                     throws cMsgException
Method to shutdown the given clients. Wildcards used to match client names with the given string.

Parameters:
client - client(s) to be shutdown
includeMe - if true, it is permissible to shutdown calling client
Throws:
cMsgException

shutdownServers

public void shutdownServers(java.lang.String server,
                            boolean includeMyServer)
                     throws cMsgException
Method to shutdown the given servers. Wildcards used to match server names with the given string.

Parameters:
server - server(s) to be shutdown
includeMyServer - if true, it is permissible to shutdown calling client's cMsg server
Throws:
cMsgException

setShutdownHandler

public void setShutdownHandler(cMsgShutdownHandlerInterface handler)
Method to set the shutdown handler of the client.

Parameters:
handler - shutdown handler

getShutdownHandler

public cMsgShutdownHandlerInterface getShutdownHandler()
Method to get the shutdown handler of the client.

Returns:
shutdown handler object

getDomain

public java.lang.String getDomain()
Get the name of the domain connected to.

Returns:
domain name

getUDL

public java.lang.String getUDL()
Get the UDL of the client.

Returns:
client's UDL

getUDLRemainder

public java.lang.String getUDLRemainder()
Get the UDL remainder (UDL after cMsg:domain:// is stripped off) of the client.

Returns:
client's UDL remainder

getName

public java.lang.String getName()
Get the name of the client.

Returns:
client's name

getDescription

public java.lang.String getDescription()
Get the client's description.

Returns:
client's description

getHost

public java.lang.String getHost()
Get the host the client is running on.

Returns:
client's host

getString

public java.lang.String getString()
Get a string that the implementation class wants to return up to the top (this) level API.

Returns:
a string

isReceiving

public boolean isReceiving()
Method telling whether callbacks are activated or not. The start and stop methods activate and deactivate the callbacks.

Returns:
true if callbacks are activated, false if they are not