Overview (Isode Java DSAPI Classes)

This is the specification for the Isode's Java DSAPI class library.

The Java DSAPI class library consists of a set of Java classes which make use of Isode native libraries to provide a set of functionality useful for applications dealing with directory servers. This section provides a brief overview of some of the main aspects of the API; you should consult the documentation for individual classes and methods for full details on the functionality provided.

Java DSAPI functionality includes the following features

ability to connect to, query, and modify data in a directory server
validation of data against the currently installed directory schema
processing and generating LDIF data files

Java DSAPI can access a directory using either DAP or LDAPv3. While in most cases client applications need not be aware of which protocol is being used, there are certain situations where behaviour is different (for example, signed operations are not supported over LDAP). The documentation makes clear those cases when the protocol being used affects functionality.

Writing an application which uses Java DSAPI

Client applications will typically follow this this basic structure (see the sections below):

Initialize the Java DSAPI library
Create DirectorySession objects corresponding to the directories servers that will be used
Perform directory operations
Unbind from the directory

Initializing Java DSAPI

An application which uses Java DSAPI must make a call to DSapi.initialize() before doing anything else. This method is used to load and initialize native libraries which Java DSAPI requires: attempts to use any other Java DSAPI functions before initializing the library are likely to result in UnsatisfiedLinkError exceptions.

Applications wishing to make use of X.509 for strong authentication should use DSapi.initializeSecurity()

DirectorySession objects

The DirectorySession class is used to encapsulate information about a directory connection. DirectorySession objects are constructed by specifying the presentation address of a directory server, which is a String that may be an RFC 1278 format presentation address (for example, "internet=server.host.net+102") or an RFC 2255 format LDAP URL (for example, "ldap://server.host.net:389").

Having created a DirectorySession object, an application will use one of the bind() methods to bind to the directory server. Such methods return a bind indication, which may be inspected by callers to obtain extra information that might have been returned (for example, relating to password policy).

Performing Directory Operations

The DirectorySession class provides various methods to read from or write to the directory. As well as any parameters specific to the operation concerned, many DirectorySession methods accept a CommonArgs parameter, and return an Indication object. Operations which fail (either due to a local error, or because the directory server has returned an error) will throw a DSAPIException.

A CommonArgs parameter may be used to control the use of certain service parameters. For example, applications may wish to specify a sizelimit on the number of results returned from a search operation, or to control the behaviour of the directory server with respect to alias entries.

In all cases, it is possible to specify null as an argument for CommonArgs: in this case a set of default values is used.

Indication objects contain information about the result of a directory operation. In the case of a search and read operations, applications use the Indication to retrieve information about entries returned from the server, but it not always necessary to worry about the returned Indication object: for example, the Indication returned by a successful call to DirectorySession.delete() is typically of little interest.

Unbinding from a Directory

The unbind() method is used to unbind from a directory. DirectorySession objects will call unbind() when they are finalized, and so it is not necessary for applications to do this explicitly, but in the absence of a guarantee about when the garbage collector will run, it is good practice for applications to unbind once they no longer require a connected session.

Exceptions

Java DSAPI uses DSAPIExceptions to report errors which are likely to be caught and handled by user code. For example, an attempt to read a non-existent entry from a directory will result in a NoSuchEntryException being thrown.

NativeLibraryExceptions are thrown only in cases where a fatal error has been detected that prevents Java DSAPI from continuing. Applications need not use catch clauses for NativeLibraryExceptions, which are subclassed from RuntimeException. If a NativeLibraryException is thrown, then it will contain a message describing the underlying problem. Where possible (and assuming logging has been enabled), information will be written to the application's event log. Unless the NativeLibraryException is caused by some identifiable factor (e.g. memory exhaustion, or incorrectly installed software), you should contact Isode support if this happens.

Building and Deploying an application which uses Java DSAPI

The Java DSAPI class library is contained inside isode-dsapi.jar, which by default is installed, along with various other class libraries, in the directory (LIBDIR)/java/classes. To compile an application which uses Java DSAPI, you must ensure that isode-dsapi.jar appears on the CLASSPATH used by the compiler.

To run an application which uses Java DSAPI, you must have isode-dsapi.jar on your CLASSPATH, and you must also make sure that the JVM is able to locate shared libraries that are used by Java DSAPI. These shared libraries are installed in (LIBDIR).

For example, to build an application on Unix, you would use something like:

% javac -cp /opt/isode/lib/java/classes/isode-dsapi.jar MyClass.java

and to run the application:

% java -Djava.library.path=/opt/isode/lib -cp /opt/isode/lib/java/classes/isode-dsapi.jar:. MyClass

Examples

Display entries from a directory

The following program performs a subtree seach of an LDAP directory and displays all the entries that are returned (showing all the values of each attribute).

The example specifies an LDAP URL as the server's presentation address, which means that Java DSAPI will make an LDAP connection to the server. Changing the presentation address to, e.g. "internet=server.host.net+102" would cause Java DSAPI to attempt a DAP connection instead: the rest of the program need not be changed.

import com.isode.dsapi.*;

public class SearchDemo {
    static public void main(String[] args)
    {
        DSapi.initialize();
        DirectorySession ds = null;
        Indication ind = null;
        try {
            ds = new DirectorySession("ldap://server.host.net:389");
            ds.bind(null); // anonymous bind

            ind = ds.searchSubTree(
                    new DN("ou=staff,o=big corp"),
                    DirectorySession.MATCHALL, // match all entries
                    new Selection());          // request all user attributes
            // No exception was thrown so the search returned something
            for (Entry entry : ind) {
                System.out.println(entry.getDN());
                for (Attribute attribute : entry) {
                    System.out.println("  " + attribute.getAttributeName() + ":");
                    for (AttributeValue attributeValue : attribute) {
                        System.out.println("    " + attributeValue);
                    }
                }
            }
        }
        catch (DSAPIException e) {
            System.out.println("Exception: " + e);
        }
    }
}

Packages
Package	Description
com.isode.dsapi
com.isode.dsapi.atnds