UserPreferences

LightweightNetworkInterface/Client

Lightweight Network Interface / Download and Client

Topics

Downloads

/!\ This code should not be considered stable. It is subject to change at any time, and may not work with the current development or released version of DSpace. Use it for exploration and evaluation only. There are not yet any final plans for releasing it; much depends on the course of the AddOnMechanism project.

Installing LNI in DSpace 1.4

Start with a download of the DSpace 1.4 source. This was tested against the CVS Head as of March 28, 2006, which was after most of the patches to the first 1.4 alpha release were integrated.

Building

Follow these steps to add an LNI server and client to your DSpace installation. If you only need the client (i.e. you're testing against an existing LNI server), then you can skip this step and just download the client library JAR from the link above.

  1. Apply the diffs with the Unix command patch -p0 < lni-1.4-diffs.txt while in your checkout directory.

  2. Unpack the "new files" Zip, lni-1.4-new.zip, which overlays the new files on your source tree.

  3. Build the WAR files as usual with ant build_wars. Observe that a new file appears: build/dspace-lni.war. This is the LNI webapp.

  4. Now build the client library with ant lni_client. This creates the client library: build/dspace-lni-client.jar

Install Server

To install the LNI server, follow your usual procedure for installing webapp WAR files in your servlet container. For example if you are running Tomcat 5.0 installed at /tomcat, you'd execute this command: 

    cp build/dspace-lni.war /tomcat/webapps

Then restart or reconfigure the Tomcat server to deploy the new webapp.

Testing Server

To test the server, run the Smoke Test client against it with some trivial command, such as getting the properties of a DSpace object. You'll need to know the "endpoint" URL (see below for details) and how to compose a URL with your login credentials.

Invoke the test client by running the JAR file directly. This only works on the machine where you built and installed DSpace, since it relies on DSpace support JARs being in [dspace]/lib. For example: 

java -jar build/dspace-lni-client.jar -e http://me%40uni.edu:password@dspace.uni.edu/dspace-lni/lni/DSpaceLNI -p 123456789/4

Using the LNI Clients

This section discusses using the SOAP-based and WebDAV clients with the LNI.

Server URLs and Endpoints

To connect to an LNI server you must first determine its "endpoint" URL (for SOAP), or DAV base URL (for WebDAV). For each server, these are very similar.

Note: The LNI requires authentication credentials (unless configured to allow anonymous access). If you are authenticating with the default EPerson username and password mechanism, they are passed to the LNI through the HTTP Basic Authentication protocol. For clients built on the Axis SOAP implementation, you specify the username and password in the URL in the standard way, as shown below. Note that any "@" in your username (which is likely since DSpace usernames are email addresses), you'll have to URL-escape it as "%40", e.g. "me%40myuni.edu".

The SOAP endpoint URL has the following elements:

For example, if the user is florey@mit.edu and password is xyzzy, and the host is sub.mit.edu, then the endpoint URL would be: 

  http://florey%40mit.edu:xyzzy@sub.mit.edu/dspace-lni/lni/DSpaceLNI

The WebDAV base URL is exactly like the SOAP endpoint, except the path ends with dav, instead of lni/DSpaceLNI, For example: 

  http://florey%40mit.edu:xyzzy@sub.mit.edu/dspace-lni/dav

For convenience, i.e. to make it easier to write applications including both SOAP and WebDAV calls, the GET and PUT WebDAV methods will also work against the URLs based on the "parent directory" of an LNI SOAP endpoint, e.g.

The Smoke Test Client

NOTE: The LNISmokeTest client is supplied as an example and an easy way to test that your server is installed correctly. It is not a production-quality utility and should never be used as such. Its source is supplied for your reference as an example of LNI programming, to help develop your own clients. Note that even its name [WWW]"smoke test" implies it is only a very preliminary and simple test.

Invoking LNISmokeTest: Shortcut On the Server

If you are running the Smoke Test client on the DSpace server, you can take advantage of the way it is packaged in an executable JAR file. This only works on your server, because the JAR's manifest has a class path referring to JARs in the DSpace installation directory.

e.g.

Invoking LNISmokeTest: Normally with CLASSPATH

You can also run the smoke test client like any other Java application: Start up a JVM with the correct class path and name the class whose main() function gets invoked. for example:

The class path must include the dspace-lni-client.jar file, and the following additional libraries. They are available as open source from the links below. Acquire the appropriate jar files and append their paths into a CLASSPATH value, e.g. /java/lib/activation.jar:/java/lib/mail.jar:....

Library version
activation.jar             [WWW]Sun bean activation framework 1.0.2
axis.jar           [WWW]Apache Axis 1.3
axis-ant.jar       Apache Axis 1.3
jaxrpc.jar    Apache Axis 1.3
saaj.jar      Apache Axis 1.3
wsdl4j-1.5.1.jar    Apache Axis 1.3
commons-codec-1.3.jar      [WWW]Apache Jakarta Commons Codec 1.3
([WWW]Downloads page for these 4 Jakarta Commons sub-projects)
commons-discovery-0.2.jar  [WWW]Apache Jakarta Commons Discovery 0.2
commons-logging.jar        [WWW]Apache Jakarta Commons Logging 1.0.3
(Appears [WWW]v.1.0.4 and [WWW]v.1.0.2 are available, but not 1.0.3 (?) Try 1.0.4 (wreilly))
commons-cli-1.0.jar        [WWW]Apache Jakarta Commons CLI 1.0
jdom.jar                   [WWW]JDOM 1.0 (jdom.org)
log4j.jar                  [WWW]Apache log4j 1.2.8
([WWW]Best for now to get no-longer-latest version 1.2.8)
mail.jar                  [WWW]Sun Java``Mail 1.3.2 javax.mail

For example, this does a PROPFIND on the DSpace object whose handle is 123456789/4: 

  setenv LNI_CLASSPATH "/some/path/activation.jar:/some/path/axis.jar:..."

  java -cp  dspace-lni-client.jar:$LNI_CLASSPATH \
   LNISmokeTest -e http://user:password@mydspace.edu/dspace/lni/DSpaceLNI -f 123456789/4

Smoke Test Command Options

No matter how you invoke it, the Smoke Test client takes command-line arguments introduced by Unix-style switches, i.e. a dash followed by a letter. Give the command with the -h option ("help") to get a list of all the other options.

Some options expect to be followed by a value, e.g. the -e option, which names the SOAP endpoint URL.

Running a WebDAV client

You can also test the LNI with a standard WebDAV client, such as [WWW]Cadaver. Start it at the DAV base URL, and explore from there. For example, start cadaver on a Unix system:

Building Your Own Clients

The source to LNISmokeTest is in the file dspace-lni-client.jar, so refer to that for an example of creating a SOAP connection and managing basic operations. The client API source is also included. See the javadoc comments in the org.dspace.app.dav.clietn.LNIClientUtils class for more details.

A WSDL file is also provided if you prefer to build a SOAP client on some other platform. See dspace-lni.wsdl in the client JAR.

Configuring Lightweight Network Interace Client for HTTPS

This section describes what you need to do to run the DSpace LightweightNetworkInterface client against a server that requires (or provides) HTTPS -- HTTP over SSL.

It only covers running the LNI Smoke Test Client under Sun's Java 1.4.x JRE (Java Runtime Environment), on a Unix-based platform. You should be able to adapt these instructions to work under Sun's Java on other platforms.

1. Set up your local Java keystore

The exact steps you need to do here depend on the nature of the server's certificate, that is, the X.509 certificate that identifies it. The first two conditions are most likely.

All of the Unix shell commands below assume that you have set the environment variable JAVA_HOME to the root of the tree where your Sun JRE is installed. For eample, if your Java command runs out of /usr/local/jre/bin/java, then 

    setenv JAVA_HOME /usr/local/jre
      (if using /bin/csh or tcsh)

    JAVA_HOME=/usr/local/jre ; export JAVA_HOME
      (if using /bin/sh or bash)

Now, follow the instructions in ONE and ONLY ONE of the following sections "a", "b", or "c", as applicable:

Option (a): For Server using self-signed Test Certificate

If the server was set up for testing, prototyping, or demonstration, it probably has a temporary "self-signed" certificate. Ask the server administrator, he or she will know.

To get your client to accept such a server, you need to import a copy of the server's certificate into your local keystore as a trusted host.

First, get a copy of the server's certificate from your server administrator, in "DER" format. They can produce it with a command like: 

    $JAVA_HOME/bin/keytool -keystore /var/local/tomcat/conf/keystore \
        -v -export -file /tmp/server-cert.der -alias tomcat

Second, copy that file over to your client system, e.g. in the file /tmp/server-cert.der. Then, import it into your own keystore with the following command. The alias can be any word, if "lni-server" already exists. 

    $JAVA_HOME/bin/keytool -import -v -trustcacerts -alias lni-server \
            -file /tmp/server-cert.der

If it asks you whether to trust this certificate, answer "yes", e.g.
Trust this certificate? [no]: yes

If you have to give a password to create your keystore, use changeit.

Option (b): When server has real certificate from Private CA

Use this procedure when your server has a certificate from a private Certifying Authority, or CA, such as MIT's Server CA. The client's SSL implementation won't know about this CA, so it has to be told to trust its certificates, as follows:

First, get a copy of the CA's "CA Certificate" in DER format:

At MIT, the command would be: 

        wget -O mitca.der http://big-screw.mit.edu/mitca.ca

Then, save it in your keystore as a trusted certificate. Note that the "alias" argument can be anything that isn't already in the keystore: 

        $JAVA_HOME/bin/keytool -keystore ~/.keystore \
             -import -alias mitServerCA -v -file mitca.pem

If it asks you whether to trust this certificate, answer "yes", e.g.
Trust this certificate? [no]: yes

If you have to give a password to create your keystore, use changeit.

Option (c): Server has Commercial Certificate

If your LNI web server has a commercially-made certificate from a company such as Verisign, then chances are, the Java client's SSL already knows about its CA. You should try skipping this step first, to see if it works.

2. Running the Java Client

Add these options to the Java command line that starts the LNI client, before the classname: 

        -Djavax.net.ssl.trustStore=${HOME}/.keystore
        -Djavax.net.ssl.trustStorePassword=changeit

e.g. a typical invocation might look like: 

    java -cp  dspace-lni-client.jar:$LNI_CLASSPATH \
        -Djavax.net.ssl.trustStore=${HOME}/.keystore
        -Djavax.net.ssl.trustStorePassword=changeit
        LNISmokeTest -e http://user:password@mydspace.edu/dspace/lni/DSpaceLNI \
            -f 123456789/4

3. Configuring Truststore Permanently

To run your client in an existing JVM as part of another application, or without specifying the system property settings on the command line, you can make the special truststore (keystore of trusted keys) configuration permanent. There are two ways to do this, as detailed in [WWW]Sun's Java SDK documentation on "Customizing JSSE":

Option (a): Modifying the default truststore file

The default truststore is typically in $JAVA_HOME/lib/security/cacerts, where $JAVA_HOME is the root of your JRE installation. If this JRE is dedicated to your application and you don't mind modifying it, then just add the necessary trusted CA certificate to its truststore by modifying the cacerts file. For example, if the CA certificate for the LNI server you are working with is in the file mySpecialCA.pem, this command would add it to the truststore: 

  $JAVA_HOME/bin/keytool -keystore $JAVA_HOME/lib/security/cacerts -storepass changeit
     -import -v -trustcacerts -alias mySpecialCA -file mySpecialCA.pem

Of course, replace the alias "mySpecialCA" to something appropriate for the CA you are adding, and the filename to your local CA certificate file.

Option (b): Setting system properties in the code

If you cannot or prefer not to modify the truststore, then the only other option is to set the system properties to override the default truststore. Instead of running the JVM ("java") with options to define system properties like -Djavax.net.ssl.trustStore, you can set them in your client program code, so long as you do it before any LNI connections or invocations. Adding the following lines to an initializtion block should be adequate.

This example sets the truststore to "/absolute/path/to/keystore", so of course substitute the absolute pathname of your trusted keystore, and its keystore password, as appropriate: 

 System.setProperty("javax.net.ssl.trustStore", "/absolute/path/to/keystore");
 System.setProperty("javax.net.ssl.trustStorePassword", "changeit");

NOTE: Be sure no other applications running in your JVM have truststore needs that conflict with yours. If they do, you may have to add all the necessary certificates from the default truststore to the one you are using, with the keytool application. See its documentation for details.

4. Debugging

If this fails, and you need to collect more debugging info for experts to figure out what's going on, add this option to the Java command: 

    -Djavax.net.debug=ssl,handshake

Also, you can examine the contents of your keystore with the command: 

    $JAVA_HOME/bin/keytool -keystore ~/.keystore -import -list -v