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