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.