# LDAP Classes for Java

February 28, 2008

## 1.0 LDAP Classes for Java

LDAP (Lightweight Directory Access Protocol) is an emerging Internet standard for accessing directory information, allowing LDAP-enabled applications to access multiple directories. LDAP v3 supports such features as secure connections (through TLS(SSL) and SASL), entry management, schema management, and LDAP controls and extensions for expanding LDAP’s functionality.

The LDAP Classes for Java kit enables you to write applications to access, manage, update, and search for information stored in Novell eDirectory and other LDAP-aware directories.

This API is a work-in-progress implementing the IETF draft 18 of the Java LDAP API (draft-ietf-ldapext-ldap-java-api-18.txt), and as such, most but not all features in the IETF draft are currently implemented. For details, see sections 10.0 and 11.0.

## 2.0 Dependencies

Developing and running an application that uses the LDAP Classes for Java requires the following:

- JRE 1.2 or higher, required to run an application.

- JDK 1.2 Standard Edition or higher, required to develop an application (The LDAP Classes for Java no longer support JDK 1.1.7).

- JDK/JRE 1.4 or higher, required for building and running applications that use the new DSML functionality. Optionally, you can use JDK/JRE 1.2 or higher by installing the JAXP package and setting the associated jar files in your classpath.

- JDK/JRE 1.4 or higher, required for building and running applications that create TLS(SSL) connections. Optionally, you can download a Sun-compliant JSSE implementation to run with JDK/JRE 1.2 or higher.

- A directory that supports TLS(SSL), required if you wish to run applications that create TLS(SSL) connections. Novell eDirectory 8 or higher supports TLS(SSL). Novell eDirectory 8.7 or higher supports Start/Stop TLS functionality.

- Novell eDirectory 8.5 or higher, required if you wish to run applications that use the LDAP extensions for partition and replica management.

## 3.0 Installation

1. To install the libraries obtained from the Novell developer website, select one of the following:

   - For Windows and NetWare, run the install on a Windows machine. It will give instructions for installing on NetWare.

   - For Solaris, Linux, and HP-UX, download the tar.gz file and extract it.

2. Copy the ldap.jar file to a directory of your choice on your platform. On Windows, this directory is typically:

   c:\novell\ndk\ndssdk\java\lib

3. Add the complete path, including the file name, of the ldap.jar file to your CLASSPATH.

## 4.0 LDAPv2 and LDAPv3 Support

This version of the LDAP Classes for Java supports mainly LDAPv3. Since the consensus in the LDAP community is to encourage everyone to update to LDAPv3, Novell has not made a commitment to ensure that these libraries support LDAPv2 servers.

## 5.0 LDAP Controls

LDAP servers may support controls. Query the root DSE to get a list of supported controls. See the GetDSE.java sample for coding example.

The LDAP Classes for Java supply methods to help applications use supported controls.

## 6.0 LDAP Extensions

eDirectory 8.5 onwards supports the following LDAP extensions for obtaining effective rights, managing replicas and partitions, and refreshing the LDAP server:

    2.16.840.1.113719.1.27.100.1   Nds To Ldap Response
    2.16.840.1.113719.1.27.100.2   Nds To Ldap Request
    2.16.840.1.113719.1.27.100.3   Split Partition Request
    2.16.840.1.113719.1.27.100.4   Split Partition Response
    2.16.840.1.113719.1.27.100.5   Merge Partition Request
    2.16.840.1.113719.1.27.100.6   Merge Partition Response
    2.16.840.1.113719.1.27.100.7   Add Replica Request
    2.16.840.1.113719.1.27.100.8   Add Replica Response
    2.16.840.1.113719.1.27.100.9   Refresh Server Request
    2.16.840.1.113719.1.27.100.10  Refresh Server Response
    2.16.840.1.113719.1.27.100.11  Remove Replica Request
    2.16.840.1.113719.1.27.100.12  Remove Replica Response
    2.16.840.1.113719.1.27.100.13  Partition Entry Count Request
    2.16.840.1.113719.1.27.100.14  Partition Entry Count Response
    2.16.840.1.113719.1.27.100.15  Change Replica Type Request
    2.16.840.1.113719.1.27.100.16  Change Replica Type Response
    2.16.840.1.113719.1.27.100.17  Get Replica Info Request
    2.16.840.1.113719.1.27.100.18  Get Replica Info Response
    2.16.840.1.113719.1.27.100.19  List Replica Request
    2.16.840.1.113719.1.27.100.20  List Replica Response
    2.16.840.1.113719.1.27.100.21  Receive All Updates Request
    2.16.840.1.113719.1.27.100.22  Receive All Updates Response
    2.16.840.1.113719.1.27.100.23  Send All Updates Request
    2.16.840.1.113719.1.27.100.24  Send All Updates Response
    2.16.840.1.113719.1.27.100.25  Request Partition Sync Request
    2.16.840.1.113719.1.27.100.26  Request Partition Sync Response
    2.16.840.1.113719.1.27.100.27  Request Schema Sync Request
    2.16.840.1.113719.1.27.100.28  Request Schema Sync Response
    2.16.840.1.113719.1.27.100.29  Abort Partition Operation Request
    2.16.840.1.113719.1.27.100.30  Abort Partition Operation Response
    2.16.840.1.113719.1.27.100.31  Get Bind DN Request
    2.16.840.1.113719.1.27.100.32  Get Bind DN Response
    2.16.840.1.113719.1.27.100.33  Get Effective Privileges Request
    2.16.840.1.113719.1.27.100.34  Get Effective Privileges Response
    2.16.840.1.113719.1.27.100.35  Set Replication Filter Request
    2.16.840.1.113719.1.27.100.36  Set Replication Filter Response
    2.16.840.1.113719.1.27.100.37  Get Replication Filter Request
    2.16.840.1.113719.1.27.100.38  Get Replication Filter Response
    2.16.840.1.113719.1.27.100.39  Create Orphan Partition Request
    2.16.840.1.113719.1.27.100.40  Create Orphan Partition Response
    2.16.840.1.113719.1.27.100.41  Remove Orphan Partition Request
    2.16.840.1.113719.1.27.100.42  Remove Orphan Partition Response

Extensions to trigger NDS background processes (See the TriggerBackground.java sample for coding example):

    2.16.840.1.113719.1.27.100.43  Trigger Backlinker Request
    2.16.840.1.113719.1.27.100.44  Trigger Backlinker Response
    2.16.840.1.113719.1.27.100.47  Trigger Janitor Request
    2.16.840.1.113719.1.27.100.48  Trigger Janitor Response
    2.16.840.1.113719.1.27.100.49  Trigger Limber Request
    2.16.840.1.113719.1.27.100.50  Trigger Limber Response
    2.16.840.1.113719.1.27.100.51  Trigger Skulker Request
    2.16.840.1.113719.1.27.100.52  Trigger Skulker Response
    2.16.840.1.113719.1.27.100.53  Trigger Schema Synch Request
    2.16.840.1.113719.1.27.100.54  Trigger Schema Synch Response
    2.16.840.1.113719.1.27.100.55  Trigger Partition Purge Request
    2.16.840.1.113719.1.27.100.56  Trigger Partition Purge Response

Extensions for eDirectory events. These extensions are considered "early access" and are not yet supported.

    2.16.840.1.113719.1.27.100.79  Monitor Events Request
    2.16.840.1.113719.1.27.100.80  Monitor Events Response
    2.16.840.1.113719.1.27.100.81  Event Notification

To use any of these Novell extensions, the LDAP server must be running on eDirectory version 8.5 or higher.

To obtain a copy, see Novell’s download site.

The LDAP Classes for Java include functions to help applications use these extensions.

If you have an early beta version of eDirectory 8.5, be aware that the OIDs for the extensions changed in beta 5.

The Novell Import Convert Export utility uses the following extensions. These are not general extensions designed for developer use, but are designed to support the LDAP Bulk Update Replication Protocol (LBURP).

    2.16.840.1.113719.1.142.100.1 startFramedProtocolRequest
    2.16.840.1.113719.1.142.100.2 startFramedProtocolResponse
    2.16.840.1.113719.1.142.100.4 endFramedProtocolRequest
    2.16.840.1.113719.1.142.100.5 endFramedProtocolResponse
    2.16.840.1.113719.1.142.100.6 lburpOperationRequest
    2.16.840.1.113719.1.142.100.7 lburpOperationResponse

This function is provided for applications to obtain the LDAP format of the distinguished name instead of namemapped format.

    2.16.840.1.113719.1.27.100.101  Convert DNS name to X500 name Request

    2.16.840.1.113719.1.27.100.102  Convert DNS name to X500 name Response

## 7.0 Running Core LDAP Classes and Sample Programs on NetWare

To run or execute some of the core LDAP classes and sample programs on NetWare, that read input from command line (i.e., by reading System.in) enter following command:

    java -ns classname [program args...]

For example to run PersistenceSearchCallback on NetWare enter the following:

    Usage: java -ns PersistenceSearchCallback <host_name> <login_dn> <password> <search_base>

    Example: java -ns PersistenceSearchCallback Acme.com "cn=admin,o=Acme" secret "ou=sales,o=Acme"

## 8.0 SASL APIs

The dependency of using namespaces starting with "javax.security.sasl" in Javaldap codebase is removed. Now, the client application can run using LDAP APIs in all the versions of Java 2 including JDK 1.5. This has also removed the licensing issues of using classes starting with "javax.security.sasl" namespace from LDAP APIs.

IMPORTANT:Any Novell products using these APIs previously need to change all the references from "javax.security.sasl" to "com.novell.security.sasl" in their code before using the SASL APIs.

## 9.0 Novell Import Convert Export Utility

The Novell Import Convert Export utility (ICE) transfers LDAP data from one source to another destination. ICE can use the following as sources or destinations for LDAP data:

- LDIF file

- Comma-delimited file

- Any LDAP directory ("works with LDAP2000" certified)

In addition, ICE contains a schema cache to compare and update schema and the DirLoad driver to generate LDAP data from a template.

This utility is Novell’s recommended utility for making schema additions and modifications. It is distributed with the LDAP Libraries for C.

The utility is available on all eDirectory servers running eDirectory 8.5. For instructions on using this command line utility and for creating LDIF files, see

http://developer.novell.com/ndk/doc/cldap/ldaplibc/data/a5hgmnu.html

## 10.0 Documentation

We have enabled Start menu documentation entries on Windows platforms. After you have installed the documentation, use the "NDK Documents" entry on your Start menu to quickly locate and access NDK documentation.

For non Windows platforms, download the documentation from the NDK. These files are a combination of html and pdf files and can be viewed with your browser.

To read or print the documentation, you need Adobe Acrobat Reader, a free download from

http://www.adobe.com.

The documents in this download were created as standalone files; therefore, links between files in this download and links to files in other downloads will not resolve.

The download includes the following files:

- ldap_enu.pdf (LDAP and NDS Integration guide) located at [install location]\doc\ldapover

- LDAP Classes for Java documentation and JavaDoc located at [install location]\doc\jldap\jldapenu

- dsov_enu.pdf (NDS Technical Overview) and schm_enu.pdf (NDS Schema Reference) located at [install location]\doc\ndslib

## 11.0 Connection Services

### 11.1 Bind

The LDAP Classes for Java support simple bind, i.e. password authentication and SASL bind. For non-encrypted connections, the LDAP server must be configured to allow clear-text passwords (not recommended).

We recommend the use of encrypted connections using TLS (SSL).

### 11.2 TLS (SSL) Integration

TLS (SSL) is used to create secure connections to the LDAP directory and can use certificates to verify identity. This is not the same as performing a bind, which authenticates you to the directory.

The LDAP Classes for Java support client and server verification, during which the server and client exchange certificates to ensure data is exchanged between a trusted host and trusted client.

Instructions for setting up TLS (SSL) are included with the LDAP Classes for Java documentation. These libraries support Sun JSSE-compliant TLS (SSL) implementations.

## 12.0 Known Issues and Solutions

The following are the known issues and solutions:

- The API does not yet return the exception LDAPLocalException.

  The class LDAPExtendedResponse has not yet implemented the register method.

- Beginning with the September 2002 NDK, an incompatibility with previous releases exists for applications using LDAPSchema.getAtribute() and LDAPSchemaElement.getName(). Both methods were deprecated in the May 2002 NDK. These methods have been removed in this release of the API to comply with IETF draft version 18 (draft-ietf-ldapext-ldap-java-api-18.txt). The reason for this change is described in the following text.

  LDAPSchema now extends LDAPEntry. This means that LDAPSchema inherits the getAttribute method from LDAPEntry which has the same signature as the getAttribute method of LDAPSchema, but the two methods differ in functionality. Thus, the getAttribute method of LDAPSchema has been removed from the IETF draft and from the API in this release.

  To fix your application, use the getAttributeSchema method of LDAPSchema instead of getAttribute.

  The following error will occur when trying to compile code using this deprecated method:

  - incompatible types;
  - found: com.novell.ldap.LDAPAttribute,
  - required: com.novell.ldap.LDAPSchemaElement

  The following error will occur when trying to run code using this deprecated method:

  java.lang.NoSuchMethodError

  LDAPSchemaElement now extends LDAPAttribute. This means that LDAPSchemaElement inherits the getName method from LDAPAttribute, which has the same signature as the getName method of LDAPSchemaElement, but the two methods differ in functionality.

  Thus, the getName method of LDAPSchemaElement has been removed from the IETF draft and from the API in this release.

  To fix your application, use the getNames method of LDAPSchemaElement instead of getName.

  NOTE:You will not get a compile or runtime error if your code uses this deprecated method. You may, however, get errors trying to intrepret the data returned.

- You must recompile your applications to run with the September 2002 LDAP Classes for Java. The September 2002 libraries are not binary compatible with previous versions, i.e. applications compiled with previous versions may not run with the September 2002 version. The applications will run, except as noted above, if they are recompiled, without changes, against the September 2002 LDAP Classes for Java jar file. For example, the code:

      attribute = new LDAPAttribute("objectclass", objectclass_values);
       attributeSet.add(attribute);

  will get the error:

      java.lang.NoSuchMethodError
       at MyApp.main(MyApp.java:77)
       Exception in thread "main"

  but if recompiled will run correctly. This is because the add method currently implemented is an implementation of the Set class where the previous add method was not.

- eDirectory on NetWare returns an LDAP 80 (unknown error) when an invalid password is entered.

- Unlike eDirectory, the LDAP standard does not define an "alias" structural class. When using LDIF tools such as the Novell Import Convert Export Utility (ICE), you may encounter errors adding aliased objects.

- eDirectory has provided an interim solution to inform the application that the password is expiring. See the sample "gracelogin.java" for further information.

- There is a problem using the LDAP utilities on NetWare when specifying "localhost" as the host name. This issue is resolved in NetWare 5.1 SP2 and NetWare 5.0 SP6.

## 13.0 Revision History

The following sub-sections outlines all the changes made to the LDAP Classes for Java SDK (in reverse chronological order):

### 13.1 Changes for the February 2008 NDK

The following changes are made for the February 2008 NDK:

- A new control LDAPPagedResultsControl is added for the results to be returned in pages of specified size from server.

- LDAP Connection constructor with the time out value is modified to use the socketFactory, which is set through the method setSocketFactory().

- New exception is thrown in case of connection failure.

- Fix for PoolManager being unable to rebind the existing available connections on LDAP server failure.

### 13.2 Changes for the October 2007 NDK

The following change is made for the October 2007 NDK:

A new LDAP extension is implemented to obtain the X500 DN from the DNS name given.

### 13.3 Changes for the June 2006 NDK

The following change is made for the June 2006 NDK:

Support for JDK 1.5 is added.

### 13.4 Changes for the March 2006 NDK

The following changes are made for the March 2006 NDK:

- A new constructor with the parameter timeout in LDAPConnection class to support Socket Timeout value is added.

- Two new methods setSocketTimeOut and getSocketTimeOut to set and get the socket connect timeouts respectively are added.

- ConnectTimeOut.java is removed as the constructor in the ldapconnection class does the same function.

- NmasBind.java is removed as NMAS bind (through Simple Password and NDS mechanisms) is not supported in NMASClient.jar.

- Fixed the defect for thread synch.

### 13.5 Changes for the October 2005 NDK

The following changes are made for the October 2005 NDK:

- Fixed defect so that the connection fails when the same connection is used to connect to an LDAP server multiple times.

- Transitioned to revised Novell standards.

### 13.6 Changes for the June 2005 NDK

The following sub-sections outlines all changes made to the LDAP Classes for Java:

#### 13.6.1 New Functionality

- Support for Subnordinate Subtree search scope for Novell Virtual Directory Services (NVDS).

- Support for LDAP EffectivePrivilegesControl for NVDS.

- Added DSML serialization support for com.novell.ldap.LDAPSearchResults.java class.

- Added Junit test automation to verify thread safe of Java LDAP SDK code base. This basically tests thread safety in pool of LDAPConnection clones, while handling the client requests simultaneously.

- Verified IntermediateResponse operation in Java LDAP SDK as per the standard mentioned in the http://www.ietf.org/internet-drafts/draft-ietf-ldapbis-protocol-29.txt for NVDS.

### 13.7 Changes for the March 2005 NDK

The following sub-sections outlines all changes made to the LDAP Classes for Java.

#### 13.7.1 New Functionality

Support for LDAP based backup and restore extensions in the following LDAP classes:

- com.novell.ldap.extensions.BackupRestoreConstants.java
- com.novell.ldap.extensions.LDAPBackupRequest.java
- com.novell.ldap.extensions.LDAPBackupResponse.java
- com.novell.ldap.extensions.LDAPRestoreRequest.java

#### 13.7.2 New Sample Code

The following sample program demonstrates the use of LDAP based backup and restore APIs.

GetLDAPBackupRestore.java

#### 13.7.3 Bug Fixes

The following bugs are fixed for the October 2004 NDK:

- Javaldap codebase had the dependency of using namespaces starting with "javax.security.sasl". This fix has resolved two issues:

  - The client application can run using LDAP APIs in all the versions of Java 2 (including JDK 1.5). There will be no namespace issues in JDK 1.5.

  - The licensing issues of using classes starting with "javax.security.sasl" namespace from LDAP APIs.

  NOTE:Any Novell products using these APIs previously need to change all the references from "javax.security.sasl" to "com.novell.security.sasl" in their code before using the SASL APIs.

- Java docs were missing for com.novell.ldap.events.edir.eventdata.* classes.

### 13.8 Changes for the October 2004 NDK

#### 13.8.1 New Functionality

Support for default DSML serialization and de-serialization in following LDAP classes:

- +---com.novell.ldap
- | Connection.java
- | LDAPAddRequest.java
- | LDAPAttribute.java
- | LDAPAttributeSchema.java
- | LDAPAttributeSet.java
- | LDAPCompareRequest.java
- | LDAPControl.java
- | LDAPDeleteRequest.java
- | LDAPDITContentRuleSchema.java
- | LDAPDITStructureRuleSchema.java
- | LDAPEntry.java
- | LDAPExtendedOperation.java
- | LDAPExtendedRequest.java
- | LDAPExtendedResponse.java
- | LDAPMatchingRuleSchema.java
- | LDAPMatchingRuleUseSchema.java
- | LDAPMessage.java
- | LDAPModification.java
- | LDAPModifyDNRequest.java
- | LDAPModifyRequest.java
- | LDAPNameFormSchema.java
- | LDAPObjectClassSchema.java
- | LDAPResponse.java
- | LDAPSchema.java
- | LDAPSearchRequest.java
- | LDAPSearchResult.java
- | LDAPSearchResultReference.java
- | LDAPSyntaxSchema.java
- | LDAPUrl.java

#### 13.8.2 New Sample Code

The following sample programs demonstrate the use of default DSML serialization and de-serialization APIs:

- LDAPAttributeDSMLSerialization.java

- LDAPSchemaDSMLSerialization.java

#### 13.8.3 Bug Fixes

The following bugs are fixed for the October 2004 NDK:

- LDAPConnetion class was producing one more connection handle while calling stopTLS().

- DSMLWriter class was ignoring LDAP controls while writing some categories of LDAPMessages.

### 13.9 Changes for the June 2004 NDK

#### 13.9.1 New Functionality

Support for Persistence Search events and Novell eDirectory native events.

The following classes are added for Persistence Search events:

- +---com.novell.ldap.events
- | EventConstant.java
- | LDAPEvent.java
- | LDAPEventListener.java
- | LDAPEventSource.java
- | LDAPExceptionEvent.java
- | PSearchEventListener.java
- | PsearchEventSource.java
- | SearchReferralEvent.java
- | SearchResultEvent.java

The following classes are added for eDirectory native events:

- +---com.novell.ldap.events.edir
- | EdirEventConstant.java
- | EdirEventIntermediateResponse.java
- | EdirEventSource.java
- | EdirEventSpecifier.java
- | EventResponseData.java
- | MonitorEventRequest.java
- | MonitorEventResponse.java
- | MonitorFilterEventRequest.java
- \---eventdata
- | BinderyObjectEventData.java
- | ChangeAddressEventData.java
- | ConnectionStateEventData.java
- | DebugEventData.java
- | DebugParameter.java
- | DSETimeStamp.java
- | EntryEventData.java
- | GeneralDSEventData.java
- | ModuleStateEventData.java
- | NetworkAddressEventData.java
- | ReferralAddress.java
- | SecurityEquivalenceEventData.java
- | ValueEventData.java

#### 13.9.2 New Sample Code

- PersistenceSearchCallback.java: Sample programs demonstrating use of Persistence Search events APIs.

- EdirEventsCallback.java: Sample programs demonstrating use of Default Novell eDirectory native events APIs.

### 13.10 Changes for the February 2004 NDK

#### 13.10.1 New Functionality

- Support for LDAP Bulk Update/Replication Protocol (LBURP) APIs.

- Support for LDAPExtendedResponse.register method that includes implementing a generalized response factory for LDAP Extended Responses.

- Existing extensions are modified to use LDAPExtendedResponse.register method

- Object Serialization. The following classes is Serializable as per draft 18:

  - LDAPAttribute

  - LDAPAttributeSet

  - LDAPConstraints

  - LDAPControl

  - LDAPEntry

  - LDAPExtendedOperation

  - LDAPMessage

  - LDAPModification

  - LDAPSchema

  - LDAPUrl

- Support for writing of any LDAPRequests using DSMLWriter.

- Support for reading any LDAPResponse using DSMLReader.

- Adding readDSML and writeDSML methods to all serialzable classes, so as to provide DSML serialization of data.

#### 13.10.2 New Sample Code

- Sample program demonstrating use of LBURP API.

- Samples program for converting a LDIF requests file to corresponding DSML requests document.

#### 13.10.3 Bug Fixes

The following bugs are fixed for the February 2004 NDK:

- LDIFWriter did not support multi-value attribute in modify request.

- LDIFWriter did not recognize attribute values starting with the “<” character.

### 13.11 Changes for the October 2003 NDK

#### 13.11.1 New Functionality

- Implementation of The Java SASL Application Program Interface as specified in JSR28 and draft-weltman-java-sasl-05.txt.

- Implementation of NMAS_LOGIN SASL Mechanism.

- Implementation of DIGESTMD5 SASL Mechanism.

- Implementation of EXTERNAL SASL Mechanism.

- HP-UX support.

#### 13.11.2 New Sample Code

- MD5Bind.java - Sample to show how to authenticate to an LDAP server using a the DIGEST-MD5 SASL mechanism.

- NmasBind.java - Sample to show how to authenticate to an LDAPserver using a Novell Modular Authentication Service (NMAS)login sequence.

- SaslExternalBind.java - Sample to Demonstrates how to do a SASL External Bind with an LDAP Server.

- GetAttributeSchema.java - Sample to show how to read an entry and print the attribute schema of all of its attribute.

#### 13.11.3 Enhancements

Due to changes in the IETF drafts from version 13 to 18, changes had to be made to the code that required deprecating many methods. For complete details see the drafts in the draft-ietf-ldapext-ldap-java-api-18.txt.

The following lists the key changes to the draft that required deprecating the methods:

Renamed Listener classes to MessageQueue

LDAPListener renamed to LDAPMessageQueue. LDAPResponseListener renamed to LDAPResponseQueue. LDAPSearchListener renamed to LDAPSearchQueue. abstract class LDAPMessageQueue class LDAPResponseListener extends LDAPMessageQueue class LDAPResponseQueue extends LDAPResponseListener class LDAPSearchListener extends LDAPMessageQueue class LDAPSearchQueue extends LDAPSearchListener The key functionality is in the abstract class LDAPMessageQueue The classes LDAPResponseListener and LDAPSearchListener are eliminated. The code in LDAPConnection and other classes which was referencing LDAPxxxxListener classes for backwards compatibility has been be changed to LDAPxxxxxQueue classes. The classes affected by this change are: LDAPConnection.java LDAPListener.java LDAPMessageQueue.java LDAPResponseListener.java LDAPResponseQueue.java LDAPSearchListener.java LDAPSearchQueue.java

Renamed Referral handling classes

LDAPRebind renamed to LDAPAuthHandler. LDAPRebindAuth renamed to LDAPAuthProvider. interface LDAPReferralHandler interface LDAPAuthHandler extends LDAPReferralHandler interface LDAPRebind extends LDAPReferralHandler class LDAPRebindAuth Classes LDAPRebind and LDAPRebindAuth is removed, and references changed appropriately. Files affected: LDAPConnection.java LDAPRebind.java LDAPRebindAuth.java

LDAPModificationSet replaced by LDAPModificaton[]

Files that were referencing LDAPModificationSet were: LDAPAttributeSchema.java LDAPConnection.java LDAPModificationSet.java LDAPObjectClassSchema.java LDAPSchema.java LDAPSyntaxSchema.java These files have been modified to use LDAPModificaton[] instead of LDAPModificationSet and LDAPModificationSet class is removed.

LDAPAttributeSet implements java.util.set.

This change caused an incompatibility with previous release. The incompatibility is outlined in the README files as follows: "LDAPSchemaElement now extends LDAPAttribute.This means that LDAPSchemaElement inherits the getName method from LDAPAttribute, which has the same signature as the getName method of LDAPSchemaElement, but the two methods differ in functionality. Thus, the getName method of LDAPSchemaElement has been removed from the IETF draft and from the API in this release. To fix your application, use the getNames method of LDAPSchemaElement instead of getName." Other methods made obsolete by this change are removed.

bind methods in LDAP Connection All bind() signatures which take String instead of byte[] for password are marked deperecated since these methods were removed from the draft.We did not remove these methods and simply marked them deprecated as it is common for applications to use String values passwords. Replaced Hashtable with Map in SASL bind methods. Since these are not implemented, we did no deprecation here.Schema changes The LDAPSchema class previously acted like an I/O class, but this did not fit well into the rest of the model. In draft 18, all schema I/O was moved to LDAPConnection (see fetchSchema and getSchemaDN). The LDAPSchema class was integrated into the rest of the classes by extending LDAPEntry. However, this change caused a compatibility problem with previous releases and is explained in the README.txt file as follows: "LDAPSchema now extends LDAPEntry. This means that LDAPSchema inherits the getAttribute method from LDAPEntry which has the same signature as the getAttribute method of LDAPSchema, but the two methods differ in functionality. Thus, the getAttribute method of LDAPSchema has been removed from the IETF draft and from the API in this release. To fix your application, use the getAttributeSchema method of LDAPSchema instead of getAttribute." Other schema files were changed because various methods were renamed to include the "Schema" as part of the method name. Schema files that were having deprecated methods are: LDAPAttributeSchema.java LDAPObjectClassSchema.java LDAPSchema.java LDAPSchemaElement.java LDAPSyntaxSchema.java These files are changed to remove the deprecated methods. Files in com/novell/ldap, which were having deprecated methods: LDAPAttributeSchema.java LDAPAttributeSet.java LDAPBind.java LDAPCompareAttrNames.java LDAPConnection.java LDAPConstraints.java LDAPEntryComparator.java LDAPException.java LDAPListener.java LDAPMessageQueue.java LDAPModificationSet.java LDAPObjectClassSchema.java LDAPRebind.java LDAPRebindAuth.java LDAPResponseListener.java LDAPResponseQueue.java LDAPSchema.java LDAPSchemaElement.java LDAPSearchListener.java LDAPSearchQueue.java LDAPSearchResults.java LDAPSecureSocketFactory.java LDAPSyntaxSchema.java LDAPUrl.java These files are changed to remove the deprecated methods. Files in com/novell/ldap/extensions which were having deprecated methods: AbortNamingContextOperationRequest.java CreateNamingContextRequest.java CreateOrphanNamingContextRequest.java GetContextIdentityNameRequest.java GetContextIdentityNameResponse.java MergeNamingContextsRequest.java NamingContextEntryCountRequest.java NamingContextEntryCountResponse.java NamingContextSyncRequest.java RemoveOrphanNamingContextRequest.java. These files are changed to remove the deprecated methods. Added a method to the LDAPConnection class which checks whether a connection is still alive or not

#### 13.11.4 Bug Fixes

The following bugs are fixed for the October 2003 NDK:

- LDIFWriter WriteEntry does not insert newline after a record.

- LDIFReader local error 82 for empty fields.

- Deprecated LDAPException calls need to be removed from API.

- Remove usage of PARAM_ERROR from NDK.

- isConnected() method in LDAPConnection class do not return the correct state of the connection.

- Casting error in com.novell.ldap.LDAPSearchConstraints.

- LDAPAttributeSet.iterator() returns iterator of com.novell.ldap.LDAPAttribute, not org.ietf.ldap.LDAP.

- Passing null to LDAPAttribute constructor.

### 13.12 Changes for the June 2003 NDK

#### 13.12.1 New Functionality

- com.novell.ldap - Added the method "getAuthenticationDN" to the LDAPBindRequest class.

- com.novell.ldap - Added accessor methods to the LDAPSearchRequest class, including a method to retrieve the search filter parsed into its separate components.

- com.novell.ldap.connectionpool - Added new this new package. It contains classes to support management of connection pools. These classes were previously in the samples directory.

- New samples in the samples/dsml_consumers directory.

- New sample ConnectionPool.java demonstrates connection pool usage.

#### 13.12.2 Bug Fixes

- com.novell.ldap - Corrected behavior in LDAPConnection for the "isBound" and "getAuthenticationDN" methods. They were returning incorrect values for connections with anonymous authentication.

- com.novell.ldap - Corrected a problem parsing search requests with complex search filters where "or" operators were mistakenly treated like "and" operators.

- com.novell.ldap.util - Fixed namespace problems in the DomReader class.

- com.novell.ldap.util - The DomWriter class returned a meaningless error message when invalid credentials are supplied.

- com.novell.ldap.util - The DomHandler class sometimes generated an exception when processing complex search filters with a substring matching expression, followed by another search expression.

- The Search.java sample was modified to Base64 encode attribute values that are not printable.

### 13.13 Changes for the March 2003 NDK

- Improved LDAP filter error checking and fixed some encoding errors. Filters can now include characters outside the ASCII set (0 - 0x7f). These are represented in Java as Unicode characters and are converted directly to UTF-8 when sent to the LDAP server. They no longer need to be escaped.

- Added samples demonstrating a mechanism for connection pooling.

- Added the classes representing LDAP requests to support LDIF & DSML.

- Added support for reading and writing LDIF files (LDIF V1 API for LDAP). See the com.novell.ldap.util package.

- Added support for reading and writing DSML files (DSML V2.0 API for LDAP). See the com.novell.ldap.util package.

- Added the following LDAP utility applications, in the bin directory:

  - jldaprootdse | Displays the contents of the root DSE for the specified LDAP server (see sample GetDSE.java).
  - jldapsearch | Performs general LDAP searches (see sample SearchUtil.java).
  - jldapschema | Displays the attribute or object class schema (see sample ListSchema.java).
  - jldappassword | Allows a user to modify an ldap password (see sample ModifyPassword.java).

  Use the -? option to list the command format of these utilities.

  - Added functionality to jldapsearch to write search output in DSML or LDIF format specified via the -x option.

  - Synchronous searches have been modified to conform to the current draft. Previously the synchronous search method of LDAPConnection returned only after at least one search result had been received by the client. It now returns immediately. As before, the next method of LDAPSearchResults blocks until at least the number of results specified by the BatchSize parameter of LDAPSearchConstraints have been received.

  - The getCount method of LDAPSearchResults now reports the correct value. It previously counted the number of result items received so far. The getCount now reports the number of items received, but not yet retrieved by the application. The number may vary between two consecutive call to the method, as new results may have been received. When no results are available it reports zero, even if not all results have been received from the server.

- LDAPSearchQueue and LDAPResponseQueue classes had separate and sometimes different implementations. The two now leverage a common class to handle the queue functionality.

- Clone was implemented incorrectly in some classes and not implemented in others. This is now corrected.

- Bind did not allow a null String password. This is corrected.

### 13.14 Patch to September 2002 NDK

- Fixed LDAPConnection.getCount() to return correct results as per the IETF specification:

  "Returns a count of the entries and exceptions in the object. If the search was submitted with a batch size greater than 0, this reports the number of results received so far but not numerated with next()."

### 13.15 Changes for the September 2002 NDK

- Changed the schema model to use standard LDAP operations to manipulate the schema, per Java API IETF draft 18. This means that LDAPSchema becomes a parsing class, and modifications to the schema use the add, modify, or delete operations of LDAPConnection.

- Sorting is now done using the Collections framework. LDAPEntry LDAPAttribute now have natural ordering.

The following list details the latest changes made to the LDAP Classes for Java.

Changes applying only to the com.novell.ldap package are marked with "com" in the package column, while changes applying only to the org.ietf.ldap package are marked with an "org" in the package column. Changes applying to both packages are marked with "com" and "org" in the package column.

Package Modified Classes and Methods

---------------------------------------------

LDAPAttribute

com org Implements Comparable

LDAPCompareAttrNames

com org Implements java.util.Comparator instead of LDAPEntryComparator.

LDAPConnection

com org FetchSchema(): new method

com org getSchemaDN(): new method

com org Remove get/setInputStream methods

com org Remove get/setOnputStream methods

LDAPEntry com org implements Comparable

LDAPEntryComparator

org Remove class: See LDAPCompareAttrNames

com Deprecate class:

com org LDAPException

com org constructors: Add serverMessage as parameter

com org toString(): Method overrides the default toString behavior

com org errorCodeToString(): Rename to resultCodeToString().

com errorCodeToString(): Deprecate

org errorCodeToString(): Delete

com org getLDAPResultCode(): Rename to getResultCode ().

com getLDAPResultCode(): Deprecate

org getLDAPResultCode(): Delete

com org Result codes: Add INVALID_RESPONSE

com org Result codes: Add AMBIGUOUS_RESPONSE

com Result codes: Deprecate PARAM_ERROR

org Result codes: Remove PARAM_ERROR

LDAPLocalException

com org New class for local exceptions

LDAPSchema

com org extends LDAPEntry

org fetchSchema: Removed method

com fetchSchema: Deprecated method

org saveSchema: Removed method

com saveSchema: Deprecated method

org add: Removed method

com add: Deprecated method

org modify: Removed method

com modify: Deprecated method

org delete: Removed method

com delete: Deprecated method

LDAPSchemaElement

com org extends LDAPAttribute

LDAPSearchResults

org No longer implements Enumeration.

com Enumeration methods depcrecated.

org nextElement(): Remove method

com nextElement(): deprecate method

com hasMoreElements(): deprecated

com org hasMoreElements(): Rename to hasMore().

org sort(): Remove method (sorting can now be done by

classes/interfaces of the Collections framework.

com sort(): Deprecate method

com org

### 13.16 Changes for the May 2002 NDK

The following list details the latest changes made to the LDAP Classes for Java.

Changes applying only to the com.novell.ldap package are marked with "com" in the package column, while changes applying only to the org.ietf.ldap package are marked with an "org" in the package column. Changes applying to both packages are marked with "com" and "org" in the package column.

Package Modified Classes and Methods -------------------------------------------------------------------------- LDAPAttributeSchema com Deprecate Constructor that takes "String name" and "String[] aliases". org Remove Constructor that takes "String name" and "String[] aliases". com org Add Constructor that takes "String[] names, and no aliases" com isModifiable(): Deprecate & Rename to isUserModifiable() org isModifiable(): Delete method com deprecate getValue(): use superclass toString() org delete getValue() com deprecate add() org delete add() com deprecate modify() org delete modify() com deprecate remove() org delete remove() com org LDAPAuthHandler - new class, replaces LDAPRebind LDAPRebind - replaced by LDAPAuthHandler com Deprecate LDAPRebind org Delete LDAPRebind com org LDAPAuthProvider - new class, replaces LDAPRebindAuth LDAPRebindAuth - replaced by LDAPAuthProvider com Deprecate LDAPRebindAuth org Delete LDAPRebindAuth com org LDAPBindHandler - new class, replaces LDAPBind LDAPBind - replaced by LDAPBindHandler com Deprecate LDAPBind org Delete LDAPBind LDAPConnection com org bind(): Add signatures that take a byte array com org bind(): Add signatures that take byte[] as password parameter, com bind(): Deprecate signatures which do not take a version parameter org bind(): Remove signatures which do not take a version parameter com bind(): Deprecate all signatures which take String for password. org bind(): Remove all signatures which take String for password. com org bind(): Modify signatures for SASL to take an authzId parameter com org bind(): Use Hashtable, not Properties, in all SASL bind signatures com org bind(): Replace Hashtable as parameter with Map com org getAuthenticationPassword(): remove method com org getSaslBindProperties(): Replace Hashtable with Map com org modify(): replace LDAPModificationSet with LDAPModification[] com modify(): deprecate methods using LDAPModificationSet com org read(): throws LDAPException with AMBIGUOUS_RESPONSE if there is than one result com org rename(): takes newParentdn before deleteOldRdn (one of the eight signatures had order reversed) com org setInputStream(): throws an LDAPException. com org setOutputStream(): throws an LDAPException. com org Move setProperty to LDAPConstraints object com org LDAP_PROPERTY_SDK is of type String rather than Float. com org LDAP_PROPERTY_PROTOCOL is of type Integer rather than Float. com setSearchConstraints(): Deprecate method org setSearchConstraints(): Remove method com org stopTLS(): add method LDAPConstraints com org Implements Cloneable. com org getReferralHandler(): Remove method com org getServerControls(): rename to getControls. com org setServerControls(): rename to setControls. com get/setServerControls(): deprecate com org getProperty(): add Method com org setProperty(): add Method com org getClientControls(): remove method com org setClientControls(): remove method com get/setClientControls(): deprecate method LDAPControl com org Remove all references to "client controls". LDAPDITContentRuleSchema com org Remove Constructor that takes "String name" and "String[] aliases". com org Add Constructor that takes "String[] names, and no aliases" com org delete getValue() com org delete add() com org delete modify() com org delete remove() LDAPDITStructureRuleSchema com org Remove Constructor that takes "String name" and "String[] aliases". com org Add Constructor that takes "String[] names, and no aliases" com org delete getValue() com org delete add() com org delete modify() com org delete remove() LDAPDN com org isValid(): new Method com org normalize(): new Method LDAPException com org Result codes: Add INVALID_RESPONSE com org Result codes: Add AMBIGUOUS_RESPONSE com Result codes: Deprecate PARAM_ERROR org Result codes: Remove PARAM_ERROR com Remove PARAM_ERROR usage from API com org LDAPMessageQueue - new class, replaces LDAPListner LDAPListener - replaced by LDAPMessageQueue. com Deprecate class LDAPListener org Delete class LDAPListener LDAPMatchingRuleSchema com org Constructor: Combine the two constructors with explicit field parameters, and "String[] aliases". com org getSyntaxString(): returns String instead of String[] com org Remove Constructor that takes "String name" and "String[] aliases". com org Add Constructor that takes "String[] names, and no aliases" com org delete getValue() com org delete add() com org delete modify() com org delete remove() LDAPMatchingRuleUseSchema com org Remove Constructor that takes "String name" and "String[] aliases". com org Add Constructor that takes "String[] names, and no aliases" com org delete getValue() com org delete add() com org delete modify() com org delete remove() LDAPMessage com org Implements Serializable LDAPModificationSet com Deprecate class org Remove class: (replace with LDAPModification[] as parameter where referenced, see LDAPConnection.modify() in the Javadoc). LDAPNameFormSchema com org Remove Constructor that takes "String name" and "String[] aliases". com org Add Constructor that takes "String[] names, and no aliases" com org isModifiable(): Deprecate & Rename to isUserModifiable() com org delete getValue() com org delete add() com org delete modify() com org delete remove() LDAPObjectClassSchema com Deprecate Constructor that takes "String name" and "String[] aliases". org Remove Constructor that takes "String name" and "String[] aliases". com org Add Constructor that takes "String[] names, and no aliases" com deprecate getValue(): use superclass toString() org delete getValue() com deprecate add() org delete add() com deprecate modify() org delete modify() com deprecate remove() org delete remove() com org LDAPResponseQueue - new class, replaces LDAPResponseListener LDAPResponseListener - replaced by LDAPResponseQueue com Deprecate class org Delete class LDAPSchema com org add(): Add method com Deprecate & Rename getAttribute() to getAttributeSchema() org Rename getAttribute() to getAttributeSchema() com Deprecate & Rename getAttributes() to getAttributeSchemas() org Rename getAttributes() to getAttributeSchemas() com Deprecate & Rename getDITContentRule() to getDITContentRuleSchema() org Rename getDITContentRule() to getDITContentRuleSchema() com Deprecate & Rename getDITContentRules() to getDITContentRuleSchemas() org Rename getDITContentRules() to getDITContentRuleSchemas() com Deprecate & Rename getDITStructureRule() to getDITStructureRuleSchema() org Rename getDITStructureRule() to getDITStructureRuleSchema() com Deprecate & Rename getDITStructureRules() to getDITStructureRuleSchemas() org Rename getDITStructureRules() to getDITStructureRuleSchemas() com Deprecate & Rename getMatchingRule() to getMatchingRuleSchema() org Rename getMatchingRule() to getMatchingRuleSchema() com Deprecate & Rename getMatchingRules() to getMatchingRuleSchemas() org Rename getMatchingRules() to getMatchingRuleSchemas() com Deprecate & Rename getMatchingRuleUse() to getMatchingRuleUseSchema() org Rename getMatchingRuleUse() to getMatchingRuleUseSchema() com Deprecate & Rename getMatchingRuleUses() to getMatchingRuleUseSchemas() org Rename getMatchingRuleUses() to getMatchingRuleUseSchemas() com Deprecate & Rename getNameForm() to getNameFormSchema() org Rename getNameForm() to getNameFormSchema() com Deprecate & Rename getNameForms() to getNameFormSchemas() org Rename getNameForms() to getNameFormSchemas() com Deprecate & Rename getObjectClass() to getObjectClassSchema() org Rename getObjectClass() to getObjectClassSchema() com Deprecate & Rename getObjectClasss() to getObjectClassSchemas() org Rename getObjectClasss() to getObjectClassSchemas() com Deprecate & Rename getSyntax() to getSyntaxSchema() org Rename getSyntax() to getSyntaxSchema() com Deprecate & Rename getSyntaxes() to getSyntaxSchemas() org Rename getSyntaxes() to getSyntaxSchemas() com org modify(): Add method com org remove(): Add method com org saveSchema(): Add method LDAPSchemaElement com add(): Remove method, implementation deprecated in subclass org add(): Remove method com getAliases(): Deprecate method org getAliases(): Remove method com getName(): Deprecate & rename to getNames() org getName(): Rename to getNames() com getValue(): Deprecate & rename to toString() org getValue(): Rename to toString() com modify(): Remove method, implementation deprecated in subclass org modify(): Remove method com remove(): Remove method, implementation deprecated in subclass org remove(): Remove method LDAPSearchConstraints com org constructor: add constructor that takes LDAPConstraints as parameter. com org LDAPSearchQueue - new class, replaces LDAPSearchListener LDAPSearchListener - replaced by LDAPSearchQueue com Deprecate class LDAPSearchListener org Delete class LDAPSearchListener LDAPSocketFactory com org makeSocket(): Rename method to createSocket(). com makeSocket(): Deprecate org makeSocket(): Delete LDAPSyntaxSchema com deprecate getValue(): use superclass toString() org delete getValue() com deprecate add() org delete add() com deprecate modify() org delete modify() com deprecate remove() org delete remove()

### 13.17 Changes for the February 2002 NDK

- Support for the extension GetBindDN was added.

- Made public the constructor in LDAPJSSESecureSocketFactory that exposes context.

- Deprecated LDAPSecureSocketFactory.

- Corrected memory leak doing synchronous searches.

- Corrected bug in extension APIs so that the APIs no longer decode results if the server returned an error.

- Corrected LDAPConnection.getAuthenticationDN so that it returns an empty String instead of null.

- Added a default constructor for class LDAPDN.

- Corrected constructor for LDAPEntry where it created an empty dn instead of an empty attribute set.

- Fixed the LDAPAttribute class so it distinguished properly between String and byte[] attribute values.

- Corrected a null pointer exception in the copy constructor of org.ietf.ldap.LDAPAttribute.

- Added javadoc to LDAPUrl.

- Put links in the javadoc to point to relevant sample code.

- To eliminate confusion between the Novell and IETF classes, the javadoc for the two were separated into separate javadoc directories.

- Renamed the NamingContext APIs to Replica & Partition APIs. The old APIs are deprecated.

- Added samples

  - DynamicGroup

  - JSSEConnection

  - LDAPOIDs

  - ListGroups

  - MakeContainer

  - NameAndOid

  - TLSTrustManager

  - Naming Context samples were renamed to reflect the change to use Replica and Partition APIs.

- Added sample TLSTrustManager.

- Updated and clarified existing sample code.

## 14.0 Legal Notices

Novell, Inc., makes no representations or warranties with respect to the contents or use of this documentation, and specifically disclaims any express or implied warranties of merchantability or fitness for any particular purpose. Further, Novell, Inc., reserves the right to revise this publication and to make changes to its content, at any time, without obligation to notify any person or entity of such revisions or changes.Further, Novell, Inc., makes no representations or warranties with respect to any software, and specifically disclaims any express or implied warranties of merchantability or fitness for any particular purpose. Further, Novell, Inc., reserves the right to make changes to any and all parts of Novell software, at any time, without any obligation to notify any person or entity of such changes.

Any products or technical information provided under this Agreement may be subject to U.S. export controls and the trade laws of other countries. You agree to comply with all export control regulations and to obtain any required licenses or classification to export, re-export or import deliverables. You agree not to export or re-export to entities on the current U.S. export exclusion lists or to any embargoed or terrorist countries as specified in the U.S. export laws. You agree to not use deliverables for prohibited nuclear, missile, or chemical biological weaponry end uses. See the Novell International Trade Services Web page for more information on exporting Novell software. Novell assumes no responsibility for your failure to obtain any necessary export approvals.Copyright © 2008 Novell, Inc. All rights reserved. No part of this publication may be reproduced, photocopied, stored on a retrieval system, or transmitted without the express written consent of the publisher.Novell, Inc., has intellectual property rights relating to technology embodied in the product that is described in this document. In particular, and without limitation, these intellectual property rights may include one or more of the U.S. patents listed on the Novell Legal Patents Web page and one or more additional patents or pending patent applications in the U.S. and in other countries.

- Novell, Inc.
- 404 Wyman Street, Suite 500
- Waltham, MA 02451
- U.S.A.
- www.novell.com

- Online Documentation: To access the latest online documentation for this and other Novell products, see the Novell Documentation Web page.

#### Novell Trademarks

For Novell trademarks, see the Novell Trademark and Service Mark list.

#### Third-Party Materials

All third-party trademarks are the property of their respective owners.