com.ibm.tspaces
Class TSCmdLocalImpl

java.lang.Object
  |
  +--com.ibm.tspaces.TSCmdLocalImpl

public class TSCmdLocalImpl

extends java.lang.Object

implements java.io.Serializable, TSCmd, TSResponse

This is the Local implementation of the TSCmd interface. This implementation can be used when the client is running in the same Java Virtual Machine as the TSpaces server. When the client calls the TupleSpace constructor, it will obtain an instance of TSCmd which will be used to send commands to the Server and receive the Tuple responses. The TupleSpace instance will communicate with the server by calling TSCmd.command() (*) The communication protocol: Document the protocol here

Author:

John Thomas

See Also:

CallbackThread, Waiter, Semaphore, TSDispatch, Serialized Form

Field Summary

protected static CallbackThread	_callback The CallbackThread instance for this TSCmd implementation It is a class object because there is only one per JVM
protected int	_dispatchThreadNumber the number of dispatch threads we have spawned so far --- so we can give them a unique #
protected com.ibm.tspaces.server.TS	_galaxyTS The TupleSpace of all TupleSpaces maintained by the mother of all TupleSpace Servers.
protected java.lang.String	_password The password for this TSCmdImpl.
protected java.util.Vector	_queue A Vector is used to queue the resultTuples to the CallbackThread
protected static boolean	_shutdown if true then shutdown in progress
protected java.lang.String	_userName The username for this TSCmdImpl .

Method Summary

static void	cleanup() this method is used to close the current connections to the server.
void	close() this method is used to close the current connection to the server.
SuperTuple	command(java.lang.String cmdString_, SuperTuple argTuple_, java.lang.String tsName_, Transaction enclosingTransaction_) Issue a command to the TupleSpace galaxy tuple space and pass along a Tuple as an argument.
SuperTuple	command(java.lang.String cmdString_, SuperTuple argTuple_, java.lang.String tsName_, Transaction enclosingTransaction_, long timeout_) Issue a command to the TupleSpace galaxy tuple space and pass along a Tuple as an argument.
void	eventDeRegister(int seqNum) DeRegister for an event on the server.
void	eventRegister(int seqNum, Callback callback_, java.lang.String commandName_, java.lang.String tsName_, boolean newThread_) Register for an event on the server.
static TSCmdLocalImpl	getRef(java.lang.String user_, java.lang.String password_) static class method to obtain a reference to the singleton instance for this class.
Tuple	getResponse() Get a response to the client,
java.util.Vector	getTSpaceClients() Return the TSpace clients vector
java.security.Principal	getUserPrincipal() Return the Principal object for the authenticated userid
static void	killConnection(java.lang.String key_, java.lang.Exception ioe_) this method is used to close the current connection to the server.
boolean	sendResponse(java.lang.String status_, java.lang.Integer seqNumber_, SuperTuple retValue_) Send a response to the client, All responses should come through here! If the communication fails we disable all further communication with this port, indicate that TSIOHandler should stop and return false to the caller.
void	setup(java.lang.String userName_, java.lang.String password_) Setup the command instance

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

_shutdown

protected static boolean _shutdown

if true then shutdown in progress

_callback

protected static CallbackThread _callback

The CallbackThread instance for this TSCmd implementation It is a class object because there is only one per JVM

_dispatchThreadNumber

protected int _dispatchThreadNumber

the number of dispatch threads we have spawned so far --- so we can give them a unique #

_galaxyTS

protected com.ibm.tspaces.server.TS _galaxyTS

The TupleSpace of all TupleSpaces maintained by the mother of all TupleSpace Servers.

_userName

protected java.lang.String _userName

The username for this TSCmdImpl .

_password

protected java.lang.String _password

The password for this TSCmdImpl.

_queue

protected java.util.Vector _queue

A Vector is used to queue the resultTuples to the CallbackThread

Method Detail

getRef

public static TSCmdLocalImpl getRef(java.lang.String user_,
                                    java.lang.String password_)

static class method to obtain a reference to the singleton instance for this class. If the instance has not been created, the default constructor will be called.

Returns:

instance of TSCmdLocalImpl()

setup

public void setup(java.lang.String userName_,
                  java.lang.String password_)
           throws TupleSpaceException

Setup the command instance

Parameters:

userName_ - the user's tspaces name

password_ - the user's tspaces password

Throws:

TupleSpaceException - If there is a problem

close

public void close()

this method is used to close the current connection to the server. We don't have to do anything since there is no physical connecction to be closed.

Specified by:

close in interface TSCmd

command

public SuperTuple command(java.lang.String cmdString_,
                          SuperTuple argTuple_,
                          java.lang.String tsName_,
                          Transaction enclosingTransaction_)
                   throws TupleSpaceCommunicationException,
                          TupleSpaceClientException,
                          TupleSpaceServerException

Issue a command to the TupleSpace galaxy tuple space and pass along a Tuple as an argument. The command is a text string that is recongized by the TupleSpace. The results of the command, if any, are returned as a tuple. This just calls the following command() method with a 0 timeout value specified.

Specified by:

command in interface TSCmd

Parameters:

server_ - the server to send the command to

port_ - the port for that server

userName_ - the Username to associate with this connection.

password_ - the password for the above user.

cmdString_ - The String that names the command.

argTuple_ - The argument Tuple, can be null.

tsName_ - The tuple space the command is acting on

enclosingTransaction_ - Transaction object that issued this command enclosingTransaction_ == null ---> standAlone transaction '' <> null ---> part of enclosingTransaction_

Returns:

A result Tuple, the format of which depends upon the command.

Throws:

TupleSpaceCommunicationException - There are problems connecting to the TupleSpace Server

TupleSpaceServerException - There was a problem executing the command on the server.

TupleSpaceClientException - There were problems preparing the command to be sent to the server.

See Also:

Waiter, CallbackThread

command

public SuperTuple command(java.lang.String cmdString_,
                          SuperTuple argTuple_,
                          java.lang.String tsName_,
                          Transaction enclosingTransaction_,
                          long timeout_)
                   throws TupleSpaceCommunicationException,
                          TupleSpaceClientException,
                          TupleSpaceServerException

Issue a command to the TupleSpace galaxy tuple space and pass along a Tuple as an argument. The command is a text string that is recongized by the TupleSpace. The results of the command, if any, are returned as a tuple. A time value (in ms) can be specified if the command should be aborted after the specified time. This thread of control will handle sending this command request to the server, but another thread a CallbackThread will be getting the response from the server for this request. The Waiter class allows us and the Callback thread to in some sense synchronize. The Waiter has 2 key methods that look like this:

   waitFor(timeout) {  
     mySemaphore.decr(timeout);
   }
 
   call(SuperTuple retValue, some other irrelevent junk) {
   myTuple = retValue;  
   mySemaphore.incr();
   }
 

So the command method will send the command and then call "waitFor() which blocks. When the command is complete, the callbackThread will get the response and call waiter.call(retValue) which will unblock this code. This code will then get the returned Tuple from the Waiter instance and return it to the caller. in case it isn't obvious, the methods in Waiter had better *not* be synchronized since the waitFor would then block with the lock held and call would block waiting on the lock.

Specified by:

command in interface TSCmd

Parameters:

server_ - the server to send the command to

port_ - the port for that server

userName_ - the Username to associate with this connection.

password_ - the password for the above user.

cmdString_ - The String that names the command.

argTuple_ - The argument Tuple, can be null.

tsName_ - The tuple space the command is acting on

enclosingTransaction_ - Transaction object that issued this command enclosingTransaction_ == null ---> standAlone transaction '' <> null ---> part of enclosingTransaction_

timeout_ - Time (in ms) that command shuld wait for a response.

Returns:

A result SuperTuple, the format of which depends upon the command.

Throws:

TupleSpaceCommunicationException - There are problems connecting to the TupleSpace Server

TupleSpaceServerException - There was a problem executing the command on the server.

TupleSpaceClientException - There were problems preparing the command to be sent to the server.

See Also:

Waiter, CallbackThread

eventRegister

public void eventRegister(int seqNum,
                          Callback callback_,
                          java.lang.String commandName_,
                          java.lang.String tsName_,
                          boolean newThread_)

Register for an event on the server.

The eventRegister method for the TSCmd instance is called to warn it to expect an event to arrive. The client can then send the eventRegister command to the server

Specified by:

eventRegister in interface TSCmd

Parameters:

seqNum - The sequence number assigned to the event

callback_ - what class object contains the call() method that will be called when the event happens.

commandName_ - the operation "WRITE" or "DELETE" to be on the watch for!

tsName_ - the Tuple Space name

newThread_ - If true, a new thread will be started for the callback

eventDeRegister

public void eventDeRegister(int seqNum)

DeRegister for an event on the server.

The eventRegister command is then sent to the server. he TSCmd instance is called to tell it not to expect any more events to arrive.

Specified by:

eventDeRegister in interface TSCmd

Parameters:

seqNum - The sequence number assigned to the event

killConnection

public static void killConnection(java.lang.String key_,
                                  java.lang.Exception ioe_)

this method is used to close the current connection to the server. It is called by CallbackThread and talkToAServer if they get an io error on the input end of the socket connection to the server which indicates that this socket is probably bad so instead of fooling around with the socket let's just close the streams and reopen a new socket.

Parameters:

key_ - the hostname and port catted together

ioe_ - the ioexception that occured.

See Also:

run

cleanup

public static void cleanup()

this method is used to close the current connections to the server. By default, the TupleSpace sets it up so the VM runs finalizers on exit and thus, the CallbackThread and ServerConnection classes finalizers are called and cleanup is performed that way. But, if the user did not want this, they can set _closingDownByForcingFinalizers to false and then just call this method when they are done with TupleSpace. The method closes down the streams connecting the client to the server. This way the server can tell that this is a normal termination.

getResponse

public Tuple getResponse()

Get a response to the client,

Returns:

a response Tuple

sendResponse

public boolean sendResponse(java.lang.String status_,
                            java.lang.Integer seqNumber_,
                            SuperTuple retValue_)

Send a response to the client, All responses should come through here! If the communication fails we disable all further communication with this port, indicate that TSIOHandler should stop and return false to the caller.

Specified by:

sendResponse in interface TSResponse

Parameters:

status_ - was the status OK or EXCEPTION?

seqNumber_ - the unique *client* side sequence number of this command

retValue_ - the tuple going back to the client

Returns:

a boolean indicating if the response was put into the output stream and flushed without raising an exception --- we currently assume this means the send was ok

getUserPrincipal

public java.security.Principal getUserPrincipal()

Return the Principal object for the authenticated userid

Specified by:

getUserPrincipal in interface TSResponse

Returns:

Principal for the authenticated user

getTSpaceClients

public java.util.Vector getTSpaceClients()

Return the TSpace clients vector

Specified by:

getTSpaceClients in interface TSResponse

Returns:

vector having the list of Tspace Clients