Prev Part I. Administrator Documentation Next

Chapter 16. Configuring the server

16.1. Configuring the server
16.1.1. Creating a resource file
16.1.2. Deploying a resource
16.1.3. Configuring database logins
16.1.4. Data resource configuration and deployment in one go
16.1.5. Deploying a resource template
16.1.6. Undeploying a resource
16.1.7. Logging
16.1.8. Deploying an activity
16.1.9. Extending the supported activities of a resource
16.1.10. Configuring common components

16.1. Configuring the server

[Note]Note
These instructions assume that the OGSA-DAI's default file-based persistence and configuration components are being used on the server. If this is not the case and third-party components are being used then consult the documentation for these third-party components.

16.1.1. Creating a resource file

Before deploying a resource you need to create a resource file. Information about resource files is described in Section 17.2.4, “Resource Files”. The name of the resource when deployed will be the same as the name of this file.

However if you want to use OGSA-DAI's standard relational, XMLDB or file system data resources we provide a set of commands allowing the required resource files to be created automatically.

16.1.1.1. Creating a relational resource file

To create a relational resource file run the createRelationalConfig command. This takes the following arguments:

  • dai.db.product - optional argument specifying the database product name.
  • dai.db.vendor - optional argument specifying the database product vendor.
  • dai.db.version - optional argument specifying the database product version.
  • dai.db.uri - database connection URI. See Section 3.3, “Data resource URIs”.
  • dai.db.driver - database driver class name. See Section 3.2, “Data resource drivers”.
  • dai.resource.id - data resource ID. The ID of the data resource that exposes the relational database. The resource file will have this ID as its name.

i.e. 

$ ant -Ddai.db.product=PRODUCT -Ddai.db.vendor=VENDOR -Ddai.db.version=VERSION \ 
  -Ddai.db.uri=DATABASE-URI -Ddai.db.driver=DATABASE-DRIVER-CLASS \
  -Ddai.resource.id=RESOURCE-ID createRelationalConfig

For example the following creates a resource configuration for an OGSA-DAI data resource called MySQLDataResource which exposes a MySQL database: 

$ ant -Ddai.db.product=MySQL -Ddai.db.vendor=MySQL -Ddai.db.version=5 \
 -Ddai.db.uri=jdbc:mysql://somehost:3306/daitest \
 -Ddai.db.driver=org.gjt.mm.mysql.Driver \
 -Ddai.resource.id=MySQLDataResource createRelationalConfig

As an alternative to specifying the arguments at the command-line you could use an ANT property file - see the FAQ Section C.1.3, “How can I avoid specifing lots of properties for ANT targets at the command-line?”.

16.1.1.2. Creating an XMLDB resource file

To create an XMLDB resource file run the createXMLDBConfig command. This takes the following arguments:

  • dai.db.product - optional argument specifying the database product name.
  • dai.db.vendor - optional argument specifying the database product vendor.
  • dai.db.version - optional argument specifying the database product version.
  • dai.db.uri - database connection URI. See Section 3.3, “Data resource URIs”.
  • dai.db.driver - database driver class name. See Section 3.2, “Data resource drivers”.
  • dai.resource.id - data resource ID. The ID of the data resource that exposes the XMLDB database. The resource file will have this ID as its name.

i.e. 

$ ant -Ddai.db.product=PRODUCT -Ddai.db.vendor=VENDOR -Ddai.db.version=VERSION \ 
  -Ddai.db.uri=DATABASE-URI -Ddai.db.driver=DATABASE-DRIVER-CLASS \
  -Ddai.resource.id=RESOURCE-ID createXMLDBConfig

For example the following creates a resource configuration for an OGSA-DAI data resource called ExistDataResource which exposes an eXist database: 

$ ant -Ddai.db.product=eXist -Ddai.db.vendor=eXist -Ddai.db.version=1.1.1 \
 -Ddai.db.uri=xmldb:exist://somehost:9120/exist/xmlrpc/db/littleblackbook \
 -Ddai.db.driver=org.exist.xmldb.DatabaseImpl \
 -Ddai.resource.id=ExistDataResource createXMLDBConfig

As an alternative to specifying the arguments at the command-line you could use an ANT property file - see the FAQ Section C.1.3, “How can I avoid specifing lots of properties for ANT targets at the command-line?”.

16.1.1.3. Creating a file system resource file

To create an file system resource file run the createFileSystemConfig command. This takes the following arguments:

  • dai.db.file.path - path to base directory of file system resource. See Section 3.3, “Data resource URIs”.
  • dai.resource.id - data resource ID. The ID of the data resource that exposes a file system directory. The resource file will have this ID as its name.

i.e. 

$ ant -Ddai.db.file.path=PATH -Ddai.resource.id=RESOURCE-ID createFileSystemConfig

For example the following creates a resource configuration for an OGSA-DAI data resource called FileSystemDataResource which exposes a part of a file system: 

$ ant -Ddai.db.file.path=/home/user/my-file-resource-root
 -Ddai.resource.id=FileSystemDataResource createFileSystemConfig

As an alternative to specifying the arguments at the command-line you could use an ANT property file - see the FAQ Section C.1.3, “How can I avoid specifing lots of properties for ANT targets at the command-line?”.

16.1.2. Deploying a resource

To deploy a new resource onto the OGSA-DAI server do the following:

  1. Write a resource file for your new resource, see Section 16.1.1, “Creating a resource file” for more details. The name of the resource when deployed will be the same as the name of this file.
  2. If the resource implementation classes and any required database driver classes are not already in a JAR on the server then you should create a temporary directory containing these JARs. For example: 
    $ mkdir tmpResourceDir
$ cp my-resource.jar tmpResourceDir
$ cp some-driver.jar tmpResourceDir
  3. To deploy a new resource run the deployResource command.
    • This takes the following arguments:
      • dai.resource.jar.dir - location of directory containing any required database driver JARs and resource implementation JARs. If all the required JARs are already on the server then this value can be omitted.
      • dai.resource.file - the path to the resource file.
    • If using OGSA-DAI Axis on Tomcat run: 
      $ ant -Dtomcat.dir=/PATH/TO/TOMCAT \
  -Ddai.resource.jar.dir=RESOURCE-JAR-DIR \
  -Ddai.resource.file=/PATH/TO/RESOURCE-FILE deployResource
      This takes the following arguments:
      • tomcat.dir - location of OGSA-DAI Axis on Tomcat deployment on Tomcat.
      For example 
      $ ant -Dtomcat.dir=/home/user/tomcatAxis \
  -Ddai.resource.jar.dir=tmpResourceDir \
  -Ddai.resource.file=/home/user/MyResource deployResource

16.1.3. Configuring database logins

For data resources - depending upon the data resource class and the login provider used - you may need to add or remove mappings from the caller's identity or attributes or distinguished name to database user names and passwords.

16.1.3.1. Adding database logins

If using the OGSA-DAI file-based login provider then the mappings can be added using the permit command. This takes the following arguments:

  • dai.resource.id - ID of data resource for which the login mapping is to be added.
  • dai.dn - distinguished name. Optional. If omitted the default of ANY is used. If ANY is provided or used then any DN will map to the username and password for the resource (note that in the actual login configuration files this becomes a *).
  • dai.user - username compliant with the database exposed by the data resource whose ID is the value of dai.resource.id
  • dai.password - password associated with the above username.
  • If using OGSA-DAI Axis on Tomcat run: 
    $ ant -Dtomcat.dir=/PATH/TO/TOMCAT \
  -Ddai.resource.id=RESOURCE-ID \
  -Ddai.dn=DN -Ddai.user=USER -Ddai.password=PASSWORD permit
    This takes the following arguments:
    • tomcat.dir - location of OGSA-DAI Axis deployment on Tomcat.
    For example 
    $ ant -Dtomcat.dir=/home/user/tomcatAxis \
  -Ddai.resource.id=MyJDBCResource \
  -Ddai.dn="/C=US/O=Music/OU=Band/L=Bangles/CN=susanna hoffs" \
  -Ddai.user=someDBUser -Ddai.password=123xyz456 permit

As an alternative to specifying the arguments at the command-line you could use an ANT property file - see the FAQ Section C.1.3, “How can I avoid specifing lots of properties for ANT targets at the command-line?”.

16.1.3.2. Removing database logins

If using the OGSA-DAI file-based login provider then the mappings can be removed using the deny command. This takes the following arguments:

  • dai.resource.id - ID of data resource for which the login mapping is to be removed.
  • dai.dn - distinguished name specifying the mapping to be removed. Optional. If omitted the default of ANY is used (note that in the actual login configuration files this corresponds to a *).
  • If using OGSA-DAI Axis on Tomcat run: 
    $ ant -Dtomcat.dir=/PATH/TO/TOMCAT \
  -Ddai.resource.id=RESOURCE-ID -Ddai.dn=DN deny
    This takes the following arguments:
    • tomcat.dir - location of OGSA-DAI Axis deployment on Tomcat.
    For example 
    $ ant -Dtomcat.dir=/home/user/tomcatAxis \
  -Ddai.resource.id=MyJDBCResource \
  -Ddai.dn="/C=US/O=Music/OU=Band/L=Bangles/CN=susanna hoffs" deny

As an alternative to specifying the arguments at the command-line you could use an ANT property file - see the FAQ Section C.1.3, “How can I avoid specifing lots of properties for ANT targets at the command-line?”.

16.1.4. Data resource configuration and deployment in one go

Convenience commands are provided that allow the creation of resource configurations for relational, XMLDB or file system resources, the deployment of these resources onto an OGSA-DAI server and then (for relational and XMLDB resources) the configuration of database login information. These commands just take invoke the commands described in Section 16.1.1, “Creating a resource file”, Section 16.1.2, “Deploying a resource” and Section 16.1.3.1, “Adding database logins”.

16.1.4.1. Relational data resource configuration and deployment in one go

To configure and deploy a relational resource do the following:

  1. If the resource implementation classes and any required database driver classes are not already in a JAR on the server then you should create a temporary directory containing these JARs. For example: 
    $ mkdir tmpResourceDir
$ cp my-resource.jar tmpResourceDir
$ cp some-driver.jar tmpResourceDir
  2. Write an ANT properties file called, for example, my.resource.config. This is a file of the form: 
    dai.resource.id=RESOURCE_ID
dai.db.product=PRODUCT_NAME
dai.db.vendor=VENDOR
dai.db.version=VERSION
dai.db.uri=DATABASE_URI
dai.db.driver=DATABASE_DRIVER_CLASS_NAME
dai.resource.jar.dir=DATABASE_DRIVER_JAR_DIRECTORY
dai.dn=DN
dai.user=DATABASE_USER_NAME
dai.password=DATABASE_PASSWORD
    Where each property has values as follows:
    • dai.resource.id - data resource ID. The ID of the data resource that exposes the relational database. The resource file will have this ID as its name.
    • dai.db.product - optional argument specifying the database product name.
    • dai.db.vendor - optional argument specifying the database product vendor.
    • dai.db.version - optional argument specifying the database product version.
    • dai.db.uri - database connection URI. See Section 3.3, “Data resource URIs”.
    • dai.db.driver - database driver class name. See Section 3.2, “Data resource drivers”.
    • dai.resource.jar.dir - location of directory containing any required database driver JARs and resource implementation JARs. If all the required JARs are already on the server then this value can be omitted.
    • dai.dn - distinguished name. Optional. If omitted the default of ANY is used. If ANY is provided or used then any DN will map to the username and password for the resource (note that in the actual login configuration files this becomes a *).
    • dai.user - username compliant with the database.
    • dai.password - password associated with the above username.
    For example: 
    dai.resource.id=MySQLDataResource
dai.db.product=MySQL
dai.db.vendor=MySQL
dai.db.version=5
dai.db.uri=jdbc:mysql://somehost:3306/daitest
dai.db.driver=org.gjt.mm.mysql.Driver
dai.dn="/C=US/O=Music/OU=Band/L=Bangles/CN=susanna hoffs"
dai.resource.jar.dir=tmpResourceDir
dai.user=someDBUser 
dai.password=123xyz456
  3. Run the deployRelationalResource command.
    • This command:
      1. Creates a relational resource configuration file.
      2. Deploys this resource.
      3. Adds a mapping from a distinguished name to a database user name and password for this resource.
    • If using OGSA-DAI Axis on Tomcat run: 
      $ ant -Dtomcat.dir=/PATH/TO/TOMCAT -propertyfile PROPERTY_FILE \
      deployRelationalResource
      This takes the following arguments:
      • tomcat.dir - location of OGSA-DAI Axis deployment on Tomcat.
      For example 
      $ ant -Dtomcat.dir=/home/user/tomcatAxis -propertyfile my.resource.config \
      deployRelationalResource

16.1.4.2. XMLDB data resource configuration and deployment in one go

To configure and deploy an XMLDB resource do the following:

  1. If the resource implementation classes and any required database driver classes are not already in a JAR on the server then you should create a temporary directory containing these JARs. For example: 
    $ mkdir tmpResourceDir
$ cp my-resource.jar tmpResourceDir
$ cp some-driver.jar tmpResourceDir
  2. Write an ANT properties file called, for example, my.resource.config. This is a file of the form: 
    dai.resource.id=RESOURCE_ID
dai.db.product=PRODUCT_NAME
dai.db.vendor=VENDOR
dai.db.version=VERSION
dai.db.uri=DATABASE_URI
dai.db.driver=DATABASE_DRIVER_CLASS_NAME
dai.resource.jar.dir=DATABASE_DRIVER_JAR_DIRECTORY
dai.dn=DN
dai.user=DATABASE_USER_NAME
dai.password=DATABASE_PASSWORD
    Where each property has values as follows:
    • dai.resource.id - data resource ID. The ID of the data resource that exposes the XMLDB database. The resource file will have this ID as its name.
    • dai.db.product - optional argument specifying the database product name.
    • dai.db.vendor - optional argument specifying the database product vendor.
    • dai.db.version - optional argument specifying the database product version.
    • dai.db.uri - database connection URI. See Section 3.3, “Data resource URIs”.
    • dai.db.driver - database driver class name. See Section 3.2, “Data resource drivers”.
    • dai.resource.jar.dir - location of directory containing any required database driver JARs and resource implementation JARs. If all the required JARs are already on the server then this value can be omitted.
    • dai.dn - distinguished name. Optional. If omitted the default of ANY is used. If ANY is provided or used then any DN will map to the username and password for the resource (note that in the actual login configuration files this becomes a *).
    • dai.user - username compliant with the database.
    • dai.password - password associated with the above username.
    For example: 
    dai.resource.id=ExistDataResource
dai.db.product=eXist
dai.db.vendor=eXist
dai.db.version=1.1.1
dai.db.uri=xmldb:exist://somehost:9120/exist/xmlrpc/db/littleblackbook
dai.db.driver=org.exist.xmldb.DatabaseImpl
dai.dn=/C=US/O=Music/OU=Band/L=Bangles/CN=susanna hoffs
dai.resource.jar.dir=tmpResourceDir
dai.user=someDBUser
dai.password=123xyz456
  3. Run the deployXMLDBResource command.
    • This command:
      1. Creates an XMLDB resource configuration file.
      2. Deploys this resource.
      3. Adds a mapping from a distinguished name to a database user name and password for this resource.
    • If using OGSA-DAI Axis on Tomcat run: 
      $ ant -Dtomcat.dir=/PATH/TO/TOMCAT -propertyfile PROPERTY_FILE \
      deployXMLDBResource
      This takes the following arguments:
      • tomcat.dir - location of OGSA-DAI Axis deployment on Tomcat.
      For example 
      $ ant -Dtomcat.dir=/home/user/tomcatAxis -propertyfile my.resource.config \
      deployXMLDBResource

16.1.4.3. File system data resource configuration and deployment in one go

To configure and deploy a file system resource do the following: run the deployFileSystemResource command. This command:

  1. Creates a file system resource configuration file.
  2. Deploys this resource.
  3. Adds a mapping from a distinguished name to a database user name and password for this resource.

The command takes the following arguments

  • dai.resource.id - data resource ID. The ID of the data resource that exposes the file system. The resource file will have this ID as its name.
  • dai.db.file.path - path to base directory of file system resource. See Section 3.3, “Data resource URIs”.
  • If using OGSA-DAI Axis on Tomcat run: 
    $ ant -Dtomcat.dir=/PATH/TO/TOMCAT \
  -Ddai.resource.id=RESOURCE-ID \
  -Ddai.db.file.path=PATH deployFileSystemResource
    This takes the following arguments:
    • tomcat.dir - location of OGSA-DAI Axis deployment on Tomcat.
    For example 
    $ ant -Dtomcat.dir=/home/user/tomcatAxis \
  -Ddai.resource.id=FileSystemDataResource \
  -Ddai.db.file.path=/home/user/my-file-resource-root deployFileSystemResource
  • As an alternative to specifying the arguments at the command-line you could use an ANT property file - see the FAQ Section C.1.3, “How can I avoid specifing lots of properties for ANT targets at the command-line?”.

16.1.5. Deploying a resource template

The process for deploying resource templates is the same as for deploying resources but with a -Ddai.resource.template flag being set to value true when running the deployResource command.

For example if using OGSA-DAI Axis an example is: 

$ ant -Dtomcat.dir=/home/user/tomcatAxis \
   -Ddai.resource.jar.dir=myResourceJAR \
   -Ddai.resource.file=MyResource \
   -Ddai.resource.template=true deployResource

16.1.6. Undeploying a resource

To undeploy a resource from the OGSA-DAI server:

  1. Delete the resource file from the resources directory.
  2. Restart your container.

16.1.7. Logging

OGSA-DAI uses Apache Log4J for logging. There are five types of log message:

  • DEBUG for all log messages possible, including debug messages for developers plus log messages of the types below. As this produces a lot of log messages, this level of logging is only recommended if serious problems are encountered.
  • INFO for all standard OGSA-DAI status messages, plus log messages of the types below.
  • WARN for warnings, plus log messages of the types below.
  • ERROR for error messages, plus log messages of the type below
  • FATAL for fatal errors only.
  • If using OGSA-DAI Axis on Tomcat the OGSA-DAI logs are located in: 
    /PATH/TO/TOMCAT/logs/catalina.out

16.1.7.1. Changing the logging level

To change the logging level of OGSA-DAI you need to edit the Log4J properties file on the server.

  1. Edit the log4j.properties file on the server.
    • If using OGSA-DAI Axis on Tomcat this file is in: 
      /PATH/TO/TOMCAT/webapps/dai/WEB-INF/classes/log4j.properties
  2. Insert, or if there is one already present, edit the line: 
    log4j.category.uk.org.ogsadai=LOG-LEVEL
    where LOG-LEVEL should be replaced by one of:
    • DEBUG
    • INFO
    • WARN
    • ERROR
    • FATAL
  3. You will have to restart your container for the changes to take effect.

16.1.8. Deploying an activity

To deploy a new activity onto an OGSA-DAI server do the following:

  1. If the activity class is not already in a JAR on the server then you should create a temporary directory containing this JAR. For example: 
    $ mkdir tmpActivityDir
$ cp my-activity.jar tmpActivityDir
  2. To deploy a new activity run the deployActivity command.
    • This takes the following arguments:
      • dai.activity.jar.dir - location of directory containing the activity implementation class. If the activity implementation class is already on the server then this value can be omitted.
      • dai.activity.id - activity ID. Unique ID by which the activity is known on the server.
      • dai.activity.class - name of activity implementation class.
      • dai.activity.description - human-readable description of the activity. This value is optional.
    • If using OGSA-DAI Axis on Tomcat run: 
      $ ant -Dtomcat.dir=/PATH/TO/TOMCAT \
  -Ddai.activity.jar.dir=ACTIVITY-JAR-DIR -Ddai.activity.id=ACTIVITY-ID \
  -Ddai.activity.class=ACTIVITY-CLASS \
  -Ddai.activity.description=ACTIVITY-DESCRIPTION deployActivity
      This takes the following arguments:
      • tomcat.dir - location of OGSA-DAI Axis deployment on Tomcat Tomcat.
      For example 
      $ ant -Dtomcat.dir=/home/user/tomcatAxis \
  -Ddai.activity.jar.dir=tmpActivityDir -Ddai.activity.id=MyActivityID \
  -Ddai.activity.class=org.my.ActivityClass \
  -Ddai.activity.description="This is my new activity" deployActivity
    • As an alternative to specifying the arguments at the command-line you could use an ANT property file - see the FAQ Section C.1.3, “How can I avoid specifing lots of properties for ANT targets at the command-line?”.
  3. If you are deploying an activity that creates resources then you might also (depending upon the activity implementation) need to deploy a resource template file for these resources, see Section 16.1.2, “Deploying a resource” for more details.

16.1.9. Extending the supported activities of a resource

To update a resource to support an activity do the following:

  1. Ensure that the activity is deployed and available on the OGSA-DAI server, see Section 16.1.8, “Deploying an activity” fore more details.
  2. To update a resource to support an activity run the exposeResourceActivity command.
    • This takes the following arguments:
      • dai.resource.id - resource ID. The ID of the resource that is to expose, or support, the activity. This resource must be compliant with the activity e.g. JDBC data resources are compliant with relational activities.
      • dai.activity.id - activity ID. Unique ID by which the activity is known on the server and as recorded in the activity configuration file.
      • dai.activity.name - activity name. Name by which the resource will expose the activity. This can be equal to the activity ID if desired.
      • dai.resource.template - optional flag indicating if it is an actual resource (false) or a resource template (true) to be updated. If ommitted the default value of false is used.
    • If using OGSA-DAI Axis on Tomcat run: 
      $ ant -Dtomcat.dir=/PATH/TO/TOMCAT \
      -Ddai.resource.id=RESOURCE-ID \
      -Ddai.activity.id=ACTIVITY-ID \
      -Ddai.activity.name=ACTIVITY-NAME \
      exposeResourceActivity
      This takes the following arguments:
      • tomcat.dir - location of OGSA-DAI Axis deployment on Tomcat.
      For example 
      $ ant -Dtomcat.dir=/home/user/tomcatAxis \
      -Ddai.resource.id=MySQLDataResource \
      -Ddai.activity.id=uk.org.ogsadai.SQLQuery \
      -Ddai.activity.name=uk.org.ogsadai.SQLQuery \
      exposeResourceActivity
    • As an alternative to specifying the arguments at the command-line you could use an ANT property file - see the FAQ Section C.1.3, “How can I avoid specifing lots of properties for ANT targets at the command-line?”.
  3. Restart your container.

16.1.10. Configuring common components

To configure a common component:

  1. Update the common components configuration file and provide entries for the required configuration properties, see Section 17.2.6, “Common components configuration file” fore more details.

[Note]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.

Prev Up Next
Chapter 15. Checking the server Home Chapter 17. Server configuration files