naming/ldap/package.html

0N/A<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
0N/A<html>
0N/A<head>
0N/A<!--
2362N/ACopyright (c) 1999, 2006, Oracle and/or its affiliates. All rights reserved.
0N/ADO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
0N/A
0N/AThis code is free software; you can redistribute it and/or modify it
0N/Aunder the terms of the GNU General Public License version 2 only, as
2362N/Apublished by the Free Software Foundation.  Oracle designates this
0N/Aparticular file as subject to the "Classpath" exception as provided
2362N/Aby Oracle in the LICENSE file that accompanied this code.
0N/A
0N/AThis code is distributed in the hope that it will be useful, but WITHOUT
0N/AANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
0N/AFITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
0N/Aversion 2 for more details (a copy is included in the LICENSE file that
0N/Aaccompanied this code).
0N/A
0N/AYou should have received a copy of the GNU General Public License version
0N/A2 along with this work; if not, write to the Free Software Foundation,
0N/AInc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
0N/A
2365N/APlease contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
2365N/Aor visit www.oracle.com if you need additional information or have any
2365N/Aquestions.
0N/A
0N/A-->
0N/A</head>
0N/A<body bgcolor="white">
0N/A
0N/AProvides support for LDAPv3 extended operations and controls.
0N/A
0N/A<p>
0N/AThis package extends the directory operations of the Java Naming and
0N/ADirectory Interface<font size=-2><sup>TM</sup></font> (JNDI). &nbsp;
0N/AJNDI provides naming and directory functionality to applications
0N/Awritten in the Java programming language.  It is designed to be
0N/Aindependent of any specific naming or directory service
0N/Aimplementation.  Thus a variety of services--new, emerging, and
0N/Aalready deployed ones--can be accessed in a common way.
0N/A
0N/A<p>
0N/AThis package is for applications and service providers that deal with
0N/ALDAPv3 extended operations and controls, as defined by
0N/A<a href=http://www.ietf.org/rfc/rfc2251.txt>RFC 2251</a>.
0N/AThe core interface in this package is <tt>LdapContext</tt>, which defines
0N/Amethods on a context for performing extended operations and handling
0N/Acontrols.
0N/A
0N/A<h4>Extended Operations</h4>
0N/A<p>
0N/AThis package defines the interface <tt>ExtendedRequest</tt>
0N/Ato represent the argument to an extended operation,
0N/Aand the interface <tt>ExtendedResponse</tt> to represent the result
0N/Aof the extended operation.
0N/AAn extended response is always paired with an extended request
0N/Abut not necessarily vice versa. That is, you can have an extended request
0N/Athat has no corresponding extended response.
0N/A<p>
0N/AAn application typically does not deal directly with these interfaces.
0N/AInstead, it deals with classes that <em>implement</em> these
0N/Ainterfaces.
0N/AThe application gets these classes either as part of a
0N/Arepertoire of extended operations standardized through the IETF, or
0N/Afrom directory vendors for vendor-specific extended operations.
0N/AThe request classes should have constructors that accept
0N/Aarguments in a type-safe and user-friendly manner, while the
0N/Aresponse classes should have access methods for getting the data
0N/Aof the response in a type-safe and user-friendly manner.
0N/AInternally, the request/response classes deal with encoding and decoding
0N/ABER values.
0N/A<p>
0N/AFor example, suppose an LDAP server supports a "get time" extended operation.
0N/AIt would supply classes such as
0N/A<tt>GetTimeRequest</tt> and <tt>GetTimeResponse</tt>,
0N/Aso that applications can use this feature.
0N/AAn application would use these classes as follows:
0N/A<blockquote><pre>
0N/AGetTimeResponse resp =
0N/A    (GetTimeResponse) ectx.extendedOperation(new GetTimeRequest());
0N/Along time = resp.getTime();
0N/A</pre></blockquote>
0N/A<p>
0N/AThe <tt>GetTimeRequest</tt> and <tt>GetTimeResponse</tt> classes might
0N/Abe defined as follows:
0N/A<blockquote><pre>
0N/Apublic class GetTimeRequest implements ExtendedRequest {
0N/A    // User-friendly constructor
0N/A    public GetTimeRequest() {
0N/A    };
0N/A
0N/A    // Methods used by service providers
0N/A    public String getID() {
0N/A        return GETTIME_REQ_OID;
0N/A    }
0N/A    public byte[] getEncodedValue() {
0N/A        return null;  // no value needed for get time request
0N/A    }
0N/A    public ExtendedResponse createExtendedResponse(
0N/A        String id, byte[] berValue, int offset, int length) throws NamingException {
0N/A        return new GetTimeResponse(id, berValue, offset, length);
0N/A    }
0N/A}
0N/Apublic class GetTimeResponse() implements ExtendedResponse {
0N/A    long time;
0N/A    // called by GetTimeRequest.createExtendedResponse()
0N/A    public GetTimeResponse(String id, byte[] berValue, int offset, int length)
0N/A        throws NamingException {
0N/A        // check validity of id
0N/A        long time =  ... // decode berValue to get time
0N/A    }
0N/A
0N/A    // Type-safe and User-friendly methods
0N/A    public java.util.Date getDate() { return new java.util.Date(time); }
0N/A    public long getTime() { return time; }
0N/A
0N/A    // Low level methods
0N/A    public byte[] getEncodedValue() {
0N/A        return // berValue saved;
0N/A    }
0N/A    public String getID() {
0N/A        return GETTIME_RESP_OID;
0N/A    }
0N/A}
0N/A</pre></blockquote>
0N/A
0N/A<h4>Controls</h4>
0N/A
0N/AThis package defines the interface <tt>Control</tt> to represent an LDAPv3
0N/Acontrol. It can be a control that is sent to an LDAP server
0N/A(<em>request control</em>) or a control returned by an LDAP server
0N/A(<em>response control</em>).  Unlike extended requests and responses,
0N/Athere is not necessarily any pairing between request controls and
0N/Aresponse controls.  You can send request controls and expect no
0N/Aresponse controls back, or receive response controls without sending
0N/Aany request controls.
0N/A<p>
0N/AAn application typically does not deal directly with this interface.
0N/AInstead, it deals with classes that <em>implement</em> this interface.
0N/AThe application gets control classes either as part of a repertoire of
0N/Acontrols standardized through the IETF, or from directory vendors for
0N/Avendor-specific controls.  The request control classes should have
0N/Aconstructors that accept arguments in a type-safe and user-friendly
0N/Amanner, while the response control classes should have access methods
0N/Afor getting the data of the response in a type-safe and user-friendly
0N/Amanner.  Internally, the request/response control classes deal with
0N/Aencoding and decoding BER values.
0N/A<p>
0N/AFor example, suppose an LDAP server supports a "signed results"
0N/Arequest control, which when sent with a request, asks the
0N/Aserver to digitally sign the results of an operation.
0N/AIt would supply a class <tt>SignedResultsControl</tt>  so that applications
0N/Acan use this feature.
0N/AAn application  would use this class as follows:
0N/A<blockquote>
0N/A<pre>
0N/AControl[] reqCtls = new Control[] {new SignedResultsControl(Control.CRITICAL)};
0N/Aectx.setRequestControls(reqCtls);
0N/ANamingEnumeration enum = ectx.search(...);
0N/A</pre>
0N/A</blockquote>
0N/AThe <tt>SignedResultsControl</tt> class might be defined as follows:
0N/A<blockquote><pre>
0N/Apublic class SignedResultsControl implements Control {
0N/A    // User-friendly constructor
0N/A    public SignedResultsControl(boolean criticality) {
0N/A    // assemble the components of the request control
0N/A    };
0N/A
0N/A    // Methods used by service providers
0N/A    public String getID() {
0N/A        return // control's object identifier
0N/A    }
0N/A    public byte[] getEncodedValue() {
0N/A        return // ASN.1 BER encoded control value
0N/A    }
0N/A    ...
0N/A}
0N/A</pre></blockquote>
0N/A<p>
0N/AWhen a service provider receives response controls, it uses
0N/Athe <tt>ControlFactory</tt> class to produce specific classes
0N/Athat implement the <tt>Control</tt> interface.
0N/A<p>
0N/AAn LDAP server can send back response controls with an LDAP operation
0N/Aand also with enumeration results, such as those returned
0N/Aby a list or search operation.
0N/AThe <tt>LdapContext</tt> provides a method (<tt>getResponseControls()</tt>)
0N/Afor getting the response controls sent with an LDAP operation,
0N/Awhile the <tt>HasControls</tt> interface is used to retrieve
0N/Aresponse controls associated with enumeration results.
0N/A<p>
0N/AFor example, suppose an LDAP server sends back a "change ID" control in response
0N/Ato a successful modification. It would supply a class <tt>ChangeIDControl</tt>
0N/Aso that the application can use this feature.
0N/AAn application would perform an update, and then try to get the change ID.
0N/A<blockquote><pre>
0N/A// Perform update
0N/AContext ctx = ectx.createSubsubcontext("cn=newobj");
0N/A
0N/A// Get response controls
0N/AControl[] respCtls = ectx.getResponseControls();
0N/Aif (respCtls != null) {
0N/A    // Find the one we want
0N/A    for (int i = 0; i < respCtls; i++) {
0N/A        if(respCtls[i] instanceof ChangeIDControl) {
0N/A        ChangeIDControl cctl = (ChangeIDControl)respCtls[i];
0N/A        System.out.println(cctl.getChangeID());
0N/A        }
0N/A    }
0N/A}
0N/A</pre></blockquote>
0N/AThe vendor might supply the following <tt>ChangeIDControl</tt> and
0N/A<tt>VendorXControlFactory</tt> classes. The <tt>VendorXControlFactory</tt>
0N/Awill be used by the service provider when the provider receives response
0N/Acontrols from the LDAP server.
0N/A<blockquote><pre>
0N/Apublic class ChangeIDControl implements Control {
0N/A    long id;
0N/A
0N/A    // Constructor used by ControlFactory
0N/A    public ChangeIDControl(String OID, byte[] berVal) throws NamingException {
0N/A        // check validity of OID
0N/A        id = // extract change ID from berVal
0N/A    };
0N/A
0N/A    // Type-safe and User-friendly method
0N/A    public long getChangeID() {
0N/A        return id;
0N/A    }
0N/A
0N/A    // Low-level methods
0N/A    public String getID() {
0N/A        return CHANGEID_OID;
0N/A    }
0N/A    public byte[] getEncodedValue() {
0N/A        return // original berVal
0N/A    }
0N/A    ...
0N/A}
0N/Apublic class VendorXControlFactory extends ControlFactory {
0N/A    public VendorXControlFactory () {
0N/A    }
0N/A
0N/A    public Control getControlInstance(Control orig) throws NamingException {
0N/A        if (isOneOfMyControls(orig.getID())) {
0N/A        ...
0N/A
0N/A        // determine which of ours it is and call its constructor
0N/A        return (new ChangeIDControl(orig.getID(), orig.getEncodedValue()));
0N/A    }
0N/A        return null;  // not one of ours
0N/A    }
0N/A}
0N/A</pre></blockquote>
0N/A
0N/A<p>
0N/A
0N/A<h2>Package Specification</h2>
0N/A
0N/AThe JNDI API Specification and related documents can be found in the
0N/A<a href="/technotes/guides/jndi/index.html">JNDI documentation</a>.
0N/A
0N/A@since 1.3
0N/A
0N/A</body>
0N/A</html>