The notion of an XML perform document and XML response document is no longer valid within the OGSA-DAI activity framework. This now only handles request objects and request status objects.

Keeping XML out of the OGSA-DAI activity framework simplifies the framework code and avoids problems arising from locating associated XML Schema (and accessing these locations). In addition, it allows the writing of applications that access OGSA-DAI functionality without the need to go through a web services presentation layer. It would be unreasonable and inefficient to have such applications construct an XML document only for this to be parsed again by OGSA-DAI when they could just construct the Java data structure used internally by OGSA-DAI directly and avoid XML altogether.

Perform documents have not been replaced by workflows. Perform documents are representations of workflows, they just were not termed as such. The difference is now that the workflows are represented in Java rather than in XML both client-side and server-side. The only time they are actually in an XML formt is when going from client to an OGSA-DAI web service via SOAP/HTTP.

Other changes are as follows:

As described in Section N.2.1.2, “Perform documents, requests and clients” OGSA-DAI 3.0 does not provide support for using perform documents in it's end-to-end clients or client toolkit. If you currently use perform documents you will have to implement the workflows that these represent using the client toolkit or write a client toolkit component to accept an XML representation of OGSA-DAI workflows. Either way you should respect the changes in activities betwen releases as outlined in the following tables.

Migrating workflow/request from OGSA-DAI 2.2 to OGSA-DAI 3.0 requires replacing each activity with its OGSA-DAI 3.0 equivalent. How activities correspond between these releases is shown in the following tables.

OGSA-DAI 3.0 includes the new activity, DeliverToRequestStatus. This activity writes its input to the request status. This is the only way data can be returned to the client within a SOAP response message from a data request execution service. In OGSA-DAI 2.2 any data written to an unconnected output was automatically written to the SOAP response message. In OGSA-DAI 3.0 such unconnected outputs are illegal and you have to explicitly connect them. If when migrating an application you encounter errors relating to unconnected outputs you should connect that output to a DeliverToRequestStatus activity if you wish to retrieve the data in the request status when the DRER finishes executing the workflow.

In OGSA-DAI 2.2 a request was executed synchronously if it contained one or more unconnected outputs. In OGSA-DAI 3.0 the client must explicitly specify synchronous or asynchronous execution.

If a request is executed synchronously the Execute operation will not return until the request has finished. The final request status will be returned in the SOAP response message. The request resource created for the request will be destroyed when the request is finished.

If a request is executed asynchronously the client must retrieve the final request status from the request resource that is created for the request. It is also the responsibility of the client to manager the lifetime of the request resource although by default it will expire 24 hours after creation.

OGSA-DAI 2.2 supports asynchronous data transport using the outputStream, inputStream, deliverToGDT and deliverFromGDT activities. Using these activities required the use of sessions.

In OGSA-DAI 3.0 the equivalent of asynchronous data transport is done through the use of data sinks and data sources. Clients can write data to a data sink using the data sink service. Data written to a data sink can be obtained and using within a workflow by the ReadFromDataSink activity. Similarly, clients can read data from a data source using the data source service. Data can be written to the data source from within a workflow using the WriteToDataSource activity.

Data can be passed between two OGSA-DAI servers by using the ObtainFromDataSource and DeliverToDataSink activities which, respectively, pull data from, and write data to, data sources and data sinks on remote OGSA-DAI servers.

Note that in OGSA-DAI 3.0 this type of data transport does not require use of sessions.

This section gives example of how code fragments written using the OGSA-DAI 2.2 client toolkit can be converted to code that uses the OGSA-DAI 3.0 client toolkit.

Before we start it must be stated that there is virtually is no consistency between the OGSA-DAI client toolkit classes in 2.2 and 3.0 - everything will need changed. The sections here describe some of the changes that will need to be made. The section headings are tasks described using OGSA-DAI 2.2 terminology.

In OGSA-DAI 2.2 the DataService interface was used to send perform documents to an OGSA-DAI server. The GenericServiceFetcher class was used to obtain the DataService if the client was unsure if the server was running OGSA-DAI WSI or OGSA-DAI WSRF.

The equivalent nearest equivalent of DataService in OGSA-DAI 3.0 is DataRequestExecutionResource. This is a resource proxy that provides the execute method that is the OGSA-DAI 3.0 equivalent of DataService.perform methods.

Code such as:

String handle = "http://localhost:8080/axis/services/ogsadai/DataService";
String id = "MySQLResource";
DataService service = GenericServiceFetcher.getInstance().getDataService(handle, id);

should be migrated to:

URL baseURL = new URL("http://localhost:8080/dai/services");
Server server = new ServerProxy();
server.setDefaultBaseServicesURL(baseURL);
ResourceID resourceID = new ResourceID("DataRequestExecutionResource");
DataRequestExecutionResource drer = 
    server.getDataRequestExecutionResource(resourceID)

	Note
	The Server.setDefaultBaseServicesURL method takes only the base URL that is common to all six OGSA-DAI services.

If the OGSA-DAI 2.2 code using the WSRFDataService or WSIDataService classes then these map to GTServer and AxisServer classes in OGSA-DAI 3.0. Code such as:

String handle = "http://localhost:8080/wsrf/services/ogsadai/DataService";
String id = "MySQLResource";
DataService service = new WSRFDataService(handle, id);

should be migrated to:

URL baseURL = new URL("http://localhost:8080/dai/services");
Server server = new GTServer();
server.setDefaultBaseServicesURL(baseURL);
ResourceID resourceID = new ResourceID("DataRequestExecutionResource");
DataRequestExecutionResource drer = server.getDataRequestExecutionResource(resourceID)

To obtain a list of data resources at an OGSA-DAI server in OGSA-DAI 2.2 required code like:

String handle = "http://localhost:8080/axis/services/ogsadai/DataService";
DataService service = GenericServiceFetcher.getInstance().getDataService(handle, null);
ResourceID[] resources = service.getResourceIDs();
for (int i=0; i<resources.length; i++) {
    System.out.println(resources[i].getName());
}

The equivalent of this for OGSA-DAI 3.0 is:

URL baseURL = new URL("http://localhost:8080/dai/services");
Server server = new ServerProxy();
server.setDefaultBaseServicesURL(baseURL);
ResourceID[] resources = server.listResources(ResourceType.DATA_RESOURCE);
for (int i=0; i<resources.length; i++) {
    System.out.println(resources[i].toString());
}

To build an activity request that queries a relational database, converts the results to WebRowSet format and returns the result in the response message, OGSA-DAI 2.2 code would look like:

SQLQuery query = 
  new SQLQuery("select * from littleblackbook where id='3475'");
WebRowSet rowset = new WebRowSet(query.getOutput());
ActivityRequest request = new ActivityRequest();
request.add(query);
request.add(rowset);

In OGSA-DAI 3.0 we must build a Workflow rather than an ActivityRequest. The simplest type of Workflow is a Pipeline. Here is the equivalent OGSA-DAI 3.0 code:

SQLQuery query = new SQLQuery();
query.setResourceID("MySQLResource");
query.addExpression("select * from littleblackbook where id='3475'");

TupleToWebRowSetCharArrays tupleToWebRowSet =
    new TupleToWebRowSetCharArrays();
tupleToWebRowSet.connectDataInput(query.getDataOutput());

DeliverToRequestStatus deliverToRequestStatus = 
    new DeliverToRequestStatus();
deliverToRequestStatus.connectInput(tupleToWebRowSet.getResultOutput());

PipelineWorkflow pipeline = new PipelineWorkflow();
pipeline.add(query);
pipeline.add(tupleToWebRowSet);
pipeline.add(deliverToRequestStatus);

The are several important differences between these code snippets:

To send a request to the server the OGSA-DAI 2.2 code would look like:

Response response = service.perform(request);

The OGSA-DAI 3.0 equivalent is:

RequestResource requestResource = 
  drer.execute(pipeline, RequestExecutionType.SYNCHRONOUS);

In OGSA-DAI 2.2 a perform document was executed synchronously if there was one or more unconnected outputs and asynchronously otherwise. In OGSA-DAI 3.0 requests, unconnected outputs are illegal and the client must explicitly specify synchronous or asynchronous execution.

Asynchronous execution is generally preferable to synchronous execution as it gives the client more control of the request. In particular it allows the client to terminate a request. To execute a workflow asynchronously, poll for the workflow to complete and then retrieve the final request status such that data can be read, the following code can be used:

int pollInterval = 500;     //   500ms = 0.5 seconds
int pollTimeout  = 60*1000; // 60000ms = 1 minute
RequestResource requestResource = 
  drer.execute(pipeline, RequestExecutionType.ASYNCHRONOUS);
requestResource.pollUntilRequestCompleted(
   POLL_INTERVAL, POLL_TIMEOUT);
requestResource.getRequestStatus();

The following code is an example of how to terminate a request during its execution.

RequestResource requestResource = 
  drer.execute(pipeline, RequestExecutionType.ASYNCHRONOUS);

// ... user decides the request is no longer required

// Terminate request
requestResource.destroy();

In OGSA-DAI 2.2 results can be obtained from an activity via convenience methods in the client toolkit activity implementation. For example to get a ResultSet containing the results of an SQL query the code would look like:

SQLQuery query = 
  new SQLQuery("select * from littleblackbook where id='3475'");
WebRowSet rowset = new WebRowSet( query );
ActivityRequest request = new ActivityRequest();
request.add( query );
request.add( rowset );
service.perform( request );
ResultSet rs = rowset.getResultSet();

Obtaining the results from activities is much the same in OGSA-DAI 3.0. The major difference is most activities can now return multiple results where previously they could only return one. Most activities therefore adopt an iterator pattern to access the results. The OGSA-DAI code equivalent to the above is:

SQLQuery query = new SQLQuery();
query.setResourceID("MySQLResource");
query.addExpression("select * from littleblackbook where id='3475'");

TupleToWebRowSetCharArrays tupleToWebRowSet =
    new TupleToWebRowSetCharArrays();
tupleToWebRowSet.connectDataInput(query.getDataOutput());

DeliverToRequestStatus deliverToRequestStatus = 
    new DeliverToRequestStatus();
deliverToRequestStatus.connectInput(tupleToWebRowSet.getResultOutput());

PipelineWorkflow pipeline = new PipelineWorkflow();
pipeline.add(query);
pipeline.add(tupleToWebRowSet);
pipeline.add(deliverToRequestStatus);

RequestResource requestResource = 
  drer.execute(pipeline, RequestExecutionType.SYNCHRONOUS);

ResultSet rs = tupleToWebRowSet.nextResultAsResultSet();

In OGSA-DAI 2.2 to process a sequence of SQL queries required the use of multiple SQLQuery activities. The code would look like:

 
SQLQuery query1  = 
  new SQLQuery("select * from littleblackbook where name like '%Krause'");
WebRowSet rowset1 = new WebRowSet( query1.getOutput() );
SQLQuery query2  = 
  new SQLQuery("select * from littleblackbook where name like '%Sugden'");
WebRowSet rowset2 = new WebRowSet( query2.getOutput() );
Request request = new ActivityRequest( 
    new RequestComponent[] { query1, rowset1, query2, rowset2 });
Response response = service.perform( request );

ResultSet rs1 = rowset1.getResultSet();
// code to use the result set goes here

ResultSet rs2 = rowset2.getResultSet();
// code to use the result set goes here

In OGSA-DAI 3.0 activities can generally produced multiple results. A single SQLQuery activity can now process a sequence of queries. The OGSA-DAI 3.0 equivalent of the above code is:

 
SQLQuery query = new SQLQuery();
query.setResourceID("MySQLResource");
query.addExpression("select * from littleblackbook where name like '%Krause'");
query.addExpression("select * from littleblackbook where name like '%Sugden'");

TupleToWebRowSetCharArrays tupleToWebRowSet =
    new TupleToWebRowSetCharArrays();
tupleToWebRowSet.connectDataInput(query.getDataOutput());

DeliverToRequestStatus deliverToRequestStatus = 
    new DeliverToRequestStatus();
deliverToRequestStatus.connectInput(tupleToWebRowSet.getResultOutput());

PipelineWorkflow pipeline = new PipelineWorkflow();
pipeline.add(query);
pipeline.add(tupleToWebRowSet);
pipeline.add(deliverToRequestStatus);

RequestResource requestResource = 
  drer.execute(pipeline, RequestExecutionType.SYNCHRONOUS);

while( tupleToWebRowSet.hasNextResult()) {
  ResultSet rs = tupleToWebRowSet.nextResultAsResultSet();
  
  // code to use the result set goes here
}

There are subtle differences between these two implementations. In the OGSA-DAI 2.2 version the two SQLQueries will be executed in parallel while in the OGSA-DAI 3.0 version they are executed in sequence. The OGSA-DAI 3.0 implementation of the client toolkit is based very much upon a streaming model. One side effect of this is that it is not possible to read from the two result sets at once.

In OGSA-DAI 2.2 it was possible to specify that groups of activities should be executed in parallel or sequentially using Flow and Sequence classes. For example, the following code creates the new table, loads data into this table and finally queries this new table in sequence.

 
SQLUpdate create = new SQLUpdate("create table mytable (id integer, number integer)");
SQLQuery query1  = 
   new SQLQuery("select id, phone from littleblackbook where name like '%Krause'");
WebRowSet rowset1 = new WebRowSet(query1.getOutput());
SQLBulkLoad bulkload = new SQLBulkLoad( rowset1.getOutput(), "mytable" );
SQLQuery query2 = new SQLQuery("select count(*) from mytable");
WebRowSet rowset2 = new WebRowSet(query2.getOutput());
Sequence sequence = new Sequence();
sequence.addChild(create);
sequence.addChild(query1);
sequence.addChild(rowset1);
sequence.addChild(bulkload);
sequence.addChild(query2);
sequence.addChild(rowset2);
service.perform(sequence);

In OGSA-DAI 3.0 these Flow and Sequence classes are replaced by ParallelWorkflow and SequenceWorkflow. The OGSA-DAI 3.0 equivalent of the above code is:

 
// Build 1st pipeline to create new table called 'mytable'
SQLUpdate sqlUpdate = 
    new SQLUpdate("create table mytable (id integer, number integer)");

DeliverToRequestStatus deliverToRequestStatus1 = 
    new DeliverToRequestStatus();
deliverToRequestStatus1.connectInput(sqlUpdate.getResultOutput());

PipelineWorkflow pipeline1 = new PipelineWorkflow();
pipeline1.add(sqlUpdate);
pipeline1.add(deliverToRequestStatus1);

// Build 2nd pipeline to query littleblack book and write to 'mytable'
SQLQuery query1 = new SQLQuery();
query1.setResourceID("MySQLResource");
query1.addExpression("select id, phone from littleblackbook where name like '%Krause'");

SQLBulkLoadTuples bulkload = new SQLBulkLoadTuples();
bulkload.addTableName("mytable");
bulkload.connectDataInput(query1.getDataOutput());

DeliverToRequestStatus deliverToRequestStatus2 = 
    new DeliverToRequestStatus();
deliverToRequestStatus2.connectInput(bulkload.getResultOutput());

PipelineWorkflow pipeline2 = new PipelineWorkflow();
pipeline2.add(query1);
pipeline2.add(bulkload);
pipeline2.add(deliverToRequestStatus2);

// Build third pipeline to query mytable
SQLQuery query2 = new SQLQuery();
query2.setResourceID("MySQLResource");
query2.addExpression("select count(*) from mytable");

TupleToWebRowSetCharArrays tupleToWebRowSet =
    new TupleToWebRowSetCharArrays();
tupleToWebRowSet.connectDataInput(query2.getDataOutput());

DeliverToRequestStatus deliverToRequestStatus3 = 
    new DeliverToRequestStatus();
deliverToRequestStatus3.connectInput(tupleToWebRowSet.getResultOutput());

PipelineWorkflow pipeline3 = new PipelineWorkflow();
pipeline3.add(query2);
pipeline3.add(tupleToWebRowSet);
pipeline3.add(deliverToRequestStatus);

// Put all pipelines in a sequence
SequenceWorkflow sequence = new SequenceWorkflow();
sequence.addChild(pipeline1);
sequence.addChild(pipeline2);
sequence.addChild(pipeline3);

// Execute the workflow
RequestResource requestResource = 
  drer.execute(sequence, RequestExecutionType.SYNCHRONOUS);

In OGSA-DAI 2.2 the following code could be used transfer data between two data service resources on two different OGSA-DAI servers. In this example the data is pulled rather than pushed.

 
// Create two client DataService objects for the source 
// and sink data services.
DataService sourceService =
    GenericServiceFetcher.getInstance().getDataService(
      sourceHandle, sourceResourceID);
DataService sinkService =
    GenericServiceFetcher.getInstance().getDataService(
      sinkHandle, sinkResourceID);

// Assemble the activity request for the source data service. 
// Session requirements must be specified to ensure that a new 
// session is created.

SQLQuery sqlQuery =
    new SQLQuery("select * from littleblackbook where id<3000");
WebRowSet rowset = new WebRowSet(sqlQuery.getOutput());
DTOutputStream outputStream = new DTOutputStream();
outputStream.setInput(rowset.getOutput());
ActivityRequest sourceRequest = new ActivityRequest();
sourceRequest.add(sqlQuery);
sourceRequest.add(rowset);
sourceRequest.add(outputStream);
sourceRequest.setSessionRequirements(new JoinNewSession());

// Perform the request at the source data service resource
// and retrieve details of the session that the request has 
// been joined to.

Response response = sourceService.perform(sourceRequest);
Session session = response.getSession();

// At this stage the session stream has been created at the 
// source data service resource. Next a request must be assembled 
// to instruct the sink data service resource to read the result 
// data from the session stream.

DeliverFromDT deliverFromDT = new DeliverFromDT();
deliverFromDT.setDataTransportInput(outputStream.getDataTransport());
deliverFromDT.setDataTransportMode(DataTransportMode.BLOCK);
ActivityRequest sinkRequest = new ActivityRequest();
sinkRequest.add(deliverFromDT);

// We can now send the request to the sink data service resource 
// and display the response, which should contain the transported data.

response = sinkService.perform(sinkRequest);
System.out.println(response.getAsString());

// Finally, terminate the session that was created at the source 
// data service resource.

sourceRequest = new ActivityRequest();
sourceRequest.setSessionRequirements(new TerminateSession(session));
sourceService.perform(sourceRequest);

The equivalent code for OGSA-DAI 3.0 is:

 
// Get source and sink servers and DRERs

Server sourceServer = new ServerProxy();
sourceServer.setDefaultBaseServicesURL(sourceURL);
Server sinkServer = new ServerProxy();
sinkServer.setDefaultBaseServicesURL(sinkURL);
ResourceID resourceID = new ResourceID("DataRequestExecutionResource");
DataRequestExecutionResource sourceDRER = 
    server.getDataRequestExecutionResource(resourceID)
DataRequestExecutionResource sinkDRER = 
    server.getDataRequestExecutionResource(resourceID)

// Create a data source

DataSourceResource dataSource = sourceDRER.createDataSourceResource();
  
// Assemble workflow to write data to the data source

SQLQuery query = new SQLQuery();
query.setResourceID("MySQLResource");
query.addExpression("select * from littleblackbook where id<3000");

TupleToWebRowSetCharArrays tupleToWebRowSet =
    new TupleToWebRowSetCharArrays();
tupleToWebRowSet.connectDataInput(query.getDataOutput());

WriteToDataSource writeToDataSource = new WriteToDataSource();
writeToDataSource.setResourceID(dataSource.getResourceID());
writeToDataSource.connectInput(tupleToWebRowSet.getResultOutput());

PipelineWorkflow writeWorkflow = new PipelineWorkflow();
writeWorkflow.add(query);
writeWorkflow.add(tupleToWebRowSet);
writeWorkflow.add(writeToDataSource);

// Execute this workflow

RequestResource sourceRequestResource = 
  sourceDRER.execute(writeWorkflow, RequestExecutionType.ASYNCHRONOUS);
sourceRequestResource.pollUntilRequestStarted(POLL_INTERVAL);

// Assemble workflow to read from data source

ObtainFromDataSource obtainFromDataSource = new ObtainFromDataSource();
obtainFromDataSource.addResourceID(dataSource.getResourceID());
obtainFromDataSource.addURL(
    sourceServer.getDefaultDataSourceServiceURL());
obtainFromDataSource.addMode(ObtainFromDataSource.BLOCK);
obtainFromDataSource.addNumOfBlocks(1000);

DeliverToRequestStatus deliverToRequestStatus = 
    new DeliverToRequestStatus();
deliverToRequestStatus.connectInput(obtainFromDataSource.getDataOutput());

PipelineWorkflow readWorkflow = new PipelineWorkflow();
readWorkflow.add(obtainFromDataSource);
readWorkflow.add(deliverToRequestStatus);

// Execute this workflow

RequestResource sinkRequestResource = 
  sourceDRER.execute(readWorkflow, RequestExecutionType.SYNCHRONOUS);

// Destroy the resources
sourceRequestResource.destroy();
dataSource.destroy();

If an activity encounters an error during its execution that activity will typically stop processing and the error will propagate through the workflow. Any data produced prior to the error occurring will still be available from the request status.

Consider the example where an SQLQuery activity is executes two queries. The first query is valid but the second is not. The following code shows how to retrieve the first result set and get full details of the error associated with the second one. In this example synchronous execution is used:

 
String[] expressions =
    new String[] {
"SELECT id, name, address, phone FROM littleblackbook " + 
"where id > 2 and id < 12 order by id",
"BAD QUERY"};

// Build the activities and activity chain
SQLQuery query = new SQLQuery();
query.setResourceID("MySQLResource");

for (int i=0; i<expressions.length; ++i)
{
    query.addExpression(expressions[i]);
}

TupleToWebRowSetCharArrays tupleToWebRowSet =
    new TupleToWebRowSetCharArrays();
tupleToWebRowSet.connectDataInput(query.getDataOutput());

DeliverToRequestStatus deliverToRequestStatus = 
    new DeliverToRequestStatus();
deliverToRequestStatus.connectInput(tupleToWebRowSet.getResultOutput());

// Build the workflow
PipelineWorkflow pipeline = new PipelineWorkflow();
pipeline.add(query);
pipeline.add(tupleToWebRowSet);
pipeline.add(deliverToRequestStatus);

RequestResource requestResource;
try
{
    requestResource = 
    mDRER.execute(pipeline, RequestExecutionType.SYNCHRONOUS);
}
catch(RequestExecutionException requestExecutionException)
{
    // Catch an request execution exception and get the request
    // resource from it.
    requestResource = requestExecutionException.getRequestResource();
    
    // Display status and any error messages for the activities
    
    System.out.println("Execution status: " + 
        requestResource.getRequestExecutionStatus());

    Activity[] activities = 
        new Activity[]{query, tupleToWebRowSet,deliverToRequestStatus};
    
    for (int i=0; i<activities.length; ++i)
    {
        if (activities[i].hasErrorMessages())
        {
            System.out.println(
                "Activity " + activities[i].getInstanceName() + 
                "of type " + activities[i].getActivityName() + 
                " has errors:");
    
            Message[] errorMessages = activities[i].getErrorMessages();
    
            for (int j=0; j<errorMessages.length; ++j)
            {
                System.out.println("\t" + errorMessages[j].toString());
            } 
        }
    }
}

// Process as many result sets as possible.

try
{
    while (tupleToWebRowSet.hasNextResult())
    {
        ResultSet rs = tupleToWebRowSet.nextResultAsResultSet();
        // Process the result set
        rs.close();
    }
}
catch(DataStreamErrorException dataStreamErrorException)
{
    // An error occurred when processing the data stream
}

The most important point that needs the developer's attention, and one of the major differences of activities in the new release, is that there is no longer a requirement for XML that is activity specific. Therefore, the arbitrary XML that used to exist in order to specify inputs, outputs and parameters of activities has now been removed. The rationale behind this decision is that all data that used to come into the activity as XML are now coming directly as data to be read by the activity input. Having this in mind we can now move to some other issues before reaching the actual migration of activities.

As explained above all activities are now described by a common, unique, mininal XML Schema. This means that there no longer is a need to write an explicit XML Schema describing the XML syntax for each activity. As a concequence of this, instead of the XML validation for inputs, outputs and parameters of each activity the only concern is to set up inputs and outpus for this activity properly. The common schema that is describing all activities looks like:

<!-- Activity type -->

  <xsd:complexType name="ActivityType">
    <xsd:sequence>
      <xsd:element name="inputs" type="tns:InputsType"/>
      <xsd:element name="outputs" type="tns:OutputsType"/>
    </xsd:sequence>
    <xsd:attribute name="name" type="xsd:string" use="required"/>
    <xsd:attribute name="instanceName" type="xsd:ID" use="required"/>
    <xsd:attribute name="resource" type="xsd:string" use="optional"/>
  </xsd:complexType>

  <!-- Activity inputs type -->

  <xsd:complexType name="InputsType">
    <xsd:sequence>
      <xsd:element name="input" minOccurs="0" maxOccurs="unbounded">
        <xsd:complexType>
          <xsd:choice>
            <xsd:element name="inputStream" type="tns:InputStreamType"/>
            <xsd:element name="inputLiteral" type="tns:DataType" 
                         maxOccurs="unbounded"/>
          </xsd:choice>
          <xsd:attribute name="name" type="xsd:string" use="required"/>
        </xsd:complexType>
      </xsd:element>
    </xsd:sequence>
  </xsd:complexType>

  <!-- Activity outputs type -->

  <xsd:complexType name="OutputsType">
    <xsd:sequence>
      <xsd:element name="outputStream" type="tns:OutputStreamType"
                   minOccurs="0" maxOccurs="unbounded"/>
    </xsd:sequence>
  </xsd:complexType>

  <!-- Activity input stream type -->

  <xsd:complexType name="InputStreamType">
    <xsd:attribute name="pipe" type="xsd:ID" use="required"/>
  </xsd:complexType>
  
  <!-- Activity output stream type -->

  <xsd:complexType name="OutputStreamType">
    <xsd:attribute name="name" type="xsd:string" use="required"/>
    <xsd:attribute name="pipe" type="xsd:IDREF" use="required"/>
  </xsd:complexType>

  <!-- Data values -->

  <xsd:complexType name="ListBeginType"/>

  <xsd:complexType name="ListEndType"/>

  <xsd:complexType name="DataType">
    <xsd:choice>
      <xsd:element name="string" type="xsd:string"/>
      <xsd:element name="charArray" type="xsd:string"/>
      <xsd:element name="binary" type="xsd:base64Binary"/> 
      <xsd:element name="float" type="xsd:float"/> 
      <xsd:element name="double" type="xsd:double"/> 
      <xsd:element name="int" type="xsd:int"/> 
      <xsd:element name="long" type="xsd:long"/> 
      <xsd:element name="boolean" type="xsd:boolean"/> 
      <xsd:element name="date" type="xsd:dateTime"/> 
      <xsd:element name="listBegin" type="tns:ListBeginType"/>
      <xsd:element name="listEnd" type="tns:ListEndType"/>
    </xsd:choice>
  </xsd:complexType>

As one can see, an activity there is described by:

Before providing actual coding guidelines, let's we point out how the new activity model differs from the old one:

In 2.2 release the processing of blocks produced and consumed by activities is controlled by the pipe which is an external object to the activity. Therefore, processBlock() is called many times until the processing is completed by the activity framewor. The usual case is that one block is processed per call. Furthermore, an initialize() method preceeds the block processing and is invoked to perform any initialisation that the activity requires prior to it.

In contrast, in release 3.0 the processing of blocks is controlled by the activity itself. This means that a process() method is called only once. All actions necessary for the activity processing (initialisation, actual processing and clean up) take place in this single method. Of course, as is explained later on, useful abstract classes are provided that split the processing into different stages (initial processing, main processing, post processing and clean up) to help the developer implement an activity in a more convinient way. However, it should emphasized that all these auxiliary classes do is a fragmented manipulation of the process() method.

In addition, a consequence to the fact that the process() method is called only once, an activity can produce or consume as many blocks as necessary to maximise the streaming of the workflow of which it is a part.

Detailed guidelines on how to write an activity implementation can be found in Chapter 24, How to write an activity

The remainder of this section will go though a step-by-step migration guide. The ReadFromFileActivity is used as an example for this (previously FileAccessActivity in the 2.2 release).

public class ReadFromFileActivity extends
MatchedIterativeActivity implements ResourceActivity

/** File to be read */
public static final String INPUT_FILE = "file";

/** Offset in bytes */
public static final String INPUT_OFFSET= "offset";

/** Number of bytes to read  */
public static final String INPUT_LENGHT = "lenght";

/** Activity output name */
public static final String OUTPUT_DATA = "data";

protected ActivityInput[] getIterationInputs() 
{
    return new ActivityInput[] {
    	new TypedOptionalActivityInput(INPUT_FILE, String.class, "/"),
        new TypedOptionalActivityInput(INPUT_OFFSET, Long.class, new Long(0)),
        new TypedOptionalActivityInput(INPUT_LENGHT, Long.class, new Long(-1)),
    };
}

mOutput = mContext.getOutput(mInternalOutputs[0]);

mFile = new File(mTopDir,mFilename);
// Ensure user read access to this file
mFileAccessProvider.validateReadFile(mCredentials,mFile);

public void setTargetResourceAccessor(ResourceAccessor resourceAccessor) 
{
    mResource = (FileAccessProvider) resourceAccessor;
}

public Class getTargetResourceAccessorClass()
{
    return FileAccessProvider.class;
}

String filePath = (String) iterationData[0];
Long offset = (Long) iterationData[1];
Long lenght = (Long) iterationData[2];

output.write(block) in contrary to :
output.put(buf.toString());

if (mInput.hasNext())
{
    Object inputBlock = mInput.next();
    // do something with the object
}

If you do not wish to interact with your new activity using the client toolkit then this step can be ommitted. Otherwise a client toolkit activity implementation class is needed. This is a client side class that corresponds to the server-side activity and makes it easier for clients to build workflows that include that activity.

Detailed guidelines on how to write a client toolkit implementation can be found in Chapter 24, How to write an activity

Let's go now though a step-by-step migration guide. We are going to use ReadFromFile (ReadFromFile in 2.2) as an example.

Having established that there is no more XML handling on activities describing explicitly inputs, outputs and parameters the following should easily make sense to the activity developer:

The generateXML() method no longer exists. What we do now is create client-side representations of activity inputs and outputs. To do this we declare their names which must match the input/output names of the server-side implementation. This looks like:

/** Directory input name */
public final static String FILE_INPUT = "file";
 
/** Directory input name */
public final static String OFFSET_INPUT = "offset";
 
/** Directory input name */
public final static String LENGTH_INPUT = "length";
 
/** operation status output name */
public final static String OUTPUT_DATA = "data";

in release 3.0. Furthermore we declare corresponding member variables of ActivityInput and ActivityOutput objects that are initialised in the activity constructor:

/** File input */
private ActivityInput mFileInput;

/** Offset input */
private ActivityInput mOffsetInput;

/** Recurse directories input */
private ActivityInput mLengthInput;

/** Data output */
private ActivityOutput mDataOutput;

and

/** Constructor.*/
public ReadFromFile()
{
    super(DEFAULT_ACTIVITY_NAME);
    mFileInput   = new SimpleActivityInput(FILE_INPUT);
    mOffsetInput = new SimpleActivityInput(OFFSET_INPUT, SimpleActivityInput.OPTIONAL);
    mLengthInput = new SimpleActivityInput(LENGTH_INPUT, SimpleActivityInput.OPTIONAL);
    mDataOutput = new SimpleActivityOutput(OUTPUT_DATA);
}

In 2.2 we used to have :

So addInput("readFileInput") will be replaced with:

/** Directory input name */
public final static String FILE_INPUT = "file";

/** File input */
private ActivityInput mFileInput;
mFileInput = new SimpleActivityInput(FILE_INPUT);

The setXXX methods to set the values of a parameter. Now these methods have been replaces by addXXX methods in release 3.0. So for example:

public void setFilename(String filename) 
{
    mFilename = filename;
}

will be replaced by:

public void addFile(final String filename)
{
    mFileInput.add(new StringData(filename));
}

The getXXX methods to get the value of a parameter. These do not exist anymore in 3.0.

The setInput(ActivityOutput input) methods where the output of another activity was connected to this input now use connectXXXInput(ActivityOutput input) methods for this purpose. So:

public void setInput(ActivityOutput input) 
{
    if (input == null) 
    {
        throw new IllegalArgumentException("input must not be null");
    }
    super.setInput(0, input.getName());
}

will be replaced by:

public void connectFileInput(SingleActivityOutput output)
{
    mFileInput.connect(output);
}

	Note
	In 3.0 the addXXX and connectXXX methods for an input are mutually exclusive, i.e. an activity can have exactly one of this two methods so long its a mandatory input.

Some activities used to provide getXXX methods to return the output data in a developer-friendly format. This concept exists in release 3.0 as well but the way we formulate such methods is described in detail in Chapter 24, How to write an activity

Once your activity has been written it can be deployed on the OGSA-DAI server. This is described in Section 16.1.8, “Deploying an activity”.