Mobile devices are quickly becoming indispensable tools for convenience and productivity wherever you may happen to be. Around the beginning of the year, I started to look at the Android platform for developing applications for mobile devices (and other low-end kinds of systems). I picked up a Google developer phone (basically an unlocked version of the T-Mobile G1) and was impressed by the pretty rich API that it offers. Quite a large portion of Java SE is available for use, although there are some notable exceptions. For example, it’s missing all of the GUI classes, but that makes sense since Android provides its own GUI library. But another significant omission is that of JNDI, which is the API included in Java SE for communicating with LDAP directories.

On one hand, this is a good thing since JNDI is a horrible API that is inconvenient to use and doesn’t provide very good access to the LDAP protocol, and the less opportunity there is to use it the better. But on the other hand, being able to communicate with an LDAP directory server on a mobile device can be extremely helpful. For example, it could be very convenient to have access to the entire corporate directory at your fingertips for phone numbers and e-mail addresses without the need to clutter your contacts list, or maybe to keep local contacts in sync with their corresponding entries from the corporate directory.

The good news, though, is that Android developers don’t need to worry about missing LDAP support for Android because the UnboundID LDAP SDK for Java works just fine on the Android platform. I’ve done quite a bit of testing and made sure that things just work. With a couple of exceptions (primarily CRAM-MD5, DIGEST-MD5, and GSSAPI, which require the Java SASL API that isn’t available on Android) pretty much all of the functionality that we offer in our LDAP SDK can be used on Android. This includes all of the core protocol, all of the controls and extended operations, SSL/StartTLS, connection pooling, and all the other stuff is there, too. Note that there is no special “Android” version of the LDAP SDK — the same SDK that you can use for writing desktop clients or server-side applications works without any changes on the Android platform.

To demonstrate this capability, I’ve put together a simple LDAP client for Android devices. You can see a video online at http://www.youtube.com/watch?v=1NlhwrcCeSQ.

The UnboundID LDAP SDK for Java version 0.9.6 has just been released. This post details some of the changes included since the previous 0.9.5 release. See the release notes for additional information. If you’d like to be notified by e-mail when a new release is available, send a message to ldapsdk-announce-subscribe@unboundid.com.

Some of the changes in this release were based on feedback we received regarding the LDAP SDK. If you have suggestions or other feedback, feel free to send your comments to ldapsdk-support@unboundid.com.

Intermediate Response Messages

The LDAP SDK now includes support for LDAP intermediate response messages as defined in RFC 3771. Intermediate responses make it possible for operations return multiple responses to a single request. A new IntermediateResponseListener interface has been added, and clients can use the LDAPRequest.setIntermediateResponseListener method to be notified of any intermediate responses returned for the operation.

AuthRate Tool

A new authrate tool has been added as an example program. It is similar to the existing SearchRate tool, except that when retrieving an entry it can also perform a bind to verify the user’s password. It supports simple authentication, as well as the CRAM-MD5, DIGEST-MD5, and PLAIN mechanisms.

CommandLineTool Example Usages

The CommandLineTool API has been updated so that it is now possible to provide examples in the usage output. All of the example tools provided with the LDAP SDK now provide example usages.

Connection Pool Connection Expiration

It is now possible to define a maximum age for connections included in a connection pool. If a maximum age is defined and a connection in the pool has been established for greater than this length of time, then the connection will be closed and replaced with a new connection.

Connection and Connection Pool Statistics

A new LDAPConnection.getConnectionStatistics method has been added which can be used to retrieve an LDAPConnectionStatistics object with information about how that connection has been used. This includes the number of times the connection has been established and closed, the number of times each type of request has been sent, the number of times each type of response has been received, and the total and average response time for operations.

A new LDAPConnectionPool.getConnectionPoolStatistics method has been added which can be used to retrieve an LDAPConnectionPoolStatistics object which can be used to retrieve information about how the connection pool has been used. This includes the number of connections currently available, the maximum number of connections that may be available, the number of successful and failed attempts to create new connections, the number of connections that have been closed as defunct, expired, or unneeded, the number of successful and failed attempts to retrieve a connection, and the number of valid connections released back to the pool.

This feature was suggested by Philip Peake.

Connection Pool Health Checking

A new LDAPConnectionPoolHealthCheck API has been added which makes it possible to perform health checking for connections in a connection pool. It can be used to perform checks to determine whether a connection is valid when a new connection is created, checked out, released back to the pool, or after an exception has been encountered while processing an operation in the pool. In addition, a background thread will be used to periodically invoke health checks against all available connections.

A health check implementation has been added which can be used to verify the validity of a connection by retrieving a specified entry from the directory server. It can assess the connection’s availability based on whether the entry can be retrieved and the length of time required to retrieve it.

This feature was suggested by Philip Peake.

Improved Interaction with DNs and RDNs as Strings

A number of convenience methods have been added to the DN and RDN classes to make it easier to deal with them using their string representations. This includes the ability to determine whether a string represents a valid DN or RDN, to compare DNs and RDNs based on their string representations, and to determine whether strings representing DNs have a hierarchical relationship.

This feature was suggested by Felix Gaehtgens.

Improved LDIFReader Performance

The LDIFReader class has been updated to improve its performance when reading entries containing an attribute with a large number of values (e.g., a static group). For a single-threaded test case involving reading group entries with 2000 members, the new implementation was measured at over 360 times faster.

This problem was reported by Felix Gaehtgens.

One of the things that we’ve tried to do with the UnboundID LDAP SDK for Java is to make it as easy as possible to use. Some of this is kind of intangible (e.g., providing convenience methods for doing common things that might take multiple steps in other APIs), but there are things that I think are worth mentioning that we’ve done in this area to help developers write better applications. I’ll describe some of them here.

Extensive Javadoc Documentation

We provide a number of different types of documentation with the LDAP SDK (also available online at http://www.unboundid.com/products/ldapsdk/docs/), but I think that the most helpful documentation is the Javadoc that we generate from the source code. All public and protected methods are documented, including information about each argument and the value returned, and all public and protected fields are also documented.

Other than providing information about the available fields and methods, some of the most useful information included in the Javadoc is the class-level documentation that we provide. In many cases, this is quite extensive, and we include a number of code snippets that demonstrate how to use that class. For example, the class-level documentation for nearly all of the request types as well as the controls and extended operations provide examples for using them.

Another benefit of our Javadoc documentation is that we have generated it with the “-linksource” option, so that means that the entire source code for all of the documented classes is included as part of the documentation. This makes it possible to click on the name of a class or method in the Javadoc and be taken directly to the source code for it. In the event that you have a question about the API that can’t be answered by the Javadoc documentation itself, then using this to look at the source code itself can be very useful.

Annotations

The Javadoc documentation provides extensive information about how to use the LDAP SDK, but by itself there are some questions which a developer might have for which the answers aren’t immediately obvious. For many of these, we have defined annotations that may help make this clearer. Some of those annotations include:

• @ThreadSafety — In many APIs, there isn’t much documentation available about the behavior of the associated code when accessed concurrently by multiple threads. To help make it clearer for our LDAP SDK, all public classes and interfaces have been marked with the @ThreadSafety annotation that indicates how those types of object may be treated in multithreaded contexts.
• @Extensible / @NotExtensible — These annotations are used to mark interfaces and non-final classes to indicate whether they are intended to be extended by third-party code. There are some interfaces and non-final classes in the LDAP SDK which are primarily intended to be extended only by code within the LDAP SDK, and they have been marked with the @NotExtensible annotation. On the other hand, a number of interfaces and non-final classes are safe to extend by third-party code, and they are marked with the @Extensible annotation.
• @Mutable / @NotMutable — These annotations are used to mark classes to indicate whether objects of that type are allowed to be altered by third party code. Most classes which are marked @NotMutable are fully immutable so there is no way to alter their contents at all, but there are a few cases in which it is necessary for an object to be modifiable by code within the LDAP SDK, and in those cases the associated class is marked @NotMutable to indicate that those objects shouldn’t be externally altered. For objects which may be safely altered by third-party code, the classes are marked @Mutable.
• @InternalUseOnly — There are a few cases within the LDAP SDK where constraints enforced by Java require a class or method to be public but we don’t intend for it to be used by external code (e.g., a method required by an internal interface). In such cases, the associated class or method is marked with the @InternalUseOnly annotation to indicate that it’s not intended to be used by third-party code.

These annotations have a “runtime” retention, so they are accessible via reflection (and in fact, we have a number of unit tests to ensure that classes are marked correctly). They also appear in the generated Javadoc documentation, so that helps further improve the quality of the Javadoc.

Generics

Wherever appropriate, the LDAP SDK makes full use of generics. This is particularly true for all collections that are used anywhere in the code. This is very useful for developers because it helps them understand the types of element contained in that collection.

Debugging Support

If something goes wrong with a program using the LDAP SDK, then it may be helpful to debug the processing performed by the LDAP SDK. You can, of course, step through the code using a Java debugger, but you can also enable debugging support within the LDAP SDK itself. This uses the Java logging framework to provide messages about actions performed within the SDK, including:

• Establishing and closing connections to directory servers
• LDAP requests sent and responses received
• ASN.1 elements encoded and decoded
• LDIF entries and change records read and written
• Exceptions caught within the LDAP SDK
• Information about coding errors in which the LDAP SDK was used incorrectly (e.g., an argument that was inappropriately null or had a value outside of an acceptable range)

These types of debugging can be enabled or disabled on an individual basis, and you can control the minimum log level for messages that you want to see.

Debugging can be enabled or disabled programmatically by code using the LDAP SDK by calling methods in the com.unboundid.util.Debug class). However, debugging can also be controlled through the use of Java properties without the need to make any changes in the code using the LDAP SDK. The following properties are defined for use:

• com.unboundid.ldap.sdk.debug.enabled — If this property is set to “true“, then debugging will be enabled.
• com.unboundid.ldap.sdk.debug.level— If this property is set, then it may control the minimum debug level for messages to be written. Allowed debug levels include ALL, SEVERE, WARNING, INFO, CONFIG, FINE, FINER, FINEST, or OFF.
• com.unboundid.ldap.sdk.debug.type — This may be set to a comma-delimited list of the types of debugging to be used within the LDAP SDK. Available debug types include ASN1, CODING_ERROR, CONNECT, EXCEPTION, LDAP, LDIF, and OTHER. If this property is not set, then all debug types will be used.

If debugging is enabled, then it will use a logger name of “com.unboundid.ldap.sdk“. By default, messages will be written to standard error, although the Java logging framework can be configured to use a custom logger to send the messages elsewhere.

Disconnect Notification

With many APIs that provide LDAP communication, if a connection to the directory server is lost, then the application may have no way of knowing until it tries to use that connection, and at that point it is often not possible to understand when the connection was closed or for what reason.

The UnboundID LDAP SDK for Java provides a com.unboundid.ldap.sdk.DisconnectHandler interface, which may be implemented by third-party code to provide a mechanism to notify an application whenever it detects that a connection has been closed. This interface defines the following method:

void handleDisconnect(LDAPConnection connection,
String host,
int port,
DisconnectType disconnectType,
String message,
Throwable cause)

Whenever a connection has been closed, the disconnect handler’s handleDisconnect method will be called to notify it of the disconnect and provide information about it. The DisconnectType element will provide information about the reason for the disconnect, and can be used to indicate whether the closure was expected (e.g., by calling connection.close() to perform an LDAP unbind). If desirable, the disconnect handler may attempt to re-establish the connection (perhaps to a different server), which may help avoid user-visible failures that may result from attempting to use the connection.

The LDAP Data Interchange Format (LDIF) is a standard way of representing directory data in plain text files, as defined in RFC 2849.  LDIF records can represent entire entires, or they can represent changes to be made to directory contents (add new entries, or remove, modify, or rename existing entries).  The UnboundID LDAP SDK for Java provides rich support for interacting with LDIF records, in many ways.  This post will describe the capabilities that it offers in this area.

Reading LDIF Records

The com.unboundid.ldif.LDIFReader class provides methods for reading data from LDIF files or from input streams.  Some of the methods it offers are:

• readEntry() — This reads the next entry from the LDIF file or input stream.  This should be used when reading LDIF data known to contain only entries.
• readChangeRecord() — This reads the next change record from the LDIF file or input stream.  This should only be used when reading LDIF data known to contain only change records.
• readLDIFRecord() — This reads the next entry or change record from the LDIF file or input stream (both entries and change records implement the LDIFRecord interface).  This should be used when reading LDIF data that may contain a mix of entries and change records.
• decodeEntry(String...) — This decodes the contents of the provided array as an LDIF entry.  The elements of the array should be the lines of LDIF entry to be parsed.  This is a static method and doesn’t require an LDIFReader object to be created to be able to use it.
• decodeChangeRecord(String...) — This decodes the contents of the provided array as an LDIF change record.  The elements of the array should be the lines of the LDIF change record to be parsed.  This is a static method and doesn’t require an LDIFReader object to be created to be able to use it.

When reading and parsing LDIF records, if an invalid record is encountered then the LDIF reader will throw an LDIFException.  It will include a message about the problem encountered, the line number in the LDIF data on which the problem was encountered, and a flag indicating whether or not it is possible to continue reading data from the LDIF source.  Methods used to read LDIF data from a file or input stream may also throw an IOException.

Writing LDIF Records

The com.unboundid.ldif.LDIFWriter class provides methods for writing LDIF content to files or output streams.  Some of those methods include:

• writeEntry(Entry) — This method writes the provided entry to the LDIF file or output stream.
• writeEntry(Entry,String) — This method writes the provided entry to the LDIF file or output stream, immediately preceded by the specified comment.
• writeChangeRecord(LDIFChangeRecord) — This method writes the provided change record to the LDIF file or output stream.
• writeChangeRecord(LDIFChangeRecord,String) — This method writes the provided change record to the LDIF file or output stream, immediately preceded by the specified comment.
• writeLDIFRecord(LDIFRecord) — This method writes the given LDIF record (which may either be an entry or change record) to the LDIF file or output stream.
• writeLDIFRecord(LDIFRecord,String) — This method writes the given LDIF record (which may either be an entry or change record) to the LDIF file or output stream, immediately preceded by the specified comment.

Methods used for writing LDIF data may throw an IOException.

Parallel LDIF Processing

We’ve worked hard to make the process of reading and writing LDIF data as fast as possible.  While it’s pretty fast on its own as a serial process, portions of the processing may be parallelized for better performance on multi-CPU and/or multi-core systems.

When reading LDIF data, there are two phases of processing:  the process of reading raw data from the LDIF file or input stream, and the process of decoding that data as an entry or change record.  The first phase must be performed serially, but the second can be parallelized and multiple concurrent threads may be used to decode LDIF records.  As a result, when the LDIF reader is configured to use multiple concurrent threads, it may be the case that the limiting factor is the speed at which data can be read from the disk or input stream.

In order to use parallelism in the LDIF reader, it is only necessary to specify the number of additional threads to use when parsing entries or change records at the time the reader is created.  This parallelism will be provided completely behind the scenes, so that the caller may continue to use the readEntry(), readChangeRecord(), and readLDIFRecord() methods just as if all processing were performed serially.

Of course, introducing parallelism in the LDIF reader would be of limited usefulness if it introduced the possibility that entries or change records might be made available to the caller in a different order than they were contained in the original LDIF data.  As a result, the LDIF reader will ensure that the order of the data is preserved so that the only perceptible change between serial and parallel processing is the relative speed with which LDIF records may be made available to the caller.

The LDIF writer also provides support for parallel processing, in which case multiple entries or change records may be formatted into their LDIF representations in parallel, and then will be written serially to the LDIF file or output stream. As with the LDIF reader, parallelism may be enabled by specifying the number of threads to use to perform that processing at the time that the LDIF writer is created. However, parallel processing will only be performed in the LDIF writer if the entries or change records are provided to it using the writeLDIFRecords(List<? extends LDIFRecord>) method. The order that the records are provided in the list will be preserved when they are written to the LDIF file or output stream.

Transforming Entries Read from LDIF

When reading entries from an LDIF file or input stream, it may be useful to alter those entries in some way before they are made available to the caller, and in some cases it may be desirable to exclude entries altogether.  Either or both of these may be performed by providing a class which implements the com.unboundid.ldif.LDIFReaderEntryTranslator interface to the LDIF reader. If an entry translator is provided, then whenever an entry is read, the translate(Entry,long) method will be invoked to allow the translator to return a modified version of the provided entry, a completely new entry, or null to indicate that the entry should be omitted from the data made available to callers.

If the LDIF reader has been configured to perform parallel processing, then the entry translator will be invoked during the parallel portion of that processing, and as a result it may be faster to perform this transformation using the LDIFReaderEntryTranslator interface than performing it separately after the entry has been retrieved by the caller using a method like readEntry(). This does require the translator to be threadsafe, and it cannot depend on the order in which entries are processed.

Obtaining LDIF Representations of LDAP SDK Objects

There are a number of objects provided as part of the LDAP SDK which can be represented in LDIF form without the need for an LDIF writer. This includes the following types of objects:

• com.unboundid.ldap.sdk.Entry — This can be represented as an LDIF entry.
• com.unboundid.ldap.sdk.AddRequest — This can be represented as an LDIF add change record.
• com.unboundid.ldap.sdk.DeleteRequest — This can be represented as an LDIF delete change record.
• com.unboundid.ldap.sdk.ModifyRequest — This can be represented as an LDIF modify change record.
• com.unboundid.ldap.sdk.ModifyDNRequest — This can be represented as an LDIF modify DN change record.

All of these objects provide the following methods that allow them to be represented in LDIF form:

• toLDIF() — This returns a string array whose elements comprise the lines of the LDIF representation of the associated record.
• toLDIFString() — This returns a string containing the LDIF representation of the associated record, including line breaks.

In addition, the above objects except Entry provide a toLDIFChangeRecord() method that allow them to be converted to the appropriate type of LDIF change record.

Using LDIF Records to Process Operations

The LDAP SDK also provides support for processing operations based on the LDIF representation.  There are two primary ways that this may be accomplished:

• All types of the LDIF change records provide a processChange(LDAPConnection) method which can be used to directly process an operation from that change record.  Each change record type also provides a method for converting that change record object to an LDAP request (e.g., the LDIFAddChangeRecord class provides a toAddRequest() method to convert the change record to an equivalent add request).
• Entries can be created from their LDIF representation using the Entry(String...) constructor, where the provided string array contains the lines that comprise the LDIF representation of that entry. Add requests can also be created from the LDIF representation of the entry to add using the AddRequest(String...) constructor. Modify requests can also be created from the LDIF representation of that modify request using the ModifyRequest(String...) constructor.

When writing a directory-enabled application, you can let the directory server do a lot of the work for you, and in many cases that’s appropriate.  However, there are times when it might be better to do some of that processing on the client rather than the server (e.g., because of the performance hit of the additional requests, or because some target servers might not support all of the features you want to use).  In other cases it might be useful to perform client-side validation prior to sending a request to the server to reduce the likelihood of a failure or to provide better information about what needs to be fixed.  The UnboundID LDAP SDK for Java provides support for several types of client side processing, as described in this post.

Comparing Entries

The com.unboundid.ldap.sdk.Entry class includes a diff method that can be used to compare two entries. The complete definition for this method is:

public static List<Modification> diff(Entry sourceEntry,
Entry targetEntry, boolean ignoreRDN, String... attributes)

It can be used to compare the contents of the two provided entries and will return a list of the modifications that can be applied to the source entry in order to make it look like the target. You can optionally ignore differences in the RDN attribute, and you can optionally restrict the comparison to a specified set of attributes.

There are many uses for this capability. For example, if you have an application that allows a user to alter the contents of entries, then this method may be used to compare a local copy of the updated entry with the original entry in order to determine the modifications to apply to the server. Alternately, you could use this to compare an entry in two different servers to determine whether they are in sync.

Schema Validation

The LDAP SDK provides enhanced support for parsing server schema definitions, and can use that to perform a number of types of client-side processing. One such capability is exposed through the com.unboundid.ldap.sdk.schema.EntryValidator class. This class may be initialized with schema read from the server and provides the following method:

public boolean entryIsValid(Entry entry, List<String> invalidReasons)

This method may be used to determine whether the given entry conforms to the schema constraints defined in the server. The basic checks that it can perform include:

• Ensure that the entry has a valid DN
• Ensure that the entry has exactly one structural object class
• Ensure that all of the entry’s object classes are defined in the schema
• Ensure that all of the entry’s attributes are defined in the schema
• Ensure that all of the attributes required by any of the entry’s object classes are present
• Ensure that all of the attributes contained in the entry are allowed by at least one of that entry’s object classes
• Ensure that all of the attribute values conform to the syntax defined for that attribute
• Ensure that all of the attributes with multiple values are defined as multi-valued in the server schema

In addition, if there is a DIT content rule associated with the entry’s structural object class, then it will be used to ensure that all of the auxiliary object classes in the entry are allowed and that the entry doesn’t contain any prohibited attributes, and it may also allow additional attributes not allowed by any of the object classes. If there is a name form associated with the entry’s structural object class, then the entry validator will use it to ensure that the entry’s RDN includes all of the required attributes, and that all attributes included in the entry’s RDN are allowed.

All of these checks may be individually enabled or disabled, which makes it possible to tailor the types of validation to perform. In addition, the entryIsValid method is threadsafe, so it can be called concurrently by multiple threads. If the entry is invalid, then this method will return false, and the provided list will include one or more human-readable messages detailing the problems identified with the entry. It will also collect summary statistics about all of the entries examined so that if a number of entries are processed it is easy to understand the types of problems (if any) that were encountered.

One of the example programs provided with the LDAP SDK is a validate-ldif tool which uses the EntryValidator class to perform this validation for all entries in an LDIF file. This can provide a useful way to validate that the entries contained in an LDIF file are valid without needing to actually import the data into a server. If there are any problems, then the summary provided by the tool may be easier to interpret than the errors reported by the server.

Sorting

Many directory servers provide support for the server-side sort control as defined in RFC 2891. However, some servers may not support this control, and of the servers that do support it, some of them may require special configuration or indexing, and the client may require special permissions to be allowed to request it. In addition, for small result sets, it may be significantly more efficient (and less resource-intensive on the server) to perform sorting on the client rather than asking the server to do it.

The UnboundID LDAP SDK for Java provides a com.unboundid.ldap.sdk.EntrySorter class that can be used to accomplish this. It includes the following method that makes it possible to sort a collection of entries:

public SortedSet<Entry> sort(Collection<? extends Entry> entries)

This class also implements the Comparator<Entry> interface, so it can be used with any type of Java collection that can use comparators.

It is possible to define the sort criteria, including specifying which attributes should be used and indicating whether to sort in reverse order. It can also be configured to take the entry’s position in the DIT into consideration when sorting so that entries can be sorted by hierarchy instead of or in addition to performing attribute-based sorting.

For best results, the entry sorter is able to use schema read from the directory server in order to better understand which matching rules it should use for sorting, but if no schema is available it will simply assume that all sorting should be done using case-ignore ordering.

Filter Evaluation

There are a number of cases in which it might be useful to determine whether an entry matches a given set of criteria, and search filters provide a convenient way to express that criteria. If the entry exists in a directory server, then of course a search operation may be used to make the determination, but if the client has a local copy of the entry then it may be more convenient or efficient to perform the evaluation on the client. Further, there may be cases (e.g., for an entry read from an LDIF file) in which the entry isn’t available in a server. To provide this capability, the com.unboundid.ldap.sdk.Filter class includes the following methods:

public boolean matchesEntry(Entry entry)
public boolean matchesEntry(Entry entry, Schema schema)

If a schema object is provided, then it will be used to perform more accurate evaluation, but if no schema is available then it will work using case-ignore matching. This method currently supports all types of filter evaluation except approximate and extensible matching.

In order to get the best performance and efficiency from a directory-enabled application, you will likely want to use some form of connection pooling.  Most LDAP APIs provide support for some level of connection pooling, but I’m not aware of any other API that provides anywhere near the power and convenience of the connection pooling capabilities of the UnboundID LDAP SDK for Java.  This post will examine many of the connection pooling features that it provides.

Connection Pool Implementations

The UnboundID LDAP SDK for Java actually provides two connection pool implementations.  The com.unboundid.ldap.sdk.LDAPConnectionPool class provides a single set of connections intended to be used for all types of operations. The com.unboundid.ldap.sdk.LDAPReadWriteConnectionPool class maintains two sets of connections, one set intended for use in processing write (add, delete, modify, and modify DN) operations, and the other for use in processing read (bind, compare, and search) operations. The former is the best choice for environments in which all of the directory servers have the same capabilities, while the latter is better for environments containing some a mix of read-only and read-write servers.  The read-write connection pool implementation may also be useful in environments in which it is recommended to try to send all writes to the same server, even if all of the servers technically support read and write operations.

Failover and Load Balancing

Connection pools can be created so that all connections in the pool are established to the same server, or they can be spread across multiple servers.  This can be accomplished through the com.unboundid.ldap.sdk.ServerSet API, which is used to determine which server to use at the time that a connection is created.  There are three server set implementations provided in the LDAP SDK, and you can create your own with whatever logic you choose. The included implementations are:

• com.unboundid.ldap.sdk.SingleServerSet — This is a simple implementation in which connections will always be established to the same server.
• com.unboundid.ldap.sdk.RoundRobinServerSet — This is an implementation that allows you to specify a list of servers. The first attempt to create a connection will use the first server, the second will choose the second server, and so on, and once it hits the end of the list it will wrap back around to the beginning.   If the selected server is unavailable, it will skip ahead to the next server in the list, and will only fail if none of the servers are available.
• com.unboundid.ldap.sdk.FailoverServerSet — This is an implementation that allows you to specify an ordered list of servers, and when attempting to establish a new connection it will always try the first server, but if it isn’t available then it will try the second, then the third, and so on. This implementation also provides the ability to fail over between server sets rather than individual servers, which can provide a lot of flexibility (e.g., try round-robin across all servers in the local data center, but if none of them are available then try round-robin across all the servers in a remote data center).

When a connection pool is created with a server set, then that server set will be used to establish all connections in that pool.  For example, if you create a pool with ten connections and you use the round-robin server set with a list of two servers, then five of the connections in that pool will be established to the first server and five to the second.  This provides a simple mechanism for client-side load balancing, since operations performed using pooled connections will be spread across the two servers.  It also provides better availability, since if either server becomes unavailable then connections established to it will fail over to the other (and in many cases it will be transparent to the application).

If all of the servers defined for use in a connection pool are unavailable at the same time, then obviously any attempt to use that connection pool during that time will fail.  However, as soon as any of those servers is back online, then the pool will resume normal operation and operations will again be successful without the need to restart the application or re-create the pool.

Checking out and Releasing Connections

Traditionally, connection pools simply maintain a set of connections that the application can check out, use as needed, and return.  Although the implementations provided by the UnboundID LDAP SDK for Java go well beyond this, it still possible to check out and release connections as needed.

In the LDAPConnectionPool implementation, a connection can be obtained using the getConnection() method. The application can then do the appropriate processing, and when complete it can release the connection back to the pool with the releaseDefunctConnection(LDAPConnection) method. If an error occurs during processing that indicates the connection is no longer viable, then the releaseDefunctConnection(LDAPConnection) method should be used instead, which will cause the provided connection to be closed and discarded a new connection created in its place.

The LDAPReadWriteConnectionPool implementation provides similar methods for checking out and releasing connections, but there are separate methods for interacting with the read and write pools. The getReadConnection() method may be used to check out a connection from the read pool, and the getWriteConnection() method will check out a connection from the write pool. When returning connections, the releaseReadConnection(LDAPConnection) and releaseWriteConnection(LDAPConnection) methods may be used to return valid connections, and the releaseDefunctReadConnection(LDAPConnection) and releaseDefunctWriteConnection(LDAPConnection) methods may be used to return connections that are no longer valid.

Performing Operations in the Pool

One nice feature about the connection pools provided by the UnboundID LDAP SDK for Java is that they include convenience methods for performing operations using connections from that pool.  As a result, it is not necessary to check out and release connections in order to process an operation because the pool will do it on behalf of the requester.  It will also perform any necessary error handling, and evaluate the result code to indicate whether the connection should be destroyed and a new connection created in its place.

The provided connection pool implementations implement the com.unboundid.ldap.sdk.LDAPInterface interface, which is the same interface implemented by the LDAPConnection class.  You can process a search using a pooled connection by invoking one of the LDAPConnectionPool.search or LDAPReadWriteConnectionPool.search methods just like you can call LDAPConnection.search.  Because they all implement the same interface, it’s relatively simple to write an application that can be used to work with either single connections or connection pools.

The LDAPConnectionPool class also provides a processRequests(List<LDAPRequest>,boolean) method that can be used to process multiple requests in succession on a single connection from the pool. In this case, the results of those operations will be returned in a list, and in the event that an any of those requests does not complete successfully then it may either continue attempting to process subsequent requests in the lists or it may stop at that point.

Connection Availability

It is important to understand the behavior that a connection pool exhibits whenever a connection is needed but none are immediately available. The UnboundID LDAP SDK for Java provides two settings that can be used to control the connection pool’s behavior in this case. The first setting is whether the connection pool should be allowed to create a new connection if one is needed but none are available, and the second is how long to wait for a connection to become available before either creating a new connection or returning an error. These settings are controlled by the setCreateIfNecessary(boolean) and setMaxWaitTimeMillis(long) methods, respectively.

With the combination of these settings, any of the following behaviors may be selected if a connection is needed but none are available:

• The connection pool should immediately throw an exception
• The connection pool should immediately create a new connection
• The connection pool should immediately create a new connection
• The connection pool should wait for up to a specified length of time for a connection to become available, and if that time passes without a connection becoming available then it will throw an exception
• The connection pool should wait for up to a specified length of time for a connection to become available, and if that time passes without a connection becoming available then it will throw an exception
• The connection pool should wait as long as it takes for a connection to become available.

If the pool is configured to create new connections if none are available, then there may be periods of time in which there are more total connections associated with that connection pool than the maximum number of connections to maintain in the pool.  In this case, the behavior that the pool will exhibit when a connection is released will depend on the number of connections available in the pool at that time.  As long as the number of available connections in the pool is less than the maximum, then the connection will be released back to the pool and will be made available for use by subsequent requests.  If an attempt is made to release a connection when the pool already has the maximum number of available connections, then the released connection will be closed.  This provides a scalable and efficient way for the connection pool to grow in size as needed under heavy load while ensuring that it doesn’t hold onto too many connections during slower periods.

I’ve been working with LDAP directory servers for about ten years, and for that entire time I’ve also been writing code.  I’ve written a lot of server-side code in the course of building directory servers, but I’ve written even more client-side code for interacting with them.  Unfortunately, I’ve always been a bit disappointed with the APIs that are available for LDAP communication, especially those for use in Java applications.

Java should be a great language for writing directory-enabled applications.  It’s fast, has a broad standard library, offers a number of frameworks for developing web-based and desktop applications, and it’s easy to write robust code in a short period of time.  Unfortunately, the APIs available for LDAP communication are pretty limited.  JNDI is a common choice because it’s part of the core Java runtime, but it’s very cumbersome and confusing and provides rather limited access to the elements of the LDAP protocol.  The Netscape Directory SDK for Java is more user friendly than JNDI, but it’s fairly buggy (especially under load), supports a pretty limited set of controls and extended operations, and is really showing its age after not having any new releases since 2002.  I’ve never actually used JLDAP, but it looks to expose pretty much the same API as the Netscape SDK and has also gone several years without a new release.

Today, UnboundID is correcting this problem with our release of the UnboundID LDAP SDK for Java.  It is a user-friendly, high-performance, feature-rich, and completely free Java API for communicating with LDAP directory servers and performing other directory-related tasks.  Some of the benefits that it provides include:

• It is completely free to use and redistribute.  The LDAP SDK is available under either the GNU General Public License v2 (GPLv2) or the UnboundID LDAP SDK Free Use License.
• It provides a broad feature set.  In addition to providing full support for the core LDAPv3 protocol, it also includes support for 17 standard controls, 4 standard extended operations, and 6 standard SASL mechanisms.  It also provides a number of related APIs for things like LDIF, base64 and ASN.1 parsing, working with root DSE and changelog entries, enhanced schema support, command line argument processing, and SSL/TLS communication.
• It is much more convenient and easy to use than other LDAP APIs,  It is often possible to do what you want with quite a bit less code than the alternatives, and its use of Java features like generics, enums, annotations, and varargs can further enhance the development experience.
• It provides support for connection pooling and client-side failover and load balancing.  Connections can be easily spread across multiple directory servers, and you can even have read and write operations sent to different sets of servers.  The connection pool classes implement the same interface as individual connections, so you can process operations using pooled connections without needing to deal with checking out and releasing connections and performing all of the necessary error handling (although that’s possible too if you need it).
• It provides excellent performance and scalability.  My testing has shown it to be significantly faster than either JNDI or the Netscape SDK, and the searchrate tool that we include as an example can handily outperform the popular C-based version provided by another vendor.
• It has no external dependencies.  Everything is included in a single jar file, and the only requirement is a Java SE 5.0 or higher runtime.
• It is robust and reliable.  We have an extensive test suite for the SDK itself with over 26,000 test cases covering over 94% of the code.  The LDAP SDK is also used as an integral part of other UnboundID products, so it benefits from the testing we do for them as well.  It’s frequently subjected to very heavy and highly concurrent workloads so there shouldn’t be any surprises when moving your applications from testing into production (at least, not because of the LDAP SDK).
• It includes generous documentation.  In addition to a more thorough overview of the benefits our LDAP SDK provides over other the alternatives, it also includes a getting started guide, Javadoc documentation with lots of examples, and a number of sample programs demonstrating the use of various SDK components.
• Commercial support is available.  This can help ensure fast access to patches for any problems found in the LDAP SDK, and may also be used to request enhancements and additional functionality.  Developer support is also available to assist you in using the LDAP SDK to create directory-enabled applications.

You can find the UnboundID LDAP SDK for Java available for download at http://www.unboundid.com/products/ldapsdk/.  All of the documentation is available there as well (and also in the product download), including some frequently asked questions and a more detailed list of the advantages it offers over other LDAP APIs.