Extended Operations

In addition to the repertoire of predefined operations, such as "search" and "modify," the LDAP v3 protocol defines an extended operation. The extended operation takes a request as argument and returns a response. The request contains an identifier that identifies the request and the arguments of the request. The response contains the results of performing the request. The pair of extended operation request/response is called an extension. For example, there can be an extension for "Start TLS," which is a request for the client to the server to activate the TLS protocol. These extensions can be standard (defined by the LDAP community) or proprietary (defined by a particular directory vendor).
The javax.naming.ldap defines the interface ExtendedRequest to represent the argument to an extended operation, and the interface ExtendedResponse to represent the result of the extended operation. An extended response is always paired with an extended request but not necessarily vice versa. That is, you can have an extended request that has no corresponding extended response.
An application typically does not deal directly with these interfaces. Instead, it deals with classes that implement these interfaces. The application gets these classes either as part of a repertoire of extended operations standardized through the IETF, or from directory vendors for vendor-specific extended operations. The request classes should have constructors that accept arguments in a type-safe and user-friendly manner, while the response classes should have access methods for getting the data of the response in a type-safe and user-friendly manner. Internally, the request/response classes deal with encoding and decoding BER values.
Extensions Supported by LDAP Servers
Support for specific extensions is LDAP server-dependent. Eventually, when extensions are standardized, there might be a set of popular extensions supported by most LDAP servers. However, there still might be extensions that are proprietory and vendor-specific.
Here is a simple program for finding out the list of extensions that an LDAP server supports:
// Create initial context
DirContext ctx = new InitialDirContext();

// Read supportedextension from root DSE
Attributes attrs = ctx.getAttributes(
    "ldap://localhost:389", new String[]{"supportedextension"});
Here is the output produced by running this program against an LDAP server:
{supportedextension=supportedextension: 
  1.3.6.1.4.1.1466.20037
}
Implementations
As mentioned earlier, you typically would be dealing implementation classes that implement ExtendedRequest and ExtendedResponse rather than directly using their methods. Such implementation classes typically have type-friendly constructors and accessor methods.
For example, suppose an LDAP server supports a "get time" extended operation. It would supply classes such as GetTimeRequest and GetTimeResponse, so that applications can use this feature. An application would use these classes as follows:
// Invoke extended operation
GetTimeResponse resp =
    (GetTimeResponse) lctx.extendedOperation(new GetTimeRequest());

// Get extended operation's (decoded) response
long time = resp.getTime();
The GetTimeRequest and GetTimeResponse classes might be defined as follows:
public class GetTimeRequest implements ExtendedRequest {
    // User-friendly constructor 
    public GetTimeRequest() {
    };

    // Methods used by service providers
    public String getID() {
        return GETTIME_REQ_OID;
    }
    public byte[] getEncodedValue() {
        return null;  // no value needed for get time request
    }
    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;
    // called by GetTimeRequest.createExtendedResponse()
    GetTimeResponse(String id, byte[] berValue, int offset, int length) 
        throws NamingException {
        // check validity of id
        long time =  ... // decode berValue to get time
    }

    // Type-safe and User-friendly methods
    public java.util.Date getDate() { return new java.util.Date(time); }
    public long getTime() { return time; }

    // Low level methods
    public byte[] getEncodedValue() {
        return // berValue saved;
    }
    public String getID() {
        return GETTIME_RESP_OID;
    }
}
Controls and Extensions: End of Lesson
What's next? Now you can:

Continue on in this trail to read about questions that LDAP users have when using the JNDI.
Go to the Storing Objects in the Directory lesson to learn how to store Java objects in the directory.
Go to the Reading Objects from the Directory lesson to learn how to read Java objects from the directory.
Go to the Representation in the Directory lesson to read about the physical representation of Java objects in the LDAP directory.

Controls and Extensions