uk.org.ogsadai.activity
Class Activity

java.lang.Object
  |
  +--uk.org.ogsadai.activity.Activity

Direct Known Subclasses:

AbstractDeliverFromAddressActivity, AbstractDeliverToAddressActivity, AbstractDTDeliveryActivity, AbstractFileActivity, AbstractSQLActivity, BlockAggregatorActivity, BytesToTempFileActivity, CallDataService, CSVProjectionActivity, DatabaseSchemaToXMLActivity, DataStoreActivity, DeliverFromGFTPActivity, DeliverToAttachmentActivity, DeliverToGFTPActivity, DeliverToNullActivity, DeliverToResourcePropertyActivity, DeliverToSMTPActivity, DeliverToStreamActivity, DemoCreateInstanceActivity, DemoCreateTransientInstanceActivity, DemoExternalInputActivity, DemoQueryInstanceActivity, ExampleActivity, ExtractDatabaseSchemaActivity, FrequencyDistributorActivity, GZIPCompressionActivity, GZIPDecompressionActivity, HelloWorldActivity, InputStreamActivity, MySQLExtractPhysicalSchemaActivity, NotificationActivity, ObserverActivity, OutputStreamActivity, PhysicalSchemaFileActivity, RandomSampleActivity, RemoveDuplicatesWebRowSetActivity, RemoveResourceActivity, ResultActivity, ResultsetProjectionActivity, SQLQueryMultipleActivity, SQLResultsToCSVActivity, SQLResultsToXMLActivity, SQLResultToBytesActivity, SQLServerExtractPhysicalSchemaActivity, StringTokenizerActivity, WebRowSetProjectionActivity, XMLDBActivity, XSLTransformActivity, ZIPArchiveActivity

public abstract class Activity

extends java.lang.Object

This is the abstract base class for all Activity implementations. It provides access to the activity inputs and outputs, configuration, context and session. It also defines a number of methods for setting the status of activity processing.

A concrete activity implementation must define a constructor and implement the processBlock method, and may override the initialise, processFirst and cleanUp methods.

Author:

The OGSA-DAI Project Team

COPYRIGHT_NOTICE

private static final java.lang.String COPYRIGHT_NOTICE

Copyright statement.

See Also:

Constant Field Values

LOG

private static final DAILogger LOG

Logger object for logging in this class.

mName

private final java.lang.String mName

The name of the activity.

mActivityName

private java.lang.String mActivityName

The type of the activity.

mProperties

private java.util.Properties mProperties

Activity configuration properties, if applicable, otherwise null.

mConfiguration

private ActivityConfiguration mConfiguration

Activity configuration object, if applicable, otherwise null.

mInternalInputs

protected java.lang.String[] mInternalInputs

The names of the internal inputs of the activity.

mInternalOutputs

protected java.lang.String[] mInternalOutputs

The names of the internal outputs of the activity.

mExternalInputs

protected java.lang.String[] mExternalInputs

The names of the external inputs to the activity.

mExternalOutputs

protected java.lang.String[] mExternalOutputs

The names of the external outputs to the activity.

mContext

protected ActivityContext mContext

Provides access to the data pipes, user credentials, etc.

mSession

private Session mSession

Session that the activity belongs to.

mRequest

private ActivityRequest mRequest

Activity request containing the activity.

mStatus

private final ObservableStatus mStatus

Current status of the activity.

mCause

private java.lang.Throwable mCause

Cause of any error that arises during processing.

Activity

public Activity(org.w3c.dom.Element element)
         throws ActivityCreationException,
                ActivitySpecificationException

Constructs an activity using the specified element. The name of the activity will be retrieved from element's name attribute.

Parameters:

element - Element to configure the activity with - from a perform document.

Throws:

ActivityCreationException - If there is a problem constructing the activity due to an implementation error or OGSA-DAI confguration problem.

ActivitySpecificationException - If there is a problem constructing the activity due to an invalid setting in element. mistake such as an invalid setting.

Activity

public Activity(java.lang.String name)

Constructs an activity.

Parameters:

name - The String name of the activity

cleanUp

protected void cleanUp()

This method can be overridden by any Activity implementations that need to free up resources in the event of an error or intermediate termination of the activity processing.

configureContext

final void configureContext(ActivityContext context,
                            Session session)
                     throws SessionRequestException,
                            DuplicatePipeException

Configures the activity by creating pipes for each internal output, and each external input and output. After this method has been invoked the activity is ready for the initialise method to be invoked and then for processing to commence.

Parameters:

context - Context for the activity RequestContext to configure.

session - Session that the request containing the activity has been joined to.

Throws:

DuplicatePipeException - If there is a duplicate pipe declared in the activity.

SessionRequestException - If there is a problem storing the external inputs or outputs in the session.

createOutputPipe

protected Pipe createOutputPipe(int i)

Creates an output pipe for an internal output. This method can be overriden by subclasses in order to create specific types of output pipes.

Parameters:

i - Index of the output pipe.

Returns:

an output pipe of suitable type.

getInputs

final java.lang.String[] getInputs()

Gets the names of the internal activity inputs.

Returns:

a String[] containing the input names. If there are no inputs then this will be an empty array.

getOutputs

final java.lang.String[] getOutputs()

Gets the names of the internal activity outputs.

Returns:

a String[] containing the output names. If there are no outputs then this will be an empty array.

getAllOutputs

final java.lang.String[] getAllOutputs()

Gets the names of the internal and external activity outputs.

Returns:

a String[] containing output names. If there are no outputs then this will be an empty array.

getExternalInputs

final java.lang.String[] getExternalInputs()

Gets the names of the external activity inputs.

Returns:

a String[] containing the external input names. If there are no inputs then this will be an empty array.

getExternalOutputs

final java.lang.String[] getExternalOutputs()

Gets the names of the external outputs of this activity.

Returns:

a String[] containing the external output names. If there are no outputs then this will be an empty array.

getName

public final java.lang.String getName()

Gets the name of the activity. All activity's within a request have distinct names.

Returns:

a String containing the activity's name.

getStatus

public final Status getStatus()

Gets the current status of the activity.

Returns:

activity status.

getObservableStatus

protected final ObservableStatus getObservableStatus()

Gets the current status of the activity as an ObservableStatus that can be observed using Observer implementations.

Returns:

an ObservableStatus object indicating the activity's current status.

initialise

protected void initialise()
                   throws ActivitySpecificationException,
                          ActivityExecutionException

This method should be overridden by subclasses to perform any initialisation they require before the process method invocations begin. This might be used for setting up convenient fields to reference objects contained in the context. It shouldn't be used for opening resources. That should be done in processFirst.

Throws:

ActivitySpecificationException - If a problem with settings provided by a client prevents the activity from initialising.

ActivityExecutionException - If some system problem prevents the activity from initialising.

process

public final void process()

Processes the activity implementation. This method should be invoked iteratively until the activity is finished, i.e. getStatus().isFinished() returns true.

processFirst

protected void processFirst()

This method is called during the first iteration of processing an activity. It can be overridden by subclasses to define some processing that should be done only once during the first iteration of the activity processing, for example evaluating a database query.

processBlock

protected abstract void processBlock()

Performs an iteration of the processing of an activity. This may involve reading a block of input data and writing a block of output data, or may involve some other kind of processing. When an activity is processed by the OGSA-DAI engine, this method will be invoked repeatedly until the activity either completes or stops due to an error or termination call. An implementation of this method should invoke the setCompleted method to indicate that processing is complete, or the setError method if an error occurs that will prevent the processing from completing.

setCompleted

protected final void setCompleted()

An Activity implementation should call this method to indicate that the processing is complete. This sets the activity status to completed.

setError

protected final void setError(java.lang.Throwable cause)

An Activity implementation should call this method to indicate that there has been an error during processing. This sets the activity status to error and calls the cleanUp method.

Parameters:

cause - An exception describing the reason for the error.

getCause

public final java.lang.Throwable getCause()

If the activity has entered a Status.ERROR state during processing then this method can be used to retrieve the cause of the error.

Returns:

an exception describing the cause of the error or null if there were no errors.

terminate

final void terminate()

Terminates the activity processing. This sets the activity status to Status.TERMINATED and invokes the cleanUp method.

setProperties

void setProperties(java.util.Properties properties)

Sets the (optional) activity configuation properties.

Parameters:

properties - Activity configuration properties.

getProperties

protected java.util.Properties getProperties()

Accesses the activity configuration properties.

Returns:

a Properties object containing the activity properties or null if this activity does not have any properties.

hasProperties

protected boolean hasProperties()

Indicates whether or not this activity has any configuration properties. If so, they can be accessed via the getProperties method.

Returns:

true if the activity does has configuration, otherwise false.

setActivityConfiguration

void setActivityConfiguration(ActivityConfiguration configuration)

Sets the ActivityConfiguration object. This is invoked by an ActivityCreator, if an Activity makes use of an individual ActivityConfiguration object. Note that many activities do not use ActivityConfiguration objects. TODO TS move this method into ConfigurarableActivity interface

Parameters:

configuration - Activity configuration information.

hasActivityConfiguration

protected boolean hasActivityConfiguration()

Indicates whether or not this activity has an ActivityConfiguration object. If so, it can be accessed using the getActivityConfiguration method. TODO TS move this method into ConfigurarableActivity interface or remove if no longer necessary

Returns:

true if the activity does have an ActivityConfiguration object, otherwise false.

getActivityConfiguration

protected ActivityConfiguration getActivityConfiguration()

Accesses the ActivityConfiguration object, if applicable. TODO TS move this method into ConfigurarableActivity interface

Returns:

a Properties reference

See Also:

hasActivityConfiguration()

connectsTo

public boolean connectsTo(Activity activity)

Indicates whether or not the specified activity is connected to this activity.

Parameters:

activity - The activity to check for a connection

Returns:

true if the specified activity is connected to this activity, otherwise false

getSession

protected final Session getSession()

Gets the session that this activity belongs to.

Returns:

session that this activity belongs to.

Throws:

java.lang.IllegalStateException - If invoked before the activity's session has been set. An activity should wait until it's initialise method is called before attempting to access its session.

setActivityName

public final void setActivityName(java.lang.String activityName)

Sets the name of the activity type.

Parameters:

activityName - activity type name

getActivityName

public final java.lang.String getActivityName()

Returns the name of the activity type.

Returns:

activity type name