org.jlab.coda.cMsg.cMsgDomain.subdomains

Class cMsg

java.lang.Object

org.jlab.coda.cMsg.common.cMsgSubdomainAdapter

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

Constructors

Constructor and Description
cMsg() No-arg constructor.

Method Summary

Modifier and Type	Method and Description
static java.lang.String[]	getClientNames() This method gets the names of all clients in the cMsg subdomain.
static 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	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 regular (non-server) client.
void	handleServerSendAndGetRequest(cMsgMessageFull message, java.lang.String namespace) Method to synchronously get a single message from a responder to a message being 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.common.cMsgMessageFull).
boolean	hasSendAndGet() Method saying this subdomain implements handleSendAndGetRequest(org.jlab.coda.cMsg.common.cMsgMessageFull).
boolean	hasShutdown() Method saying this subdomain implements handleShutdownClientsRequest(String, boolean).
boolean	hasSubscribe() Method saying this subdomain implements handleSubscribeRequest(String, String, int).
boolean	hasSubscribeAndGet() Method saying this subdomain implements handleSubscribeAndGetRequest(String, String, int).
boolean	hasSyncSend() Method saying this subdomain implements handleSyncSendRequest(org.jlab.coda.cMsg.common.cMsgMessageFull).
boolean	hasUnsubscribe() Method saying this subdomain implements handleUnsubscribeRequest(String, String, int).
static 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 static 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 static 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.common.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.common.cMsgMessageFull).

Specified by:

hasSyncSend in interface cMsgSubdomainInterface

Overrides:

hasSyncSend in class cMsgSubdomainAdapter

Returns:

true

hasSubscribeAndGet

public boolean hasSubscribeAndGet()

Method saying this subdomain implements handleSubscribeAndGetRequest(String, 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.common.cMsgMessageFull).

Specified by:

hasSendAndGet in interface cMsgSubdomainInterface

Overrides:

hasSendAndGet in class cMsgSubdomainAdapter

Returns:

true

hasSubscribe

public boolean hasSubscribe()

Method saying this subdomain implements handleSubscribeRequest(String, 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(String, 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(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 "/default". The namespace is specified in the client supplied UDL as follows: cMsg:cMsg://<host>:<port>/cMsg/<namespace> 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. Valid namespace characters are a-z, A_Z, 0-9, or _ .

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.

Parameters:

deliverer - object able to deliver messages to the client

isRegistered

public static 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:nameServerTcpPort".

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, socket properties cannot be set, or subdomain handler is shutdown

handleSendRequest

public void handleSendRequest(cMsgMessageFull message)
                       throws cMsgException

This method handles a message sent by regular (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, socket properties cannot be set, or subdomain handler is shutdown

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, socket properties cannot be set, or subdomain handler is shutdown

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, or subdomain handler is shutdown

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 a subscription for this subject and type already exists for this client, or subdomain handler is shutdown

handleUnsubscribeRequest

public void handleUnsubscribeRequest(java.lang.String subject,
                                     java.lang.String type,
                                     int id)
                              throws cMsgException

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)

Throws:

cMsgException - if subdomain handler is shutdown

handleServerUnsubscribeRequest

public void handleServerUnsubscribeRequest(java.lang.String subject,
                                           java.lang.String type,
                                           java.lang.String namespace)
                                    throws cMsgException

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

Throws:

cMsgException - if subdomain handler is shutdown

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, socket properties cannot be set, or if subdomain handler is shutdown

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 allow 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, socket properties cannot be set, or if subdomain handler is shutdown

handleServerSendAndGetRequest

public void handleServerSendAndGetRequest(cMsgMessageFull message,
                                          java.lang.String namespace)
                                   throws cMsgException

Method to synchronously get a single message from a responder to a message being 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 infinite 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, socket properties cannot be set, or if subdomain handler is shutdown

handleUnSendAndGetRequest

public void handleUnSendAndGetRequest(int id)
                               throws cMsgException

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

Throws:

cMsgException - if subdomain handler is shutdown

handleSubscribeAndGetRequest

public void handleSubscribeAndGetRequest(java.lang.String subject,
                                         java.lang.String type,
                                         int id)
                                  throws cMsgException

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)

Throws:

cMsgException - if subdomain handler is shutdown

handleServerSubscribeAndGetRequest

public void handleServerSubscribeAndGetRequest(java.lang.String subject,
                                               java.lang.String type,
                                               cMsgNotifier notifier)
                                        throws cMsgException

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(String, 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

Throws:

cMsgException - if subdomain handler is shutdown

handleUnsubscribeAndGetRequest

public void handleUnsubscribeAndGetRequest(java.lang.String subject,
                                           java.lang.String type,
                                           int id)
                                    throws cMsgException

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

Throws:

cMsgException - if subdomain handler is shutdown

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, socket properties cannot be set, or if subdomain handler is shutdown

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).

AFTER THIS METHOD IS RUN, NO OTHER METHODS IN THIS OBJECT SHOULD BE RUN!!!

Specified by:

handleClientShutdown in interface cMsgSubdomainInterface

Overrides:

handleClientShutdown in class cMsgSubdomainAdapter