org.jlab.coda.cMsg
Interface cMsgDomainInterface

All Known Implementing Classes:
CA, cMsg, cMsgDomainAdapter, cMsgServerClient, File, RCBroadcast, RCServer, RunControl, TCPS

public interface cMsgDomainInterface

This interface is the cMsg client API for cMsg domain.

Version:
1.0
Author:
Elliott Wolin, Carl Timmer

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 implementing class wants to send back to the user.
 java.lang.String getUDL()
          Get the client's UDL.
 java.lang.String getUDLRemainder()
          Get the client's UDL remainder.
 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 setDescription(java.lang.String description)
          Set the description of the client.
 void setName(java.lang.String name)
          Set the name of the client.
 void setShutdownHandler(cMsgShutdownHandlerInterface handler)
          Method to set the shutdown handler of the client.
 void setUDL(java.lang.String UDL)
          Set the UDL of the client.
 void setUDLRemainder(java.lang.String UDLRemainder)
          Set the UDL remainder 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.
 

Method Detail

connect

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

Throws:
cMsgException

disconnect

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

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

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

Parameters:
message - message
Throws:
cMsgException

syncSend

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

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

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

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

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 single 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

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

monitor

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

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


stop

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


shutdownClients

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

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

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

Parameters:
handler - shutdown handler

getShutdownHandler

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

Returns:
shutdown handler object

getDomain

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

Returns:
domain name

getName

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

Returns:
client's name

setName

void setName(java.lang.String name)
Set the name of the client.

Parameters:
name - name of client

getDescription

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

Returns:
client's description

setDescription

void setDescription(java.lang.String description)
Set the description of the client.

Parameters:
description - description of client

getUDL

java.lang.String getUDL()
Get the client's UDL.

Returns:
client's DUL

setUDL

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

Parameters:
UDL - UDL of client UDL

getUDLRemainder

java.lang.String getUDLRemainder()
Get the client's UDL remainder.

Returns:
client's DUL remainder

setUDLRemainder

void setUDLRemainder(java.lang.String UDLRemainder)
Set the UDL remainder of the client. The cMsg class parses the UDL and strips off the beginning domain information. The remainder is passed on to the domain implementations (implementors of this interface).

Parameters:
UDLRemainder - UDL remainder of client UDL

getHost

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

Returns:
client's host

getString

java.lang.String getString()
Get a string that the implementing class wants to send back to the user.

Returns:
a string

isReceiving

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