Author: Jacob Rosenschein
Description: Release Notes for version 4.1 of the Directory SDK for Java
Keywords: Java SDK, Directory SDK, LDAP SDK, SDK, LDAP, Directory, Netscape Directory, Netscape SDK, Java LDAP SDK

## Directory SDK 4.1 for Java Source Code Release Notes

Last Updated May 06, 2000

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 Building the Source
- Updating Java Classes in Netscape Communicator
- Reporting Problems
- Accessing the Directory Developers Newsgroup

For the latest documentation, see the Netscape Directory SDK 4.0 for Java Programmer's Guide, which is available on the iPlanet Developer Documentation site.

Reference materials for the Directory SDK 4.x for Java are produced using the Javadoc utility. They are available in the `/dist/doc/` directory where you installed the SDK or online at:
`http://developer.iplanet.com/docs/manuals/dirsdk/jsdk40/Reference/index.html.`

If you only want the Directory SDK 4.x for Java (not the source code), you can download it from the iPlanet Developer Downloads site.

What's New in Version 4.1

The 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`. It implements the `LDAPSocketFactory` interface using the Java Secure Socket Extension (JSSE) intefaces as the 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,` 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 `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 the connect 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` package 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. iPlanet bug numbers are shown in parentheses.

- Bugzilla 28001: Parsing in `LDAPUrl(String url)` ignores attributes if DN is empty.
- Bugzilla 28005: Exceptions thrown in `connect()` and `disconnect()`.
- Bugzilla 13546: `JDAPFilterOpers` throws StringIndexOutOfBoundsException.
- Bugzilla 16514: `LDAPAttributeSet.removeElementAt()` doesn't remove the attribute completely.
- Bugzilla 34326: `LDAPDN.unEscapeRDN()` removes all /'s - not just the escape characters.
- Bugzilla 29262: `LDAPSearch` doesn't apply base64-encoding to to nonprintable DNs.
- Wrong user DN supplied for referral on bind operation. (364869)
- 4.0 LDAPMatchingRuleSchema 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()` missing (I-D conformance). (388463)
- SASL bugs found at CMU. (391585)
- `LDAPCompareAttrNames` not consistently case-sensitive. (390382)
- `LDAPEntry` throws a null exception when reading non existing attribute (388577)
- NullPointerException with Malformed Filter. (390249)
- LDAP objects not really serializable. (356821)
- `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)` throw null pointer exceptions (383788)

What's New in Version 4.0

The 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 LDAP.

Additional improvements and changes to the Directory SDK are listed under Bugs Fixed Since Version 3.05.

API updates

The 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.

Asynchronous API

The 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()`.

For more information see "Using the JNDI Service Provider" in the Netscape Directory SDK 4.0 for Java Programmer's Guide.

Bugs Fixed Since Version 3.05

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)
- `LDAPSchemaElement` needs 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)

Downloading and Building the Source

The Directory SDK source code is available on the Mozilla website. You can download it at http://www.mozilla.org/directory/javasdk.html.

Follow the instructions at http://www.mozilla.org/directory/buildjsdk-4.0.txt to build the Netscape Directory SDK.

Updating Java Classes in Netscape Communicator

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:

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

Reporting Problems

Please submit your problem via the the Bugzilla bugsystem . Use the "LDAP Java SDK" component.

Accessing the Directory Developers Newsgroup

If you have additional questions or need more information about the Netscape Directory SDK 4.x for Java, please visit the Mozilla Directory newsgroup and the DevEdge Directory Server newsgroups.

Contains OROMatcher® regular expression software from ORO Java Software. © Copyright 1997 by ORO Java Software.
Redistribution separate from Netscape Directory SDK for Java or direct use of OROMatcher interfaces
requires a license from ORO Java Software. http://www.oroinc.com. OROMatcher® is a trademark of Original Reusable Objects, Inc.

For more Internet development resources, try Netscape TechSearch.