uk.ac.rdg.resc.jstyx.gridservice.client
Class SGSInstanceClient

java.lang.Object
  uk.ac.rdg.resc.jstyx.client.CStyxFileChangeAdapter
      uk.ac.rdg.resc.jstyx.gridservice.client.SGSInstanceClient

All Implemented Interfaces:

CStyxFileChangeListener

public class SGSInstanceClient
extends CStyxFileChangeAdapter

A client for a Styx Grid Service Instance. The client interacts with the SGS instance and fires events when data arrives or the service data change.

Author:

Jon Blower $Revision: 609 $ $Date: 2006-03-31 18:09:42 +0100 (Fri, 31 Mar 2006) $ $Log$ Revision 1.54 2006/02/22 08:52:57 jonblower Added debug code and support for setting service lifetime Revision 1.53 2006/02/20 17:35:01 jonblower Implemented correct handling of output files/streams (not fully tested yet) Revision 1.52 2006/02/20 08:37:32 jonblower Still working towards handling output data properly in SGSInstanceClient Revision 1.51 2006/02/17 17:34:43 jonblower Implemented (but didn't test) proper handling of output files Revision 1.50 2006/02/17 09:26:59 jonblower Changes to comments Revision 1.49 2006/01/06 10:15:36 jonblower Implemented uploadInputFilesAsync() Revision 1.48 2006/01/05 16:06:34 jonblower SGS clients now deal with possibility that client could be created on a different server Revision 1.47 2005/12/20 09:50:54 jonblower Continuing to implement reading of output streams Revision 1.46 2005/12/19 17:21:01 jonblower Preparing for including automatic download of output files in this class Revision 1.45 2005/12/13 09:04:21 jonblower Implemented correct handling of stdin Revision 1.44 2005/12/09 18:41:56 jonblower Continuing to simplify client interface to SGS instances Revision 1.43 2005/12/07 17:51:32 jonblower Changed "commandline" file to "args" Revision 1.42 2005/12/07 08:56:32 jonblower Refactoring SGS client code Revision 1.41 2005/12/01 17:17:07 jonblower Simplifying client interface to SGS instances Revision 1.39 2005/11/11 21:57:21 jonblower Implemented passing of URLs to input files Revision 1.38 2005/11/10 19:49:28 jonblower Renamed SGSInstanceChangeListener to SGSInstanceClientChangeListener Revision 1.37 2005/11/09 17:43:19 jonblower Added getInputStreamsDir() and removed urls/ directory from getInputStreams() Revision 1.36 2005/11/07 21:05:35 jonblower Added setCommandLineArgs() method Revision 1.35 2005/11/04 19:28:20 jonblower Changed structure of input files in config file and Styx namespace Revision 1.34 2005/11/02 09:01:54 jonblower Continuing to implement JSAP-based parameter parsing Revision 1.33 2005/10/18 14:08:14 jonblower Removed inputfiles from namespace Revision 1.32 2005/10/14 18:09:40 jonblower Changed getInputMethods() to getInputStreams() and added synchronous and async versions Revision 1.31 2005/09/19 07:41:43 jonblower Added a close() method Revision 1.30 2005/09/11 19:28:58 jonblower Added getSteeringFiles() and getOutputStream() Revision 1.29 2005/08/12 08:08:39 jonblower Developments to support web interface Revision 1.28 2005/08/04 16:49:17 jonblower Added and edited upload() methods in CStyxFile Revision 1.27 2005/08/02 08:05:08 jonblower Continuing to implement steering Revision 1.26 2005/08/01 16:38:05 jonblower Implemented simple parameter handling Revision 1.25 2005/07/29 16:55:49 jonblower Implementing reading command line asynchronously Revision 1.24 2005/06/14 07:45:16 jonblower Implemented setting of params and async notification of parameter changes Revision 1.23 2005/06/13 16:46:35 jonblower Implemented setting of parameter values via the GUI Revision 1.22 2005/06/10 07:53:12 jonblower Changed SGS namespace: removed "inurl" and subsumed functionality into "stdin" Revision 1.21 2005/06/07 16:44:45 jonblower Fixed problem with caching stream reader on client side Revision 1.20 2005/05/27 17:05:06 jonblower Changes to incorporate GeneralCachingStreamReader Revision 1.19 2005/05/26 16:52:06 jonblower Implemented detection and viewing of output streams Revision 1.18 2005/05/25 16:59:31 jonblower Added uploadInputFile() Revision 1.17 2005/05/23 16:48:23 jonblower Overhauled CStyxFile (esp. asynchronous methods) and StyxConnection (added cache of CStyxFiles) Revision 1.15 2005/05/20 07:45:27 jonblower Implemented getInputFiles() to find the input files required by the service Revision 1.14 2005/05/19 18:42:06 jonblower Implementing specification of input files required by SGS Revision 1.13 2005/05/18 17:13:51 jonblower Created SGSInstanceGUI Revision 1.12 2005/05/16 11:00:53 jonblower Changed SGS config XML file structure: separated input and output streams and changed some tag names Revision 1.11 2005/05/13 16:49:34 jonblower Coded dynamic detection and display of service data, also included streams in config file Revision 1.10 2005/05/12 16:00:28 jonblower Implementing reading of service data elements Revision 1.9 2005/05/12 14:21:03 jonblower Changed dataSent() method to dataWritten() (more accurate name) Revision 1.8 2005/05/12 08:00:53 jonblower Added getChildrenAsync() to CStyxFile and childrenFound() to CStyxFileChangeListener Revision 1.7 2005/05/12 07:40:54 jonblower CStyxFile.close() no longer throws a StyxException Revision 1.3 2005/03/18 16:45:14 jonblower Released ByteBuffers after use Revision 1.2 2005/03/18 13:55:59 jonblower Improved freeing of ByteBuffers, and bug fixes Revision 1.1 2005/03/16 22:16:44 jonblower Added Styx Grid Service classes to core module Revision 1.4 2005/03/16 17:59:35 jonblower Changed following changes to core JStyx library (replacement of java.nio.ByteBuffers with MINA's ByteBuffers) Revision 1.2 2005/02/21 18:12:29 jonblower Following changes to core JStyx library Revision 1.1 2005/02/16 19:22:29 jonblower Commit adding of SGS files to CVS

Constructor Summary

SGSInstanceClient(SGSClient client, CStyxFile instanceRoot)
Creates a new SGSInstanceClient for an instance that has its root in the given CStyxFile.

SGSInstanceClient(java.lang.String instanceURL)
Gets an SGSInstanceClient, given the full URL to the root of the new instance, e.g.

Method Summary

void	addChangeListener(SGSInstanceClientChangeListener listener) Adds a listener that will be notified of changes to this SGS.
void	close() Closes the underlying StyxConnection
void	dataArrived(CStyxFile file, TreadMessage tReadMsg, org.apache.mina.common.ByteBuffer data) This is called when we have read data asynchronously using readDataAsync().
void	dataWritten(CStyxFile file, TwriteMessage tWriteMsg) Required by the CStyxFileChangeListener interface.
void	error(CStyxFile file, java.lang.String message) Required by the StyxFileChangeListener interface.
java.lang.String	getArguments() Gets the command line arguments that will be executed.
void	getArgumentsAsync() Sends a message to get the command line arguments that will be executed.
StyxConnection	getConnection() Gets the underlying connection object
java.util.Vector	getInputs()
java.lang.String	getInstanceID()
CStyxFile	getInstanceRoot()
java.lang.String	getName()
java.lang.String[]	getOutputFileNames() Gets the names of all the output files
java.lang.String	getOutputFileURL(java.lang.String filename)
java.util.Vector	getParameters()
java.lang.String[]	getServiceDataNames()
java.util.Hashtable	getServiceDataValues() Gets the values of all service data elements as a Hashtable, in which the keys are the service data element names (Strings) and the values are the service data values (also Strings).
java.lang.String[]	getSteerableParameterNames()
CachedStreamReader	getStreamReader(CStyxFile stream) Gets a CachedStreamReader that can be used to read from the given stream This is not used in the current implementation of SGS but might be in the future, perhaps to support GUI applications
void	readAllParameterValuesAsync() Sends messages to get the current value of all parameters.
void	readAllServiceDataValuesAsync() Sends messages to get the current value of all pieces of service data.
void	readAllSteerableParameterValuesAsync() Sends messages to get the current value of all steerable parameters.
void	readServiceDataValueAsync(java.lang.String sdeName) Sends a message to get the current value of the given piece of service data.
void	redirectOutput(java.lang.String outputFileName, java.io.File file) Starts reading data from the given output file and redirects the data to the given local File.
void	redirectOutput(java.lang.String outputFileName, java.io.PrintStream dest) Starts reading data from the given output file and redirects the data to the given PrintStream.
void	removeChangeListener(SGSInstanceClientChangeListener listener) Removes a SGSInstanceChangeListener.
void	setInputSource(SGSInput inputFile, java.io.File file) Sets the local file from which an input file will get its data.
void	setInputSource(SGSInput inputFile, java.lang.String filenameOrUrl) Sets the file or URL from which an input file will get its data.
void	setLifetime(double lifetimeInMinutes) Set the lifetime of this SGS instance.
void	setParameterValue(SGSParam param, java.lang.String value) Sets the value of the parameter with the given name to the given value.
void	setParameterValue(SGSParam param, java.lang.String[] vals) Sets the value of the parameter with the given name to the given value.
void	setParameterValueAsync(SGSParam param, java.lang.String value) Sets the value of the parameter with the given name to the given value.
void	setSteerableParameterValueAsync(java.lang.String name, java.lang.String value) Sets the value of the steerable parameter with the given name to the given value.
void	startService() Starts the service.
void	startServiceAsync() Sends a message to start the service.
void	stopService() Stops the service.
void	stopServiceAsync() Sends a message to stop the service.
void	uploadInputFiles() Uploads the input files to the server.
void	uploadInputFilesAsync() Uploads the input files to the server.

Methods inherited from class uk.ac.rdg.resc.jstyx.client.CStyxFileChangeAdapter

childrenFound, downloadComplete, fileCreated, fileOpen, statChanged, uploadComplete

Methods inherited from class java.lang.Object

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

Constructor Detail

SGSInstanceClient

public SGSInstanceClient(SGSClient client,
                         CStyxFile instanceRoot)
                  throws StyxException

Creates a new SGSInstanceClient for an instance that has its root in the given CStyxFile. Note that this constructor will make blocking reads to the SGS server and therefore should not be called from within a callback method.

Parameters:

client - The SGSClient to which this instance belongs

instanceRoot - The file representing the root of this instance

Throws:

StyxException - if there was an error creating the client (for example, there is no instance with the given ID or there was an error reading the directory contents from the server)

SGSInstanceClient

public SGSInstanceClient(java.lang.String instanceURL)
                  throws StyxException

Gets an SGSInstanceClient, given the full URL to the root of the new instance, e.g. styx://thehost.com:9092/mySGS/instances/1234567890abcde

Throws:

StyxException - if there was an error creating the client object

Method Detail

getInstanceRoot

public CStyxFile getInstanceRoot()

Returns:

the CStyxFile at the root of this instance

getName

public java.lang.String getName()

Returns:

the name of this Styx Grid Service (note: not the name of this particular instance)

startServiceAsync

public void startServiceAsync()

Sends a message to start the service. When the confirmation arrives that the service has been started, the serviceStarted() event will be fired on all registered change listeners

startService

public void startService()
                  throws StyxException

Starts the service. Blocks until the service is started.

Throws:

StyxException - if the service could not be started

getConnection

public StyxConnection getConnection()

Gets the underlying connection object

stopServiceAsync

public void stopServiceAsync()

Sends a message to stop the service. When the confirmation arrives that the service has been stopped, the serviceAborted() event will be fired

stopService

public void stopService()
                 throws StyxException

Stops the service. Blocks until the service is stopped.

Throws:

StyxException - if the service could not be stopped

getServiceDataNames

public java.lang.String[] getServiceDataNames()

Returns:

Array of Strings, one for each element of service data that can be read.

getParameters

public java.util.Vector getParameters()

Returns:

Vector of SGSParam objects, one for each input parameter that can be set.

getSteerableParameterNames

public java.lang.String[] getSteerableParameterNames()

Returns:

Array of Strings, one for each steerable parameter that can be set

getInputs

public java.util.Vector getInputs()

Returns:

Vector of SGSInput objects, one for each input file that can be uploaded

getOutputFileNames

public java.lang.String[] getOutputFileNames()
                                      throws StyxException

Gets the names of all the output files

Returns:

Array of Strings, one for each output stream or file from which data can be read.

Throws:

StyxException

getOutputFileURL

public java.lang.String getOutputFileURL(java.lang.String filename)

Returns:

the full URL to the output file with the given name

Throws:

java.lang.IllegalArgumentException - if there is no file with the given name

getArgumentsAsync

public void getArgumentsAsync()

Sends a message to get the command line arguments that will be executed. Note that clients only need to call this once: the gotArguments() event on all registered change listeners will be called automatically whenever the command line changes.

getArguments

public java.lang.String getArguments()
                              throws StyxException

Gets the command line arguments that will be executed. This method blocks until the data are returned.

Returns:

the command line arguments that will be executed.

Throws:

StyxException - if there was an error getting the contents

setLifetime

public void setLifetime(double lifetimeInMinutes)
                 throws StyxException

Set the lifetime of this SGS instance. This method will block until the lifetime is set. This method reads the creation time from the server, adds the requested number of minutes, then sets the termination time.

Parameters:

lifetimeInMinutes - the lifetime of this instance in minutes. The instance will automatically be destroyed at this time after the instance was created.

Throws:

StyxException - if the lifetime could not be set

readServiceDataValueAsync

public void readServiceDataValueAsync(java.lang.String sdeName)

Sends a message to get the current value of the given piece of service data. When the service data value is returned, the gotServiceDataValue() event will be fired on all registered change listeners. Apart from the case of exitCode, as soon as the server replies with the new service data value, a message will be sent to read the value again immediately and automatically. Therefore you only need to call this method once for each element of service data. In the case of exitCode there is no need to read the value more than once because the server will only reply when the remote service has stopped running: the exit code will never change after this reply.

Parameters:

sdeName - the name of the service data element to read

Throws:

java.lang.IllegalArgumentException - if there is no element of service data with the given name

readAllServiceDataValuesAsync

public void readAllServiceDataValuesAsync()

Sends messages to get the current value of all pieces of service data. When the service data value is returned, the gotServiceDataValue() event will be fired on all registered change listeners. Apart from the case of exitCode, as soon as the server replies with the new service data value, a message will be sent to read the value again immediately and automatically. Therefore you only need to call this method once for each element of service data. In the case of exitCode there is no need to read the value more than once because the server will only reply when the remote service has stopped running: the exit code will never change after this reply.

readAllParameterValuesAsync

public void readAllParameterValuesAsync()

Sends messages to get the current value of all parameters. When the parameter value is returned, the gotParameterValue() event will be fired on all registered change listeners. You only need to call this method once: every time the parameter value changes, the gotParameterValue() method will be fired.

readAllSteerableParameterValuesAsync

public void readAllSteerableParameterValuesAsync()

Sends messages to get the current value of all steerable parameters. When the parameter value is returned, the gotSteerableParameterValue() event will be fired on all registered change listeners.

setInputSource

public void setInputSource(SGSInput inputFile,
                           java.lang.String filenameOrUrl)
                    throws java.io.FileNotFoundException

Sets the file or URL from which an input file will get its data. Note that many filenames or URLs can be associated with a single SGSInput object: this method adds, not replaces, a new one.

Parameters:

inputFile - SGSInput object representing the input file, as read using getInputs()

filenameOrUrl - If this String starts with the string "readfrom:", this will be interpreted as a URL from which the server will read the input file. If not, this will be interpreted as the name of a local file.

Throws:

java.lang.IllegalStateException - if there is an attempt to set more than one file or URL for a fixed input file or the standard input

java.io.FileNotFoundException - if filenameOrUrl represents the name of a file that does not exist.

setInputSource

public void setInputSource(SGSInput inputFile,
                           java.io.File file)
                    throws java.io.FileNotFoundException

Sets the local file from which an input file will get its data. Note that many filenames or URLs can be associated with a single SGSInput object: this method adds, not replaces, a new one.

Parameters:

inputFile - SGSInput object representing the input file, as read using getInputs()

file - The file from which this input file will get its data

Throws:

java.io.FileNotFoundException - if file does not exist

java.lang.IllegalStateException - if there is an attempt to set more than one file or URL for a fixed input file or the standard input

redirectOutput

public void redirectOutput(java.lang.String outputFileName,
                           java.io.PrintStream dest)

Starts reading data from the given output file and redirects the data to the given PrintStream. The same output cannot be redirected to multiple destinations (currently) so calling this method multiple times on the same output file name will have no effect.

Parameters:

outputFileName - Name of the output file (as returned by getOutputFileNames())

dest - The PrintStream (e.g. System.out) to which the data will be written.

Throws:

java.lang.IllegalArgumentException - if there is no output file with the given name

redirectOutput

public void redirectOutput(java.lang.String outputFileName,
                           java.io.File file)
                    throws java.io.FileNotFoundException

Starts reading data from the given output file and redirects the data to the given local File. The same output cannot be redirected to multiple destinations (currently) so calling this method multiple times on the same output file name will have no effect.

Parameters:

outputFileName - Name of the output file (as returned by getOutputFileNames())

file - the local file to which the data will be written.

Throws:

java.io.FileNotFoundException - if the local target file could not be created.

java.lang.IllegalArgumentException - if there is no output file with the given name

setParameterValue

public void setParameterValue(SGSParam param,
                              java.lang.String value)
                       throws java.io.FileNotFoundException,
                              StyxException

Sets the value of the parameter with the given name to the given value. This method blocks until the server responds with confirmation that the write is successful - this is not expected to take long.

Parameters:

param - The SGSParam object representing this parameter (as returned by this.getParameters()

value - The value of this parameter.

Throws:

java.io.FileNotFoundException - if the parameter represents an input file and the value represents a file that does not exist

StyxException - if there was an error writing to the parameter file, or if the new value was invalid

setParameterValue

public void setParameterValue(SGSParam param,
                              java.lang.String[] vals)
                       throws java.io.FileNotFoundException,
                              StyxException

Sets the value of the parameter with the given name to the given value. The input array is turned into a space-delimited String before being written to the server. This method blocks until the server responds with confirmation that the write is successful - this is not expected to take long.

Parameters:

param - The SGSParam object representing this parameter (as returned by this.getParameters()

vals - String array representing all the values for this parameter

Throws:

java.io.FileNotFoundException - if the parameter represents an input file and the value represents a file that does not exist

StyxException - if there was an error writing to the parameter file, or if the new value was invalid

setParameterValueAsync

public void setParameterValueAsync(SGSParam param,
                                   java.lang.String value)
                            throws java.io.FileNotFoundException

Sets the value of the parameter with the given name to the given value. This method returns immediately. In order to receive confirmation that the write has been successful, you must previously have called readAllParameterValuesAsync(): when the parameter value has been set, the gotParameterValue() method will be fired on all registered change listeners. If the write was unsuccessful, the error() event will be fired on all registered change listeners.

Throws:

java.io.FileNotFoundException - if the parameter represents an input file and the value represents a file that does not exist

setSteerableParameterValueAsync

public void setSteerableParameterValueAsync(java.lang.String name,
                                            java.lang.String value)

Sets the value of the steerable parameter with the given name to the given value. This method returns immediately. In order to receive confirmation that the write has been successful, you must previously have called readAllSteerableParameterValuesAsync(): when the parameter value has been set, the gotSteerableParameterValue() method will be fired on all registered change listeners. If the write was unsuccessful, the error() event will be fired on all registered change listeners.

Throws:

java.lang.IllegalArgumentException - if a parameter with the given name does not exist.

uploadInputFiles

public void uploadInputFiles()
                      throws StyxException

Uploads the input files to the server. This method blocks until the upload is complete.

Throws:

StyxException

uploadInputFilesAsync

public void uploadInputFilesAsync()

Uploads the input files to the server. This method returns immediately: the XXX method will be fired on all registered change listeners when each input file is uploaded.

getServiceDataValues

public java.util.Hashtable getServiceDataValues()
                                         throws StyxException

Gets the values of all service data elements as a Hashtable, in which the keys are the service data element names (Strings) and the values are the service data values (also Strings). The first time this method is called it will return immediately with the data. Subsequent calls will block until any one of the service data values change.

The procedure followed is to open each file for reading, then send a message to read each file, returning the data when it arrives. The files are not closed between calls to this function (but they might be closed through the use of other functions)

Throws:

StyxException

getInstanceID

public java.lang.String getInstanceID()

Returns:

The ID of the SGS instance to which this client is connected

getStreamReader

public CachedStreamReader getStreamReader(CStyxFile stream)

Gets a CachedStreamReader that can be used to read from the given stream This is not used in the current implementation of SGS but might be in the future, perhaps to support GUI applications

dataArrived

public void dataArrived(CStyxFile file,
                        TreadMessage tReadMsg,
                        org.apache.mina.common.ByteBuffer data)

This is called when we have read data asynchronously using readDataAsync().

Specified by:

dataArrived in interface CStyxFileChangeListener

Overrides:

dataArrived in class CStyxFileChangeAdapter

Parameters:

file - The CStyxFile containing the data

tReadMsg - The original TreadMessage that was sent (contains the offset, tag etc of the message)

data - The new data that have been read from the file

dataWritten

public void dataWritten(CStyxFile file,
                        TwriteMessage tWriteMsg)

Required by the CStyxFileChangeListener interface. Called when confirmation arrives that a message has been written to the ctl file

Specified by:

dataWritten in interface CStyxFileChangeListener

Overrides:

dataWritten in class CStyxFileChangeAdapter

Parameters:

file - The CStyxFile containing the data

tWriteMsg - The TwriteMessage that caused this event to be fired

error

public void error(CStyxFile file,
                  java.lang.String message)

Required by the StyxFileChangeListener interface. Called when an Rerror message has arrived

Specified by:

error in interface CStyxFileChangeListener

Overrides:

error in class CStyxFileChangeAdapter

Parameters:

file - the CStyxFile from which the error originated

message - the error message

close

public void close()

Closes the underlying StyxConnection

addChangeListener

public void addChangeListener(SGSInstanceClientChangeListener listener)

Adds a listener that will be notified of changes to this SGS. If the listener is already registered, this will do nothing.

removeChangeListener

public void removeChangeListener(SGSInstanceClientChangeListener listener)

Removes a SGSInstanceChangeListener. (Note that this will only remove the first instance of a given SGSInstanceChangeListener. If, for some reason, more than one copy of the same change listener has been registered, this method will only remove the first.)