UnboundID LDAP SDK for Java

Support for Java SE 5 Features

The UnboundID LDAP SDK for Java was written from the ground up to utilize the advantages that Java SE 5 and later releases offer over earlier versions. It is true that this means it is not possible to use the UnboundID LDAP SDK for Java with Java SE versions 1.4 or earlier, but Java SE 5 has been available for several years on virtually every major operating system and offers significant advantages over earlier releases. In addition, code written for earlier Java releases should work flawlessly (with or without recompilation) on Java 5, so making legacy code work in a Java SE 5 environment should not require any effort.

JNDI is part of the core Java platform and therefore has been updated to take advantage of some of the new features of recent Java releases (primarily in the form of updating collections to use generics), although much of the legacy code is still using outdated functionality. For example, the fact that it is still necessary to use Hashtable instances to define the environment properties is mind-boggling when much better alternatives have been available for a very long time, and at the very least a general-purpose Map could be used instead.

The Netscape Directory SDK for Java was originally developed in the Java 1.1 time frame and does not appear to make use of any enhancements offered by recent Java releases.

Generics

One of the most visible and useful changes that Java SE 5 offers over earlier releases is the addition of generics. This makes it possible to provide improved type safety when dealing with many kinds of objects.

For example, with earlier Java releases, a method that returned a list of Entry objects would have used a return type of "List". This had the following disadvantages:

• The Java compiler had no idea what was supposed to be placed in that list, and would allow any type of object to be included.
  
  
• The javadoc tool had no idea what was supposed to be placed in that list, and would not automatically include any information in the generated documentation to indicate what type of data it contained.
  
  
• Whenever items were accessed in the list, they were treated as generic Object elements and had to be explicitly typecast to the appropriate type of object.
  
  

With the introduction of generics, however, it is now possible to specify a return type of "List<Entry>". This means that the compiler will complain any time there is an attempt to put something in that list that is not (or might not be) an Entry object. The generated javadoc documentation will also show the return type as "List<Entry>" so developers using the code will know what type of objects are held in that list, and furthermore those objects can be directly treated as Entry objects without the need to perform any typecasting.

The UnboundID LDAP SDK for Java uses generics for all types of collections used in the code. This offers greater type safety for the SDK code itself, and makes it easier and more convenient for developers using the SDK to interact with those collections.

Varargs

The varargs capability added in Java SE 5 makes it possible to indicate that a method may take any number of objects of a given type as arguments. A varargs placeholder may only be used as the last element in the argument list, and the Java compiler will automatically convert it to an array of that type of object.

For example, consider the following constructor for the com.unboundid.ldap.sdk.Attribute class:

Attribute(String name, String... values)

This makes it possible to specify multiple values as a comma-separated list of strings instead of requiring them to be first placed in an array. This is purely a convenience feature, and it means that the following two calls have exactly the same result:

• new Attribute("myAttribute", "firstValue", "secondValue", "thirdValue")
  
  
• new Attribute("myAttribute", new String[] { "firstValue", "secondValue", "thirdValue" })
  
  

Wherever it makes sense to do so, the UnboundID LDAP SDK for Java uses varargs so that developers using the SDK have the option of providing those values either individually or in an array.

Enumerations

Java enumerations are objects which have a fixed set of well-known, immutable values. The UnboundID LDAP SDK for Java uses enumerations in a few key places, including:

• The usage types that may appear in an attribute type definition.
  
  
• The kind values that may appear in an object class definition.
  
  
• The change types that may be used in persistent search and entry change notification controls.
  
  
• The warning and error types that may be used in the password policy control defined in draft-behera-ldap-password-policy.
  
  
• The state values that a scheduled task may have.
  
  
• The failed dependency action that might be defined for a task.
  
  
• The available categories for SDK debugging information.
  
  

Note that there are a few notable instances within the SDK in which enumerations could have been used but were not in order to provide greater compatibility and to allow them to be more future-proof. Those cases include:

• Result codes. It is likely that the set of LDAP result codes will be expanded in the future, and the LDAP SDK must be able to handle result codes that it does not currently know anything about.
  
  
• Search scope values. It is possible that the set of possible search scopes may be expanded in the future (as has been proposed with the subordinate subtree scope in draft-sermersheim-ldap-subordinate-scope) without requiring any additional client-side code changes.
  
  
• Modification type values. It is possible that the set of possible modification types may be expanded in the future (as was recently done with the modify increment extension in RFC 4525) without requiring additional client-side code changes.
  
  
• Dereference policy values. It is possible that the set of alias dereference policies may be expanded in the future without requiring additional client-side code changes.
  
  

In each of these cases, there are constants available for the currently-defined values (in the ResultCode, SearchRequest, Modification, and SearchRequest classes, respectively), but if a new specification arises in the future that defines a new value for any of these elements, the UnboundID LDAP SDK will allow that value to be utilized without requiring the SDK itself to be modified.

Concurrency Utilities

Java SE 5 includes a new java.util.concurrent package structure with objects that are intended to provide safe, high-performance processing when accessed concurrently by multiple threads. Areas in which concurrent API elements were used include:

• AtomicInteger or AtomicLong objects are used in cases where an incrementing integer value may be required (e.g., message IDs for LDAP request messages).
  
  
• LinkedBlockingQueue objects are used in several places where one thread is waiting to be given an object from another thread.
  
  
• ConcurrentHashMap objects are used in cases where a highly-concurrent and threadsafe map is required.
  
  

Using these concurrent objects allows for better performance and scalability for objects that need threadsafe access than was previously possible to achieve.

Other Java 5 Improvements

The StringBuilder class introduced in Java SE 5 is virtually identical to the earlier StringBuffer class, with the exception that StringBuilder objects are not synchronized while StringBuffer objects are (and are therefore slower in code where contention isn't a concern). The UnboundID LDAP SDK for Java uses StringBuilder objects in several places throughout the code where a StringBuffer object might have been used in earlier releases.

Another new feature added in Java SE 5 is that of annotations. Annotations can be used to associate metadata with Java code elements like classes, methods, and fields. The UnboundID LDAP SDK for Java itself does not define any new annotations at this time, although it does make use of existing Java annotations (like "@Override") when it makes sense to do so. Further, the unit test code for the SDK uses the TestNG framework, which makes heavy use of annotations.