How to Write an Activity that Creates Transient Data Service Resources

In order to create a new transient data service resource an activity must do the following tasks:

Create an instance of the data resource accessor that will be used by the new data service resource.
Create an object that specifies what activities can be used with the new data service resource.
Create an object that specifies the session configuration details to be used to create sessions within the new data service resource.
Tell the OGSA-DAI framework to create the new data service resource.

These tasks will typically be carried out within the processBlock method of the activity. Once the new data service resource has been created any of your activity's outputs should be written and the setCompleted method called.

We will now describe each of the stages in turn.

1. Create an instance of a data resource accessor

Creating an instance of a data resource accessor is very easy - you create one using Java's new operator and configure it as desired. The object you create must implement the uk.org.ogsadai.dataresource.DataResourceAccessor interface.

When you pass the object to the OGSA-DAI framework (see step 4) the setResourceName method will be called by the framework. Note that when creating a transient service in the way described here the framework will not call the restoreFromConfig method even if the PersistInFiles interface is implemented.

2. Create an object that specifies what activities can be used

To specify what activities can be used with the new data service resource you must provide an object that implements the ActivitiesConfig interface (defined in the uk.org.ogsadai.service.resource.config package.)

All new data service resources created by your activity will probably use the same activity configuration so it makes sense to build it once in the data resource accessor of the factory data service resource (the resource exposing your resource creation activity) and then allow the resource creation activity to access it via this data resource accessor (which can be accessed by your activity via its ActivityContext object available in the mContext variable common to all activities.

The easiest way to create the object is create an instance of the FileBasedActivitiesConfig class (defined in the uk.org.ogsadai.service.resource.config package). This class will read the details of which activities the new data service resource will support from a standard OGSA-DAI Activity Configuration Document

It is a good idea to store the activity configuration document for the new data service resource within a seperate sub-directory of the factory data service resource's configuration directory (for example in an instance sub-directory. This file can be easily read from within the restoreFromConfig method of the factory resource's data resource accessor so it is sensible to build the FileBasedActivitiesConfig object within that method.

3. Create an object that specifies the session configuration

Specifying the session configuration to use with the new data service resource is much the same as specifying the activity configuration described above. This time the object must implement the SessionComponentFactory interface (in package uk.org.ogsadai.sessions).

As above it makes sense to create the class that implements this interface once in the factory data service resource's data resource accessor and make it available to your resource creation activity via the data resource accessor.

The easiest way to create the object is create an instance of the SessionConfigurationLoader class (defined in the uk.org.ogsadai.sessions package). This class will read the details of which session configuratio to be associated with the new data service resource from a standard OGSA-DAI Session Configuration Document

As above it is a good idea to store the session configuration document for the new data service resource within a seperate sub-directory of the factory data service resource's configuration directory (for example in an instance sub-directory. This file can be easily read from within the restoreFromConfig method of the factory resource's data resource accessor so it is sensible to build the SessionConfigurationLoader object within that method.

4. Tell the OGSA-DAI framework to create the resource

Once you have created the three objects described above all that remains is to pass them to the OGSA-DAI framework and as it to create the new data service resource. This is done using a data service resource factory (not to be confused with the factory data service resource which exposes your resource creation activity). To obtain the instance we use the ActivityContext object available in the mContext variable common to all activities:

import uk.org.ogsadai.service.resource.factory.DataServiceResourceFactory;

DataServiceResourceFactory factory = 
    mContext.getDataResourceFactory();

To create a new transient data service resource call the createResource method that has the following signature:

public String createResource(
    String                  namePrefix,
    DataResourceAccessor    dataResourceAccessor,
    ActivitiesConfig        activitiesConfig,
    SessionComponentFactory sessionComponentFactory)

where namePrefix specifies a prefix that will form the initial part of the name of the new resource. The rest of the name will be randomly created and guaranteed to unique server-side.

A detailed example

A full example of a factory data service resource with a transient resource creation activity is available. This consists of the following classes:

DemoTransientFactoryDataResourceAccessor - the data resource accessor for the factory data service resource.
DemoTransientInstanceDataResourceAccessor - the data resource accessor for resources created by the factory resource.
DemoCreateTransientInstanceActivity - the activity used to create a new data service resource from the factory data service resource.
DemoQueryInstanceActivity - an activity that can be used to query the new data service resource to show it has been correctly created. Note that this activity is the same activity as is used with the persisted data service resource example.

Deploying the example

ANT targets are provided to deploy this example factory data service resource. To deploy the resource:

Shutdown your Web services container.
Execute the following command from within the OGSA-DAI binary distribution directory:
```
$ ant deployDemoTransientFactoryResource
      -Ddai.container=/path/to/Web/services/container
      -Ddai.resource.id=DemoTransientFactoryResource
```
where dai.container specifies the location of your service container.
- If your container is Tomcat then this value should be the same as your CATALINA_HOME environment variable.
- If your container is GT4 then this value should be the same as your GLOBUS_LOCATION environment variable.
Having deployed the data service resource you must now expose it via the data service using the exposeResource or guiExposeResource targets as described in the Exposing Data Service Resources via Data Services pages. For example:
```
$ ant exposeResource -Ddai.container=/path/to/Web/services/container
      -Ddai.service.name=ogsadai/DataService
      -Ddai.resource.id=DemoTransientFactoryResource  
```
Restart your Web services container

Running the example

To run the example using the End-to-end Client to send the examples/Perform/DemoFactory/createTransientInstance.xml perform document to the factory resource. This will create a new resource whose resource ID will be returned.

$ ant dataServiceClient -Ddai.resource.id=DemoTransientFactoryResource 
      -Ddai.action=examples/Perform/DemoFactory/createTransientInstance.xml
...
     [echo] Executing Perform document on resource DemoTransientFactoryResource...
     [java] Service version: OGSA-DAI WSRF 2.2
     [java] Number of resources: 1
     [java] Resource: DemoTransientFactoryResource
     [java] Data Service Resource: DemoTransientFactoryResource
     [java] About to invoke Perform...
     [java] Perform completed!
     [java] Response:
     [java] <?xml version="1.0" encoding="UTF-8"?>
     [java] <ns1:response xmlns:ns1="http://ogsadai.org.uk/namespaces/2005/10/types">
     [java]     <ns1:session id="session-ogsadai-107098e475e"/>
     [java]     <ns1:request status="COMPLETED"/>
     [java]     <ns1:result name="create" status="COMPLETED"/>
     [java]     <ns1:result name="createOutput" status="COMPLETED">
     [java]         <![CDATA[testogsadai-107098e475f]]>
     [java]     </ns1:result>
     [java] </ns1:response>

Note how the name of the new resource is contained in the response.

You can then send the examples/Perform/DemoFactory/queryInstance.xml perform document to the new resource to obtain the name passed to the factory when the new resource was created (in this case 'Jorg'). For example:

$ ant dataServiceClient -Ddai.resource.id=testogsadai-107098e475f
      -Ddai.action=examples/Perform/DemoFactory/queryInstance.xml 
...
     [echo] Executing Perform document on resource testogsadai-107098e475f...
     [java] Service version: OGSA-DAI WSRF 2.2
     [java] Number of resources: 2
     [java] Resource: testogsadai-107098e475f
     [java] Resource: DemoTransientFactoryResource
     [java] Data Service Resource: testogsadai-107098e475f
     [java] About to invoke Perform...
     [java] Perform completed!
     [java] Response:
     [java] <?xml version="1.0" encoding="UTF-8"?>
     [java] <ns1:response xmlns:ns1="http://ogsadai.org.uk/namespaces/2005/10/types">
     [java]     <ns1:session id="session-ogsadai-107098e4760"/>
     [java]     <ns1:request status="COMPLETED"/>
     [java]     <ns1:result name="query" status="COMPLETED"/>
     [java]     <ns1:result name="queryOutput"status="COMPLETED"><![CDATA[Jorg]]></ns1:result>
     [java] </ns1:response>