Chapter 5 Using the LDAP Java Classes

This chapter covers some of the general LDAP Java classes that are commonly used when writing LDAP clients.

• "Getting Information About the SDK"
• "Handling Exceptions"
• "Handling Referrals"
• "Using an In-Memory Cache"
• "Cloning a Connection"
• "Manipulating Distinguished Names"

LDAPConnection ld = new LDAPConnection();

try {

   System.out.println( "LDAP Java Classes Version: " +

      (Float)ld.getProperty(LDAPConnection.LDAP_PROPERTY_SDK) ); 

   System.out.println( "Highest version of LDAP supported: " +

      (Float)ld.getProperty(LDAPConnection.LDAP_PROPERTY_PROTOCOL) ); 

   System.out.println( "Authentication methods supported: " +

      (String)ld.getProperty(LDAPConnection.LDAP_PROPERTY_SECURITY) );

} catch (LDAPException e) { 

   System.out.println( "Could not get SDK properties." );

   System.out.println( "Error: " + e.toString() );

}

...

• "Getting Information About the Error"
• "Getting the Error Message"

• the LDAP result code for the error that occurred
• a message containing any additional information about the error from the server

• To get the string representation of the exception, use the toString method.
• To get the LDAP result code, use the getLDAPResultCode method.
• To get any additional information sent by the server, use the getLDAPErrorMessage method.
• To get the closest matching DN (in cases where your client specified a DN to a non-existent entry), use the getMatchedDN method.

...

try {

/* Attempt to perform an LDAP operation here. */

} catch( LDAPException e ) {

   /* Get and print the result code and any other info. */

   int resultCode = e.getLDAPResultCode();

   String serverInfo = e.getLDAPErrorMessage();

   System.out.println( "LDAP Result Code: " + resultCode );

   if ( serverInfo != null ) {

      System.out.println( "Additional Info: " + serverInfo );

   }

   /* If the exception was thrown because an entry 

       was not found, print the DN of the closest entry found. */

   switch( resultCode ) {

      case LDAPException.NO_SUCH_OBJECT:

      case LDAPException.ALIAS_PROBLEM:

      case LDAPException.INVALID_DN_SYNTAX:

      case LDAPException.ALIAS_DEREFERENCING_PROBLEM:

         String matchedDN = e.getMatchedDN();

         if ( matchedDN != null ) {

            System.out.println( "Closest Entry: " + matchedDN );

         }

         break;

      default:

         break;

   }

}

...

...

try {

/* Attempt to perform an LDAP operation here. */

} catch( LDAPException e ) {

   /* Get and print the error message. */

   int resultCode = e.getLDAPResultCode();

   System.out.println( "Error: " + e.errorCodeToString( resultCode ) );

}

...

netscape/ldap/error/ErrorCodes_en_US.props 

netscape/ldap/error/ErrorCodes_en.props 

netscape/ldap/error/ErrorCodes.props 

resultcode=errormessage 

0=Success

1=Operations error

2=Protocol error

3=Timelimit exceeded

4=Sizelimit exceeded

5=Compare false

6=Compare true

...

netscape/ldap/error/ErrorCodes_language_country.props

netscape/ldap/error/ErrorCodes_language.props

netscape/ldap/error/ErrorCodes.props

• "Understanding Referrals"
• "Enabling or Disabling Referral Handling"
• "Limiting Referral Hops"
• "Binding When Following Referrals"

• If the server is not configured to send a referral, an LDAPException is thrown with the LDAP result code LDAPException.NO_SUCH_OBJECT.
• If the server is configured to refer you to another LDAP server, the server sends a referral back to your client. Depending on how your LDAP client is configured one of the following may occur:

• If your client handles referrals automatically, your client connects to the LDAP server specified in the referral and requests to modify the entry. (The client binds anonymously to that server. To bind as a specific user, see the section "Binding When Following Referrals".)
• If your client does not handle referrals automatically, an LDAPReferralException is thrown. You can get the LDAP URL specified in the referral by catching the exception and invoking the getURLs method.

By default, clients built with the Netscape Directory SDK for Java are configured to follow referrals automatically.

• To prevent the client from automatically following referrals, pass LDAPv2.REFERRALS and false as arguments to the setOption method, or pass false as the argument to the setReferrals method.
• If you want the client to automatically follow referrals again, pass LDAPv2.REFERRALS and true as arguments to the setOption method, or pass true as the argument to the setReferrals method.

1. The LDAP server sends a referral back to the client. The referral contains an LDAP URL that identifies another LDAP server.
2. The client creates a new LDAPConnection object.
3. The client connects to the host and port specified in the LDAP URL.
4. Using the getRebindProc method to find your object (the one that implements the LDAPRebind interface), the client invokes the getRebindAuthentication method, passing in the host and port specified in the LDAP URL.
5. The getRebindAuthentication method in your object returns an LDAPRebindAuth object.
6. The client invokes the getDN and getPassword methods of the returned LDAPRebindAuth object to get the DN and password to use for authentication.
7. The client invokes the authenticate method of the LDAPConnection object and passes the DN and password to authenticate to the server.

• a class that implements the LDAPRebind interface
• a getRebindAuthentication that takes host name and port number and creates an LDAPRebindAuth object that specifies the DN and password to use for authentication

• "How the Cache Operates"
• "Setting Up an In-Memory Cache"
• "Caching Requests by Base DN"
• "Sharing a Cache Between Connections"
• "Flushing the Cache"
• "Getting Cache Statistics"

• When an item's age exceeds that time limit, the item is removed from the cache. The cache is checked once a minute for expired items.
• If adding a new item will cause the cache to exceed its maximum size, items are removed from the cache to make space for the new item. Items are removed on a FIFO (first in, first out) basis.

• the host name and port number of the LDAP server
• the base DN of the search
• the search filter
• the scope of the search
• the attributes to be returned in the search results
• the DN used to authenticate the client when binding to the server
• the LDAP v3 controls specified in the search request

1. Construct a new LDAPCache object which represents the cache.
2. Invoke the setCache method of an LDAPConnection object to associate the cache with the connection.

...

import netscape.ldap.*;

import java.util.*;

...

LDAPConnection ld = null;

int status = -1;

String MY_HOST = "localhost";



try {

   ld = new LDAPConnection();



   /* Create a cache for the connection */

   int MAX_TIME_CACHED = 3600;

   int MAX_SIZE = 1000000;

   LDAPCache myCache = new LDAPCache( MAX_TIME_CACHED, MAX_SIZE );

   ld.setCache( myCache );



   /* Connect to server */

   ld.connect( MY_HOST, LDAP_PORT );

   ...

} catch( LDAPException e ) {

   System.out.println( "Error: " + e.toString() );

}

...

...

/* Create a cache for the connection */

int MAX_TIME_CACHED = 3600;

int MAX_SIZE = 1000000;

String [] BASE_DN_CACHED = {"ou=People,o=Airius.com", 

   "ou=Groups,o=Airius.com"};

LDAPCache myCache = new LDAPCache( MAX_TIME_CACHED, MAX_SIZE, 

   BASE_DN_CACHED );

...

1. Invoke the getCache methodof an LDAPConnection object to get the LDAPCache object associated with it.
2. Invoke the setCache methodof a different LDAPConnection object to associate the retrieved LDAPCache object with it.

...

import netscape.ldap.*;

import java.util.*;

...

LDAPCache myCache;

...

/* Perform search requests. */

...

/* Flush items from the cache. Flush the 

   search requests that have base DNs under the 

   "ou=People, o=Airius.com" subtree. */

myCache.flushEntries( "ou=People, o=Airius.com", 

   LDAPConnection.SCOPE_SUB );

...

myCache.flushEntries( null, 0 ); 

• To get the total amount of available space (in bytes) left in the cache, invoke the getAvailableSize method.
• To get the array of base DNs of the search requests to be cached, invoke the getBaseDNs method.
• To get the total number of items that have been flushed from the cache (not including items flushed when invoking the flushEntries method), invoke the getNumFlushes method.
• To get the maximum size of the cache (in bytes), invoke the getSize method.
• To get the maximum amount of time that an item can be cached (in seconds), get the getTimeToLive method.

• To get the total number of requests for retrieving items from the cache, invoke the getTotalOperation method.
• To get the total number of requests that retrieved an item from the cache, invoke the getNumHits method.
• To get the total number of requests that failed to find and retrieve an item from the cache, invoke the getNumMisses method.

...

import netscape.ldap.*;

import java.util.*;

...

import netscape.ldap.*;

import java.util.*;

...

LDAPConnection ld;

...

if ( (ld != null) && ld.isConnected() ) {

   LDAPCache connCache = ld.getCache();

   if ( connCache != null ) {

      System.out.println( "Cache size:\t\t" + 

         connCache.getSize()/1000 + " kbytes" );

      System.out.println( "Available:\t\t" + 

         connCache.getAvailableSize()/1000 + " kbytes" );

      System.out.println( "Maximum age:\t\t" + 

         connCache.getTimeToLive()/1000 + " seconds" );

      System.out.println( "Total hits:\t\t" + 

         connCache.getNumHits() + " hits" );

      System.out.println( "Total misses:\t\t" + 

         connCache.getNumMisses() + " misses" );

      System.out.println( "Total requests:\t\t" + 

         connCache.getTotalOperations() + " requests" );

} else {

      System.out.println( "No cache associated with the connection." );

...

• A cloned LDAPConnection object has a separate set of session preferences and constraints (in other words, it is associated with its own LDAPSearchConstraints object). Changing an option or search constraint will only affect requests issued using that object.

For example, suppose an LDAPConnection object allows a maximum of 100 results to be returned from a search. If you clone an LDAPConnection object and change the maximum number of results in the clone from 100 to 200, the initial object will still allow only 100 results to be returned.

• All clones are authenticated to the server as the same user. If you reauthenticate to the server as a different user, the current clone will be disconnected and will connect separately to the server. (The LDAPConnection object will no longer be a clone of another LDAPConnection object.)

• Set notypes to false if you want to include component names in the array.

   LDAPDN.explodeDN( "uid=bjensen, ou=People, o=Airius.com", false )

The method returns this array:

   { "uid=bjensen", "ou=People", "o=Airius.com" }

• Set notypes to true if you don't want to include the component names in the array.

   LDAPDN.explodeDN( "uid=bjensen, ou=People, o=Airius.com", true )

The method returns this array:

   { "bjensen", "People", "Airius.com" }