FRED Appropriate Copy Toolkit

The OpenURL + Handle Sample Implementation toolkit implements the OpenURL standard for context-sensitive web services as an Appropriate Copy delivery mechanism; it uses the Handle system as its registry of content instances. The implementation is described in the OpenURL + Handle Service Usage Model.

The implementation was based on the OCLC OpenURL framework, under the Common Development and Distribution License (CDDL). The implementation uses the JBoss Rules business rule engine, under the Apache Open Source License.

1. Download

The toolkit is available here (15.0 MB) as version 1.0, 2007-08-03, under Mozilla Public License 1.1. This software is copyrighted to the University of Southern Queensland.

2. Requirements

Apache Tomcat 5.x or later
- Note: The Tomcat server bundled with Fedora is also suitable
Apache Ant to install from source code
Optional: JDBC compatible database such as MySQL for global to local identifier mapping

3. Installation

Currently, this service must be installed from source as it requires build time configuration.

Get the source from: http://fred.usq.edu.au/svn/repos/openurl/trunk
```
svn co http://fred.usq.edu.au/svn/repos/openurl/trunk openurl
```
There are a few configuration files in the src/java directory to modify according to your environment. See the following section for details.
- openurl.properties
- Rule set files: *.drl, *.dsl
- jdbc-lookup.properties
Use Ant to build the web archive package
```
cd openurl
ant dist
```
Copy the package to the Tomcat webapps directory

4. Configuration

General

This general OpenURL resolver properties are specified in the src/java/openurl.properties file. The following table describes the configurable properties.

Property	Description	Comments
rules.drl	The rule set for determining repository location
rules.dsl	The domain language for the rule set as above	Recommended to use the supplied vocabulary
services.drl	The rule set for services (OpenURL svc parameters)
services.dsl	The domain language	Recommended to use the supplied vocabulary
lookup.service	The lookup service to use	See below for the available lookup services
multi.resolve.stylesheet	The XSL stylesheet used for multiple resolution results

Rule set

For general information about the rule set, see the documentation.

To use the rule sets, the rules file must be created in the src/java directory prior to building the web package. Also ensure the appropriate properties are set correctly in openurl.properties.

Lookup service

The lookup service is used to map global identifiers to local identifiers, after the base URL is determined by the repository rule set. There are currently 2 available services as described below.

Handle

To use this service specify au.edu.usq.fred.openurl.HandleLookup as the lookup.service. This will use the global handle resolver to lookup the URLs for the specified Handle identifier. There is currently no further configuration for this service.

JDBC

To use this service specify au.edu.usq.fred.openurl.JdbcLookup as the lookup.service. Then the configuration is done through the src/java/jdbc-lookup.properties file. The table below describes the available properties.

Property	Description	Comment
driver	The JDBC driver to use	For MySQL this is set to `com.mysql.jdbc.Driver`
jdbc.url	The JDBC URL for the database	For MySQL this is something like `jdbc:mysql://localhost/fred`
username	Database user login
password	Database user password
table	The table used for the lookup
global.id	Global identifier column
url	Object URL	A full URL to the object identifier by the global identifer

All the columns are string types, a sample database schema would be:

 CREATE TABLE LOOKUP (
  GLOBAL_ID VARCHAR2(255),
  BASE_URL VARCHAR2(255));

5. Ruleset Documentation

The OpenURL resolver uses a business rule engine (currently JBoss Rules) for processing OpenURL queries. Using a rule engine allows the business logic to be separated from the toolkit which allows for easy deployment to different federations.

A rule set has been created for the sample approriate copy usage scenarios. The current implementation of the resolver uses a rule set to determine which repository an object is located (i.e. the repositories base URL). This is then followed by a lookup to map the global identifier to the local object's identifier. The rules are defined by two files:

Scenarios.drl: Rule set

This file is where the business logic is written and applied. Rules are written as if-then scenarios, for example:

rule "Affiliation Boeing and Location Melbourne"
 when
    Requester affiliation is "boeing"
    Requester location is "mel"
  then
    Set base URL to "http://emeraldcity.boeing.example.com"
end

The above rule states that when the requester is affiliated with "boeing" and is located in "mel", then the object is located in the repository at "http://emeraldcity.boeing.example.com". Note how the rules are written in english-like expressions, this is handled by the domain specific language or DSL as described below.

Scenarios.dsl: Domain specific language

This file maps "human readable" predicates to a corresponding rule expression. For example:

[when]Requester location is "{location}"=request: FmtFredReq(location == "{location}");

The part surrounded by curly braces {} is a variable, which is substituted when evaluating the expression. The expression itself is checking that the "location" property of the "FmtFredReq" object is equal to the specified location.

More information about writing rules can be found in the JBoss Rules documentation