Generated by
JDiff

javax.naming.ldap Documentation Differences

This file contains all the changes in documentation in the package javax.naming.ldap as colored differences. Deletions are shown like this, and additions are shown like this.
If no deletions or additions are shown in an entry, the HTML tags will be what has changed. The new HTML tags are shown in the differences. If no documentation existed, and then some was added in a later version, this change is noted in the appropriate class pages of differences, but the change is not shown on this page. Only changes in existing text are shown here. Similarly, documentation which was inherited from another class or interface is not shown here.
Note that an HTML error in the new documentation may cause the display of other documentation changes to be presented incorrectly. For instance, failure to close a <code> tag will cause all subsequent paragraphs to be displayed differently.

Class Control

This interface represents an LDAPv3 control as defined in RFC 2251.

The LDAPv3 protocol uses controls to send and receive additional data to affect the behavior of predefined operations. Controls can be sent along with any LDAP operation to the server. These are referred to as request controls. For example a "sort" control can be sent with an LDAP search operation to request that the results be returned in a particular order. Solicited and unsolicited controls can also be returned with responses from the server. Such controls are referred to as response controls. For example an LDAP server might define a special control to return change notifications.

This interface is used to represent both request and response controls. @author Rosanna Lee @author Scott Seligman @author Vincent Ryan @version 1.5 006 01/0212/0203 @see ControlFactory @since 1.3


Class ControlFactory

This abstract class represents a factory for creating LDAPv3 controls. LDAPv3 controls are defined in RFC 2251.

When a service provider receives a response control it uses control factories to return the specific/appropriate control class implementation. @author Rosanna Lee @author Scott Seligman @author Vincent Ryan @version 1.8 01/0212/0903 @see Control @since 1.3


Class ExtendedRequest

This interface represents an LDAPv3 extended operation request as defined in RFC 2251.
 ExtendedRequest ::= [APPLICATION 23] SEQUENCE { requestName [0] LDAPOID requestValue [1] OCTET STRING OPTIONAL } 
It comprises an object identifier string and an optional ASN.1 BER encoded value.

The methods in this class are used by the service provider to construct the bits to send to the LDAP server. Applications typically only deal with the classes that implement this interface supplying them with any information required for a particular extended operation request. It would then pass such a class as an argument to the LdapContext.extendedOperation() method for performing the LDAPv3 extended operation.

For example suppose the LDAP server supported a 'get time' extended operation. It would supply GetTimeRequest and GetTimeResponse classes:

 public class GetTimeRequest implements ExtendedRequest { public GetTimeRequest() {... }; public ExtendedResponse createExtendedResponse(String id byte[] berValue int offset int length) throws NamingException { return new GetTimeResponse(id berValue offset length); } ... } public class GetTimeResponse implements ExtendedResponse { long time; public GetTimeResponse(String id byte[] berValue int offset int length) throws NamingException { time = ... // decode berValue to get time } public java.util.Date getDate() { return new java.util.Date(time) }; public long getTime() { return time }; ... } 
A program would use then these classes as follows:
 GetTimeResponse resp = (GetTimeResponse) ectx.extendedOperation(new GetTimeRequest()); long time = resp.getTime(); 
@author Rosanna Lee @author Scott Seligman @author Vincent Ryan @version 1.7 01/0212/0903 @see ExtendedResponse @see LdapContext#extendedOperation @since 1.3

Class ExtendedResponse

This interface represents an LDAP extended operation response as defined in RFC 2251.
 ExtendedResponse ::= [APPLICATION 24] SEQUENCE { COMPONENTS OF LDAPResult responseName [10] LDAPOID OPTIONAL response [11] OCTET STRING OPTIONAL } 
It comprises an optional object identifier and an optional ASN.1 BER encoded value.

The methods in this class can be used by the application to get low level information about the extended operation response. However typically the application will be using methods specific to the class that implements this interface. Such a class should have decoded the BER buffer in the response and should provide methods that allow the user to access that data in the response in a type-safe and friendly manner.

For example suppose the LDAP server supported a 'get time' extended operation. It would supply GetTimeRequest and GetTimeResponse classes. The GetTimeResponse class might look like:

 public class GetTimeResponse implements ExtendedResponse { public java.util.Date getDate() {...}; public long getTime() {...}; .... } 
A program would use then these classes as follows:
 GetTimeResponse resp = (GetTimeResponse) ectx.extendedOperation(new GetTimeRequest()); java.util.Date now = resp.getDate(); 
@author Rosanna Lee @author Scott Seligman @author Vincent Ryan @version 1.4 005 01/0212/0203 @see ExtendedRequest @since 1.3

Class HasControls

This interface is for returning controls with objects returned in NamingEnumerations. For example suppose a server sends back controls with the results of a search operation the service provider would return a NamingEnumeration of objects that are both SearchResult and implement HasControls.
 NamingEnumeration enum = ectx.search((Name)name filter sctls); while (enum.hasMore()) { Object entry = enum.next(); // Get search result SearchResult res = (SearchResult)entry; // do something with it // Get entry controls if (entry instanceof HasControls) { Control[] entryCtls = ((HasControls)entry).getControls(); // do something with controls } } 
@author Rosanna Lee @author Scott Seligman @author Vincent Ryan @version 1.4 005 01/0212/0203 @since 1.3

Class InitialLdapContext

This class is the starting context for performing LDAPv3-style extended operations and controls.

See javax.naming.InitialContext and javax.naming.InitialDirContext for details on synchronization and the policy for how an initial context is created.

Request Controls

When you create an initial context (InitialLdapContext) you can specify a list of request controls. These controls will be used as the request controls for any implicit LDAP "bind" operation performed by the context or contexts derived from the context. These are called connection request controls. Use getConnectControls() to get a context's connection request controls.

The request controls supplied to the initial context constructor are not used as the context request controls for subsequent context operations such as searches and lookups. Context request controls are set and updated by using setRequestControls().

As shown there can be two different sets of request controls associated with a context: connection request controls and context request controls. This is required for those applications needing to send critical controls that might not be applicable to both the context operation and any implicit LDAP "bind" operation. A typical user program would do the following:

 InitialLdapContext lctx = new InitialLdapContext(env critConnCtls); lctx.setRequestControls(critModCtls); lctx.modifyAttributes(name mods); Controls[] respCtls = lctx.getResponseControls(); 
It specifies first the critical controls for creating the initial context (critConnCtls) and then sets the context's request controls (critModCtls) for the context operation. If for some reason lctx needs to reconnect to the server it will use critConnCtls. See the LdapContext interface for more discussion about request controls.

Service provider implementors should read the "Service Provider" section in the LdapContext class description for implementation details. @author Rosanna Lee @author Scott Seligman @author Vincent Ryan @version 1.6 007 01/0212/0203 @see LdapContext @see javax.naming.InitialContext @see javax.naming.directory.InitialDirContext @see javax.naming.spi.NamingManager#setInitialContextFactoryBuilder @since 1.3


Class LdapContext

This interface represents a context in which you can perform operations with LDAPv3-style controls and perform LDAPv3-style extended operations. For applications that do not require such controls or extended operations the more generic javax.naming.directory.DirContext should be used instead.

Usage Details About Controls

This interface provides support for LDAP v3 controls. At a high level this support allows a user program to set request controls for LDAP operations that are executed in the course of the user program's invocation of Context/DirContext methods and read response controls resulting from LDAP operations. At the implementation level there are some details that developers of both the user program and service providers need to understand in order to correctly use request and response controls.

Request Controls

There are two types of request controls:

The former is used whenever a connection needs to be established or re-established with an LDAP server. The latter is used when all other LDAP operations are sent to the LDAP server. The reason why a distinction between these two types of request controls is necessary is because JNDI is a high-level API that does not deal directly with connections. It is the job of service providers to do any necessary connection management. Consequently a single connection may be shared by multiple context instances and a service provider is free to use its own algorithms to conserve connection and network usage. Thus when a method is invoked on the context instance the service provider might need to do some connection management in addition to performing the corresponding LDAP operations. For connection management it uses the connection request controls while for the normal LDAP operations it uses the context request controls.

Unless explicitly qualified the term "request controls" refers to context request controls.

Context Request Controls

There are two ways in which a context instance gets its request controls:
  1. ldapContext.newInstance(reqCtls)
  2. ldapContext.setRequestControls(reqCtls)
where ldapContext is an instance of LdapContext. Specifying null or an empty array for reqCtls means no request controls. newInstance() creates a new instance of a context using reqCtls while setRequestControls() updates an existing context instance's request controls to reqCtls.

Unlike environment properties request controls of a context instance are not inherited by context instances that are derived from it. Derived context instances have null as their context request controls. You must set the request controls of a derived context instance explicitly using setRequestControls().

A context instance's request controls are retrieved using the method getRequestControls().

Connection Request Controls

There are three ways in which connection request controls are set:
  1. new InitialLdapContext(env connCtls)
  2. refException.getReferralContext(env connCtls)
  3. ldapContext.reconnect(connCtls);
where refException is an instance of LdapReferralException and ldapContext is an instance of LdapContext. Specifying null or an empty array for connCtls means no connection request controls.

Like environment properties connection request controls of a context are inherited by contexts that are derived from it. Typically you initialize the connection request controls using the InitialLdapContext constructor or LdapReferralContext.getReferralContext(). These connection request controls are inherited by contexts that share the same connection--that is contexts derived from the initial or referral contexts.

Use reconnect() to change the connection request controls of a context. Invoking ldapContext.reconnect() affects only the connection used by ldapContext and any new contexts instances that are derived form ldapContext. Contexts that previously shared the connection with ldapContext remain unchanged. That is a context's connection request controls must be explicitly changed and is not affected by changes to another context's connection request controls.

A context instance's connection request controls are retrieved using the method getConnectControls().

Service Provider Requirements

A service provider supports connection and context request controls in the following ways. Context request controls must be associated on a per context instance basis while connection request controls must be associated on a per connection instance basis. The service provider must look for the connection request controls in the environment property "java.naming.ldap.control.connect" and pass this environment property on to context instances that it creates.

Response Controls

The method LdapContext.getResponseControls() is used to retrieve the response controls generated by LDAP operations executed as the result of invoking a Context/DirContext operation. The result is all of the responses controls generated by the underlying LDAP operations including any implicit reconnection. To get only the reconnection response controls use reconnect() followed by getResponseControls().

Parameters

A Control[] array passed as a parameter to any method is owned by the caller. The service provider will not modify the array or keep a reference to it although it may keep references to the individual Control objects in the array. A Control[] array returned by any method is immutable and may not subsequently be modified by either the caller or the service provider. @author Rosanna Lee @author Scott Seligman @author Vincent Ryan @version 1.8 01/0212/0903 @see InitialLdapContext @see LdapReferralException#getReferralContext(java.util.Hashtable javax.naming.ldap.Control[]) @since 1.3

Class LdapReferralException

This abstract class is used to represent an LDAP referral exception. It extends the base ReferralException by providing a getReferralContext() method that accepts request controls. LdapReferralException is an abstract class. Concrete implementations of it determine its synchronization and serialization properties.

A Control[] array passed as a parameter to the getReferralContext() method is owned by the caller. The service provider will not modify the array or keep a reference to it although it may keep references to the individual Control objects in the array. @author Rosanna Lee @author Scott Seligman @author Vincent Ryan @version 1.8 01/0212/0903 @since 1.3


Class UnsolicitedNotification

This interface represents an unsolicited notification as defined in RFC 2251. An unsolicited notification is sent by the LDAP server to the LDAP client without any provocation from the client. Its format is that of an extended response (ExtendedResponse). @author Rosanna Lee @author Scott Seligman @author Vincent Ryan @version 1.5 006 01/0212/0203 @see ExtendedResponse @see UnsolicitedNotificationEvent @see UnsolicitedNotificationListener @since 1.3

Class UnsolicitedNotificationEvent

This class represents an event fired in response to an unsolicited notification sent by the LDAP server. @author Rosanna Lee @author Scott Seligman @author Vincent Ryan @version 1.6 01/0212/0903 @see UnsolicitedNotification @see UnsolicitedNotificationListener @see javax.naming.event.EventContext#addNamingListener @see javax.naming.event.EventDirContext#addNamingListener @see javax.naming.event.EventContext#removeNamingListener @since 1.3

Class UnsolicitedNotificationListener

This interface is for handling UnsolicitedNotificationEvent. "Unsolicited notification" is defined in RFC 2251. It allows the server to send unsolicited notifications to the client. A UnsolicitedNotificationListener must:
  1. Implement this interface and its method
  2. Implement NamingListener.namingExceptionThrown() so that it will be notified of exceptions thrown while attempting to collect unsolicited notification events.
  3. Register with the context using one of the addNamingListener() methods from EventContext or EventDirContext. Only the NamingListener argument of these methods are applicable; the rest are ignored for a UnsolicitedNotificationListener. (These arguments might be applicable to the listener if it implements other listener interfaces).
@author Rosanna Lee @author Scott Seligman @author Vincent Ryan @version 1.4 005 01/0212/0203 @see UnsolicitedNotificationEvent @see UnsolicitedNotification @see javax.naming.event.EventContext#addNamingListener @see javax.naming.event.EventDirContext#addNamingListener @see javax.naming.event.EventContext#removeNamingListener @since 1.3