Installing the OAIB server February 8, 2005 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. Joel Plutchak 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.4.2 or higher
  • Cocoa v2.0 (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.0)

Installing the OAIB server requires two main steps:

  1. Download and install the required packages.
  2. Download Cocoa (includes OAIB) and configure the OAIB server and servlet host, either by hand or with the OAIB Installer and OAIB Configuration Wizard.

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.4.2 or later.
  2. Install an RDBMS. Cocoa and OAIB were developed and tested using the MySQL v 12.22; MySQL 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. Cocoa and OAIB were developed and tested using the MySQL 3.0.16 driver, and tested using the Oracle thin driver or Java 1.4.
  4. Install a Java Servlet application. Cocoa and OAIB were developed and tested using The Apache Software Foundation's Tomcat versions 4.0.3 and 5.5.4.
  5. Download The Apache Software Foundation's Xerces XML parser.
  6. Download Cocoa (includes OAIB)
  7. Install OAIB. If you use Apache Tomcat or a similar servlet package, you can run the OAIB Installer, which will create the directories and build or move the necessary files. To run the OAIB Installer, execute the cocoa.jar file included with the OAIB distribution:
    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.dlt.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.dlt.oai.target.JDBCTarget). This is only necessary if you have developed a custom OAIB target class; by default the provided JDBCTarget class is used.
  8. 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&metadataPrefix=oai_dc
    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 use the Java-based configuration wizard included in the download. To make it easier to run, the wizard is executed using a Unix shell script in the installation directory:

    OAIConfigWizard
    The Java-based wizard requires you to have the xerces.jar and cocoa.jar files in your classpath; this is set by the shell script. If you want the wizard to verify access to the database your JDBC database driver class also needs to be accessible from the classpath.

    An annotated configuration file and dataset are included in the download for use as an example. You will have to configure OAIB to use you own data and database; doing so may require knowledge of SQL or the assistance of your local database administrator.

Current limitations and bugs

  • A package was inadvertently left out of the 2.0 release jar and src archives. A new set of files labeled 2.0b has replaced to 2.0 set as of 28-Sep-2005.
  • 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 a type and format that can be internally converted to the SQL TIMESTAMP type, 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.
  • The Configuration Wizard has an error that causes an incorrect set-column tag to be included in the output file if no column and table are specified in the set-column field. If you don't want Set support in your database remove the set-column tag from the output configuration file using a text editor before you start the OAIB server.