Mozilla LDAP SDK Programmer's Guide/Extended Operations With LDAP Java SDK

This section explains LDAP v3 extended operations. This section also explains how to use the extended operations that are supported by your LDAP server.

How Extended Operations Work With LDAP Java SDK

Extended operations are part of LDAP v3. Each extended operation is identified by an object identifier (OID).

LDAP clients can request the operation by sending an extended operation request. Within the request, the client specifies the following:

• The OID of the extended operation to perform
• Data specific to the extended operation

The server receives the request. The server then performs the extended operation. The server can send back to the client a response containing:

• An OID
• Any additional data

To use extended operations, both the server and the client must know the specific extended operation to be performed.

• You must write a client that can send requests for a specific extended operation. The client must also be able to receive extended responses from the server.
• Your LDAP server needs to be able to handle requests for specific extended operations. The server also must be able to send responses back to the client.

Implementing Support for Extended Operations on the Server With LDAP Java SDK

Directory Server supports a plug-in API that allows you to write your own server plug-in to handle extended operations. You can write an extended operation that does the following:

• Registers the OID of an extended operation as supported, so the OID appears as a value of the supportedExtension attribute on the root DSE
• Gets information from an extended operation request
• Creates and sends an extended operation response back to the client

Determining the Extended Operations Supported With LDAP Java SDK

To determine the extended operations supported by the server, get the root DSE of the server, and check the supportedExtension attribute. The values of this attribute are the OIDs of the extended operations supported by this server.

If the root DSE does not have a supportedExtension attribute, the server does not support any extended operations. For instructions on reading the root DSE, refer to Getting the Root DSE With LDAP Java SDK.

Performing an Extended Operation With LDAP Java SDK

To request an extended operation, do the following:

1. Construct a new LDAPExtendedOperation object, specifying the OID of the extended operation and the data that you want applied to the operation.
2. Invoke the extendedOperation method of the LDAPConnection object, passing the method of the newly constructed LDAPExtendedOperation object.

The LDAPExtendedOperation object that is returned represents the server response. You can invoke the getID and getValue methods of this object to get the OID and the data from the server's response.

Example Extended Operation With LDAP Java SDK

The following example shows an LDAP client that requests an extended operation with the OID 1.2.3.4 from the server.

import netscape.ldap.*;
import java.util.*;
import java.io.*;
 
public class ExtOpt {
    private static String OID = "1.2.3.4";
    public static void main(String[] args) {
        try {
            UserArgs userArgs = new UserArgs("ExtOpt", args, true);
            LDAPConnection ld = new LDAPConnection();
            ld.connect(userArgs.getHost(), userArgs.getPort());
            ld.authenticate(3, userArgs.getBindDN(),userArgs.getPassword());
            System.out.println("Authenticated to directory.");
 
            /* Create an extended operation object */
            String myval = "My Value";
            byte vals[] = myval.getBytes("UTF8");
            LDAPExtendedOperation exop =
                new LDAPExtendedOperation(OID, vals);
 
            /* Request the extended operation from the server. */
            LDAPExtendedOperation exres = ld.extendedOperation(exop);
            System.out.println("Performed extended operation.");
 
            /* Get data from the response sent by the server. */
            System.out.println("OID returned: " + exres.getID());
            String retValue = new String(exres.getValue(),"UTF8");
            System.out.println("Value returned: " + retValue);
 
            ld.disconnect();
        }
        catch(LDAPException e) {
            System.out.println("Error: " + e.toString());
        }
        catch(UnsupportedEncodingException e) {
            System.out.println("Error: UTF8 not supported");
        }
    }
}