Installing the OAIB Open Archives (OAI) Server

OAIB (Open Archives "in a box") is an easy-to-use application for exporting metadata stored in a relational database management system (RDBMS) over the Open Archives Initiative protocol for metadata harvesting.

Requirements

• Java 1.2.2 or higher
• Cocoa v0.4 (Components for Constructing Open Archives)
• An SQL database with JDBC driver
• A Java Servlet implementation, such as Apache Tomcat.
• The Apache Xerces XML parser.

Installing OAIB (version 2 beta)

The following steps assume none of the required software is loaded on your computer. If you already have the required software and versions installed, skip the corresponding step.

1. Install Java, version 1.2.2 or later.
2. Install an RDBMS. Cocoa and OAIB were developed and tested using MySQL, which can be found at http://www.mysql.com/. If your SQL database allows remote connections, it is not necessary for it to be located on the same computer as the OAIB servlet.
3. Locate a JDBC driver for your RDBMS.
4. Install a Java Servlet application. Cocoa and OAIB were developed and tested using The Apache Software Foundation's JServ and most recently Jakarta Tomcat versions 3.3-b2 and 4.0.3.
5. Install The Apache Software Foundation's Xerces XML parser.
6. Install Cocoa. If you use Apache Tomcat or a similar servlet package, you can run the OAIBInstaller, which will create the directories and build or move the necessary files. To run the Installer, download the cocoa.jar file, and execute it:

   java -jar cocoa.jar

   You will have to either create the configuration file (see below) beforehand, or use a stand-in file and tailor it to your installation before starting the servlet.

   If your servlet engine uses WAR files you can still use the Installer. Create a new temporary directory and use it as the servlet directory. After the Installer completes create a WAR file from the temporary directory and install it according to your package documentation.

   Otherwise, install the servlet as required by your software:

   • Add cocoa.jar as a library for the servlet;
   • Add the ncsa.emerge.oai.server.JDBCServer class file as the main application class file for the servlet;
   • Add the following parameters to the servlet:
     • config-file - the name of the configuration file specified as a either a file name with preceding path separator, or a complete URL.
     • targetClass - the fully-qualified name of the target class (e.g., ncsa.emerge.oai.target.JDBCTarget). This is only necessary if you have developed a custom OAIB target class; by default the provided JDBCTarget class is used.
7. Test the installation. The exact syntax depends on your servlet engine and where you installed the servlet. Use a web browser to enter OAI requests such as:

   http://your.server.org/servletpath/servletname?verb=Identify
   http://your.server.org/servletpath/servletname?verb=ListIdentifiers
   

   You should receive OAI responses in XML format.

Notes

• SQL

  The JDBC driver class file for the SQL database must be in the library directory of the servlet.

  The database server must be up and running in order for the servlet to return data.

• Cocoa

  The Cocoa JAR file must be in the library directory or the root directory of the class files for the expanded cocoa.jar must be in the classes directory of the servlet.

• OAIB

  The OAIB configuration file must be specified in the servlet's config-file parameter, and must be valid XML with the required tags defined. In particular, the JDBC connection URL is correct, the user and password (if necessary) are valid for accessing the data, etc.

  In order to create a configuration file, either create the file by hand, or download and run the Java-based configuration wizard:

  java OAIConfigWizard

  The java-based wizard requires you to have the xerces.jar and cocoa.jar files in your classpath. If you want the wizard to verify access to the database your JDBC database driver class also needs to be accessible.

  An annotated version 0.2 example configuration file for the test database is available to use as an example.

Current limitations and bugs

• There must be a single column in the database that acts is a unique key and will act as the OAI identifier.
• A date field (of type DATE) is also required in order to meet the OAI requirement of a modification date.
• The configuration file must contain non-empty admin-email and repository-name elements. This is required by the OAI specification but not strictly enforced by OAIB.
• To use the default JDBCTarget class, your SQL must support the LIMIT keyword for queries.