Dublin Core Metadata Initiative logo
The Dublin Core Metadata Registry
About
Browse | Search
SPARQL
Administration
Help

v 3.3.8

Installation Guide

The Dublin Core Metadata Initiative's (DCMI) Metadata Registry is an application designed to promote the discovery and reuse of exiting metadata definitions. Discovery and reuse are essential to standardization, and promote greater interoperability between metadata element sets.

The DCMI Metadata Registry provides users and applications with an authoritative source of information about the Dublin Core element set and related vocabularies. This information is intended to simplify the discovery of terms, and their definitions, and to illustrate the relationship between terms.

This document describes the steps that are necessary to install a DCMI metadata registry.

 

Contents

I. Overview
II. Installing The Base Software
2.1 Java
2.2 Apache HTTP Server
2.3 Jakarta Tomcat Application Server
2.4 Jakarta Ant
2.5 PostgreSQL
2.6 Jena
2.7 Axis
2.8 WSIL4J
2.9 UDDI4J
III. Setting Your Environment Variables
IV. Configuring Tomcat
4.1 Deploy The Java Properties File
4.2 Load The JAR files
4.3 Configure the Apache-Tomcat mod_jk Connector (optional)
V. Download The Project Source
VI. Building The Application
6.1 The Application Configuration Property File
6.2 Building and Deploying
VII. Creating And Loading The Database
VIII. Enabling The Axis (SOAP) Application Interface
8.1 Deploy The Services
8.2 Enable Service Discovery
IX. Installation Verification
Appendix A: Project Directory
Appendix B: Sample WSIL Document

 

I. Overview

The DCMI registry was developed, and is distributed, as an open-source project. It is built entirely upon open-source / open-standards software. The registry is a Java application, and as such, can be run on any platform that can run Java. That being said, the application was developed on Linux, and the installation instructions described in this document are intended for installation on a Linux platform. While it is possible to run the application on other operating systems (i.e., Windows), this has not been tested. It is reasonable to expect a modest number of changes to the application configuration to enable this degree of portability.

Since the application is built upon open standards it is also possible to replace core components of the underlying architecture with functionally-equivelent replacements. For example, the registry was developed using the Jakarta Tomcat application server, but could be run on any application server that complies with the servlet 2.3 specification. Likewise, this document describes the installation of PostgreSQL as a backend data store. The Jena RDF API that is part of the application also supports other databases (i.e., MySQL). These could be implemented instead.

There are alternative ways to accomplish many of the tasks outlined in this document. This includes the online tools provided in the administration area of the Registry. However, this is a simple, fast and recommended way to install a registry for implementers new to the project.

 

II. Installing The Base Software

 

2.1 Java

Java is an object-oriented programming language. The Registry is written in this language. The full software developers kit (sdk) is needed. j2sdk1.4.2_03 is recommended, but earlier 1.4 releases should work also.

Java can be be downloaded from here: http://java.sun.com/

 

2.3 Apache HTTP Server

Apache is the leading HTTP server. An HTTP server is actually optional - the Registry can run without it. However, it is recommended since it (in combination with the mod_jk connector) enables installations to offer Tomcat applications (such as the Registry) via port 80. This eliminates the need to expose any port other than port 80, and thereby reduces potential security exposures.

Apache can be downloaded here: http://httpd.apache.org

 

Jakarta Tomcat Application Server

Tomcat is a Java appliation server. This is a extension to an HTTP server, although it can also run as a stand-alone server.

Release jakarta-tomcat-5.0.18 is recommended, but any 4.1+ release should work. Tomcat can be downloaded here: http://jakarta.apache.org/

 

2.4 Jakarta Ant

Ant is a Java-based build tool. It is similar to the Unix make command - in principle. However, unlike make it is written in Java and uses XML build files for target definition. Ant is used to build and deploy the Registry.

Version 1.6.1 or higher is required, and is available here: http://ant.apache.org/

 

2.5 PostgreSQL

PostgreSQL is a relational database application. The Registry uses PostgreSQL to store metadata terms. Release postgresql-7.2.4 is recommended. However any version 7.1 or 7.2 will also work. Version 7.3 is also reported to work, but this has not been tested.

Configure PostgreSQL with Java and Unicode support:

./configure --with-java --enable-unicode --enable-multibyte='UNICODE'

PostgreSQL can be downloaded here: http://www.postgresql.org/

 

2.6 Jena

Jena is the RDF application interface the Registry uses to create and manage RDF data. Version 2.0 is required. Note: Do not use Jena 2.1. There are still unresolved issues (i.e., the way models are serialized) that present problems for the Registry.

Jena can be downloaded here: http://jena.sourceforge.net/

 

2.7 Axis

Axis is a SOAP-based toolkit for implementing web services. The registry uses Axis to offer a SOAP-style application interface. Version 1.1 is required.

Axis can be downloaded here: http://ws.apache.org/axis/index.html

 

2.8 WSIL4J

WSIL4J is a Java-based discovery mechanism for web services. The Registry uses WSIL4J to facilitate the discovery of it's SOAP-style application interface.

WSIL4J can be downloaded here: http://cvs.apache.org/viewcvs/*checkout*/ws-wsil/java/README.htm

 

2.9 UDDI4J

UDDI4J is a Java API for interacting with a UDDI (Universal Description, Discovery and Integration) registry.

UDDI4J can be downloaded here: http://www-124.ibm.com/developerworks/oss/uddi4j/

 

III Setting Your Environment Variables

Verify that you have the following environment variables set:
setenv JAVA_HOME /usr/java/j2sdk1.4.2_03
setenv TOMCAT_HOME /usr/apache/tomcat
setenv CATALINA_HOME ${TOMCAT_HOME}
setenv ANT_HOME /usr/apache/apache-ant-1.6.1/
setenv LD_LIBRARY_PATH /usr/local/pgsql/lib
setenv PGDATA /usr/local/pgsql/data
setenv JENAROOT /usr/local/Jena/Jena-2.0
setenv AXISROOT /usr/local/axis-1_1
setenv REGISTRY ~/work/projects/dcregistry-3.0/build/WEB-INF/classes/
setenv WSILROOT /usr/local/xml-axis-wsil/java/build/lib
 
setenv CLASSPATH .:${REGISTRY}
setenv CLASSPATH ${CLASSPATH}:${ANT_HOME}/lib/ant.jar
setenv CLASSPATH ${CLASSPATH}:/usr/local/pgsql/share/java/postgresql.jar
setenv CLASSPATH ${CLASSPATH}:${JENAROOT}/lib/antlr.jar
setenv CLASSPATH ${CLASSPATH}:${JENAROOT}/lib/icu4j.jar
setenv CLASSPATH ${CLASSPATH}:${JENAROOT}/lib/jena.jar
setenv CLASSPATH ${CLASSPATH}:${JENAROOT}/lib/xercesImpl.jar
setenv CLASSPATH ${CLASSPATH}:${AXISROOT}/lib/log4j-1.2.8.jar
setenv CLASSPATH ${CLASSPATH}:${JENAROOT}/lib/concurrent.jar
setenv CLASSPATH ${CLASSPATH}:${JENAROOT}/lib/jakarta-oro-2.0.5.jar
setenv CLASSPATH ${CLASSPATH}:${JENAROOT}/lib/junit.jar
setenv CLASSPATH ${CLASSPATH}:${JENAROOT}/lib/rdf-api-2001-01-19.jar
setenv CLASSPATH ${CLASSPATH}:${JENAROOT}/lib/xmlParserAPIs.jar
setenv CLASSPATH ${CLASSPATH}:${AXISROOT}/lib/axis.jar
setenv CLASSPATH ${CLASSPATH}:${AXISROOT}/lib/jaxrpc.jar
setenv CLASSPATH ${CLASSPATH}:${AXISROOT}/lib/saaj.jar
setenv CLASSPATH ${CLASSPATH}:${AXISROOT}/lib/wsdl4j.jar
setenv CLASSPATH ${CLASSPATH}:${AXISROOT}/lib/log4j-1.2.8.jar
setenv CLASSPATH ${CLASSPATH}:${AXISROOT}/lib/log4j-1.2.8.jar
setenv CLASSPATH ${CLASSPATH}:${AXISROOT}/lib/commons-discovery.jar
setenv CLASSPATH ${CLASSPATH}:${AXISROOT}/lib/commons-logging.jar
setenv CLASSPATH ${CLASSPATH}:${WSILROOT}/wsil4j.jar
 
setenv PATH .:${JAVA_HOME}/bin:${ANT_HOME}/bin
setenv PATH ${PATH}:/usr/local/pgsql/bin:/home/wagnerh/bin
setenv PATH ${PATH}:/usr/kerberos/bin:/usr/local/bin
setenv PATH ${PATH}:/usr/bin:/bin:/usr/X11R6/bin:/sbin

 

IV. Configuring Tomcat

 

4.1 Deploy The Java Properties File

Add a 'properties' directory to your Tomcat installation. For example, if your tomcat is installed in '/usr/apache/tomcat' then create a directory named '/usr/apache/tomcat/properties'. Copy the 'dcregi18n.jar' property file into this directory (this file is created during in the build process which is described below).

Configure Tomcat to include this file in it's CLASSPATH. Edit the tomcat/bin/catalina.sh file. Look for a line that reads:

# Add on extra jar files to CLASSPATH

Add the following lines immediately after it:

CLASSPATH="$CLASSPATH":"$CATALINA_HOME"/properties/dcregi18n.jar CLASSPATH="$CLASSPATH":/usr/java/j2sdk1.4.2_03/lib/tools.jar

 

4.2 Load The JAR files

Copy the following files to your tomcat/shared/lib directory:

From your axis/lib directory:
axis-ant.jar axis.jar commons-discovery.jar commons-logging.jar
jaxrpc.jar log4j-1.2.8.jar saaj.jar wsdl4j.jar
 
From your Jena/lib directory:
antlr.jar icu4j.jar jena.jar xercesImpl.jar
concurrent.jar jakarta-oro-2.0.5.jar junit.jar rdf-api-2001-01-19.jar
xmlParserAPIs.jar
 
From your postgreSQL/share/java directory:
postgresql.jar
 
From your uddi4j/lib directory:
uddi4j.jar
 
From your wsil/java/build/lib directory:
wsil4j.jar

 

4.3 Configure the Apache-Tomcat mod_jk Connector (optional)

Configure the apache-tomcat connector to enable users to access the Registry via port 80. While this step is optional. it is recommend as a security precaution. . It is also recommended that implementers do this step last, after the registry is installed and functional, unless they are comfortable with configuring this connector.

See http://jakarta.apache.org/tomcat/tomcat-3.3-doc/mod_jk-howto.html for detailed instructions regarding installing the Apache-Tomcat connector.

 

V. Download The Project Source

Download the source from the SVN repository. To access the repository follow the instructions found here.

 

VI. Building The Application

 

6.1 Application Configuration

The registry uses a Java properties file to specify a number of customizable options. These are described below. This file is located in the project/web/WEB-INF/ directory and is named jdbc.properties. Installers should edit this file prior to a build to verify it matches their installation.

db_user = someUser
Specifies the authorized PostgreSQL user.
db_uri = jdbc:postgresql://localhost:5432/registry3
Specifies the database URI
JDBCDriver = org.postgresql.Driver
Specifies the PostgreSQL JDBC driver
registry_model = registry
Specifies the name of the registry model
provenance_model = provenance
Specifies the name of the provenance model
translations_model = translations
Specifies the name of the translations model
account_model = account
Specifies the name of the account model
remote_model = remote
Specifies the name of the remote model
collection_model = collection
Specifies the name of the collection model
canonical_model = canonical
Specifies the name of the canonical model
extensions_model = extensions
Specifies the name of the extensions model
db_type = PostgreSQL
Identifies the database type being used
defaut_ui_lang = en_US
Specifies the default user interface language
defaut_rs_lang = en_US
Specifies the default data language
provenance = N
Indicates whether or not to enable the provenance function for non-English default language data (no longer used)
restLog = /usr/apache/tomcat/logs/rest.log
file name to use as log file for the REST-style web services
axisLog = /usr/apache/tomcat/logs/rest.log
file name to use as log file for the SOAP-style web services
appLog = /usr/apache/tomcat/logs/rest.log
file name to use as log file for the web interface
summary_xsl = summary-3col-itemized.xsl
The name of the XSLT stylesheet to use for the summary function
detail_xsl = detail.xsl
The name of the XSLT stylesheet to use for the item detail function
documents_xsl = documents.xsl
The name of the XSLT stylesheet to use for the documents function
translations_xsl = translations.xsl
The name of the XSLT stylesheet to use for the translations function
refinements_xsl = refinements.xsl
The name of the XSLT stylesheet to use for the refinements function
query_xsl = query.xsl
The name of the XSLT stylesheet to use for the query function
preference_xsl = preference.xsl
The name of the XSLT stylesheet to use for the preference function
properties_xsl = properties.xsl
The name of the XSLT stylesheet to use for the properties function
provenance_xsl = provenance.xsl
The name of the XSLT stylesheet to use for the provenance function
searchResults_xsl = searchResults.xsl
The name of the XSLT stylesheet to use for the search-results function
encodingSchemes_xsl = encodingSchemes.xsl
The name of the XSLT stylesheet to use for the encoding-schemes function
elements_xsl = elements.xsl
The name of the XSLT stylesheet to use for the elements function
controlledTerms_xsl = controlledTerms.xsl
The name of the XSLT stylesheet to use for the controlled-terms function
classes_xsl = classes.xsl
The name of the XSLT stylesheet to use for the classes function

 

6.2 Building and Deploying

Modify the project 'build.xml' file (located in the project root directory) to reflect your installation. Only the following lines should be changed:

<property name="catalina.home" value="/usr/apache/tomcat"/>
<property name="axis.home" value="/usr/local/axis-1_1"/>
<property name="wsil.home" value="/usr/local/xml-axis-wsil/java"/>
<property name="uddi.home" value="/usr/local/uddi4j"/>

Change the value= to reflect your installation.

The build.xml file is an Ant build-file and includes the following targets for building the registry.

All of the commands are prefixed with "ant" and should be executed from the project home directory (for example ant deploy). To get started quickly execute the ant deploy command, followed by the ant dist command. Then copy the files in the project/dist directory to your tomcat installation. Copy the jar file to your tomcat/properties file, the war file to your tomcat/webapps directory and the logger.dtd file to the directory that your log files are being written to (The directory specified for the appLog, restLog and axisLog in the jdbc.properties file).

 

VII. Creating And Loading The Database

Jena 2.0 uses one database for all models. This is a departure from previous releases and greatly simplifies the database build process. Follow these procedures to build and load the database:

  1. Start PostgreSQL. Be sure to use the '-i' option to enable the Java interface. For example:

    pg_ctl start -l logfile -o "-i -N 64 -B 128"

  2. Create the database with the following commands:
  3. Load the database. There are a number of ways this can be done. Here is a simple, but effective, approach:

 

VIII. Enabling The Axis (SOAP) Application Interface

 

8.1 Deploy The Services

The following steps outline how to enable the Registry SOAP-style web services:

  1. Copy the axis/webapps/axis directory (and it's contents) to your tomcat/webapps directory.
  2. Edit the 'deployAll.wsdd' file in the project/axis/wsdd directory. This file describes 8 services that are standard with the registry. Each of these services uses a log file, which is specified in this file. The file name is: /usr/apache/tomcat/logs/axis.log Change this (for each service) to point to your tomcat log file directory.
  3. Deploy the services by executing the Ant target:

    ant axis-deploy

    This will compile the Axis services, move them (and the jdbc.properties file) to the tomcat/webapps/axis directory and deploy the services using the Axis AdminService.

 

8.2 Enable Service Discovery

The Web Services Inspection Language (WSIL) is a distributed discovery mechanism that enables discovery of SOAP service descriptions (WSDL). WSIL documents are XML documents, which rely on conventions, not only for specifying the service description syntax, but also for specifying the name and location within a Web site that should be inspected for service descriptions.

The DCMI Registry follows these conventions by providing a WSIL service description document in a /services directory off of the root directory of the server the Registry is deployed on. For example: the registry deployed at http://dublincore.org/dcregistry/ includes a WSIL service description document at the following address: http://dublincore.org/services/inspection.wsil. This document is included in the projects/axis/wsil directory. It is also listed in Appendix B for reference. Use it as a starting point for creating your own WSIL document. Change the document abstract, and the location attribute for each service to reflect your installation and place this file at your server's root/services. Note that the accepted convention for this file name is 'inspection.wsil'. This is the name applications will use when searching for deployed services.

 

IX. Installation Verification

Start your tomcat and access to at:

http://<your server>:8080/dcregistry/

or at

http://<your server>/dcregistry/

if you have installed the Apache-Tomcat connector.

 

Appendix A: Project Directory

/dcregistry-3.0

build.xml  This is the project Ant build-file

/axis
    /wsdd  Axis web services deployment descriptors
    /wsil  Sample web services inspection language document

/RDF  This is the core Dublin core terms, their translations and related provenance data

/src
    /org
        /dublincore
            /dcregistry
                     /bean  JavaBeans directory
                     /filters  Filter for setting UTF8 character encoding
                     /services  Inter-registry communication modules
                           /axis  SOAP-style services
                           /rest  REST-style services
                     /servlet  Application servlets
                     /tools  Batch tools

/tools
  ShellScripts  Sample shell scripts for using the batch tools

/web
    index.html, volunteers.html and sample code.
    /CSS  Cascading style sheets
    /images  Application images
    /properties  Java property files used for internationalization
    /WEB-INF  Application properties file and web.xml file
    /xsl  XML files and XSLT stylesheets

 

Appendix B: Sample WSIL Document

<?xml version="1.0" encoding="UTF-8"?>
<inspection xmlns="http://schemas.xmlsoap.org/ws/2001/10/inspection/">
<abstract>Dublin Core Metadata Initiative</abstract>

<service>
<name>ItemSummary</name>
<abstract>This service returns a list of all resources that are registered. No input parameters are required.
</abstract>
<description referencedNamespace="http://schemas.xmlsoap.org/wsdl/"
location="http://dublincore.org/axis/services/itemSummary?wsdl"></description>
</service>

<service>
<name>ItemDetail</name>
<abstract>This service returns all known information about a resource in the requested language.
This interface requires a resource name (i.g., http://purl.org/dc/elements/1.1/creator) and a
language code (i.g., en-US).
</abstract>
<description referencedNamespace="http://schemas.xmlsoap.org/wsdl/"
location="http://dublincore.org/axis/services/itemDetail?wsdl"></description>
</service>

<service>
<name>encodingSchemesSummary</name>
<abstract>This service returns a list of all registered encoding schemes. No input parameters are required.
</abstract>
<description referencedNamespace="http://schemas.xmlsoap.org/wsdl/"
location="http://dublincore.org/axis/services/encodingSchemesSummary?wsdl"></description>
</service>

<service>
<name>refinementsSummary</name>
<abstract>This service returns a list of all registered element refinements. No input parameters are required.
</abstract>
<description referencedNamespace="http://schemas.xmlsoap.org/wsdl/"
location="http://dublincore.org/axis/services/refinementsSummary?wsdl"></description>
</service>

<service>
<name>termUpdates</name>
<abstract>This service returns a list of all changes to the Registry, in a specific language, since a specific date.
This interface requires a date and a language (i.g., 20021015 en-US).
</abstract>
<description referencedNamespace="http://schemas.xmlsoap.org/wsdl/"
location="http://dublincore.org/axis/services/termUpdates?wsdl"></description>
</service>

<service>
<name>vocabularyTermsSummary</name>
<abstract>This service returns a list of all registered controlled vocabulary terms. No input parameters are required.
</abstract>
<description referencedNamespace="http://schemas.xmlsoap.org/wsdl/"
location="http://dublincore.org/axis/services/vocabularyTermsSummary?wsdl"></description>
</service>

<service>
<name>languagesSummary</name>
<abstract>This service returns a list of all supported languages. No input parameters are required.
</abstract>
<description referencedNamespace="http://schemas.xmlsoap.org/wsdl/"
location="http://dublincore.org/axis/services/languagesSummary?wsdl"></description>
</service>

<service>
<name>elementSummary</name>
<abstract>This service returns a list of all registered elements. No input parameters are required.
</abstract>
<description referencedNamespace="http://schemas.xmlsoap.org/wsdl/"
location="http://dublincore.org/axis/services/elementSummary?wsdl"></description>
</service>

</inspection>