This page describes options for configuring and customizing your jOAI software. These instructions assume the software has already been installed according to the installation instructions.
Create a custom search page
A search client template is included with jOAI that can be used to implement a custom search page for your data provider. See the search client template section in the ODL documentation for information about using and customizing the template.
Enable access control in Tomcat (BASIC Auth)
Restrict access to the software administrative pages so that the public does not
have access to sensitive information or can change administrative settings. To enable
BASIC Auth protection for the administrative pages, do the following (Tomcat v7 or v8):
1. Uncomment the 'security-constraint' and 'login-config' elements found
in the oai "WEB-INF/web.xml" file (if needed). Assuming a default installation, this
would be located at $CATALINA_HOME/webapps/oai/WEB-INF/web.xml ($CATALINA_HOME refers to the location of the Tomcat installation).
2. Edit the default '$CATALINA_HOME/conf/tomcat-users.xml' file and define a role named 'oai_admin'
and one or more users that are assigned to this role. See the documentation in the tomcat-users.xml
file for details.
3. Start or restart Tomcat.
4. (recommended) BASIC auth does not encrypt user names and passwords sent over the Internet. To enable encryption,
configure jOAI to run under https/ssl. You may use Apache Module mod_proxy_ajp
(or the older mod_jk) to proxy the jOAI webapp through your Apache HTTP server and
configure https/ssl to the jOAI administrative pages that way
(see Apache HTTP server docs for details).
Configure UTF-8 URI encoding for Tomcat
When Tomcat decodes the URLs it receives from a browser, it normally uses ISO-8859-1 character encoding. This causes problems in the forms throughout jOAI when UTF-8 characters are used as input.
- Edit the $tomcat/conf/server.xml file at the line where the HTTP Connector is defined, which should look something like
<Connector port="8080" ... />
- Add the attribute URIEncoding="UTF-8"
<Connector port="8080" URIEncoding="UTF-8" ... />
- Restart Tomcat
If you are using mod_jk to proxy between Apache and Tomcat, you should also apply this setting for the AJP connector in your Apache mod_jk configuration:
<Connector port="8009" protocol="AJP/1.3" URIEncoding="UTF-8"/>
Configure multiple formats in the data provider
The jOAI data provider can disseminate any given metadata file in multiple formats. See Providing files in multiple formats for information about configuring this functionality.
Configure software settings
Change certain settings and behaviors in the data provider and harvester by editing the following parameters in the "web.xml" or "server.xml" files. Changes made in web.xml are overwritten when the software is re-installed. Changes made in server.xml are not overwritten. The following assumes the use of at least Tomcat 5.5.x or 6.x.
To make "web.xml" changes, use the OAI "WEB-INF/web.xml" file. Assuming a default installation, this would be located at $CATALINA_HOME/webapps/oai/WEB-INF/web.xml ($CATALINA_HOME refers to the location of the Tomcat installation).
To make "server.xml" changes, use the file in the Tomcat "conf" directory. Set up a <Context> definition inside the <Host> element for jOAI, and add context parameters as needed. For example:
<Context path="/oai" docBase="oai" debug="0" reloadable="true">
Any changes to these parameters requires a restart of Tomcat.
This parameter defines where the repository indexes and configuration files are stored on disc. These include the index of metadata files, metadata files configuration, sets information, repository name and email and other persistent data used by the data provider. By default, these are stored inside the WEB-INF directory of the jOAI installation. Set this to a directory outside of the Tomcat installation to make it easy to upgrade or reinstall jOAI while preserving your settings. You may backup and restore this directory to preserve a snapshot of data and settings. This directory must be on a local, non-network drive.
<Parameter name="repositoryData" value="/oai_data/joai_settings_and_data/repository_settings_and_data" override="false"/>
The value should be an absolute directory path.
This parameter defines where harvester indexes and configuration files are stored on disc. These include an index of harvest history, the harvest configuration and other persistent data used by the harvester. By default, these are stored inside the WEB-INF directory of the jOAI installation. Set this to a directory outside of the Tomcat installation to make it easy to upgrade or reinstall jOAI while preserving your settings. You may backup and restore this directory to preserve a snapshot of data and settings.This directory must be on a local, non-network drive.
<Parameter name="harvesterData" value="/oai_data/joai_settings_and_data/harvester_settings_and_data" override="false"/>
The value should be an absolute directory path.
This parameter defines the indexing interval for synching the data provider index with the files.
<Parameter name="updateFrequency" value="1440" override="false"/>
The value is in minutes. Set to 0 to disable automatic indexing and allow manual indexing only.
This parameter may be used to hide the 'Data Provider' and 'Harvester' administrative menus in the user interface, which may be desirable for some public installations of the software. Note that this only hides but does not disable or restrict access to those pages. See Enableing access control in Tomcat.
<Parameter name="hideAdminMenus" value="true" override="false"/>
Set to 'true' to hide the administrative menus from users.
This parameter controls when to log client (harvester) requests made to the data provider. The log is stored as an index and can be viewed from the provider status page (see Reports). The index is stored on disc and over time can grow large. To reduce or eliminate the write operations to this index use the 'FinalResumption' or 'NoLog' settings.
<Parameter name="dataProviderAccessLogLevel" value="FinalResumption" override="false"/>
Set to 'Full' to log all client interactions with the data provider. Set to 'FinalResumption' to log only client requests for the final segment of a ListRecords or ListIdentifiers request, indicating a complete harvest. Set to 'NoLog' to have no log written for client interactions with the data provider (this is the default if not set).
This parameter defines where zipped harvest files are saved to. The path specified should be relative to the context root.
An absolute path may also be specified, however this will mean the zip files will not be available for download via the web-based UI.
<Parameter name="zippedHarvestsDirectory" value="admin/zipped_harvests" override="false"/>
This parameter defines the scheme, hostname and port for the server, which is displayed in the base URL for the
data provider and elsewhere, for example http://www.example.org or http://www.example.org:8080.
If the value '[determine-from-client]' is supplied (default), then the scheme, hostname and port number will be
determined by examining the URL that was requested by the client. Note that when using mod_proxy with Apache, Tomcat must be configured properly in order for this mechanism to work. Refer to the Tomcat proxy how to documentation for information about configuring Tomcat for use with mod_proxy.
<Parameter name="serverUrl" value="http://www.example.org" override="false"/>
Additional configuration opations
See the jOAI web.xml file for notes and comments that describe additional configuration options.
See the build instructions for detailed infromation about obtaining the source code and building jOAI using Ant.