UnboundID LDAP SDK for Java

Easy Access to Debugging Information

Whenever an application is behaving in an incorrect or unexpected manner, it is important to be able to quickly analyze the behavior and determine the source of the problem. For applications that use an API for communicating with a directory server, it is important for that API to provide adequate debugging information to help determine where the cause of the problem might exist.

JNDI Debugging Capabilities

JNDI appears to provide the following support for debugging:

• The com.sun.jndi.ldap.trace.ber property can be set with a value that is an OutputStream object in the initial environment properties used when creating a connection. If this is done, then JNDI will write hexadecimal dumps of all ASN.1 BER data to that output stream. This will happen for the duration of the connection, and it cannot be enabled or disabled during the life of the connection.
  
  
• The com.sun.jndi.ldap.connect.pool.debug property can be set with a value of either "fine" or "all" in order to enable debugging of information related to connection pooling. It appears that this debug information would be written using the Java logging framework.
  
  

There does not appear to be any other mechanism for accessing debug information in JNDI.

Netscape Directory SDK for Java Debugging Capabilities

The Netscape Directory SDK for Java provides the following support for debugging:

• The "debug" property can be set to "true" using the LDAPConnection.setProperty method (and presumably as a system property) to enable debugging, in which case a small set of messages will be written to standard output. There are very few things that can generate debug messages in the SDK, and it is not possible to specify an alternate location for this debug information.
  
  
• The "com.netscape.ldap.trace" property can be set to either a PrintWriter or LDAPTraceWriter object using the LDAPConnection.setProperty method. If this is done, then messages will be written to the provided writer for key events like establishing connections, sending requests, and reading responses. It appears that it is possible to specify this as a system property with no value in order to cause this information to be written to standard error.
  
  

UnboundID LDAP SDK for Java Debugging Capabilities

The UnboundID LDAP SDK for Java provides significant access to debugging information. The types of debug information that can be generated include:

• Information about LDAP messages read from or written to a directory server.
  
  
• Information about ASN.1 elements read from or written to a directory server.
  
  
• Information about connection establishment and termination.
  
  
• Information about connection pool processing.
  
  
• Information about entries and change records read from and written to LDIF.
  
  
• Information about exceptions caught within the SDK.
  
  
• Information about monitor entry parsing.
  
  
• Information about coding errors and other incorrect uses of the LDAP SDK.
  
  

Each of these types of debugging can be enabled or disabled individually, and debugging can be configured either programmatically or using system properties. Debug messages are handled using the Java logging framework. See the class documentation for the com.unboundid.util.Debug class for more information.

In addition to the code-based debugging, the LDAP SDK comes with the ldap-debugger example tool that can be used to help better understand what directory-enabled applications are actually doing when they communicate with an LDAP directory server. This tool may be used to create a simple LDAP proxy server that can sit between the client and the target directory server, and it will intercept and decode any communication passing between it. This tool can be used for any LDAP communication in which the client can be configured to use an alternate address and/or port for the directory server, regardless of the type of server or the API used to create the client application.