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:

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.

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.

• dist Used to build a distribution. This will create the 'dcregistry.war' file and 'dcregi18n.jar' files. These are saved in the project /dist directory by Ant.
• deploy This target will build the application and deploy it to the tomcat/webapps directory.
• clean Used to cleanup old build directory (work area used by Ant buildfile).
• javadoc This target will generate the application documentation.
• axis-prepare This target will copy the files required to enable the SOAP interface to the tomcat/webapps/axis directories.
• axis-deploy Used to deploy the SOAP services.
• axis-undeploy Used to undeploy the SOAP services.

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:
   • psql template1
   • create database registry3 with encoding='UNICODE';
3. Load the database. There are a number of ways this can be done. Here is a simple, but effective, approach:
   • Verify that your PATH and CLASSPATH variables are set correctly (see the example above).
   • Evaluate the RDF files found in the /RDF directory. By default, the /RDF/schemas and /RDF/provenance directories include translations for all of the currently supported languages. Your installation may not require all of these translations. Delete any translations that you do not plan to support. Note that the importRDF tool will load all files in a directory, but will skip the '.svn' directory.
   • Change to the project/tools/ShellScripts directory.
   • Run the 'initRegistry.sh'. This will initialize the Registry models, load them with default values and create an administrative account. For example: 'initRegistry.sh aUser aPassword' will initialize the Registry and create an administrative account for 'aUser', with a password of 'aPassword'.

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>