org.jlab.coda.cMsg.common

Interface cMsgDomainInterface

All Known Implementing Classes:

CA, cMsg, cMsgDomainAdapter, cMsgServerClient, EmuClient, File, RCMulticast, 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

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.
int	getDebug() Get client's level of debug output.
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.
cMsgShutdownHandlerInterface	getShutdownHandler() Method to get the shutdown handler of the client.
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 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 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 and a single synchronous response is received.
void	setDebug(int debug) Set client's level of debug output.
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 client(s).
void	shutdownServers(java.lang.String server, boolean includeMyServer) Method to shutdown the given server(s).
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 subdomain handler that got it.
void	unsubscribe(cMsgSubscriptionHandle handle) Method to unsubscribe a previous subscription to receive messages of a subject and type from the domain.

Method Detail

connect

void connect()
      throws cMsgException

Method to connect to a particular domain.

Throws:

cMsgException - for cMsg error.

disconnect

void disconnect()
         throws cMsgException

Method to close the connection to the domain. This method results in this object becoming functionally useless.

Throws:

cMsgException - for cMsg error.

isConnected

boolean isConnected()

Method to determine if this object is still connected to the domain 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 for further distribution.

Parameters:

message - message to send

Throws:

cMsgException - for cMsg error.

syncSend

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 subdomain handler that got it.

Parameters:

message - message to send

timeout - time in milliseconds to wait for a response

Returns:

response from subdomain handler (0 for cMsg domain/subdomain)

Throws:

cMsgException - for cMsg error.

flush

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

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 domain 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 - for cMsg error.

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 and a single synchronous response is received. 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 server

timeout - time in milliseconds to wait for a response message, zero means wait forever.

Returns:

response message

Throws:

cMsgException - for cMsg error.

java.util.concurrent.TimeoutException - if timeout occurs

subscribe

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

unsubscribe

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

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

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 client(s).

Parameters:

client - client(s) to be shutdown

includeMe - if true, it is permissible to shutdown calling client

Throws:

cMsgException - for cMsg error.

shutdownServers

void shutdownServers(java.lang.String server,
                     boolean includeMyServer)
              throws cMsgException

Method to shutdown the given server(s).

Parameters:

server - server(s) to be shutdown

includeMyServer - if true, it is permissible to shutdown calling client's cMsg server

Throws:

cMsgException - for cMsg error.

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)
     throws cMsgException

Set the UDL of the client.

Parameters:

UDL - UDL of client

Throws:

cMsgException - for cMsg error.

getCurrentUDL

java.lang.String getCurrentUDL()

Get the UDL the client is currently connected to.

Returns:

UDL the client is currently connected to

getUDLRemainder

java.lang.String getUDLRemainder()

Get the client's UDL remainder.

Returns:

client's UDL 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

getServerHost

java.lang.String getServerHost()

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

Returns:

server's host

getServerPort

int getServerPort()

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

Returns:

server's port

getInfo

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 - input string

Returns:

output 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

setDebug

void setDebug(int debug)

Set client's level of debug output.

Parameters:

debug - client's level of debug output

getDebug

int getDebug()

Get client's level of debug output.

Returns:

client's level of debug output