These release notes contain information about:

• What's New in Version 4.1
• Bugs Fixed Since Version 4.0
• What's New in Version 4.0
• Bugs Fixed Since Version 3.05
• Downloading and Installing the SDK
• Updating Java Classes in Netscape Communicator
• Getting Started
• Reporting Problems
• Accessing the Directory Developers Newsgroup

Reference materials for the Directory SDK  for Java are produced using the Javadoc utility. They are available online at: http://developer.iplanet.com/docs/manuals/dirsdk/jsdk41/Reference/index.html.

For additional details about the Directory SDK for Java 4.x as well as practical examples of how to use the SDK to create LDAP-enabled applications, see LDAP Programming with Java by Rob Weltman and Tony Dahbura (Addison-Wesley Pub Co. ISBN: 0201657589).

What's New in Version 4.1

The Netscape Directory SDK 4.1 for Java is a bug fix relase. Please check the list of Bugs Fixed Since Version 4.0. The following new features have been added in this release:

• A new class, netscape.ldap.factory.JSSESocketFactory, which implements the LDAPSocketFactory interface. This class uses the collection of Java Secure Socket Extension (JSSE) intefaces as an SSL provider. A JSSE implementation is not packaged with the Directory SDK classes; you will need to have one in your CLASSPATH to be able to use JSSESocketFactory. A reference implementation of JSSE interfaces is available at http://java.sun.com/products/jsse/.
• A new interface,netscape.ldap.LDAPTraceWriter, which enables logging of LDAP trace messages in environments where an OutputStream cannot be used. The interface is meant primarily for integrating LDAP tracing with the servlet log facility.
• A new method called setConnectTimeout() has been added to LDAPConnection. This method allows you to limit  the amount of time that application code waits for LDAPConnection.connnect() to establish a connection. By setting a connection timeout, an application can avoid blocking for a long period of time when a Directory Server host is down or unreachable.
• All base classes in the netscape.ldap and netscape.ldap.util packages are now serializable.

Bugs Fixed Since Version 4.0

The following bugs have been fixed since the release of the Directory SDK 4.0 for Java. Bug numbers are shown in parentheses.

• Wrong user DN supplied for referral on bind operation. (364869)
• 4.0 LDAPMatchingRuleSchema is not binary compatible with 3.x. (365423)
• LDAP JDK does not properly abandon operation. (341439)
• RDN.equals() assumes case-insensitivity, ignores multiple values. (365574)
• authenticate() with bad password does not throw exception. (366578)
• Should provide DSML option for LDAPSearch. (368416)
• Incorrect signature for LDAPResponseListener.merge(). (364775)
• MS JVM throws LDAPSortControl runtime exception. (365574)
• Need new method LDAPDN.equals( String dn1, String dn2). (365575)
• Some 3.x LDAPSchema public methods are protected in 4.x. (381574)
• Server using VLV for non-search operations - 'Critical extension unavailable' error in log. (382605)
• LDAPSearchResults.getCount() returns wrong count. (355336)
• LDAPCache.cleanup() throws NullPointerException. (388736)
• LDAPConnection.read() doesn't return subentries (387722)
• LDAP SDK 4.0 causes NAS crash. (390128)
• NullPointerException in deleteThreadConnEntry(). (389228)
• LDAPSchema.getSyntaxes() is missing (I-D conformance). (388463)
• Parsing in LDAPUrl(String url) ignores attributes if DN is empty. (390883)
• SASL bugs found at CMU. (391585)
• Exceptions thrown in connect() and disconnect(). (390862)
• JDAPFilterOpers throws StringIndexOutOfBoundsException. (390864)
• LDAPAttributeSet.removeElementAt() doesn't remove attributes completely. (390863)
• LDAPCompareAttrNames is not consistently case-sensitive. (390382)
• LDAPEntry throws a null exception when reading non existing attribute. (388577)
• LDAPDN.unEscapeRDN() removes all /'s - not just the escape characters. (390857)
• NullPointerException thrown with malformed filters. (390249)
• LDAP objects not really serializable. (356821)
• LDAPSearch doesn't apply base64-encoding to nonprintable DNs. (390861)
• LDAPSearch -l option does not work correctly. (393676)
• NullPointerException in LDAPSearch. (387453)
• java-object-schema.conf is not packaged with SDK. (390154)
• JNDI SP: LdapContextImpl.reconnect(null) throws null pointer exceptions. (383788)

The Netscape Directory SDK 4.0 for Java provides programmers with the tools to develop directory-enabled software.  This release includes:

• Application Program Interface (API) updates to match the newest LDAP (Lightweight Directory Access Protocol) Internet drafts
• an asynchronous interface to LDAP
• a new SASL (Simple Authentication and Security Layer) API
• the Netscape LDAP Service Provider for JNDI (Java Naming and Directory Interface).

API updates

The Netscape Directory SDK 4.0 for Java supports these changes to the LDAP API:

• Sophisticated client-side management of referral authentication using the LDAPBind interface.
• Dynamic registration and instantiation of server response controls using the register and newInstance methods of LDAPControl.
• The separation of the constraint class into LDAPConstraints and its subclass LDAPSearchConstraints. LDAPConstraints contains only those methods implemented in the interface that apply to all operations. LDAPSearchConstraints is unchanged. All LDAPConnection methods that used to take LDAPSearchConstraints as an argument (except for read and search methods) now pass LDAPConstraints instead.
• When using LDAPConnection for searching, retrieval of server response controls is now handled by LDAPSearchResults. Although the SDK is backward compatible, you should call LDAPSearchResults.getResponseControls() instead of LDAPConnection.getResponseControls()when writing new code.
• LDAPConnection.getServerControls() now automatically parses controls. As a result, calling parseResponse() is no longer necessary.
• Support for transparent failover connection policies. The available policies are: (1) serial, (2) parallel with no delay, and (3) parallel with delay. For more information, see LDAPConnection.setConnSetupDelay() in the javadocs.
• LDAPConnection has a new method called reconnect(). This method first disconnects and then connects and binds again using the same parameters and mechanisms as the original connection..
• Support for connection pools. For more information see netscape.ldap.util.ConnectionPool in the javadocs.
• The addition of LDAPInterruptedException, which is thrown if an LDAP operation is interrupted.
• The addition of LDAPProxiedAuthControl, which can execute operations, using different credentials, without rebinding.
• LDAPConnection now runs as a daemon thread. You no longer need to call System.exit when terminating your program.

The Netscape Directory SDK 4.0 for Java provides an interface called LDAPAsynchronousConnection. This interface contains methods for performing LDAP operations asynchronously. Instead of blocking while waiting for a response, methods in LDAPAsynchronousConnection return control to an application before they complete. For more information on the asynchronous interface, see "Using the Asynchronous Interface" in the Netscape Directory SDK 4.0 for Java Programmer's Guide.

SASL API

SASL allows clients and servers to communicate securely. The API accomplishes this by finding a common authentication scheme and facilitating a series of challenge and response interchanges between the client and server. If these interchanges complete successfully, the client is authenticated. For more information on SASL see "Using SASL Authentication" in the Netscape Directory SDK 4.0 for Java Programmer's Guide.

JNDI Service Provider for LDAP

JNDI is a Java API that provides a common way for programmers to access a variety of naming and directory services. This is accomplished via a layer of software called a Service Provider. The Directory SDK includes a Service Provider for LDAP.

The following JNDI features are not implemented in this release of the Netscape LDAP Service Provider:

• Support for federated names
• Support for the "code base" attribute for objects stored in an LDAP directory. The class name specified by the javaClassName attribute must exist in the local CLASSPATH
• The search() method for schema directory contexts. To perform searches in a schema directory context use a Context.lookup() request instead of DirContext.search().

The following bugs have been fixed since the release of the Directory SDK 3.05 for Java. Bug numbers are shown in parentheses.

• LDAPSearchResults.getCount() returns 0 for synchronous searches. (355365)
• Applets in Communicator can't fetch an error string. (351004)
• DN.contains() is implemented and documented incorrectly. (354615)
• Search timeout is not handled correctly. (350998)
• LDAPSchemaElementneeds a modify() method. (350997)
• LDAPBasePropertySupport should enable referrals. (350996, 350995)
• Cannot set the cache once LDAPConnection has connected. (355904)
• LDAPCache changes the contents of returned attributes. (355942)
• The SDK calls Thread.stop(), suspend(), and resume(). (354503)
• VLV controls don't support the optional context field. (355215)
• The SDK doesn't support all the schema options described in RFC 2252. (354347)
• LDAP Beans don't handle referrals. (353306)
• LDAPIsMember doesn't handle dynamic groups. (353305)
• The netscape.ldap.util.DN class does not consider "" to be a valid DN. (352804)
• LDAPCompareAttrNames should allow for the specification of a locale. (351022)
• LDAPSearch aborts on a size limit exception. (350624)
• LDAPModificationSet is missing a toString method. (353308, 351719)
• LDAPGetEntries should allow a choice of which attributes to return. (353307)
• The SDK should support the latest LDIF specification. (356470, 352056)
• The SDK should treat a "null" filter as meaning "objectclass=*". (354682)
• LDAPSchema contains unnecessary public "add" methods. (354997)

The Directory SDK is available on the Netscape DevEdge website. You can download it at http://developer.netscape.com/tech/directory/downloads.html.

Follow these instructions to install the Netscape Directory SDK:

UNIX (Solaris, HP-UX, IRIX, AIX, Digital UNIX):

1. Save the file to the location on your hard drive where you want the SDK installed.
2. Unzip the file by entering the command:

gunzip <filename>.tar.gz
3. Untar the resulting tar file by entering the command:

tar -xvof <filename>.tar

1. Save the file to disk.
2. Extract the file using a program such as WinZip or StuffIt Expander.

The LDAP Java classes contained in Netscape Communicator 4.7 and earlier are outdated. You can upgrade these class files to the latest versions using Communicator's SmartUpdate feature.

The SmartUpdate page for the LDAP Java classes is at: http://developer.netscape.com/software/ldap/ldap.html

Note: This page uses Communicator's SmartUpdate feature to update the classes. Before visiting this page, you must enable SmartUpdate, Java, JavaScript, and cookies in Communicator.

To enable SmartUpdate, Java, JavaScript, and cookies:

1. Go to the Edit menu and choose Preferences
2. Select Advanced and make sure that Accept all cookies is active (it's radio button is filled).
3. Make sure that Enable Java and Enable JavaScript are checked.
4. Choose Advanced | SmartUpdate from the left-hand panel.
5. Make sure that Enable SmartUpdate is checked.
6. Click OK.

The Netscape Directory SDK 4.1 for Java includes classes for the LDAP API. You can use these classes to write your own application to connect to, search, and update LDAP servers.

After downloading and extracting the SDK, read the documentation in the /dist/doc directory and look at the samples in the examples directory.

Reading the Documentation

The Netscape Directory SDK for Java includes a programmer's guide and a set of reference materials. The programmer's guide and the reference are both in HTML format.

To view the programmer's guide:

1. Start Netscape Communicator.
2. Open the <SDK-Root>/doc/index.htm file in the browser.

1. Start Netscape Communicator.
2. In the browser, open the index.html file created by Javadoc.

All documentation is also available online at: http://docs.iplanet.com/docs/manuals/directory.html#SDK

Using the Examples

The Directory SDK also includes sample programs that you can modify, compile, and run. Each program demonstrates how to use the classes to search or update an LDAP server. The samples are in the examples directory.

For more information on these sample clients, see the README file in the examples directory.

Please submit your problem via the DevEdge Bug Report Form.

If you have additional questions or need more information about the Netscape Directory SDK 4.1 for Java, please visit the DevEdge Directory Server newsgroups.