Chapter 17. Server configuration files

Prev	Part I. Administrator Documentation	Next

17.1. Container configuration files

Here the configuration files that OGSA-DAI uses as required by the environments under which OGSA-DAI runs (e.g. servlet containers) are described.

17.1.1. OGSA-DAI GT and Globus Toolkit

On an OGSA-DAI GT deployment - whether under Tomcat or within the GT standalone container - the GT-specific configuration files that OGSA-DAI needs to provide are located within the GT.

17.1.1.1. OGSA-DAI, Globus Toolkit and Tomcat

In an OGSA-DAI GT deployment Tomcat these files are located relative to the root directory of Globus Toolkit as deployed under Tomcat. By default this will be within the directory:

/PATH/TO/TOMCAT/webapps/wsrf/

Within this directory there are the following files and directories

dai-manager.jsp - OGSA-DAI JSP page for browsing the OGSA-DAI server state.
share/schema - directory containing Globus Toolkit, WSRF and OGSA-DAI XML Schema and WSDL documents.
WEB-INF/classes/log4j.properties - the Globus Toolkit Log4J properties file.
WEB-INF/etc/dai - OGSA-DAI file-based persistence configuration files (as described in Section 17.2, “OGSA-DAI configuration files”. This assumes the administrator used the default GAR name of dai.
WEB-INF/etc/dai/jndi-config.xml. This file specifies the OGSA-DAI server configuration including the OGSA-DAI version and classes to be used to handle persistence and configuration and the management of state within an OGSA-DAI server (see Chapter 18, Advanced server configuration). This also specifies resource implementation classes and their association to OGSA-DAI services.
WEB-INF/etc/dai/server-config.wsdd - Axis deployment descriptor declaring the available OGSA-DAI services and type mappings to support interaction with these by clients.
WEB-INF/lib - Globus Toolkit, OGSA-DAI and other JARs required to run Globus Toolkit and OGSA-DAI.

17.1.1.2. OGSA-DAI, Globus Toolkit and Globus Toolkit standalone container

In an OGSA-DAI GT deployment onto the Globus Toolkit standalone container these files are located relative to the root directory of Globus Toolkit.

etc/dai - OGSA-DAI file-based persistence configuration files (as described in Section 17.2, “OGSA-DAI configuration files”.
etc/dai/jndi-config.xml. This file specifies the OGSA-DAI server configuration including the OGSA-DAI version and classes to be used to handle persistence and configuration and the management of state within an OGSA-DAI server (see Chapter 18, Advanced server configuration). This also specifies resource implementation classes and their association to OGSA-DAI services.
etc/dai/server-config.wsdd - Axis deployment descriptor declaring the available OGSA-DAI services and type mappings to support interaction with these by clients.
lib - Globus Toolkit, OGSA-DAI and other JARs required to run Globus Toolkit and OGSA-DAI.
log4j.properties - the Globus Toolkit Log4J properties file.
share/schema - directory containing Globus Toolkit, WSRF and OGSA-DAI XML Schema and WSDL documents.

17.2. OGSA-DAI configuration files

	Note
	Note that the use of configuration files is not mandatory. Configuration is an OGSA-DAI extensibility point and third-party developers may implement their own means by which an OGSA-DAI server is configured. Please see Chapter 18, Advanced server configuration.

17.2.1. Configuration files directory

On an OGSA-DAI server, OGSA-DAI configuration files are located in a configuration files directory.

If using OGSA-DAI GT on Tomcat configuration files are located in:

/PATH/TO/TOMCAT/webapps/wsrf/WEB-INF/etc/dai/

assuming that the default webapp of wsrf and GAR name of dai were used.

If using OGSA-DAI GT on Globus Toolkit configuration files are located in:

/PATH/TO/GT/etc/dai/

assuming that the default GAR name of dai was used.

The structure of the configuration files directory is as follows:

activities.txt
config.txt
logins.txt
resources/
  DataRequestExecutionResource
  JDBCDataResource
  XMLDBDataResource
  FileDataResource
  SomeDataResource
  ...
resourceTemplates/
  uk.org.ogsadai.DATA_SINK_TEMPLATE
  uk.org.ogsadai.DATA_SOURCE_TEMPLATE
  uk.org.ogsadai.REQUEST_TEMPLATE
  uk.org.ogsadai.RESOURCE_GROUP_TEMPLATE
  uk.org.ogsadai.SESSION_TEMPLATE
  ...

17.2.2. Activity specification file

All activities available to all the resources on an OGSA-DAI server are specified in an activity specification file.

17.2.2.1. Activity specification file name and location

The activity specification file has name activities.txt and is located in the OGSA-DAI configuration files directory Section 17.2.1, “Configuration files directory”.

17.2.2.2. Activity specification file format

The activity specification file declares, for each activity, the following information:

Activity ID. This consists of a namespace and a local part. The following are both examples of valid activity ID declarations:
```
id=SomeActivity
id=some.company.SomeOtherActivity
```
Activity implementation class name, for example:
```
class=uk.org.ogsadai.SomeActivityClassName
```

Human readable description, for example:

description=This activity does something.

Zero or more activity configuration properties:
- Specific to the activity implementation class.
- Delimited by CONFIG and END delimiters.
- Even if 0 properties are provided then the end block markers must be provided.
- Keys consist of a namespace and a local part, e.g. SomeKey or some.other.SomeOtherKey.
- Values are strings. Activities receive all values as strings. Should numbers or booleans be required then the activity can parse the string appropriately.
- An example configuration might consist of teh following:
```
CONFIG
some.upper.bound=10
some.timeout=100
some.control.parameter=BIN123
some.flag=false
END
```

To summarise therefore, each entry is of the form:

id=ACTIVITY-ID 
class=ACTIVITY-CLASS
description=ACTIVITY-DESCRIPTION
CONFIG
[KEY=VALUE]*
END

and the activity specification file consists of 0 or more such entries.

17.2.2.3. Activity specification file example

The standard activity specification file can be seen in OGSA-DAI source or binary distributions in deploy/server-config/activities.txt.

17.2.3. Logins File

OGSA-DAI supports the specification of mappings from the caller's identity and attributes (as contained in the security context) to database usernames and passwords via a logins file.

	Note
	Note that use of a logins file is not mandatory. How the security context is mapped to database logins is application-specific. We just provide the file-based login provider as one example of how this can be done. Information on writing a login provider is in Chapter 32, How to write a login provider.

17.2.3.1. Logins file name and location

The logins file has name the logins.txt and is located in the OGSA-DAI configuration files directory Section 17.2.1, “Configuration files directory”.

17.2.3.2. Logins file format

The logins file declares zero or more mappings from distinguished names to database usernames and passwords for zero or more OGSA-DAI data resources.

Data resource ID. This consists of a namespace and a local part. The following are both examples of valid resource ID declarations:
```
id=SomeDataResource
id=some.company.SomeOtherDataResource
```
Zero or more mapping from distinguished names to database user names and passwords:
- Terminated by a LOGIN-END delimiter.
- Even if 0 mappings are provided then the end block marker must be provided.
- A distinguished name may be an actual distinguished name or a wildcard * character which is assumed to match to any credential. For example, the following are all examples.
```
userID=/C=USA/O=Music/OU=Bands/L=Bangles/CN=Susanna Hoffs
userID=/C=UK/O=Music/OU=Bands/L=Madness/CN=Suggs
userID=*
```
- User names can be a string or omitted if the user name is an empty string. For example:
```
username=
username=susanna
```
- Passwords can be a string or omitted if the password is an empty string / null. For example:
```
password=
password=EternalFlame
```
- Naturally the username and password must be valid for the database corresponding to the OGSA-DAI data resource ID.
An END delimiter to terminate the entry for the resource.

To summarise therefore, each resource can have an entry of form:

id=RESOURCE-ID
[
userID=STRING or *
username=USER
password=PASSWORD
LOGIN-END
]*
END

and the logins file contains zero or more such entries.

17.2.3.3. Logins file example

An example logins file is as follows, which declares two mappings for BanglesDataResource, two for MadnessDataResource and none for SpecialsDataResource

id=uk.org.ogsadai.BanglesDataResource
userID=/C=USA/O=Music/OU=Bands/L=Bangles/CN=Susanna Hoffs
username=susanna
password=EternalFlame
LOGIN-END
userID=/C=USA/O=Music/OU=Bands/L=Bangles/CN=Debbie Petersen
username=debbie
password=ManicMonday
LOGIN-END
END
id=uk.org.ogsadai.MadnessDataResource
userID=/C=UK/O=Music/OU=Bands/L=Madness/CN=Suggs
username=graham
password=mcpherson
userID=*
username=nutty
password=boys
END
id=uk.org.ogsadai.SpecialsDataResource
END

17.2.4. Resource Files

All persisted resources known to an OGSA-DAI server are specified in resource files.

17.2.4.1. Resource files name and location

Resource files are named after their resource. The file name is exactly identical to the resource ID and vice-versa. Resource IDs consist a namespace and a local part. The following are examples of valid resource IDs (and thus also file names):

SomeDataResource
some.company.SomeOtherResource
DataRequestExecutionResource
MySQLDataResource
uk.org.ogsadai.JDBCResource

Resource files reside in a resources directory located in the OGSA-DAI configuration files directory Section 17.2.1, “Configuration files directory”.

	Caution
	All files in `resources` are assumed to be resource files.

17.2.4.2. Resource files format

A resource file declares the following information for a resource:

Resource ID. This consists of a namespace and a local part and matches the file name, for example:
```
id=SomeResource
```
Resource type. Section I.2, “Default resource type names” provides a complete list of OGSA-DAI resource type names, for example:
```
type=uk.org.ogsadai.DATA_RESOURCE
```
Creation time - value in milli-seconds from the start of the epoch or null, for example:
```
creationTime=null
```
Termination time - value in milli-seconds from the start of the epoch or null, for example:
```
terminationTime=null
```

Zero or more persisted resource properties:

Any entry in this list is exposed as a resource property and is accessible to clients using the resource.
Delimited by PROPERTIES and END delimiters.
Even if 0 properties are provided then the end block markers must be provided.
Names consist of an absolute namespace and a local part, e.g. http://SomePropertyName or http://some.other.SomeOtherPropertyName.

Values are strings. Currently all persisted resource properties are assumed to be strings.

	Note
	String-only resource property serialization/deserialization is a characteristic of the implementation of file-based resource configuration and persistence used by OGSA-DAI. This persistence component is an extensibility point and can be completely replaced. Please see Chapter 18, Advanced server configuration.

For example:

PROPERTIES
http://uk.org.ogsadai.resource.dataresource.product=MySQL
http://uk.org.ogsadai.resource.dataresource.vendor=MySQL
http://uk.org.ogsadai.resource.dataresource.version=5.0
END

Zero or more resource configuration properties:
- Specific to the resource implementation class.
- Delimited by CONFIG and END delimiters.
- Even if 0 properties are provided then the end block markers must be provided.
- Keys consist of a namespace and a local part, e.g. SomePropertyName or some.other.SomeOtherPropertyName.
- Values are strings. Resources receive all values as strings. Should numbers or booleans be required then the resource can parse the string appropriately.
- For example:
```
CONFIG
dai.driver.class=org.gjt.mm.mysql.Driver
dai.data.resource.uri=jdbc:mysql://myhost:3306/daitest
dai.login.provider=uk.org.ogsadai.LOGIN_PROVIDER
END
```
Zero or more supported activities:
- Delimited by ACTIVITIES and END delimiters.
- Even if 0 activities are supported then the end block markers must be provided.
- Supported activities consist of an activity name and an activity ID.
- The activity name is the name of the activity as it is exposed to clients and is the name clients use when citing the activity in requests.
- The activity ID is the ID of an activity known to the OGSA-DAI server. There must be an entry with that ID in the activity specification file.
- For example:
```
ACTIVITIES
uk.org.ogsadai.SQLQuery=uk.org.ogsadai.SQLQuery
uk.org.ogsadai.SQLUpdate=uk.org.ogsadai.SQLUpdate
END
```

17.2.4.3. Resource files format - data request execution resources

Data request execution resource files use the generic resource format shown above in Section 17.2.4.2, “Resource files format” but also support the following.

An accept requests flag which is either true or false - is the data request execution resource currently accepting requests, for example:
```
acceptRequests=true
```
Zero or more engine configuration properties:
- Specific to the engine implementation class.
- Delimited by ENGINE-CONFIG and END delimiters.
- Constraints on these properties are as for general resource configuration properties.
- For example:
```
ENGINE-CONFIG
dai.concurrency.queue.length=20
dai.concurrency.request.pool.size=10
END
```
Section 17.2.7, “Data request execution resource configuration properties” lists OGSA-DAI data request execution resource configuration properties.

17.2.4.4. Resource files format - data resources

Data resource files use the generic resource format shown above in Section 17.2.4.2, “Resource files format” but also support the following.

Name of the class implementing the data resource, for example:

dataResourceClass=uk.org.ogsadai.resource.dataresource.jdbc.JDBCDataResource

Section 17.2.8, “Data resource configuration properties and classes” lists OGSA-DAI data resource classes and configuration properties.

17.2.4.5. Resource files format - sessions

Session files use the generic resource format shown above in Section 17.2.4.2, “Resource files format” but also support the following.

Default termination time. Time in minutes which is added to the current time when the resource is first created. If omitted then a default of 1440 (1 day) is used. If the resource termination time is non-null/empty then this default termination time is ignored, for example:
```
defaultTerminationTime=2880
```
Zero or more persisted session state entries:
- Delimited by SESSION-STATE and END delimiters.
- Constraints on these properties are as for persisted resource properties.
- For example:
```
SESSION-STATE
something.stored.in.the.session=12345
something.else.stored.in.the.session=Having fun and playing fools.
END
```

17.2.4.6. Resource files format - data sinks

Data sink files use the generic resource format shown above in Section 17.2.4.2, “Resource files format” but also support the following.

Default termination time. Time in minutes which is added to the current time when the resource is first created. If omitted then a default of 1440 (1 day) is used. If the resource termination time is non-null/empty then this default termination time is ignored, for example:
```
defaultTerminationTime=2880
```

17.2.4.7. Resource files format - data sources

Data source files use the generic resource format shown above in Section 17.2.4.2, “Resource files format” but also support the following.

Default termination time. Time in minutes which is added to the current time when the resource is first created. If omitted then a default of 1440 (1 day) is used. If the resource termination time is non-null/empty then this default termination time is ignored, for example:
```
defaultTerminationTime=2880
```
Default buffer size greater than zero. Largest number of blocks the data source can buffer. If ommited a default of 1000 is used, for example:
```
defaultBufferSize=2000
```

17.2.4.8. Resource files format - request resources

Request resource files use the generic resource format shown above in Section 17.2.4.2, “Resource files format” but also support the following.

Default termination time. Time in minutes which is added to the current time when the resource is first created. If omitted then a default of 1440 (1 day) is used. If the resource termination time is non-null/empty then this default termination time is ignored. For example:
```
defaultTerminationTime=2880
```

17.2.4.9. Resource files format summary

To summarise therefore, a resource file starts with a block of form:

id=RESOURCE-ID
type=RESOURCE-TYPE
creationTime=CREATION-TIME
terminationTime=TERMINATION-TIME
PROPERTIES
[NAME=VALUE]*
END
CONFIG
[KEY=VALUE]*
END
ACTIVITIES
[ACTIVITY-NAME=ACTIVITY-ID]*
END

Data request execution resources then have a block of form:

acceptRequests=[true|false]
ENGINE-CONFIG
[KEY=VALUE]*
END

Section 17.2.7, “Data request execution resource configuration properties” lists OGSA-DAI data request execution resource configuration properties.

Data resources then have a block of form:

dataResourceClass=CLASS-NAME

Section 17.2.8, “Data resource configuration properties and classes” lists OGSA-DAI data resource classes and configuration properties.

Session resources then have a block of form:

defaultTerminationTime=TERMINATION-TIME-IN-MINUTES-GREATER-THAN-OR-EQ-0
SESSION-STATE
[KEY=VALUE]*
END

Data source resources then have a block of form:

defaultTerminationTime=TERMINATION-TIME-IN-MINUTES-GREATER-THAN-OR-EQ-0
bufferSize=BUFFER-SIZE-GREATER-THAN-ZERO

Data sink resources then have a block of form:

defaultTerminationTime=TERMINATION-TIME-IN-MINUTES-GREATER-THAN-OR-EQ-0

Request resources then have a block of form:

defaultTerminationTime=TERMINATION-TIME-IN-MINUTES-GREATER-THAN-1

17.2.4.10. Resource files example

The standard OGSA-DAI data request execution resource file can be seen in OGSA-DAI source or binary distributions in deploy/server-config/resources/.

Example OGSA-DAI data resource files - which are used in deploying data resources - can be seen in OGSA-DAI source or binary distributions in deploy/config-blanks.

17.2.5. Resource template files

Resource template files are used to configure resources that are dynamically created at runtime. These include:

Resources created by the OGSA-DAI core e.g. session and request resources.
Resources created by resource creation activities e.g. data sources, data sinks, resource groups.

When a resource is created using a template then it is configured using the template. Resource templates have IDs. OGSA-DAI components that create resources specify the ID of the template to use.

17.2.5.1. Resource template files name and location

Resource templates are named after the type of resource they are the template for. Resource template IDs have the same format as resource IDs i.e. a namespace and a local part. Section I.3, “Default resource template IDs” lists OGSA-DAIs standard resource template IDs.

Resource template files reside in a resources directory located in the OGSA-DAI configuration files directory Section 17.2.1, “Configuration files directory”.

17.2.5.2. Resource template files format

The format for resource template files is the same as for resource files.

17.2.5.3. Resource template files example

Resource templates for the standard OGSA-DAI session, request, data source and data sink resources can be seen in OGSA-DAI source or binary distributions in deploy/server-config/resourceTemplates/.

17.2.6. Common components configuration file

The configuration of common components is specified in a common components configuration file.

	Note
	OGSA-DAI has no components that use common components configuration. However, any application-specific components developed by third-party developers may make use of this.

17.2.6.1. Common components configuration file name and location

The common components configuration file has the name config.txt and is located in the OGSA-DAI configuration files directory Section 17.2.1, “Configuration files directory”.

17.2.6.2. Common components configuration file format

The common components configuration file declares zero or more configuration values for common OGSA-DAI components.

Keys consist of a namespace and a local part e.g. SomeKey or some.other.SomeOtherKey.
Values are strings. Common components receive all values as strings. Should numbers or booleans be required then the common components can parse the string appropriately.

For example:

CONFIG
some.upper.bound=10
some.timeout=100
some.control.parameter=BIN123
some.flag=false
END

To summarise therefore, this file is of the form:

[KEY=VALUE1]*

17.2.6.3. Common components configuration file example

An example common components configuration file can be seen in OGSA-DAI source or binary distributions in deploy/server-config/config.txt.

17.2.7. Data request execution resource configuration properties

OGSA-DAI's data request execution resource supports the following engine configuration properties:

dai.concurrency.request.pool.size - number of requests that can be executed concurrently. Must be >= 1.
dai.concurrency.queue.length - length of pending requests queue. Must be >= 0 and ideally > the value of dai.concurrency.request.pool.size.

17.2.8. Data resource configuration properties and classes

OGSA-DAI provides support for the following types of data resource.

17.2.8.1. Relational data resources

OGSA-DAI data resources are configured to expose JDBC data resources using the following configuration properties and class name:

dai.driver.class - database driver class - name of JDBC database driver class.
dai.data.resource.uri - database URI - connection URI to database.
dai.login.provider - login provider - ID of OGSA-DAI login provider known to the OGSA-DAI server (see Section 18.8, “Login provider”) that is configured to provide database usernames and passwords for this resource.
Data resource class - for JDBC data resources OGSA-DAI provides the uk.org.ogsadai.resource.dataresource.jdbc.JDBCDataResource class.

17.2.8.2. XMLDB data resources

OGSA-DAI data resources are configured to expose XMLDB data resources using the following configuration properties and class name:

dai.driver.class - database driver class - name of XMLDB database driver class.
dai.data.resource.uri - database URI - connection URI to database.
dai.login.provider - login provider - ID of OGSA-DAI login provider known to the OGSA-DAI server (see Section 18.8, “Login provider”) that is configured to provide database usernames and passwords for this resource.
Data resource class - for XMLDB data resources OGSA-DAI provides the uk.org.ogsadai.resource.dataresource.xmldb.XMLDBDataResource class.

17.2.8.3. File system data resources

OGSA-DAI data resources are configured to expose file system data resources using the following configuration properties and class name:

dai.data.resource.path - path to root directory of file system resource.
Data resource class - for file system data resources OGSA-DAI provides the uk.org.ogsadai.resource.dataresource.file.FileDataResource class.

17.2.8.4. Resource group data resources

OGSA-DAI data resources are configured to expose resource groups - groups of resource IDs - using the following configuration properties and class name:

A set of entries of form:

RESOURCE-ID=RESOURCE-ID

for each resource in the group, for example:

uk.org.ogsadai.SomeResource=uk.org.ogsadai.SomeResource
uk.org.ogsadai.SomeOtherResource=uk.org.ogsadai.SomeOtherResource

Data resource class - for resource group data resources OGSA-DAI provides the uk.org.ogsadai.resource.dataresource.group.ResourceGroupDataResource class.

17.2.8.5. Third party data resources

Data resources are an OGSA-DAI extensibility point. Third party developers may implement their own data resource classes which will require implementation-specific configuration settings. The third party developers will be able to advise you of these. Please see Chapter 30, How to write a data resource for more details.

Prev	Up	Next
Chapter 16. Configuring the server	Home	Chapter 18. Advanced server configuration