org.jlab.coda.cMsg

Class cMsg

java.lang.Object

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>

• initial cMsg: is not necessary

• cMsg and domainType are case independent

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

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

• port is not necessary to specify but is the name server's TCP port if connecting directly or the server's UDP port if multicasting. Defaults used if not specified are cMsgNetworkConstants.nameServerTcpPort if connecting directly, else cMsgNetworkConstants.nameServerUdpPort if multicasting

• host can be "localhost" and may also be in dotted form (129.57.35.21)

• if domainType is cMsg, subdomainType is automatically set to cMsg if not given. if subdomainType is not cMsg, it is required

• the domain name is case insensitive as is the subdomainType

• remainder is passed on to the subdomain plug-in

• client's password is in tag=value part of UDL as cmsgpassword=<password>

• multicast timeout is in tag=value part of UDL as multicastTO=<time out in seconds>

• the tag=value part of UDL parsed here is given by regime=low or regime=high means:

  • low message/data throughtput client if regime=low, meaning many clients are serviced by a single server thread and all msgs retain time order

  • high message/data throughput client if regime=high, meaning each client is serviced by multiple threads to maximize throughput. Msgs are NOT guaranteed to be handled in time order

  • if regime is not specified (default), it is assumed to be medium, where a single thread is dedicated to a single client and msgs are guaranteed to be handled in time order

Constructor Summary

Constructors

Constructor and Description
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

Modifier and Type	Method and Description
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	getInfo(java.lang.String s) General purpose I/O method which gets a string that the implementation class wants to return up to the top (this) level API.
java.lang.String	getName() Get the name of the client.
java.lang.String	getServerHost() Get the host of the server (if any) that this client is connected to.
int	getServerPort() Get the port of the server (if any) that this client is connected to.
org.jlab.coda.cMsg.common.cMsgShutdownHandlerInterface	getShutdownHandler() Method to get the shutdown handler of the client.
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(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:

• cMsgConstants.debugNone for no output

• cMsgConstants.debugSevere for severe error output

• cMsgConstants.debugError for all error output

• cMsgConstants.debugWarn for warning and error output

• cMsgConstants.debugInfo for information, warning, and error output

Parameters:

debug - level of debug output

connect

public void connect()
             throws cMsgException

Method to connect to a particular domain.

Throws:

cMsgException - if cMsg error.

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 - if cMsg error.

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 - if cMsg error.

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 - if cMsg error.

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 - if cMsg error.

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 - if cMsg error.

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(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 - if cMsg error.

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 - if cMsg error.

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; or null if none

Throws:

cMsgException - if cMsg error.

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 - if cMsg error.

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 - if cMsg error.

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 - if cMsg error.

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

getServerHost

public java.lang.String getServerHost()

Get the host of the server (if any) that this client is connected to.

Returns:

server's host; null if unknown

getServerPort

public int getServerPort()

Get the port of the server (if any) that this client is connected to.

Returns:

server's port; 0 if unknown

getInfo

public java.lang.String getInfo(java.lang.String s)

General purpose I/O method which gets a string that the implementation class wants to return up to the top (this) level API.

Parameters:

s - string

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