<!--

Copyright 2000-2007 Sun Microsystems, Inc. All Rights Reserved.
Portions copyright 1999 Netscape Communications Corporation. All
Rights Reserved.

The contents of this document are subject to the terms of the
Creative Commons Attribution-ShareAlike 2.5 license or any later
version (the "License"). You may not use this document except in
compliance with the License.

See the License for the specific language governing
permissions and limitations under the License. You can obtain
a copy of the License at
http://creativecommons.org/licenses/by-sa/2.5/legalcode.

-->
<chapter id="extended-ops"><title>Extended Operations With &DirectorySDKForJava;</title>
<highlights>
<para>This chapter explains LDAP v3 extended operations. This chapter also
explains how to use the extended operations that are supported by your LDAP
server.</para>
<itemizedlist>
<para>This chapter covers the following topics:</para>
<listitem><para><olink targetptr="extops-overview">How Extended Operations
Work With Directory SDK for Java</olink></para></listitem>
<listitem><para><olink targetptr="extops-server-side">Implementing Support
for Extended Operations on the Server With Directory SDK for Java</olink></para>
</listitem>
<listitem><para><olink targetptr="extopts-view-supported">Determining the
Extended Operations Supported With Directory SDK for Java</olink></para>
</listitem>
<listitem><para><olink targetptr="extopts-client-side">Performing an Extended
Operation With Directory SDK for Java</olink></para></listitem>
<listitem><para><olink targetptr="extopts-example">Example Extended Operation
With Directory SDK for Java</olink></para></listitem>
</itemizedlist>
</highlights>
<sect1 id="extops-overview"><title>How Extended Operations Work With &DirectorySDKForJava;</title>
<para>Extended operations are part of LDAP v3. Each extended operation is
identified by an object identifier (OID).</para>
<itemizedlist>
<para>LDAP clients can request the operation by sending an extended operation
request. Within the request, the client specifies the following:</para>
<listitem><para>The OID of the extended operation to perform</para></listitem>
<listitem><para>Data specific to the extended operation</para></listitem>
</itemizedlist>
<itemizedlist>
<para>The server receives the request. The server then performs the extended
operation. The server can send back to the client a response containing:</para>
<listitem><para>An OID</para></listitem>
<listitem><para>Any additional data</para></listitem>
</itemizedlist>
<itemizedlist>
<para>To use extended operations, both the server and the client must know
the specific extended operation to be performed.</para>
<listitem><para>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.</para></listitem>
<listitem><para>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.</para></listitem>
</itemizedlist>
</sect1>
<sect1 id="extops-server-side"><title>Implementing Support for Extended Operations
on the Server With Directory SDK for Java</title>
<indexterm>
<primary>LDAP servers</primary>
<secondary>extended operations and</secondary>
</indexterm>
<para>&cnDirectoryServer; supports a plug-in API that allows you to write
your own server plug-in to handle extended operations.</para>
<itemizedlist>
<para>You can write an extended operation that does the following:</para>
<listitem><para>Registers the OID of an extended operation as supported, so
the OID appears as a value of the <literal>supportedExtension</literal> attribute
on the root DSE</para></listitem>
<listitem><para>Gets information from an extended operation request</para>
</listitem>
<listitem><para>Creates and sends an extended operation response back to the
client</para></listitem>
</itemizedlist>
</sect1>
<sect1 id="extopts-view-supported"><title>Determining the Extended Operations
Supported With &DirectorySDKForJava;</title>
<para>To determine the extended operations supported by the server, get the
root DSE of the server, and check the <literal>supportedExtension</literal> attribute.
The values of this attribute are the OIDs of the extended operations supported
by this server.</para>
<para>If the root DSE does not have a <literal>supportedExtension</literal> attribute,
the server does not support any extended operations. For instructions on reading
the root DSE, refer to <olink type="auto-generated" targetptr="server-info-dse-info">Getting the Root DSE With Directory SDK for
Java</olink>.</para></sect1>
<sect1 id="extopts-client-side"><title>Performing an Extended Operation With &DirectorySDKForJava;</title>
<indexterm>
<primary>LDAP clients</primary>
<secondary>extended operations and</secondary>
</indexterm>
<orderedlist>
<para>To request an extended operation, do the following:</para>
<listitem><para>Construct a new <classname>LDAPExtendedOperation</classname> object,
specifying the OID of the extended operation and the data that you want applied
to the operation.</para></listitem>
<listitem><para>Invoke the <literal>extendedOperation</literal> method of
the <classname>LDAPConnection</classname> object, passing the method of the
newly constructed <classname>LDAPExtendedOperation</classname> object.</para>
</listitem>
</orderedlist>
<para>The <classname>LDAPExtendedOperation</classname> object that is returned
represents the server response. You can invoke the <literal>getID</literal> and <literal>
getValue</literal> methods of this object to get the OID and the data from
the server's response.</para></sect1>
<sect1 id="extopts-example"><title>Example Extended Operation With &DirectorySDKForJava;</title>
<para>The following example shows an LDAP client that requests an extended
operation with the OID <literal>1.2.3.4</literal> from the server.</para>
<programlisting>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");
        }
    }
}</programlisting>
</sect1>
</chapter>
