<?xml version="1.0" encoding="utf-8"?>
<html>

Lightweight Network Interface / Download and Client

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.

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.

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.

Apply the diffs with the Unix command `patch -p0 < lni-1.4-diffs.txt` while in your checkout directory.
Unpack the "new files" Zip, `lni-1.4-new.zip`, which overlays the new files on your source tree.
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.
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:

<nowiki>
    cp build/dspace-lni.war /tomcat/webapps
</nowiki>

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:

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

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:

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

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

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

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

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`

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.

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

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

<tr>
<td>* Library *</td>
<td>* version *</td>
</tr>
<tr>
<td>`activation.jar `</td>
<td>Sun bean activation framework 1.0.2</td>
</tr>
<tr>
<td>`axis.jar `</td>
<td>Apache Axis 1.3 </td>
</tr>
<tr>
<td>`axis-ant.jar `</td>
<td>Apache Axis 1.3</td>
</tr>
<tr>
<td>`jaxrpc.jar `</td>
<td>Apache Axis 1.3</td>
</tr>
<tr>
<td>`saaj.jar `</td>
<td>Apache Axis 1.3</td>
</tr>
<tr>
<td>`wsdl4j-1.5.1.jar `</td>
<td>Apache Axis 1.3</td>
</tr>
<tr>
<td>`commons-codec-1.3.jar `</td>
<td>Apache Jakarta Commons Codec 1.3
(Downloads page for these 4 Jakarta Commons sub-projects)</td>
</tr>
<tr>
<td>`commons-discovery-0.2.jar `</td>
<td>Apache Jakarta Commons Discovery 0.2 </td>
</tr>
<tr>
<td>`commons-logging.jar `</td>
<td>Apache Jakarta Commons Logging 1.0.3
(Appears [ v.1.0.4|http://apache.oregonstate.edu/jakarta/commons/logging/binaries/commons-logging-1.0.4.tar.gz] and v.1.0.2 are available, but not 1.0.3 Try 1.0.4 (wreilly))</td>
</tr>
<tr>
<td>`commons-cli-1.0.jar `</td>
<td>Apache Jakarta Commons CLI 1.0</td>
</tr>
<tr>
<td>`jdom.jar `</td>
<td>JDOM 1.0 (jdom.org) </td>
</tr>
<tr>
<td>`log4j.jar `</td>
<td>Apache log4j 1.2.8
(Best for now to get no-longer-latest version 1.2.8)</td>
</tr>

</table>

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

<nowiki>
  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
</nowiki>

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
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\* (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/>`

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

<nowiki>
    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)
</nowiki>

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:

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

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.

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

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:

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

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:

<nowiki>
        $JAVA_HOME/bin/keytool -keystore ~/.keystore \
             -import -alias [[mit Server C A]] -v -file mitca.pem
</nowiki>

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:

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

e.g. a typical invocation might look like:

<nowiki>
    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
</nowiki>

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":

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:

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

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

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

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:

<nowiki>
    -Djavax.net.debug=ssl,handshake
</nowiki>

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

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

</html>

Page tree

LightweightNetworkInterface DownloadsAndClients