How to Write an Activity that Creates Persisted Data Service Resources

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

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

We will now describe each of the stages in turn.

1. Name the new data service resource

Naming the new data service resource is the easiest stage as it simply involves obtaining a class instance and calling a method. The class instance we need to obtain is a data service resource factory. This class provides an activity with much of the functionality required to create data service resources. 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 get a unique name for the new data service resource we call a method on this object: 

String resourceName = factory.getNewResourceName();
We now have a unique name for the new data service resource. It would be possible in theory for the client to provide this name but would result it the possibility of name clashes so it is better to create unique names at the server. However, you could write your resource creation activity to check for name clashes and raise a ActivitySpecificationException, for return to the client, if such a clash occurs.

2. Create a configuration directory

All data service resources are configured using a set of configuration files. This configuration files are stored in a directory unique to that data service resource. An activity that wishes to create a new data service resource must create this configuration directory for the resource. This is again done using a method of the DataServiceResourceFactory: 

File configDir = factory.getResourceConfigDirectory(resourceName);

This method will create a new directory for the named resource and return a File object that refers to the directory.

3. Populate the configuration directory

Now that we have created the configuration directory for the new data service resource we must populate it with the appropriate files. All data service resource configuration directories must contain the following files:

These configuration files are described in more detail on the Configuration Files page.

The dataResourceClassConfig.xml file will be created by the data service resource factory at a later stage so we can ignore that for the moment. The activity must ensure that the configuration directory contains the activityConfig.xml and sessionConfig.xml files. A typical way of doing this would be to copy these files to the directory from somewhere else in the server's file system. The logical place to locate these files server-side is within a sub-directory of the configuration files directory of the factory data service resource (the resource which exposes your resource creation activity). For example: 

// Get the data resource accessor of the factory data service
// resource.
// Cast it to ConfigDirectoryProvider. The activity assumes that
// data service resources that support it use accessors that 
// implement this interface.
ConfigDirectoryProvider configDirProv =
    (ConfigDirectoryProvider)mContext.getDataResourceAccessor();

// Get a reference to the "instance" sub-directory of the
// configuration directory for the factory data service resource.
File sourceDir = 
    new File(configDirProv.getConfigDirectory(), "instance");

// Copy the contents of the "instance" directory to the configuration
// directory for the new data service resource.
FileUtilities.copyDirectoryContents(sourceDir, configDir);

In this example the factory data service resource's data resource accessor implements the uk.org.ogsadai.service.resource.factory.ConfigDirectoryProvider interface that allows its activities to obtain the path to its configuration directory. Once this path is known the files in its instance sub-directory are easily copied to the configuration directory of the new data service resource.

In addition to these general configuration files you will also need to add the configuration files specific to the data resource accessor of the new data service resource. It is the responsibility of the activity to do this. There are typically two approaches to doing this:

  1. Create and write to these files directory from within the activity.
  2. Include template versions of the configuration files within the factory data service resource's instance directory which are copied to the new resource's configuration directory. These template configuration files can then be populated with data specific to the new resource.

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

Once the configuration directory for the new resource has been populated, all that remains is to tell OGSA-DAI to create the new data service resource. This is done using the data service resource factory: 

factory.createResource(resourceName, "com.thirdParty.MyDataResourceAccessor");

where the first parameter is the name of the new data service resource and the second parameter is the name of the class that is the data resource accessor for the new data service resource. This class must implement the uk.org.ogsadai.dataresource.DataResourceAccessor interface and should also implement the uk.org.ogsadai.dataresource.PersistInFiles interface as it is to read its initial configuration from the files in its configuration directory.

A detailed example

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

Deploying the example

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

  1. Shutdown your Web services container.
  2. Execute the following command from within the OGSA-DAI binary distribution directory: 
    $ ant deployDemoFactoryResource
      -Ddai.container=/path/to/Web/services/container
      -Ddai.resource.id=DemoFactoryResource
    where dai.container specifies the location of your service container.
  3. 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=DemoFactoryResource
  4. Restart your Web services container

Running the example

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

$ ant dataServiceClient -Ddai.resource.id=DemoFactoryResource 
      -Ddai.action=examples/Perform/DemoFactory/createInstance.xml
...
     [echo] Executing Perform document on resource DemoFactoryResource...
     [java] Service version: OGSA-DAI WSRF 2.1
     [java] Number of resources: 1
     [java] Resource: DemoFactoryResource
     [java] Data Service Resource: DemoFactoryResource
     [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[ogsadai-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 'Bob'). For example: 

$ ant dataServiceClient -Ddai.resource.id=ogsadai-107098e475f
    -Ddai.action=examples/Perform/DemoFactory/queryInstance.xml 
...
     [echo] Executing Perform document on resource ogsadai-107098e475f...
     [java] Service version: OGSA-DAI WSRF 2.1
     [java] Number of resources: 2
     [java] Resource: ogsadai-107098e475f
     [java] Resource: DemoFactoryResource
     [java] Data Service Resource: ogsadai-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[Bob]]></ns1:result>
     [java] </ns1:response>
Up: How to Write an Activity that Creates Data Service Resources
© International Business Machines Corporation, 2002-2006 © The University of Edinburgh, 2002-2006