org.jlab.coda.cMsg.cMsgDomain.client
Class cMsg

java.lang.Object
  extended by org.jlab.coda.cMsg.cMsgDomainAdapter
      extended by org.jlab.coda.cMsg.cMsgDomain.client.cMsg
All Implemented Interfaces:
cMsgDomainInterface
Direct Known Subclasses:
cMsgServerClient

public class cMsg
extends cMsgDomainAdapter

This class implements a cMsg client in the cMsg domain.

Version:
1.0
Author:
Carl Timmer

Field Summary
 java.lang.String monitorXML
          String containing monitor data received from a cMsg server as a keep alive response.
 java.util.Set<cMsgSubscription> subscriptions
          Collection of all of this client's message subscriptions which are cMsgSubscription objects.
 
Fields inherited from class org.jlab.coda.cMsg.cMsgDomainAdapter
connected, description, domain, host, name, receiving, shutdownHandler, UDL, UDLremainder
 
Constructor Summary
cMsg()
          Constructor which does NOT automatically try to connect to the name server specified.
 
Method Summary
 void connect()
          Method to connect to the domain server from this client.
 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.
 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 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.
 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 org.jlab.coda.cMsg.cMsgDomainAdapter
getDescription, getDomain, getHost, getName, getShutdownHandler, getString, getUDL, getUDLRemainder, isConnected, isReceiving, setDescription, setName, setShutdownHandler, setUDL, setUDLRemainder, start, stop
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

monitorXML

public java.lang.String monitorXML
String containing monitor data received from a cMsg server as a keep alive response.


subscriptions

public java.util.Set<cMsgSubscription> subscriptions
Collection of all of this client's message subscriptions which are cMsgSubscription objects. This set is synchronized. A client is either a regular client or a bridge but not both. That means it does not matter that a bridge client will add namespace data to the stored subscription but a regular client will not.

Constructor Detail

cMsg

public cMsg()
     throws cMsgException
Constructor which does NOT automatically try to connect to the name server specified.

Throws:
cMsgException - if local host name cannot be found
Method Detail

connect

public void connect()
             throws cMsgException
Method to connect to the domain server from this client. This method handles multiple UDLs, but passes off the real work to connectDirect().

Specified by:
connect in interface cMsgDomainInterface
Overrides:
connect in class cMsgDomainAdapter
Throws:
cMsgException - if there are problems parsing the UDL or communication problems with the server(s)

flush

public void flush(int timeout)
Method to force cMsg client to send pending communications with domain server. In the cMsg domain implementation, this method does nothing.

Specified by:
flush in interface cMsgDomainInterface
Overrides:
flush in class cMsgDomainAdapter
Parameters:
timeout - ignored in this domain

disconnect

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

Specified by:
disconnect in interface cMsgDomainInterface
Overrides:
disconnect in class cMsgDomainAdapter

send

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

Specified by:
send in interface cMsgDomainInterface
Overrides:
send in class cMsgDomainAdapter
Parameters:
message - message to send
Throws:
cMsgException - if there are communication problems with the server; subject and/or type is null; message is too big for UDP packet size if doing UDP send

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.

Specified by:
syncSend in interface cMsgDomainInterface
Overrides:
syncSend in class cMsgDomainAdapter
Parameters:
message - message
timeout - ignored in this domain
Returns:
response from subdomain handler
Throws:
cMsgException - if there are communication problems with the server; subject and/or type is null

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. Note about the server failing and an IOException being thrown. All existing subscriptions are resubscribed on the new failover server by the keepAlive thread. However, this routine will recover from an IO error during the subscribe itself if the failover is successful.

Specified by:
subscribe in interface cMsgDomainInterface
Overrides:
subscribe in class cMsgDomainAdapter
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 - if the callback, subject and/or type is null or blank; an identical subscription already exists; there are communication problems with the server

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. Note about the server failing and an IOException being thrown. To have "unsubscribe" make sense on the failover server, we must wait until all existing subscriptions have been successfully resubscribed on the new server.

Specified by:
unsubscribe in interface cMsgDomainInterface
Overrides:
unsubscribe in class cMsgDomainAdapter
Parameters:
obj - the object "handle" returned from a subscribe call
Throws:
cMsgException - if there are communication problems with the server; object arg is null

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. NOTE: Disconnecting when one thread is in the waiting part of a subscribeAndGet may cause that thread to block forever. It is best to always use a timeout with subscribeAndGet so the thread is assured of eventually resuming execution.

Specified by:
subscribeAndGet in interface cMsgDomainInterface
Overrides:
subscribeAndGet in class cMsgDomainAdapter
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 - if there are communication problems with the server; server dies; subject and/or type is null or blank
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 the first response back to the original sender regardless of its subject or type. NOTE: Disconnecting when one thread is in the waiting part of a sendAndGet may cause that thread to block forever. It is best to always use a timeout with sendAndGet so the thread is assured of eventually resuming execution.

Specified by:
sendAndGet in interface cMsgDomainInterface
Overrides:
sendAndGet in class cMsgDomainAdapter
Parameters:
message - message sent to server
timeout - time in milliseconds to wait for a reponse message
Returns:
response message
Throws:
cMsgException - if there are communication problems with the server; server died; subject and/or type is null
java.util.concurrent.TimeoutException - if timeout occurs

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.

Specified by:
monitor in interface cMsgDomainInterface
Overrides:
monitor in class cMsgDomainAdapter
Parameters:
command - directive for monitoring process
Returns:
response message containing monitoring information
Throws:
cMsgException

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. No failover done here because you do not want to automatically shutdown clients on the new server. It's better to have this call fail.

Specified by:
shutdownClients in interface cMsgDomainInterface
Overrides:
shutdownClients in class cMsgDomainAdapter
Parameters:
client - client(s) to be shutdown
includeMe - if true, it is permissible to shutdown calling client
Throws:
cMsgException - if there are communication problems with the server

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. No failover done here because you do not want to automatically shutdown servers connected to the new server. It's better to have this call fail.

Specified by:
shutdownServers in interface cMsgDomainInterface
Overrides:
shutdownServers in class cMsgDomainAdapter
Parameters:
server - server(s) to be shutdown
includeMyServer - if true, it is permissible to shutdown calling client's cMsg server
Throws:
cMsgException - if server arg is not in the correct form (host:port), the host is unknown, client not connected to server, or IO error.