From DSpace Wiki

[edit] Lightweight Network Interface / Download and Client

[edit] Downloads

• lni-1.4-diffs.tar Patch to DSpace 1.4alpha source (28-Mar-06)
• lni-1.4-new.zip New files to add to DSpace 1.4 alpha (28-Mar-06)
• dspace-lni-client.jar Pre-built client library JAR and WSDL -- not needed when building from source.

[edit] Installing LNI in DSpace 1.5

LNI comes as an addon to 1.5 and can be installed as the default.

The current maintenance branch can be found here:

http://dspace.svn.sourceforge.net/svnroot/dspace/branches/dspace-1_5_x/dspace-lni/[

If your just looking for a copy of the client there is a SNAPSHOT version located here

dspace-lni-client-1.5-SNAPSHOT-jar-with-dependencies.jar

There is still the same client as above, but now it can be gotten packaged with all its dependencies for easy execution and can be placed anywhere on the filesystem.

Building DSpace 1.5 is much different than 1.4 please follow the instructions in the dspace documentation for building LNI or any other Addon.

[edit] 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.

[edit] 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`

[edit] 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.

[edit] 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

[edit] Using the LNI Clients

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

[edit] 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:

  `http://`user`:`password`@`host`/dspace-lni/lni/DSpaceLNI`

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.

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

[edit] 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 "smoke test" implies it is only a very preliminary and simple test.

[edit] 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.

   `java -jar `path-to-dspace-lni-client.jar-file  smoke-test-options

e.g.

   `java -jar /var/src/dspace/build/dspace-lni-client.jar -e `endpoint ...

[edit] 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:

   `java -classpath `class-path` [LNISmokeTest] `smoke-test-options

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:....`

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 \
   [[L N I Smoke Test]] -e http://user:password@mydspace.edu/dspace/lni/DSpaceLNI -f 123456789/4

[edit] 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.

[edit] Running a WebDAV client

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

  `% cadaver http://mydspace.mit.edu/dspace-lni/dav
  
Username: florey@mit.edu
  
Password: xyzzy
  
dav:/dspace-lni/dav/> ls
  
Listing collection /dspace-lni/dav/: succeeded.
  
Coll:   dso_123456789$1                        0  Dec 31  1969
  
Coll:   dso_123456789$83                       0  Dec 31  1969
  
dav:/dspace-lni/dav/>`

[edit] 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.

[edit] 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.

[edit] 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:

[edit] 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`.

[edit] 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 [[mit Server C A]] -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`.

[edit] 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.

[edit] 2. Running the Java Client

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

        -Djavax.net.ssl.[[trust Store]]=${HOME}/.keystore
        -Djavax.net.ssl.[[trust Store Password]]=changeit

e.g. a typical invocation might look like:

    java -cp  dspace-lni-client.jar:$LNI_CLASSPATH \
        -Djavax.net.ssl.[[trust Store]]=${HOME}/.keystore
        -Djavax.net.ssl.[[trust Store Password]]=changeit
        [[L N I Smoke Test]] -e http://user:password@mydspace.edu/dspace/lni/DSpaceLNI \
            -f 123456789/4

[edit] 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 Sun's Java SDK documentation on "Customizing JSSE":

[edit] 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.

[edit] 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 initialization 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.

[edit] 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