BioMOBY Registry Servlets

The BioMOBY registry servlets are a required install for all you wishing to host your very own BioMOBY registry. These servlets contain the code that is used to retrieve information regarding the ontologies in RDF format, code for generating RDF that is served to the service providers upon successful service registration, an LSID resolution authority, and much more.

The following is a list of items contained in this release:

1. RESOURCES 'script' - a servlet that is used to generate RDF dumps for the Object, Namespace, Service Type, and Service Instance ontologies.
2. Types 'script' - a servlet that is used to generate textual dumps for the Object, Namespace and Service Type ontologies.
3. LSID Authority Servlet - a servlet that is used to resolve biomoby.org*, LSIDs to metadata.
4. Service Tester Servlet - a servlet that periodically 'pings' the services contained in the registry to determine whether or not the services URL are resolvable.
5. RDFAgent Validator - a servlet that can be used to test whether your installation of the agent was successful, or to test an RDF document that describes your services for syntactical errors.
6. LSID client web applications that can be used to resolve LSIDs. One of these applications uses AJAX and provides auto complete functionality.

• Prerequisites
• Installation
• Configuration
• Testing

Prerequisites

• In order to install these servlets you will have to ensure that you have a full J2EE container installed. We are using Apache servlet engine Tomcat, but you are free to use whatever engine you like. The instructions in this document assume that you have chosen Tomcat, but may be applicable to other engines.
• These servlets also require that a JAVA virtual machine version 5 or greater be installed on the machine hosting these servlets.
• Finally, these servlets are meant to be used in conjunction with a BioMOBY registry and not stand alone, so please ensure that you have installed your local registry first.

Installing the Servlets

Installing the servlets is extremely straight-forward and quite easy. You have 2 choices for installation: use a graphical installer or build your own installation using the latest codebase.

A. Using the Installer:

1. Download the installation file from http://bioinfo.icapture.ubc.ca/ekawas/servlets/install.jar
   
   
2. From the command line, enter the following command
   

   java -jar install.jar

   A GUI should result that will guide you through the installation process.

3. You're done! Now all you have to do is configure your newly installed servlets.

B. Building your own installation from the cvs

1. Please familiarize yourself with the information here for getting and building jMOBY from the cvs.
   
   
2. From the command line, enter the following command from a *nix box
   

   ant bindist-registry

3. Once the build is complete, a zip file will be located at /moby-live/Java/build/registry_servlets called authority.zip. Unzip this file into the webapps directory of Tomcat or other J2EE container.
   
   
4. You're done. All that is left for you to do is configure the newly installed servlets.

Configuring Your Servlets

To Configure the servlets, you must know the following details regarding your local registry:

• The BioMOBY registry URL and URI
• The exact location of the mobycentral.config (confused? refer here)
• Your JAVA J2EE servers complete address

How to Configure

• context.xml
• mobycentral.config
• DNS records & Apache (If you wish to use the LSID authority servlet).

Once you have those values, you will have to modify the servlets configuration file that is located at /path/to/tomcat/webapps/authority/META-INF/context.xml

The file context.xml is written in XML and contains numerous entries that look like this:

	
	<Environment name="SOME_KEY" value="SOME_VALUE_IN_QUOTES" type="java.lang.String"/>
    

Where SOME_KEY is a configurable parameter and SOME_VALUE_IN_QUOTES is value for that specific parameter.

The following is an explanation of the various parameters:

MOBY_CENTRAL_CONFIG	The complete path to the mobycentral.config file as described here.
MOBY_SERVER	The endpoint of your local registry
MOBY_URI	The namespace of your local registry
CACHE_PATH	A path that you would like the servlets to cache to. This path must have the correct write permissions set.
ServiceInstanceCachingClass	The class that is implementing the caching of the Service Instance RDF
LSID_SERVER	The domain name of the server that is acting as the LSID authority. localhost is an unacceptable value
LSID_PORT	The port for your server that will be acting as an LSID authority
FULL_SERVER_URL	The full address of your server. This is most likely http://localhost:8080/authority

In this file, there also exists a fragment that looks like the following:

<Valve className="org.apache.catalina.valves.FastCommonAccessLogValve"
                 directory="MobyLogs"  prefix="moby_access_log-" suffix=".txt"
                 pattern="common" resolveHosts="false" fileDateFormat="yyyy-MM"/>

This fragment performs server access logging for the servlets. If you would like to turn this off, you can delete the text in its entirety or wrap the code with

<!-- fragment goes here --> 

You can configure the location of the access logs by modifying the following parameters:

directory	The path to the directory that you would like to store these logs
prefix	The file name prefix
suffix	The file name suffix

For a more precise explanation of how to configure this aspect of the servlets, please refer to
http://tomcat.apache.org/tomcat-5.5-doc/config/valve.html

Once you have modified these parameters in this file, you may close the file.

Next, you will have to open the file mobycentral.config and add or modify a couple of configuration parameters:

• To the [mobycentral] section of this file, please ensure that the following parameters are set:

lsid_authority	Your domain name, as you would like it in urn:lsid:lsid_authority:namespace:object
lsid_namespace	The namespace that you would like service instances to use when resolving LSIDs, e.g. urn:lsid:lsid_authority:namespace:object
resourceURL	The URL that would return the RDF describing the service instances registered in your registry. This value is most likely: http://yourDomain:yourPort/authority/RESOURCES/MOBY-S/ServiceInstances
allResources	The URL that would return the RDF describing all ontologies in your registry. This value is most likely: http://yourDomain:yourPort/authority/RESOURCES/MOBY-S/FULL
rdf_generator	The location of the RDFGenerator included with the Registry Servlet that you are currently installing, i.e. http://your.domain/authority/RDFGenerator

 

• To the [mobyobject] section of this file, please ensure that the following parameters are set:

lsid_authority	Your domain name, as you would like it in urn:lsid:lsid_authority:namespace:object
lsid_namespace	The namespace that you would like Objects to use when resolving LSIDs, e.g. urn:lsid:lsid_authority:namespace:object
resourceURL	The URL that would return the RDF describing the datatypes registered in your registry. This value is most likely: http://yourDomain:yourPort/authority/RESOURCES/MOBY-S/Objects

 

• To the [mobynamespace] section of this file, please ensure that the following parameters are set:

lsid_authority	Your domain name, as you would like it in urn:lsid:lsid_authority:namespace:object
lsid_namespace	The namespace that you would like namespaces to use when resolving LSIDs, e.g. urn:lsid:lsid_authority:namespace:object
resourceURL	The URL that would return the RDF describing the namespaces registered in your registry. This value is most likely: http://yourDomain:yourPort/authority/RESOURCES/MOBY-S/Namespaces

 

• To the [mobyservice] section of this file, please ensure that the following parameters are set:

lsid_authority	Your domain name, as you would like it in urn:lsid:lsid_authority:namespace:object
lsid_namespace	The namespace that you would like service instances to use when resolving LSIDs, e.g. urn:lsid:lsid_authority:namespace:object
resourceURL	The URL that would return the RDF describing the service types registered in your registry. This value is most likely: http://yourDomain:yourPort/authority/RESOURCES/MOBY-S/ServiceTypes

 

To enable the LSID authority servlets, you will have to perform up to 2 more tasks:

• Create a DNS record for your domain
• Add ProxyPass directives to your Apache servers' configuration file (optional)

Setting up DNS (excerpt)

All that you - or your system administrator - must do, is to add a service record for the machine that will run the authority.

Suppose the machine is authority.company.net and that it will serve as the authority named company.net. Further suppose that the service will be on port 8080. The record that must be added should go into the master zone file for company.net's DNS server (perhaps a file named /var/named/company.net.zone on company.net):

_lsid._tcp      IN      SRV     1       0       8080    authority.company.net.

If the authority name is supposed to be authority.company.net rather than company.net, the record in company.net's zone file should look like:

_lsid._tcp.authority    IN      SRV     1       0       8080    authority.company.net. 

Enabling ProxyPass Apache Directives

For those of you that are running Tomcat on a non-standard port, you may find that users of your registry cannot access those ports due to firewall restrictions. One way around this is to set up ProxyPass directives in your web server.

Before you begin, it is highly recommended that you backup any files mentioned here that you will be updating.

Open up your Apache servers httpd.conf file and make sure that following line is uncommented:

LoadModule proxy_module modules/mod_proxy.so 

Then add the following to the bottom of the file

ProxyPass /authority http://localhost:8080/authority
ProxyPass /authority/ http://localhost:8080/authority/
ProxyPass authority http://localhost:8080/authority
ProxyPass authority/ http://localhost:8080/authority/ 

Now requests made to localhost/authority will be sent to localhost:8080/authority and your users should not have any problems accessing the URLs.

Once these values have been added or modified, make sure to save the configuration files and restart the server. Your changes should be reflected in your registry.

Testing Your Servlets

Once you have installed and configured the servlets, you can determine if the install was successful by attempting to resolve the following URL:

http://your.domain.com:your_port/authority/moby.jsp

where your.domain.com is the domain name of the server that the servlets were installed on and your_port is the server port.

The resulting page will outline those servlets that are included in this distribution and will provide you with links to test them.