Previous | Next | Trail Map | Tips for LDAP Users | Controls and Extensions

Request Controls

A request control is sent by a client to modify or augment an LDAP operation. You can use a control either to send more information to the server than is allowed by the operation's request or to modify the behavior of the operation altogether.

Request controls come in two types:

The former is used when 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.

These two types of request controls must be differentiated because the JNDI is a high-level API that does not deal directly with connections. It is the job of the service provider to do any necessary connection management. Consequently, a single connection may be shared by multiple Context instances, and a service provider may use its own algorithms so as 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, and for the normal LDAP operations, it uses the context request controls.

Unless explicitly qualified, the term request controls is meant here to mean context request controls.

Controls Supported by LDAP Servers

Support for specific controls is LDAP server-dependent. Eventually, when controls are standardized, LDAP servers might support a set of popular controls. However, some controls still might be proprietary and vendor-specific.

Here is a simple program for finding out the list of controls that an LDAP server supports.

// Create the initial context
DirContext ctx = new InitialDirContext();

// Read the supportedcontrol from the root DSE
Attributes attrs = ctx.getAttributes(
    "ldap://localhost:389", new String[]{"supportedcontrol"});
Here is the output produced by running this program against an LDAP server.
{supportedcontrol=supportedcontrol: 
  2.16.840.1.113730.3.4.2, 
  2.16.840.1.113730.3.4.3, 
  2.16.840.1.113730.3.4.4, 
  2.16.840.1.113730.3.4.5, 
  1.2.840.113556.1.4.473, 
  2.16.840.1.113730.3.4.9, 
  2.16.840.1.113730.3.4.12
}

Implementations

The Control(in the API reference documentation) interface is generic for all request and response controls. Typically, you will deal with implementation classes that implement this interface rather than directly use the methods in this interface. Such implementation classes typically have type-friendly constructors and accessor methods. For example, Sun provides classes that implement some popular controls, such as the Paged Results control. This allows you to retrieve the results of an LDAP "search" operation in pages. To create a Paged Results control, you use its constructor, PagedResultsControl, as follows.
// Specify a page size of 20
Control prctl = new PagedResultsControl(20);
The next few pages offer other examples of how to construct and use controls.


Previous | Next | Trail Map | Tips for LDAP Users | Controls and Extensions