org.jlab.coda.cMsg.subdomains
Class cMsg

java.lang.Object
  extended by org.jlab.coda.cMsg.cMsgSubdomainAdapter
      extended by org.jlab.coda.cMsg.subdomains.cMsg
All Implemented Interfaces:
cMsgSubdomainInterface

public class cMsg
extends cMsgSubdomainAdapter

This class handles all client cMsg requests in the cMsg subdomain. Much of the functionality of this class is obtained by using static members. Practically, this means that only 1 name server can be run in a single JVM when using the cMsg subdomain.

Version:
1.0
Author:
Carl Timmer

Constructor Summary
cMsg()
          No-arg constructor.
 
Method Summary
 java.lang.String[] getClientNames()
          This method gets the names of all clients in the cMsg subdomain.
 java.lang.String[] getClientNamesAndNamespaces()
          This method gets the names and namespaces of all clients in the cMsg subdomain.
 java.lang.String getNamespace()
          Getter for namespace.
 void handleClientShutdown()
          Method to handle a client or domain server shutdown.
 void handleKeepAlive()
          Method to handle keepalive sent by domain client checking to see if the domain server socket is still up.
 void handleSendAndGetRequest(cMsgMessageFull message)
          Method to synchronously get a single message from a responder to a message being sent by the client.
 void handleSendRequest(cMsgMessageFull message)
          This method handles a message sent by reuglar (non-server) client.
 void handleServerSendAndGetRequest(cMsgMessageFull message, java.lang.String namespace)
          Method to synchronously get a single message from a resonder to a message beug sent by the server client.
 int handleServerSendAndGetRequest(cMsgMessageFull message, java.lang.String namespace, cMsgNotifier notifier)
          Method to synchronously get a single message from a responder to a message being sent by the client.
 void handleServerSubscribeAndGetRequest(java.lang.String subject, java.lang.String type, cMsgNotifier notifier)
          Method for regular client to synchronously get a single message from the server for a one-time subscription of a subject and type.
 void handleServerSubscribeRequest(java.lang.String subject, java.lang.String type, java.lang.String namespace)
          Method to handle subscribe request sent by another cMsg server (server client).
 void handleServerUnsubscribeRequest(java.lang.String subject, java.lang.String type, java.lang.String namespace)
          Method to handle unsubscribe request sent by another cMsg server (server client).
 void handleShutdownClientsRequest(java.lang.String client, boolean includeMe)
          Method to handle request to shutdown clients sent by client.
 void handleSubscribeAndGetRequest(java.lang.String subject, java.lang.String type, int id)
          Method for regular client to synchronously get a single message from the server for a one-time subscription of a subject and type.
 void handleSubscribeRequest(java.lang.String subject, java.lang.String type, int id)
          Method to handle subscribe request sent by regular client.
 int handleSyncSendRequest(cMsgMessageFull message)
          Method to handle message sent by client in synchronous mode.
 void handleUnSendAndGetRequest(int id)
          Method to handle remove sendAndGet request sent by any client (hidden from user).
 void handleUnsubscribeAndGetRequest(java.lang.String subject, java.lang.String type, int id)
          Method to handle a remove subscribeAndGet request sent by client (hidden from user).
 void handleUnsubscribeRequest(java.lang.String subject, java.lang.String type, int id)
          Method to handle unsubscribe request sent by regular client.
 boolean hasSend()
          Method saying this subdomain implements handleSendRequest(org.jlab.coda.cMsg.cMsgMessageFull).
 boolean hasSendAndGet()
          Method saying this subdomain implements handleSendAndGetRequest(org.jlab.coda.cMsg.cMsgMessageFull).
 boolean hasShutdown()
          Method saying this subdomain implements handleShutdownClientsRequest(java.lang.String, boolean).
 boolean hasSubscribe()
          Method saying this subdomain implements handleSubscribeRequest(java.lang.String, java.lang.String, int).
 boolean hasSubscribeAndGet()
          Method saying this subdomain implements handleSubscribeAndGetRequest(java.lang.String, java.lang.String, int).
 boolean hasSyncSend()
          Method saying this subdomain implements handleSyncSendRequest(org.jlab.coda.cMsg.cMsgMessageFull).
 boolean hasUnsubscribe()
          Method saying this subdomain implements handleUnsubscribeRequest(java.lang.String, java.lang.String, int).
 boolean isRegistered(java.lang.String name)
          Method to see if domain client is registered.
 void localSend(cMsgMessage message, java.lang.String namespace)
          This method handles a message sent by a local bridge object's callback.
 void printSizes()
           
static void printStaticSizes()
           
 void registerClient(cMsgClientInfo info)
          Method to register a domain client.
 void registerServer(cMsgClientInfo info)
          Method to register cMsg domain server as client.
static boolean registrationLock(int delay)
          This lock must be locked before a client registration in the cMsg subdomain can be made.
static void registrationUnlock()
          Unlock the registration lock.
 void setMessageDeliverer(cMsgDeliverMessageInterface deliverer)
          Method to give the subdomain handler on object able to deliver messages to the client.
 void setUDLRemainder(java.lang.String UDLRemainder)
          This method gives this subdomain handler the appropriate part of the UDL the client used to talk to 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()
No-arg constructor.

Method Detail

printStaticSizes

public static void printStaticSizes()

printSizes

public void printSizes()

getNamespace

public java.lang.String getNamespace()
Getter for namespace. This is needed in the registration process for the client. Since it is the subdomain handler object which parses out the namespace and the client/namespace combo must be unique, the registration process must query the subdomain handler what the client's namespace would be if it's accepted as a client.

Returns:
namespace of client

registrationLock

public static boolean registrationLock(int delay)
This lock must be locked before a client registration in the cMsg subdomain can be made. Because this method and its lock are static, there is effectively one lock per cMsg server.

Parameters:
delay - time in milliseconds to wait for the lock before timing out
Returns:
true if lock successful, false otherwise

registrationUnlock

public static void registrationUnlock()
Unlock the registration lock.


getClientNames

public java.lang.String[] getClientNames()
This method gets the names of all clients in the cMsg subdomain.

Returns:
an array of names of all clients in the cMsg subdomain

getClientNamesAndNamespaces

public java.lang.String[] getClientNamesAndNamespaces()
This method gets the names and namespaces of all clients in the cMsg subdomain.

Returns:
an array of names and namespaces of all clients in the cMsg subdomain

hasSend

public boolean hasSend()
Method saying this subdomain implements handleSendRequest(org.jlab.coda.cMsg.cMsgMessageFull).

Specified by:
hasSend in interface cMsgSubdomainInterface
Overrides:
hasSend in class cMsgSubdomainAdapter
Returns:
true

hasSyncSend

public boolean hasSyncSend()
Method saying this subdomain implements handleSyncSendRequest(org.jlab.coda.cMsg.cMsgMessageFull).

Specified by:
hasSyncSend in interface cMsgSubdomainInterface
Overrides:
hasSyncSend in class cMsgSubdomainAdapter
Returns:
true

hasSubscribeAndGet

public boolean hasSubscribeAndGet()
Method saying this subdomain implements handleSubscribeAndGetRequest(java.lang.String, java.lang.String, int).

Specified by:
hasSubscribeAndGet in interface cMsgSubdomainInterface
Overrides:
hasSubscribeAndGet in class cMsgSubdomainAdapter
Returns:
true

hasSendAndGet

public boolean hasSendAndGet()
Method saying this subdomain implements handleSendAndGetRequest(org.jlab.coda.cMsg.cMsgMessageFull).

Specified by:
hasSendAndGet in interface cMsgSubdomainInterface
Overrides:
hasSendAndGet in class cMsgSubdomainAdapter
Returns:
true

hasSubscribe

public boolean hasSubscribe()
Method saying this subdomain implements handleSubscribeRequest(java.lang.String, java.lang.String, int).

Specified by:
hasSubscribe in interface cMsgSubdomainInterface
Overrides:
hasSubscribe in class cMsgSubdomainAdapter
Returns:
true

hasUnsubscribe

public boolean hasUnsubscribe()
Method saying this subdomain implements handleUnsubscribeRequest(java.lang.String, java.lang.String, int).

Specified by:
hasUnsubscribe in interface cMsgSubdomainInterface
Overrides:
hasUnsubscribe in class cMsgSubdomainAdapter
Returns:
true

hasShutdown

public boolean hasShutdown()
Method saying this subdomain implements handleShutdownClientsRequest(java.lang.String, boolean).

Specified by:
hasShutdown in interface cMsgSubdomainInterface
Overrides:
hasShutdown in class cMsgSubdomainAdapter
Returns:
true

setUDLRemainder

public void setUDLRemainder(java.lang.String UDLRemainder)
                     throws cMsgException
This method gives this subdomain handler the appropriate part of the UDL the client used to talk to the domain server. In the cMsg subdomain of the cMsg domain, each client sends messages to a namespace. If no namespace is specified, the namespace is "/defaultNamespace". The namespace is specified in the client supplied UDL as follows: cMsg:cMsg://:/cMsg/ A single beginning forward slash is enforced in a namespace. A question mark will terminate but will not be included in the namespace. All trailing forward slashes will be removed.

Specified by:
setUDLRemainder in interface cMsgSubdomainInterface
Overrides:
setUDLRemainder in class cMsgSubdomainAdapter
Parameters:
UDLRemainder - last part of the UDL appropriate to the subdomain handler
Throws:
cMsgException - if there's an invalid namespace

setMessageDeliverer

public void setMessageDeliverer(cMsgDeliverMessageInterface deliverer)
Method to give the subdomain handler on object able to deliver messages to the client. This copy of the deliverer is not used in the cMsg subdomain -- only the one in the cMsgClientInfo object.

Specified by:
setMessageDeliverer in interface cMsgSubdomainInterface
Overrides:
setMessageDeliverer in class cMsgSubdomainAdapter
Parameters:
deliverer - object able to deliver messages to the client

isRegistered

public boolean isRegistered(java.lang.String name)
Method to see if domain client is registered.

Parameters:
name - name of client
Returns:
true if client registered, false otherwise

registerClient

public void registerClient(cMsgClientInfo info)
                    throws cMsgException
Method to register a domain client.

Specified by:
registerClient in interface cMsgSubdomainInterface
Overrides:
registerClient in class cMsgSubdomainAdapter
Parameters:
info - information about client
Throws:
cMsgException - if client already exists or argument is null

registerServer

public void registerServer(cMsgClientInfo info)
Method to register cMsg domain server as client. Name is of the form "nameServerHost:nameServerPort".

Parameters:
info - information about client

localSend

public void localSend(cMsgMessage message,
                      java.lang.String namespace)
               throws cMsgException
This method handles a message sent by a local bridge object's callback. Try to follow this. A bridge object has a server client. That client of another cMsg server has a callback. So when messages come in from the remote server, the callback gets run. That callback uses the single subdomain handler for the bridge and passes the message on to this server by means of this method. Thus, the message which originated on another server gets passes around to the REGULAR clients of this server (that's why it's called a LOCAL send). If it were to pass these messages to ALL clients on this server, we could get infinite loops. The message's subject and type are matched against all clients' subscriptions. For each client, the message is compared to each of its subscriptions until a match is found. At that point, the message is sent to that client. The client is responsible for finding all the matching gets and subscribes and distributing the message among them as necessary. No messages are sent to server clients to avoid infinite loops. This method is synchronized because the use of sendToSet is not thread-safe otherwise. Multiple threads in the domain server can be calling this object's methods simultaneously.

Parameters:
message - message from sender
namespace - namespace of original message sender
Throws:
cMsgException - if a channel to the client is closed, cannot be created, or socket properties cannot be set

handleSendRequest

public void handleSendRequest(cMsgMessageFull message)
                       throws cMsgException
This method handles a message sent by reuglar (non-server) client. The message's subject and type are matched against all clients' subscriptions. For each client, the message is compared to each of its subscriptions until a match is found. At that point, the message is sent to that client. The client is responsible for finding all the matching gets and subscribes and distributing the message among them as necessary. This method is synchronized because the use of sendToSet is not thread-safe otherwise. Multiple threads in the domain server can be calling this object's methods simultaneously.

Specified by:
handleSendRequest in interface cMsgSubdomainInterface
Overrides:
handleSendRequest in class cMsgSubdomainAdapter
Parameters:
message - message from sender
Throws:
cMsgException - if a channel to the client is closed, cannot be created, or socket properties cannot be set

handleSyncSendRequest

public int handleSyncSendRequest(cMsgMessageFull message)
                          throws cMsgException
Method to handle message sent by client in synchronous mode. It requires a synchronous integer response from this object.

Specified by:
handleSyncSendRequest in interface cMsgSubdomainInterface
Overrides:
handleSyncSendRequest in class cMsgSubdomainAdapter
Parameters:
message - message from sender
Returns:
response from this object
Throws:
cMsgException - if a channel to the client is closed, cannot be created, or socket properties cannot be set

handleSubscribeRequest

public void handleSubscribeRequest(java.lang.String subject,
                                   java.lang.String type,
                                   int id)
                            throws cMsgException
Method to handle subscribe request sent by regular client.

Specified by:
handleSubscribeRequest in interface cMsgSubdomainInterface
Overrides:
handleSubscribeRequest in class cMsgSubdomainAdapter
Parameters:
subject - subject to subscribe to
type - type to subscribe to
id - id (not used)
Throws:
cMsgException - if a subscription for this subject and type already exists for this client

handleServerSubscribeRequest

public void handleServerSubscribeRequest(java.lang.String subject,
                                         java.lang.String type,
                                         java.lang.String namespace)
                                  throws cMsgException
Method to handle subscribe request sent by another cMsg server (server client).

Parameters:
subject - subject subscribed to
type - type subscribed to
namespace - namespace subscription resides in
Throws:
cMsgException - if subscription already exists for this particular server client

handleUnsubscribeRequest

public void handleUnsubscribeRequest(java.lang.String subject,
                                     java.lang.String type,
                                     int id)
Method to handle unsubscribe request sent by regular client.

Specified by:
handleUnsubscribeRequest in interface cMsgSubdomainInterface
Overrides:
handleUnsubscribeRequest in class cMsgSubdomainAdapter
Parameters:
subject - subject of subscription
type - type of subscription
id - id (not used)

handleServerUnsubscribeRequest

public void handleServerUnsubscribeRequest(java.lang.String subject,
                                           java.lang.String type,
                                           java.lang.String namespace)
Method to handle unsubscribe request sent by another cMsg server (server client).

Parameters:
subject - subject of subscription
type - type of subscription
namespace - namespace subscription resides in

handleSendAndGetRequest

public void handleSendAndGetRequest(cMsgMessageFull message)
                             throws cMsgException
Method to synchronously get a single message from a responder to a message being sent by the client.

Specified by:
handleSendAndGetRequest in interface cMsgSubdomainInterface
Overrides:
handleSendAndGetRequest in class cMsgSubdomainAdapter
Parameters:
message - message requesting what sort of message to get
Throws:
cMsgException - if a channel to the client is closed, cannot be created, or socket properties cannot be set

handleServerSendAndGetRequest

public int handleServerSendAndGetRequest(cMsgMessageFull message,
                                         java.lang.String namespace,
                                         cMsgNotifier notifier)
                                  throws cMsgException
Method to synchronously get a single message from a responder to a message being sent by the client. This method is called as a result of a regular client calling sendAndGet. If there are bridges to other cMsg servers (server cloud contains more than one server), then this server does a LOCAL sendAndGet (this method) before doing a sendAndGet through all the bridge objects. The purpose of this is to install the notifier object and letting local responders immediate ability to respond to the message going out from this sendAndGet.

Parameters:
message - message requesting what sort of message to get
namespace - namespace message resides in
notifier - object used to notify others that a response message has arrived
Returns:
the unique id generated for the sendAndGet message to be sent
Throws:
cMsgException - if a channel to the client is closed, cannot be created, or socket properties cannot be set

handleServerSendAndGetRequest

public void handleServerSendAndGetRequest(cMsgMessageFull message,
                                          java.lang.String namespace)
                                   throws cMsgException
Method to synchronously get a single message from a resonder to a message beug sent by the server client. This method is called as a result of a bridge client doing a serverSendAndGet to a remote server. No notifier is needed here. We only want to send to local responders to avoid imfinite loops that would occur if servers should get this request.

Parameters:
message - message requesting what sort of message to get
namespace - namespace message resides in
Throws:
cMsgException - if a channel to the client is closed, cannot be created, or socket properties cannot be set

handleUnSendAndGetRequest

public void handleUnSendAndGetRequest(int id)
Method to handle remove sendAndGet request sent by any client (hidden from user).

Specified by:
handleUnSendAndGetRequest in interface cMsgSubdomainInterface
Overrides:
handleUnSendAndGetRequest in class cMsgSubdomainAdapter
Parameters:
id - sendAndGet message's senderToken id

handleSubscribeAndGetRequest

public void handleSubscribeAndGetRequest(java.lang.String subject,
                                         java.lang.String type,
                                         int id)
Method for regular client to synchronously get a single message from the server for a one-time subscription of a subject and type.

Specified by:
handleSubscribeAndGetRequest in interface cMsgSubdomainInterface
Overrides:
handleSubscribeAndGetRequest in class cMsgSubdomainAdapter
Parameters:
subject - subject subscribed to
type - type subscribed to
id - id (not used)

handleServerSubscribeAndGetRequest

public void handleServerSubscribeAndGetRequest(java.lang.String subject,
                                               java.lang.String type,
                                               cMsgNotifier notifier)
Method for regular client to synchronously get a single message from the server for a one-time subscription of a subject and type. This method is called as a result of a regular client calling subscribeAndGet. If there are bridges to other cMsg servers (server cloud contains more than one server), then this server does NOT call handleSubscribeAndGetRequest(java.lang.String, java.lang.String, int) but instead calls this method after doing a subscribeAndGet through all the bridge objects. The purpose of this is to install the notifier object.

Parameters:
subject - subject subscribed to
type - type subscribed to
notifier - object used to notify others that a matching message has arrived

handleUnsubscribeAndGetRequest

public void handleUnsubscribeAndGetRequest(java.lang.String subject,
                                           java.lang.String type,
                                           int id)
Method to handle a remove subscribeAndGet request sent by client (hidden from user).

Specified by:
handleUnsubscribeAndGetRequest in interface cMsgSubdomainInterface
Overrides:
handleUnsubscribeAndGetRequest in class cMsgSubdomainAdapter
Parameters:
subject - subject of subscription
type - type of subscription
id - request id

handleShutdownClientsRequest

public void handleShutdownClientsRequest(java.lang.String client,
                                         boolean includeMe)
                                  throws cMsgException
Method to handle request to shutdown clients sent by client.

Specified by:
handleShutdownClientsRequest in interface cMsgSubdomainInterface
Overrides:
handleShutdownClientsRequest in class cMsgSubdomainAdapter
Parameters:
client - client(s) to be shutdown
includeMe - if true, this client may be shutdown too
Throws:
cMsgException - if a channel to the client is closed, cannot be created, or socket properties cannot be set

handleKeepAlive

public void handleKeepAlive()
Method to handle keepalive sent by domain client checking to see if the domain server socket is still up. Normally nothing needs to be done as the domain server simply returns an "OK" to all keepalives. This method is run after all exchanges between domain server and client.

Specified by:
handleKeepAlive in interface cMsgSubdomainInterface
Overrides:
handleKeepAlive in class cMsgSubdomainAdapter

handleClientShutdown

public void handleClientShutdown()
Method to handle a client or domain server shutdown. This method is run after all exchanges between domain server and client but before the domain server thread is killed (since that is what is running this method).

Specified by:
handleClientShutdown in interface cMsgSubdomainInterface
Overrides:
handleClientShutdown in class cMsgSubdomainAdapter