This feature allows the service provider to expose existing data resources containing existing data to users of the GRIA OGSA-DAI service.

Connecting an existing data resource

1. Click the "Connect existing data resource" button.
2. Enter the JDBC URL of the data resource you wish to connect to. You can also enter a description.
3. Click the "Save changes" button to apply the changes.

Adding Roles

You will now need to add one or more data resource roles to your data resource. Roles allow you to specify which username and password combinations to use on the data resource backend.

Adding a role to a data resource

1. Click the "Add role" button beside the data resource you wish to modify.
2. Enter the username and password details of the user you are adding.
   Entering a Metric URI allows you to create Service Level Agreements (SLAs) that constrain on specific data resource roles. See the Metrics and SLAs section for more details.
   Repeat steps 1 and 2 if you need to add more than one role.
3. Click the "Save changes" button to apply the changes.

The role has now been created.

Setting Permissions on Resources

See the Access Control section to learn how you can control which users have permission to subscribe to your new resources.

Creating New Databases

This feature allows the service provider to create a new data resources that users can subscribe to and fill with data.

Creating a new data resource

1. Click the "Create new data resource" button.
2. Enter a description for the new data resource.
   You can optionally enter a Metric URI, a modified version of which will be assigned to the three automatically generated roles. Doing this allows you to create Service Level Agreements (SLAs) that constrain on specific data resource roles. See the Metrics and SLAs section for more details.
   
3. Click the "Save changes" button to apply the changes.

The new data resource has now been created. You will notice the OGSA-DAI service has automatically generated three data resource roles. These have the following permissions:

• Administrative role: can view data, modifiy data, and create and delete tables.
• Read/write role: can view and modify data in existing tables.
• Read only role: can view data in existing tables.

Setting Permissions on Resources

See the Access Control section to learn how you can control which users have permission to subscribe to your new resources.

Viewing Subscriptions

It is possible to create a subscription from the web interface.

Creating a data resource role subscription

1. Click the subscribe button on a particular role.
2. Enter description of new subscription.
3. Click save changes button.

After carrying out these steps you should see something similar to that below.

Click the icon circled in red to view your newly created subscription.

Setting Permissions on Resources

See the Access Control section to learn how you can control which users have permission to use your new subscription.

The GRIA service provider management package contains an SLA service that can be used to limit the number of resources users can create and charge them for those that they use. The OGSA-DAI service defines a number of metrics that the service provider can use when creating SLAs. The service generates usage reports using these metrics whenever a user creates a new resource. The SLA service collects these usage reports and charges the user accordingly.

The service provider may wish to set up different pricing terms for individual databases or roles. For example he may wish to charge for read/write access to a database while making read only access free. In this situation the service provider can specify a custom metric URI for each role, and then set up the SLA to constrain on those.

It would be helpful to read this section in conjunction with the SLA Management Service manual.

The OGSA-DAI service provides metrics for each of the resource types:

Example

User A has been given permission by the service provider to create databases. He wants to create a new database, create some tables in that database, and then give User B read/write access to those tables.

• User A calls createDatabase.

  Usage report for User A - Database
  http://www.gria.org/sla/metric/activity/ogsadai/db
  Total now: 1
  Usage report for User A - Administrative Role
  http://www.gria.org/sla/metric/activity/ogsadai/role
  Total now: 1
  Usage report for User A - Read/Write Role
  http://www.gria.org/sla/metric/activity/ogsadai/role
  Total now: 2
  Usage report for User A - Read Only Role
  http://www.gria.org/sla/metric/activity/ogsadai/role
  Total now: 3

• User A calls subscribe on his administrative role so he can create a table.

  Usage report for User A - Subscription
  http://www.gria.org/sla/metric/activity/ogsadai/subscription
  Total now: 1
  Usage report for User A - Subscriber
  http://www.gria.org/sla/metric/resource/ogsadai/subscriber
  Total now: 1

• User A calls perform on his subscription, creating a table.

• User A gives User B permission to subscribe to his Read/Write role.

• User B calls subscribe on the Read/Write role.

  Usage report for User B - Subscription
  http://www.gria.org/sla/metric/activity/ogsadai/subscription
  Total now: 1
  Usage report for User A - Subscriber
  http://www.gria.org/sla/metric/resource/ogsadai/subscriber
  Total now: 2

• User B executes some queries on his Read/Write subscription.

At the end of this example, the usage for the two users is as follows:

In some situations the service provider may wish to charge or constrain differently for different databases or database roles. For example, he may want to make read-only access to a database free while charging for read/write access.

This can be implemented through the use of custom metric URIs. There are two places where a custom URI can be entered:

• When adding a new role.
• When creating a new database (the automatically generated roles get assigned metric URIs based on the one provided).

When a user subscribes to a database role that uses custom metric URIs he generates one usage report for the standard subscription metric (http://www.gria.org/sla/metric/activity/ogsadai/subscription) and one for the custom metric. This is different from subscribing to a role without a custom metric URI, where the user would only generate a usage report for the standard subscription metric.

Providing a custom metric URI when creating a new database will assign similar metric URIs to the three automatically generated database roles. These URIs are generated using the same rules as username generation - the three postfixes are appended onto the end of the metric URI for each of the three roles.

For example, supposing you keep the default values for the username postfixes (eg, ".a" for the administrative role and ".r" for the read-only role), and specify a metric URI http://www.test.com/metric/test_database, the following metric URIs would be generated for the three roles:

• Administrative role: http://www.test.com/metric/test_database.a
• Read/write role: http://www.test.com/metric/test_database.w
• Read Only role: http://www.test.com/metric/test_database.r

SLA templates can be created to constrain on any of the above metrics. Several example sections of SLA templates are given below. See the GRIA user documentation for information on constructing full SLA template XML documents.

Limiting database creation

When inserted into the <constraints> section of an SLA template, this capacity constaint will limit the user to creating only one database. The user may still subscribe to other databases, and other users may subscribe to his database.

<constraint type='INSTANTANEOUS'>
    <metric type='ACTIVITY'>
        <uri>http://www.gria.org/sla/metric/activity/ogsadai/db</uri>
        <description>
            <description>database</description>

        </description>
        <units type='DECIMAL'>
            <instantaneous>database</instantaneous>
        </units>
    </metric>

    <bound>LE</bound>
    <private>false</private>
    <limit>1.0</limit>
    <contention>1.0</contention>

    <repeating>false</repeating>
</constraint>

Limiting subscriptions

When inserted into the <constraints> section of an SLA template, these capacity constraints will allow the user to subscribe to three database roles, and have one person subscribe to any roles he creates. The user can create an unlimited number of databases.

<constraint type='INSTANTANEOUS'>
    <metric type='ACTIVITY'>
        <uri>http://www.gria.org/sla/metric/activity/ogsadai/subscription</uri>
        <description>
            <description>subscription</description>

        </description>
        <units type='DECIMAL'>
        <instantaneous>subscription</instantaneous>
    </units>
    </metric>

    <bound>LE</bound>
    <private>false</private>
    <limit>3.0</limit>
    <contention>1.0</contention>

    <repeating>false</repeating>
</constraint>

<constraint type='INSTANTANEOUS'>
    <metric type='RESOURCE'>
        <uri>http://www.gria.org/sla/metric/resource/ogsadai/subscriber</uri>

        <description>
            <description>subscriber</description>
        </description>
        <units type='DECIMAL'>
            <instantaneous>subscriber</instantaneous>

        </units>
    </metric>
    <bound>LE</bound>
    <private>false</private>
    <limit>1.0</limit>

    <contention>1.0</contention>
    <repeating>false</repeating>
</constraint>

Visit the URL of the GRIA OGSA-DAI Service you wish to access and drag the wsdl link from the webpage in to the service view of the client.

Connecting to an OGSA-DAI Service from Client

If you are running the GRIA OGSA-DAI 1.0 client drag the OGSA-DAI Service legacy link, otherwise use the OGSA-DAI Service link. It is most likely that you are using a 5.2 client.

This feature allows you to expose existing databases containing existing data to users of the GRIA OGSA-DAI service. To use this feature you need to have been given access to the connect-database PBAC role on the OGSA-DAI service. See the Access Control section for more information.

Before starting you should ensure that the OGSA-DAI service is listed in your client. If it does not exist you can add it by either left clicking on the "Services" menu item and selecting "Add a service", or dragging the service's WSDL link onto the "Services" entry.

Right click on the OGSA-DAI service and select "Connect existing resource".

This will open a dialog box where you can enter the details of the database you wish to connect. You are able to enter the JDBC URL of any type of database here, and also a short description of the database.  No checks as to the validity of the JDBC URL are made.

Once you have connected you data resource you are able to add roles.  Right click on the connected data resource and select "Connect role".

Enter a description plus the username and password of the role on your database.

After clicking "OK", the role you have created is added to the list.

Setting Permissions on Roles

See the Access Control section to learn how you can control which users have permission to subscribe to your new data resource role.

Creating New Data Resources

This feature allows you to create new data resources which you can either subscribe to and use yourself, or give permission for others to use. To create new data resource you need to have been given access to the create-dataresource PBAC role on the OGSA-DAI service. See the Access Control section for more information.

Before starting you should ensure that the OGSA-DAI service is listed in your client. If it does not exist you can add it by either left clicking on the "Services" entry and selecting "Add a service", or dragging the service's WSDL link into the client.

Right click on the OGSA-DAI service and select "Create new dataresource".

Enter a description and press ok.

The database and its three roles have now been created.

Setting Permissions on Data Resources

See the Access Control section to learn how you can control which users have permission to subscribe to your new data resources.

Getting a subscription to a database role allows you to execute queries (perform documents) on it. By default you are allowed to subscribe to roles created by yourself. To be able to subscribe to roles created by other people, they need to have given you the client PBAC role on their resource. See the Access Control section for more information.

If you have been given access to a role and it does not appear in your client, try right clicking on the OGSA-DAI service and selecting "Discover existing resources".

Before starting you should ensure that the OGSA-DAI service is listed in your client. If it does not exist you can add it by either left clicking on the "Services" menu item and selecting "Add a service", or dragging the service's WSDL link into the client.

Right click on the role you wish to subscribe to and select "Subscribe". You will be asked to enter a short description for the subscription.

The subscription is now listed in your client. You can execute SQL queries on it directly from the client by right clicking on it and selecting one of "Execute query" or "Execute update" entries.  Note this only works on SQL Database types of data resources.

Usage

Delegating access to a Subscription

This feature allows you to permit another user to execute database queries using your subscription. Note that the delegate only gets access to a subset of methods on your subscription:

Left click on the database subscription that you wish to delegate access to, and select "Access control list".

Now add a new access control rule for the "delegate" role. In the screenshot below we are adding a rule such that everyone is considered a delegate to this subscription, and will be able to run perform documents on it.

The GRIA client allows you to destroy any of the resources for which you have the owner PBAC role. To do this simply right click on the resource and select "Destroy".

Destroying Data Resources

When destroying a data resource that was created by the OGSA-DAI service (ie. by using the create new data resource feature), all tables and data in that database will be removed from the RDBMS.

Destroying a data resource that already existed (and was configured using the connect existing database feature) will only remove the link between the OGSA-DAI service and the back-end, and will leave the data intact.

Destroying a database will cause all roles and subscriptions on the database to be destroyed in addition to the database resource itself.

Destroying Role Resources

Destroying a role resource will also destroy any subscriptions that use that role.

Note you cannot destroy roles that were automatically created by the OGSA-DAI service. These roles exist until the database that they belong to is destroyed.

Destroying Subscription Resources

Removing a subscription resource will prevent any further queries from being run using that subscription.

Please see the JavaDoc for a detailed descrition of the API.

The GRIA API is used to create and manage the GRIA resources representing databases, roles and subscriptions. See the AXIS plugin for OGSA-DAI clients document for instructions for using the OGSA-DAI API for OGSA-DAI operations (e.g. "perform").

Configuring your Classpath

To use the GRIA OGSA-DAI libraries from your own application, ensure that all of the following are in your application's classpath:

1. All the jars from the standard graphical client's lib directory, except for gria-client-cli-2.jar, which is the default client itself.
2. The gria-ogsadai-client-5.2.jar and gria-ogsadai-common-5.2.jar file from inside the client directory of this package.
3. The client-config.wsdd and implementationfactory.properties files from inside gria-client-cli-2.jar.

   The WSDD file causes messages to be signed correctly and contains type mappings telling Axis how to serialise various types.

4. The crypto.properties file from the client's conf directory, which gives details of the keystore to use.

The StateRepository

A StateRepository stores resources (accounts, SLAs, databases, roles and subscriptions) and services. There are two implementations provided with the GRIA library:

• FileStateRepository stores them in an XML format file.
• MemoryStateRepository only stores them in memory. Quitting the application will cause them to be forgotten.

Creating a StateRepository

To create a new memory repository:

StateRepository repository = new MemoryStateRepository();

To create a new repository that stores its state in a file called client.state (this is what the standard client uses):

StateRepository repository = new FileStateRepository("client.state");

It is probably easiest to use FileStateRepository as you can create objects using the standard client and then use them from your own program.

Adding services to a repository

Just as when using the graphical client interface, services must be added to the repository before they can be used. All the details about an object in a StateRepository are represented as a WS-Addressing EndpointReference. For example, to add a RemoteOgsaDaiService proxy to an OGSA-DAI service:

EndpointReference serviceEPR = new EndpointReference("https://.../services/DataService");

RemoteOgsaDaiService ogsaDaiService = repository.getOrCreateObject(RemoteOgsaDaiService.class, serviceEPR);

The getOrCreateObject method takes an EPR for the object you want, and a Java interface for the resulting object. If the object is already in the respository then it returns it, otherwise it creates a new one, adds it to the repository, and returns that.

Billing Information

For methods which create new resources, the client software will automatically add a SOAP header containing the billing information (i.e. the ID of the SLA managing the resource).

Useful Methods

The following methods will be the most useful when using the OGSA-DAI service. For a full list of classes and methods see the Javadoc.

• getResources()

• createDataResource(String label)
• connectDataResource(String label, Map<String, String> attributes)

• connectDataResourceRole(String label, Map<String, String> attributes)

• createSubscription(String label)

• Once you have a subscription resource ID, the standard OGSA-DAI API should be used for querying the database. See example code.

Many classes have the following common methods:

• destroy()
• setLabel(String label)
• GetValidRoles()
• getAccessControlRules()
• addAccessControlRule(MatchRule rule)
• removeAccessControlRule(MatchRule rule)

Overview

The service comes complete with interfaces to MySQL and PostgreSQL. There are minor differences between the required interface for one JDBC database and another. To integrate the GRIA OGSA-DAI service with a different JDBC database, follow the method below.

Method

1. Implement an additional BackendHelper class. For reference, see the MySQLBackendHelper and PostgreSQLBackendHelper.
2. Put the new class on the classpath of the webapp.
3. Don't forget to put the JDBC driver jar for the database in the tomcat classpath.
4. In the database server configuration tool of the service's web interface, add the class name of the new BackendHelper and save changes.

Overview

In order to add a completely different data resource to the service, implementations for several interfaces must be written. The implementations are loaded through the ImplementationFactory and the implementing classes must be defined in the implementationfactory.properties file.

The GRIA OGSA-DAI service makes the distinction between connecting and creating data resources and data resource roles (e.g. databases and database users). The term "connecting" means configuring the service to make use of pre-existing data resources or users. The term "creating" refers to the service instructing the back-end system to create new data resources or users. A new implementation may want to just provide the facility to connect to existing data resources.

Method

Implement a DataResourceManager

The abstract class OgsaDaiDataResourceManager is the OGSA-DAI service's implementation of the DataResourceManager interface. It contains convenience functions useful for handling OGSA-DAI configuration files. It must be extended by a class specific to the back-end system. The only class that extends it so far is the RDBMSDataResourceManager.

One of the functions of the DataResourceManager is to connect an existing data resource. In order to do this, a new OGSA-DAI instance must be created and deployed. The RDBMSDataResourceManager creates the configuration files of the new OGSA-DAI instance by using template files contained within WEB-INF/etc/skeletons in the GRIA OGSA-DAI webapp. The templates are transformed into complete configuration files and written into the defined configuration directory of the GRIA OGSA-DAI service.

Two of the methods of DataResourceManager are createDataResource and connectDataResource

• Loaded by the ImplementationFactory
• OgsaDaiDataResourceManager Javadoc
• RDBMSDataResourceManager Javadoc

Implement the Presentation Interface

This is used by both the web interface and SOAP clients to provide presentation information about the OgsaDaiDataResourceManager subclass that is being used. The only class that implements it so far is RDBMSPresentation, which through the implementation of the DataResourceManager (see above) also saves the configuration data entered in the web interface. When extending OgsaDaiDataResourceManager another implementation for this class must also be written.

• Loaded by the ImplementationFactory
• Presentation Javadoc
• RDBMSPresentation Javadoc

Implement the OGSA-DAI RoleMapper Interface

The OGSA-DAI RoleMapper provides the OGSA-DAI SQL activities with credentials for data resources they need to access. The interface defined by OGSA-DAI takes a string defining the credentials and a string defining the database to be used and returns an OGSA-DAI Role object containing whatever is required to log in to the database.

For the GRIA OGSA-DAI service RDBMSSubscriptionRoleMapper has been written. It takes a DataResourceSubscription ID for the credentials and a DataResource ID for the database specifier. As the DataResourceSubscription is already in the context of a user on a database, it just uses the DataResourceSubscription to retrieve the username and password from the parent DataResourceRole object and returns them in the OGSA-DAI DatabaseRole object (a standard implementation of Role).

It is suggested that custom OGSA-DAI activities also use the RoleMapper system for obtaining login credentials. If the database login only requires a username and password then the existing implementation (RDBMSSubscriptionRoleMapper) will be sufficient, otherwise another implementation for this class and for the OGSA-DAI Role class must also be written.

• Loaded by specifying a class name in the OGSA-DAI configuration files.
• RoleMapper Javadoc
• Role Javadoc
• DatabaseRole Javadoc
• RDBMSSubscriptionRoleMapper Javadoc

Supporting Additional Activities

A whitelist of permitted OGSA-DAI activities is specified in the activityConfig.xml file in OGSA-DAI's configuration directory. This file is generated by RDBMSDataResourceManager from a template (WEB-INF/etc/skeletons/activityConfigRelational.xml in the webapp). In order to support new types of activity, a replacement for RDBMSDataResourceManager would have to be created to generate these different configuration files (see above). This new implementation would also need to interface differently with whatever back-end it used (RDBMS has a BackendHelper to do this). It would likely still be able to use OgsaDaiInstance (a protected field inherited from OgsaDaiDataResourceManager) to deploy and undeploy data resources on OGSA-DAI.

Modifying the Client Plug-in

The GRIA OGSA-DAI service client plug-in provides maangement abilities for OGSA-DAI resources. For subscription resources it also has menu options for executing SQL select and update statements. These methods are provided just for convenience and it is not expected that anyone would use them for serious work. It would be possible to write an alternative client plug-in that provided similar convenience methods for whatever operations were useful for the alternative back-end.

• OgsaDaiClientPlugin Javadoc

Overview

In some cases, an Activity executed by the OGSA-DAI service may require the identity details (X.509 distinguished name, additional tokens, etc) of the client that invoked the service. These details are available from the user's SubjectDescription object. This is stored in a HashMap keyed off the unique name of each activity.

Example Code

The following is an example of using the current users SubjectDescription to make a call on another GRIA OGSA-DAI Service. The example is of the processBlock method in an OGSA-DAI activity implementation.

public void processBlock() {
	StateRepository repos = new MemoryStateRepository();
	EndpointReferenceType epr = ConversationID.getEPR("https://bodegas.it-innovation.soton.ac.uk:8443/gria-ogsadai-service/services/OgsaDaiSubscription#ff808181-14fede48-0114-fef342c9-0006");
    	
	OgsaDaiSubscriptionConversation convo = repos.getOrCreateObject(OgsaDaiSubscriptionConversation.class, epr);

	try {		
		//getName() returns a unique string for each activity instance.  
		//The SubjectDescription of the user that made the perform call that initiated the activity
		//Is stored in the OgsaDaiServiceImpl.activityClientMap
		SubjectDescription client = OgsaDaiServiceImpl.activityClientMap.get(getName());

		convo.checkPolicyRule(client,"perform");
	} catch (RemoteException e) {
		setError(e);
	}
}

Example Scenario

One specific example where the client's credentials are required is when the OGSA-DAI service is acting on behalf of many clients, for instance if the OGSA-DAI service is installed as an intermediary between the client and the final GRIA OGSA-DAI service. This situation is represented in a simplified form in the following figure.

A GRIA OGSA-DAI service acting as an intermediary

In the figure, Client A sends a request to Service B (step 1). Service B executes an OGSA-DAI activity that requires access to Service C (for instance, Service B may be in place to rewrite the query in a different query language). For Service B to access Service C (step 3) it must be authorised in the usual way on Service C, but it is a security loop-hole if step 3 is carried out with no further access control checks. In step 2, Service B checks that Client A is permitted to access Service C and only if Client A can access Service C will Service B access Service C on Client A's behalf.

There is no context displayed in the figure, instead the context of each call is listed below:

1. perform (Client A to Service B)
• Identity: Client A's X.509 identity plus additional tokens from membership groups etc
• Resource: The query is performed on a data resource subscription from Service B
• Parameters:
• The query
• The endpoint reference for Client A's data resource subscription at Service C
2. checkPolicyRule (Service B to Service C)
• Identity: Service B's X.509 identity
• Resource: The endpoint reference for Client A's data resource subscription at Service C
• Parameters
• Client A's identity (found using the activityClientMap as shown above)
• The operation name ("perform")
3. perform (Service B to Service C)
• Identity: Service B's X.509 identity
• Resource: The endpoint reference for Client A's data resource subscription at Service C
• Parameters
• The query Service B wants to execute on Client A's behalf

For this scenario to operate, Client A will have to authorise Service B to use Client A's data resource subscription at Service C (e.g. as a "delegate").

With these steps in place Client A can only access data at Service C that Client A is permitted to see. If step 2 is not used then a different client ("Client Z") who was authorised on Service B but not Service C, could find out the endpoint reference of Client A's subscription at Service C and perform the same query on Service B as above. Service B would then blindly perform a query on Service C and return the results to Client Z, exposing the data.