157 lines
7.3 KiB
Plaintext
157 lines
7.3 KiB
Plaintext
<!--
|
|
|
|
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>
|