Configuring and Testing OAICatMuseum with a sample MySQL database using JDBC

These notes describe how to configure and test the OAICatMuseum repository 
application with a sample MySQL database using JDBC.  These instructions are 
intended to establish a baseline Tomcat/MySQL configuration and confirm that 
JDBC access is available from the OAICatMuseum application.  


- Setup a Tomcat server

Download, install, and test Tomcat. Download from 

	http://tomcat.apache.org/download-55.cgi. 
	
Detailed installation instructions can be found at 
http://www.coreservlets.com/Apache-Tomcat-Tutorial/; for Mac OS X detailed 
instructions are at http://developer.apple.com/internet/java/tomcat1.html. 


- Install a MySQL server

The MySQL Community Server software can be downloaded from 

	http://dev.mysql.com/downloads/mysql/5.0.html
	
Your MySQL server installation must be on a system that is accessible from the 
OAICatMuseum Tomcat server.


- Create a sample MySQL database

A sample database can be created from a database dump file named oaicatdb.sql, 
available along with the OAICatMuseum distribution from OCLC.
 
It can be imported as a new database in your MySQL server; it will define the 
required tables and load sample records and associated sets.  For example, to 
create a database named oaicatdb:

mysqladmin –u [user] -p create oaicatdb

then import the .sql file to create tables and add values:

mysql -u [user] -p oaicatdb < oaicatdb.sql


- Download and install the OAICatMuseum application

Copy the oaicatmuseum.war file distributed by OCLC to the Tomcat server's webapps 
folder, then restart the Tomcat server.  After restarting, the application files 
should be found in Tomcat's webapps/oaicatmuseum folder.   


- Install a MySQL JDBC Driver

The preferred JDBC Driver is "Connector/J", which can be downloaded free of 
charge from mysql.com and used under the terms of the GNU General Public License.

	http://dev.mysql.com/downloads/connector/j/5.1.html

Once downloaded, you should have a Java Archive (.jar) file for the Connector/J 
driver, e.g., "mysql-connector-java-5.1.6-bin.jar".  Copy it to the common/lib 
folder of your Tomcat server.  

Restart the Tomcat server for the MySQL driver to be recognized.


- Configure oaicat.properties
 
Settings for your installation of OAICatMuseum are made in the oaicat.properties 
file, found in the oaicatmuseum/WEB-INF/classes folder.  After making a backup 
copy of the file, make these changes to logon to your MySQL server and locate 
your database:

1. Change JDBCLimitedOAICatalog.jdbcURL to the path to your MySQL database, e.g., 
jdbc:mysql://localhost:3306/oaicatdb (you’ll need to set the hostname, port, 
and database name to match your MySQL Server and database)
2. Change JDBCLimitedOAICatalog.jdbcLogin to the username for your MySQL server
3. Change JDBCLimitedOAICatalog.jdbcPasswd to the password for your MySQL server

The OAI-PMH standard requires that data is delivered in UTF-8.  If your MySQL  
data is encoded in Latin-1, the OAICatMuseum application can automatically
transform it to UTF-8.  In that case, change this oaicat.properties setting 
to "1":
JDBCOAICatalog.latin1

In addition, you should edit these properties:
1. Identify.repositoryName – A title for your repository 
2. Identify.adminEmail – The email address of a contact person 
3. Identify.earliestDatestamp - Set to the earliest datestamp in your collection
4. Identify.description – Description details about your collection.  In 
particular, you should modify the repositoryIdentifier and sampleIdentifier fields 
to include a unique identifier for your institution, rather than the default value 
oaicat.oclc.org. 


- Restart and Test

Once all the JDBC driver, Tomcat, OAICat, and MySQL changes have been made, 
restart TomCat, start the MySQL server, and begin testing access to the database.  

The "index.html" file in the OAICatMuseum Tomcat root directory provides an 
interface to various OAI-PMH commands.  For those requests that require a 
metadata prefix to be supplied, use "oai_dc" or "cdwalite".

For example, test the OAI-PMH Identify response with

	http://localhost:8080/oaicatmuseum/identify.html
	
if you have installed Tomcat on the same machine as your web client and are 
using port 8080 for Tomcat; otherwise, test it at 

	http://DOMAIN:PORT/oaicatmuseum/identify.html 
	
where "DOMAIN" is the domain name or IP address of your server and PORT is its 
port address for Tomcat, if not the default http port (80).