LSID (Life Science Identifier) Files

LSID Java Client 0.3.3
----------------------

Author: Ben Szekely (bhszekel@us.ibm.com)

Contents
--------
1.) Introduction
1A.) Modifications
2.) Requirements
3.) Setup
4.) API Documentation
5.) Testing
6.) Meta Data stores
7.) Security
8.) Foreign authorities


1.) Introduction

	Thank you for evaluating the LSID Java Client.  These Classes provide a simple API for adding Life Science ID 
	functionality to your application. Bugs should be sent to: http://oss.software.ibm.com/developerworks/bugs/?group_id=124
	
1.A) Version 0.3.3 of the Java Client is fully compliant with version 3 of the LSID protocol. This new version contains:
	
	- support for adding protocol specific headers for SOAP and HTTP requests
	- XML-based configuration for client and credentials (replaces lsid-client.properties and lsid-client.credentials)
	- foreign authority support.  For given lsids,authorities or namespaces, specific foreign authorites may asked for WSDL.
	- several bug fixes

	
2.) Requirements

	- The binary version is built against Java 1.4, but should build against Java 1.3

	- To run and build the LSID Java Client, you must have the following Java libraries in your classpath:
	
		xalan.jar (Xalan 2.4.1)       \
		xml-apis (Xalan 2.4.1)         - http://xml.apache.org/dist/xalan-j/xalan-j_2_4_1-bin.zip
		xercesImpl.jar (Xalan 2.4.1)  /
		
		jax-qname.jar (jaxrpc 1.0) http://java.sun.com/xml/downloads/jaxrpc.html#jaxrpcclass9
									download: "JAR with javax.xml.namespace.QName API Class Files 1.0"
									
		wsdl4j.jar (wsdl4j 1.2) http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-axis/java/lib/wsdl4j.jar?rev=1.12
		
		dnsjava-1.3.2.jar (dns java 1.3.2) http://www.xbill.org/dnsjava/download/dnsjava-1.3.2.jar
		
		castor-0.9.5.jar (castor 0.9.5) ftp://ftp.exolab.org/pub/castor/castor_0.9.5/castor-0.9.5.jar 
 
		
3.) Installation instructions

	NOTE: These are rough instructions for capabale Java users to begin evaluating the API.  Expect more complete
	instructions in a later release.  Feel free to email questions.

	A.) Source distribution
	
		- Obtain the source from either the Developer Works LSID download section or from the
		  CVS module "lsid-java/client".  Follow the CVS instructions on Developer Works.
	
		- Compile the source against the jars in 2.)
		
			(if not using HP Jena, remove the files in com/ibm/lsid/client/metadata/rdf/jena/)
		
		- Add compiled Classes to your classpath
		
	B.) Binary distribution
	
		- Obtain the binary distribution for from above Developer Works
		
		- place the file lib/lsid-client.jar in your classpath.
		
4.) API Documentation

	The JavaDoc is available at docs/index.html in either distribution
		
5.) Testing

	I. Setting up the client
	
		By default, the client performs no caching, sets no authority-endpoint mappings, and uses a simple
		meta data store. If this behavior is sufficient, no configuration is necessary.  On  client startup, a home
		directory c:/lsid-client (unix: ~/.lsid-client) will be created, with a default config file. Modify this
		generated file, or create a new configuration tree as follows:
		
		- create an LSID_CLIENT_HOME directory.
		
		- create an LSID_CACHE directory (LSID_CLIENT_HOME/cache will be used by default.
	
		- create a client config file: LSID_CLIENT_HOME/lsid-client.xml
		
			- a sample file is included in the root of each client distribution and in cvs
		
		- create a cache config file LSID_CACHE/lsid-cache.properties
		
			- a sample file is included in the root of each client distribution and in cvs
		
Cache Configuration Note:

A config file should be placed in the root of the cache. Additional configuration files may be placed in subdirectories
 such as C:/LSID/java/cache/wsdl, C:/LSID/java/cache/metadata or C:/LSID/java/cache/data.  These configuration files
 can only tighten cache bounds, not loosen bounds found in the parent directory.  Files in child directories contribute
 to the total size of the parent directory.  Furthemore, only the logging policy of the root is considered.
 If no file is found in a directory and the directory has no parent, no bounds and no logging are assumed.
 	
 	II. Running the sample
 	
 		- Open LSIDTestClient.java. 
 		  
 		- the method testAuthority() should work on all i3c-based LSIDs (genbank, pubmed, swissprot, etc...)
 	
 		- Compile the sample LSIDTestClient.java
 		
 		- run the sample, specifying the client root on the command line, for example:
 		
 		 		java LSIDTestClient -DLSID_CLIENT_HOME="C:\LSID\java"
 		 		
 		- If you are embedding the LSID stack into an application, and you don't have access to the java command line,
 		  you may set the system property programatically *before* you reference com.ibm.lsid.client.LSIDResolver 	
 		 		
 		 		System.setProperty(LSIDResolverConfig.LSID_CLIENT_HOME,"C:\LSID\java");
 		 		
6.) Meta Data Stores

	This version of the LSID stack comes with a framework for parsing and storing meta data. The nature of meta data
	is evolving and may take on different formats depending on the LSID provider.  Currently, we support XML RDF meta
	data in our client stack.  When getMetaData() is invoked on a resolver, an interface into the meta data store is
	returned.  An underlying implementation is selected by the resolver based on the factory specified in the client
	configuration.  The default meta data store simply uses XSLT to canonicalize the RDF into simple format.  
	
	The HP Jena RDF Store
	
	A more advanced implementation uses the HP Jena 2 preview  to store the RDF. 
	
	- download at http://prdownloads.sourceforge.net/jena/Jena-2p1.zip?download  
	
	- add the following jars from the /lib directory of Jena to your classpath
	
		- jena.jar log4j-1.2.7.jar icu4j.jar concurrent-1.3.0.jar
		
	- build the client stack with com.ibm.lsid.client.metadata.rdf.jena included.
	
	- in the client config xml, include the following meta data settings
	
		meta-data-factory = com.ibm.lsid.client.metadata.rdf.jena.JenaMetaDataFactory
		param: model-type value: memory
		
7.) Security 

	In version 0.3.2, basic HTTP authentication was added to the stack.  Authentication can be specified
	dynamically on the LSIDDataPort and LSIDMetaDataPort interfaces.  
	
		LSIDPort port;
		
		// intialization of port omitted
	
		// specify specific creds
		LSIDCredentials creds = new LSIDCredentials();
		creds.setProperty(LSIDCredentials.BASICUSERNAME,"username");
		creds.setProperty(LSIDCrednetials.BASICPASSWORD,"password");
		port.setLsidCredentials(creds);
		
	Authentication can be specified in the config file LSID_CLIENT_HOME/lsid-credentials.xml.  An example
	file can be found in the root of each distrubution.  In this file, credentials can be specifed for 
	individual LSIDs or classes of LSIDs (whole authority spaces or namespaces).  Creds may also be 
	specified for a given wsdl port.  
	
	The credentials that are actually used for a given call are determined by checking the above locations
	in the following order:
	
		dynimcally set credentials ==> credentials for a given port ==> credentials for a given LSID.  
		
	For example, dynically set creds take precedence over any creds defined in the config file.

8.) Foreign authorities.

	In addition to the authority specified by a given LSID, other authorities may know something about that
	LSID.  These other authorities, known as "foreign authorities," may be specified for LSIDs or classes
	of LSIDs in the lsid-client.xml document. When the LSID in question is resolved against its native 
	authority, the foreign authorities will also be asked about it.