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 domain. The instantiated object will be the main means by which the client will interact with cMsg.

This class is the "top level" API and acts as a multiplexor to direct a cMsg client to the proper domain based on the Uniform Domain Locator (UDL) given. Note that not all of the methods of this object are implemented in a particular domain and thus may return an exeception. The UDL has the general form:

cMsg:<domainType>://<domain dependent remainder>

For the cMsg domain the UDL has the more specific form:

cMsg:cMsg://<host>:<port>/<subdomainType>/<subdomain remainder>?tag=value&tag2=value2 ...


Constructor Summary
cMsg(java.lang.String UDL, java.lang.String name, java.lang.String description)
          Constructor which creates the object used to connect to the UDL (domain) specified.
 
Method Summary
 void connect()
          Method to connect to a particular domain.
 void disconnect()
          Method to close the connection to the domain.
 void flush(int timeout)
          Method to force cMsg client to send pending communications with domain.
 java.lang.String getCurrentUDL()
          Get the UDL the client is currently connected to.
 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.
 org.jlab.coda.cMsg.common.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 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 domain the user is connected to.
 void send(cMsgMessage message)
          Method to send a message to the domain 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 setDebug(int debug)
          Set level of debug output.
 void setShutdownHandler(org.jlab.coda.cMsg.common.cMsgShutdownHandlerInterface handler)
          Method to set the shutdown handler of the client.
 void setUDL(java.lang.String UDL)
          Set the UDL 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.
 cMsgSubscriptionHandle 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.
 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 for further distribution and wait for a response from the domain that got it.
 void unsubscribe(cMsgSubscriptionHandle handle)
          Method to unsubscribe a previous subscription to receive messages of a subject and type from the domain.
 
Methods inherited from class java.lang.Object
equals, 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 creates the object used to connect to the UDL (domain) specified.

Parameters:
UDL - semicolon separated list of Uniform Domain Locators. These UDLs have different specifics in each domain. In the cMsg domain each of the UDLs 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 domain; name contains colon; the UDL is invalid; the UDL contains an unreadable file; any of the arguments are null
Method Detail

setDebug

public void setDebug(int debug)
Set level of debug output. Argument may be one of:

Parameters:
debug - level of debug output

connect

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

Throws:
cMsgException

disconnect

public void disconnect()
                throws cMsgException
Method to close the connection to the domain. 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 or not.

Returns:
true if connected to domain, false otherwise

send

public void send(cMsgMessage message)
          throws cMsgException
Method to send a message to the domain 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 for further distribution and wait for a response from the domain that got it.

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

flush

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

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 domain sends the first incoming message of the requested subject and type to the caller.

Parameters:
subject - subject of message desired from domain
type - type of message desired from domain
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 domain 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 domain
timeout - time in milliseconds to wait for a response message
Returns:
response message
Throws:
cMsgException
java.util.concurrent.TimeoutException - if timeout occurs

subscribe

public cMsgSubscriptionHandle 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.

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(cMsgSubscriptionHandle handle)
                 throws cMsgException
Method to unsubscribe a previous subscription to receive messages of a subject and type from the domain.

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

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 domain the user is connected to. This method, by nature, is highly dependent on the specifics of the domain the client is connected to. In the cMsg domain (the only one in which this method is currently implemented), the argument is ignored and an XML string is returned in the message's text field.

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. In the cMsg domain, wildcards used to match client names with the given string. Specifically, "*" means any or no characters, "?" means exactly 1 character, and "#" means 1 or no positive integer.

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. In the cMsg domain, wildcards used to match server names with the given string. Specifically, "*" means any or no characters, "?" means exactly 1 character, and "#" means 1 or no positive integer.

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

setShutdownHandler

public void setShutdownHandler(org.jlab.coda.cMsg.common.cMsgShutdownHandlerInterface handler)
Method to set the shutdown handler of the client.

Parameters:
handler - shutdown handler

getShutdownHandler

public org.jlab.coda.cMsg.common.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

setUDL

public void setUDL(java.lang.String UDL)
            throws cMsgException
Set the UDL of the client.

Parameters:
UDL - UDL of client
Throws:
cMsgException

getCurrentUDL

public java.lang.String getCurrentUDL()
Get the UDL the client is currently connected to.

Returns:
UDL the client is currently connected to

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