com.ibm.tspaces.server
Class TSServer

java.lang.Object
  |
  +--com.ibm.tspaces.server.TSServer

public class TSServer
extends java.lang.Object
implements java.lang.Runnable, com.ibm.tspaces.server.util.Logger, AclFactory.DefaultPermissions

TSServer is the main daemon process that serves requests for TupleSpace clients. TSServer listens on a port (default 8200) and, for each connection, creates a thread (TSIOHandler) to talk with each connecting client. TSIOHandler reads in the command tuple, then fires up a TSDispatch thread to actually do whatever the client requested. The TSIOHandler then gets ready for the next request from the client. TSDispatch will process the command tuple from the client. The command tuple has three fields, the first is a String with the name of the TS, the second is a String with the name of a command, and the third is a "data" Tuple, ie., the Tuple to be operated on by the command in the context of the Tuple Space. TSDispatch locates the TS and then asks it to process the command given the data tuple. The TS takes the commnad string and gives it to an instance of TSFactory that returns an instance of TSHandler, it is this instance that implements the actual command.

  +--------+             +-----------+----------+
  |        | Open Socket |           | galaxyTS |
  | Client |-------------| TS Server +----------+
  |        |             |           |
  +--------+             +-----------+
  
The Client opens a socket on a port that the TS Server is listening to. The TSServer immediately fires off a thread, running TSIOHandler, to handle the new conversation.
  +--------+             +-----------+----------+
  |        |             |           | galaxyTS |
  | Client |-------------| TS Server +----------+
  |        |             |           |
  +--------+             +-----------+
                                   |
                         +-----------------------+
                         | TS IOHandler| TSG ref |
                         +-----------------------+
 
The TS Dispatch thread is passed a pointer to the TupleSpace Galaxy, which resides in the TS Server.

The central database root is the galaxyTS. The TSG has several "built-in" databases along with the user-defined databases.

(*) The ADMIN database, tracks users, groups, permissions and passwords. The ability to create and delete TupleSpaces is controled by the ADMIN database.

(*) The GALAXY database tracks all of the TupleSpaces (TS) for this server. NOTE: TS Servers are currently autonomous entities, but eventually they will collaborate to form the TS Universe.

TSServer Operation

TSServer.main() get control from the command line entry. It parses the various command line switches and then creates an instance of TSServer. Since TSServer is a Runnable class, it then does a start to get a new thread running. It then issues a prompt to STDIN and waits for possible subcommands.

The TSpaces constructor use the information that is either passed to the construtor as parameters or is in the Configuration file to start up the pieces of the TSServer.

   Setup Checkpointing 
   Setup Debug and Log options
   Setup HTTP Server
   Setup Galaxy space
   Setup Admin Space 
   Setup FileStore   
 

When the run() method gets control, it listens on a port (default 8200) and, for each connection, creates a thread (TSIOHandler) to talk with each connecting client.

Author:
Tobin Lehman, Daniel Ford, John Thomas
See Also:
TS, TSDispatch, TSDB, TSFactory, TSIOHandler, TupleSpace, Tuple

Field Summary
static boolean _CHECK_PERMISSIONS
          should the server be in checking access permissions mode? see TS.command to see where this is used.
static boolean _DEBUG
          is debugging on the server on or off??
static boolean _DEBUG_COMMUNICATION
           
static boolean _DEBUG_SECURITY
          if _DEBUG_SECURITY is true then additional debug info relating to authorization and access permissions will be produced.
static boolean _exit
          This flag is set true when it is signalled that we want to exit.
static java.lang.String _GALAXY_DBTYPE
          what type is the galaxy? Must know for recovery as well as creating it the first time The galaxy tells us the types of the rest of the spaces.
static java.lang.String _SERVER_VERSION
          Code Version.Level.Modification Change this when a new level of code is to be released
protected  boolean _shutdown
          indicates that shutdown is in process so no new sessions should be started
protected  int connectCounter
          counts the number of connections.
static java.lang.String CREATE_ACL
          Name for Create_Acl
static java.lang.String DEFAULT_ACL
          Name for Default Acl
protected static java.lang.String DEFAULT_CONFIG_FILENAME
          Configuration object.
protected  java.lang.String hostName
          The name and IP address of the host that the server is running on.
protected static boolean HTTP_ADMIN_OK
          This flag will allow or disallow Admin and Erase freatures from the HTTP server.
protected  int httpPort
           
protected  com.ibm.tspaces.server.http.HTTPServer httpServer
           
protected static boolean HTTPServerSupport
          This flag controls whether or not a HTTP server is started.
protected  java.lang.String ipAddress
           
protected  com.ibm.tspaces.server.util.Log logFile
          The logfile for the server.
protected  int port
          The port that the server listens on for new connections from client TupleSpaces.
protected  java.lang.Runtime runTime
          Source of information about the java VM
protected  java.util.Date startTime
          The time that server started execution.
 
Fields inherited from interface com.ibm.tspaces.ac.AclFactory.DefaultPermissions
P_ADMIN, P_ALL, P_CREATE, P_READ, P_RW, P_RWC, P_WRITE
 
Constructor Summary
TSServer()
          Create a TSServer using the default parameters.
TSServer(int port_, java.lang.String checkpointDir_, boolean freshStart_, double checkpointInterval_, java.lang.String configFile)
          Create a TSServer using the specified parameters It will use the information that is either passed to the construtor as parameters or is in the Configuration file to start up the pieces of the TSServer.
 
Method Summary
 com.ibm.tspaces.server.TS admin()
          Return the admin space for this TSServer.
 java.lang.String debugHostPort()
          Return a string that combines the ip address of this host with the port on which the HTTP server is listen for conections.
 com.ibm.tspaces.server.TS galaxy()
          Return the galaxy space for this TSServer.
 TsAclDBase getAclDBase()
          TsAclDBase aclDB = null; Return the AclDB object for this TSServer.
static AuthChecker getAuthChecker()
          Return a reference to the Authentication checker object
static com.ibm.tspaces.server.util.Configuration getConfiguration()
          Return a reference to the Configuration object that contains the information read from the Config file
 java.security.acl.Acl getCreateAcl()
          Return the Create Acl for this TSServer.
 java.security.acl.Acl getDefaultAcl()
          Return the Default Acl for this TSServer.
 void getDefaultAcl(java.security.acl.Acl defaultAcl)
          Update the Default Acl for this TSServer.
 int getHandlerCount()
          Return the count of active TSIOHandler Threads.
 java.lang.String getHostName()
          Return the name of the host the server is running on.
static com.ibm.tspaces.lock.LockManager getLockMgr()
          Return a reference to the current lock manager
static TSServer getRef()
          Return a reference to the current TSServer instance If it returns null then maybe you are a client and not a server but if you are running a client in the same Java Virtual Machine as the server than you would get the refernce to the server even though you are just a lowly client.
 java.lang.String getServerHostPort()
          Return a string that combines the ip address of this host with the port on which the server is listening for conections.
static com.ibm.tspaces.server.TransactionManager getTransMgr()
          Return a reference to the current transaction manager
 int getUpdateCount()
          This returns a counter that is incremented when the ACL and/or usertable has been updated.
static java.lang.String getVersion()
          Return the version string for the server
 void incrementUpdateCount()
          The TSHAdmin SetUpdateFlag command will invoke this method as a signal that the User and/or ACL information has changed.
static boolean isShutdown()
          Return the shutdown status
 void log(java.util.Properties props)
          Deposit the stack trace of the thrown error or exception into the log.
 void log(java.lang.String string)
          Deposit the string into the log.
 void log(java.lang.Throwable t)
          Deposit the stack trace of the thrown error or exception into the log.
static void main(java.lang.String[] args_)
          The main entry point for the TSServer Program.
 void run()
          The execution entry point for this thread.
 void shutdown(int time_)
          Start the TSpaces shutdown process.
 void startRMIServer()
          Starts the RMI server and registers the remote methods to the Registry.
 java.lang.String status()
          Generate a string that contains useful status info
 java.lang.String toString()
          Enhanced toString method to give useful status info
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

_SERVER_VERSION

public static final java.lang.String _SERVER_VERSION
Code Version.Level.Modification Change this when a new level of code is to be released

_CHECK_PERMISSIONS

public static boolean _CHECK_PERMISSIONS
should the server be in checking access permissions mode? see TS.command to see where this is used.

_DEBUG

public static boolean _DEBUG
is debugging on the server on or off??

_DEBUG_COMMUNICATION

public static boolean _DEBUG_COMMUNICATION

_DEBUG_SECURITY

public static boolean _DEBUG_SECURITY
if _DEBUG_SECURITY is true then additional debug info relating to authorization and access permissions will be produced.

DEFAULT_ACL

public static final java.lang.String DEFAULT_ACL
Name for Default Acl

CREATE_ACL

public static final java.lang.String CREATE_ACL
Name for Create_Acl

_GALAXY_DBTYPE

public static final java.lang.String _GALAXY_DBTYPE
what type is the galaxy? Must know for recovery as well as creating it the first time The galaxy tells us the types of the rest of the spaces.

HTTP_ADMIN_OK

protected static boolean HTTP_ADMIN_OK
This flag will allow or disallow Admin and Erase freatures from the HTTP server. Really it needs a way to specify which users can do admin commands but that will have to wait. This flag will be set true via the -A flag on the command line. If true, it will allow Admin action via the HTTP interface

HTTPServerSupport

protected static boolean HTTPServerSupport
This flag controls whether or not a HTTP server is started.

_exit

public static boolean _exit
This flag is set true when it is signalled that we want to exit.

DEFAULT_CONFIG_FILENAME

protected static final java.lang.String DEFAULT_CONFIG_FILENAME
Configuration object. This contains all of the information that is read from the Config file that is specified at server startup.

port

protected int port
The port that the server listens on for new connections from client TupleSpaces.

logFile

protected com.ibm.tspaces.server.util.Log logFile
The logfile for the server. This is for logging errors and such, not logging transactions.

runTime

protected java.lang.Runtime runTime
Source of information about the java VM

startTime

protected java.util.Date startTime
The time that server started execution.

hostName

protected java.lang.String hostName
The name and IP address of the host that the server is running on.

ipAddress

protected java.lang.String ipAddress

httpPort

protected int httpPort

httpServer

protected com.ibm.tspaces.server.http.HTTPServer httpServer

connectCounter

protected int connectCounter
counts the number of connections.

_shutdown

protected boolean _shutdown
indicates that shutdown is in process so no new sessions should be started
Constructor Detail

TSServer

public TSServer()
         throws TupleSpaceException,
                com.ibm.tspaces.server.RollbackException,
                com.ibm.tspaces.server.CheckpointException,
                com.ibm.tspaces.lock.LMAbortedException
Create a TSServer using the default parameters.
Throws:
TupleSpaceException - if the type of database and factory for the galaxy cannot be found or accessed
com.ibm.tspaces.server.RollbackException - if there is a problem recovering previously saved state the galaxy cannot be found or accessed
com.ibm.tspaces.server.CheckpointException - if there is a problem creating the CheckpointManager

TSServer

public TSServer(int port_,
                java.lang.String checkpointDir_,
                boolean freshStart_,
                double checkpointInterval_,
                java.lang.String configFile)
         throws TupleSpaceException,
                com.ibm.tspaces.server.RollbackException,
                com.ibm.tspaces.server.CheckpointException,
                com.ibm.tspaces.lock.LMAbortedException
Create a TSServer using the specified parameters It will use the information that is either passed to the construtor as parameters or is in the Configuration file to start up the pieces of the TSServer. Setup Checkpointing Setup Log file Setup HTTP Server Setup Galaxy space Setup Admin Space Setup FileStore
Parameters:
port_ - The port that the TSServer will listen on.
checkpointDir_ - the directory to be used for checkpointing
freshStart_ - set true if the server should ignore any checkpoint on disk?
checkpointInterval_ - how often to dump the databases to disk.
configFile - is the file name for the configuration file.
Throws:
TupleSpaceException - if the type of database and factory for the galaxy cannot be found or accessed
com.ibm.tspaces.server.CheckpointException - if there is a problem creating the CheckpointManager
com.ibm.tspaces.server.RollbackException - if there is a problem recovering previously saved state
com.ibm.tspaces.lock.LMAbortedException - if the Lock Manager has severe problems.
Method Detail

getVersion

public static java.lang.String getVersion()
Return the version string for the server
Returns:
the version string for the server

getConfiguration

public static com.ibm.tspaces.server.util.Configuration getConfiguration()
Return a reference to the Configuration object that contains the information read from the Config file
Returns:
the Configuration object

getRef

public static TSServer getRef()
Return a reference to the current TSServer instance If it returns null then maybe you are a client and not a server but if you are running a client in the same Java Virtual Machine as the server than you would get the refernce to the server even though you are just a lowly client. So be careful.
Returns:
the TSServer object

getLockMgr

public static com.ibm.tspaces.lock.LockManager getLockMgr()
Return a reference to the current lock manager
Returns:
the lockmanager object

getTransMgr

public static com.ibm.tspaces.server.TransactionManager getTransMgr()
Return a reference to the current transaction manager
Returns:
the transaction manager object

getAuthChecker

public static AuthChecker getAuthChecker()
Return a reference to the Authentication checker object
Returns:
the AuthCheck object

startRMIServer

public void startRMIServer()
                    throws java.rmi.RemoteException
Starts the RMI server and registers the remote methods to the Registry.
Throws:
java.rmi.RemoteException - if there is a problem in binding the remote server .

getUpdateCount

public int getUpdateCount()
This returns a counter that is incremented when the ACL and/or usertable has been updated. These methods do not need to be synchronized because the timing of the updates is not critical.

incrementUpdateCount

public void incrementUpdateCount()
                          throws com.ibm.tspaces.lock.LMAbortedException
The TSHAdmin SetUpdateFlag command will invoke this method as a signal that the User and/or ACL information has changed. Increments the Update counter. It also updates the in memory copy of the AclDBase and UserTable.

galaxy

public com.ibm.tspaces.server.TS galaxy()
Return the galaxy space for this TSServer. Used by TSHGalaxy to create new TupleSpaces, delete them and check on their status. Might be used in the future for other ops. Should probably change this to a protected method PW
Returns:
the galaxy TS

admin

public com.ibm.tspaces.server.TS admin()
Return the admin space for this TSServer. Used by TS instances to do access control checking and by the TS creation method in TS to set the initial permissions for a space. Should probably change this to a protected method PW
Returns:
the admin TS

getDefaultAcl

public java.security.acl.Acl getDefaultAcl()
Return the Default Acl for this TSServer. Used by TS instances to do access control checking and by the TS creation method in TS to set the initial permissions for a space.
Returns:
the defaault ACL

getDefaultAcl

public void getDefaultAcl(java.security.acl.Acl defaultAcl)
Update the Default Acl for this TSServer. Used by TS instances to do access control checking and by the TS creation method in TS to set the initial permissions for a space.
Parameters:
defaault - ACL

getCreateAcl

public java.security.acl.Acl getCreateAcl()
Return the Create Acl for this TSServer. Used by TS instances to do access control checking for permission to do TSCreate
Returns:
the _createACL

getAclDBase

public TsAclDBase getAclDBase()
TsAclDBase aclDB = null; Return the AclDB object for this TSServer. Used by TS instances to do access control checking and by the TS creation method in TS to set the initial permissions for a space.
Returns:
the AclDBase object

getServerHostPort

public java.lang.String getServerHostPort()
Return a string that combines the ip address of this host with the port on which the server is listening for conections.
Returns:
a string that combines the ip address of this host with the port on which the server is listen for conections.

debugHostPort

public java.lang.String debugHostPort()
Return a string that combines the ip address of this host with the port on which the HTTP server is listen for conections.
Returns:
a string that combines the ip address of this host with the port on which the HTTP server is listen for conections.

getHostName

public java.lang.String getHostName()
Return the name of the host the server is running on.
Returns:
the name of the host the server is running on.

getHandlerCount

public int getHandlerCount()
Return the count of active TSIOHandler Threads.
Returns:
the count of active TSIOHandler Threads.

run

public void run()
The execution entry point for this thread.
 It will do the following:
   - Setup a ServerSocket instance on the specified port
   - Startup a checkpointManager thread
   - Startup the HTTP server 
   - Sit in a loop 
       - get incomming client socket
       - start TSIOHandler thread
 
Specified by:
run in interface java.lang.Runnable

shutdown

public void shutdown(int time_)
Start the TSpaces shutdown process. It will do the following. Start up a thread to do the shutdown in so that the triggering transaction can terminate cleanly. The following steps will all be done in the new thread.

Inform the TSIOHandlers that a shutdown is in process

wait for period of time for application shutdown

Inform the TSIOHandler to shutdown. This is a signal that the IOHandler should abort any remaining transactions.

wait for period of time for application abort operations

invoke the checkpoint.shutdown(). This will take a checkpoint and terminate wait for period of time for application shutdown

TSServer will wait for the CheckpointManager to terminate and then System.exit exit

Parameters:
time - The time in seconds to allow for shutdown

isShutdown

public static boolean isShutdown()
Return the shutdown status
Returns:
true if the Server has completed the shutdown process

log

public void log(java.lang.String string)
Deposit the string into the log.
Parameters:
string - the string.

log

public void log(java.lang.Throwable t)
Deposit the stack trace of the thrown error or exception into the log.
Parameters:
t - the Exception or Error to be logged.

log

public void log(java.util.Properties props)
Deposit the stack trace of the thrown error or exception into the log.
Parameters:
t - the Exception or Error to be logged.

status

public java.lang.String status()
Generate a string that contains useful status info
Returns:
string that represents the status of the TSServer

toString

public java.lang.String toString()
Enhanced toString method to give useful status info
Overrides:
toString in class java.lang.Object
Returns:
string that represents the status of the TSServer

main

public static void main(java.lang.String[] args_)
The main entry point for the TSServer Program. The TSServer program create a server that starts a frame and then listens for new client connections. For each client connection, it spawns off a new TSDispatch that then takes the client's requests to manage tuples.
 Usage: com.ibm.tspaces.server [options]

  Options:
    [-a password]           Specify sysadmin password
    [-b]                        boot TSpaces from scratch
    [-B]                        boot TSpaces and userinfo from scratch
    [-c configurationFilename]  Configuration filepath
    [-d writabledirectory]      specify a checkpoint directory
    [-p port#]                  specify a port number
    [-i double]                 specify a checkpoint interval
    [-D]                        Turn on Debug output
    [-Dmax]                    Turn on Maximum Debug support
    [-S]                        Enable the HTTP Server interface
    [-A]                        Enable Administrative HTTP functions
                                   -A implies -S 
    [-noPrompt]                 disable prompt for subcommands

  Note that the spaces after flags are required. );
 
Parameters:
args_ - Arguments from the command line. See above