--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/jdk/src/share/classes/javax/naming/ldap/package.html Sat Dec 01 00:00:00 2007 +0000
@@ -0,0 +1,268 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
+<html>
+<head>
+<!--
+Copyright 1999-2006 Sun Microsystems, Inc. All Rights Reserved.
+DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+
+This code is free software; you can redistribute it and/or modify it
+under the terms of the GNU General Public License version 2 only, as
+published by the Free Software Foundation. Sun designates this
+particular file as subject to the "Classpath" exception as provided
+by Sun in the LICENSE file that accompanied this code.
+
+This code is distributed in the hope that it will be useful, but WITHOUT
+ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+version 2 for more details (a copy is included in the LICENSE file that
+accompanied this code).
+
+You should have received a copy of the GNU General Public License version
+2 along with this work; if not, write to the Free Software Foundation,
+Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+
+Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
+CA 95054 USA or visit www.sun.com if you need additional information or
+have any questions.
+
+-->
+</head>
+<body bgcolor="white">
+
+Provides support for LDAPv3 extended operations and controls.
+
+<p>
+This package extends the directory operations of the Java Naming and
+Directory Interface<font size=-2><sup>TM</sup></font> (JNDI).
+JNDI provides naming and directory functionality to applications
+written in the Java programming language. It is designed to be
+independent of any specific naming or directory service
+implementation. Thus a variety of services--new, emerging, and
+already deployed ones--can be accessed in a common way.
+
+<p>
+This package is for applications and service providers that deal with
+LDAPv3 extended operations and controls, as defined by
+<a href=http://www.ietf.org/rfc/rfc2251.txt>RFC 2251</a>.
+The core interface in this package is <tt>LdapContext</tt>, which defines
+methods on a context for performing extended operations and handling
+controls.
+
+<h4>Extended Operations</h4>
+<p>
+This package defines the interface <tt>ExtendedRequest</tt>
+to represent the argument to an extended operation,
+and the interface <tt>ExtendedResponse</tt> 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.
+<p>
+An application typically does not deal directly with these interfaces.
+Instead, it deals with classes that <em>implement</em> 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.
+<p>
+For example, suppose an LDAP server supports a "get time" extended operation.
+It would supply classes such as
+<tt>GetTimeRequest</tt> and <tt>GetTimeResponse</tt>,
+so that applications can use this feature.
+An application would use these classes as follows:
+<blockquote><pre>
+GetTimeResponse resp =
+ (GetTimeResponse) ectx.extendedOperation(new GetTimeRequest());
+long time = resp.getTime();
+</pre></blockquote>
+<p>
+The <tt>GetTimeRequest</tt> and <tt>GetTimeResponse</tt> classes might
+be defined as follows:
+<blockquote><pre>
+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()
+ public 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;
+ }
+}
+</pre></blockquote>
+
+<h4>Controls</h4>
+
+This package defines the interface <tt>Control</tt> to represent an LDAPv3
+control. It can be a control that is sent to an LDAP server
+(<em>request control</em>) or a control returned by an LDAP server
+(<em>response control</em>). Unlike extended requests and responses,
+there is not necessarily any pairing between request controls and
+response controls. You can send request controls and expect no
+response controls back, or receive response controls without sending
+any request controls.
+<p>
+An application typically does not deal directly with this interface.
+Instead, it deals with classes that <em>implement</em> this interface.
+The application gets control classes either as part of a repertoire of
+controls standardized through the IETF, or from directory vendors for
+vendor-specific controls. The request control classes should have
+constructors that accept arguments in a type-safe and user-friendly
+manner, while the response control classes should have access methods
+for getting the data of the response in a type-safe and user-friendly
+manner. Internally, the request/response control classes deal with
+encoding and decoding BER values.
+<p>
+For example, suppose an LDAP server supports a "signed results"
+request control, which when sent with a request, asks the
+server to digitally sign the results of an operation.
+It would supply a class <tt>SignedResultsControl</tt> so that applications
+can use this feature.
+An application would use this class as follows:
+<blockquote>
+<pre>
+Control[] reqCtls = new Control[] {new SignedResultsControl(Control.CRITICAL)};
+ectx.setRequestControls(reqCtls);
+NamingEnumeration enum = ectx.search(...);
+</pre>
+</blockquote>
+The <tt>SignedResultsControl</tt> class might be defined as follows:
+<blockquote><pre>
+public class SignedResultsControl implements Control {
+ // User-friendly constructor
+ public SignedResultsControl(boolean criticality) {
+ // assemble the components of the request control
+ };
+
+ // Methods used by service providers
+ public String getID() {
+ return // control's object identifier
+ }
+ public byte[] getEncodedValue() {
+ return // ASN.1 BER encoded control value
+ }
+ ...
+}
+</pre></blockquote>
+<p>
+When a service provider receives response controls, it uses
+the <tt>ControlFactory</tt> class to produce specific classes
+that implement the <tt>Control</tt> interface.
+<p>
+An LDAP server can send back response controls with an LDAP operation
+and also with enumeration results, such as those returned
+by a list or search operation.
+The <tt>LdapContext</tt> provides a method (<tt>getResponseControls()</tt>)
+for getting the response controls sent with an LDAP operation,
+while the <tt>HasControls</tt> interface is used to retrieve
+response controls associated with enumeration results.
+<p>
+For example, suppose an LDAP server sends back a "change ID" control in response
+to a successful modification. It would supply a class <tt>ChangeIDControl</tt>
+so that the application can use this feature.
+An application would perform an update, and then try to get the change ID.
+<blockquote><pre>
+// Perform update
+Context ctx = ectx.createSubsubcontext("cn=newobj");
+
+// Get response controls
+Control[] respCtls = ectx.getResponseControls();
+if (respCtls != null) {
+ // Find the one we want
+ for (int i = 0; i < respCtls; i++) {
+ if(respCtls[i] instanceof ChangeIDControl) {
+ ChangeIDControl cctl = (ChangeIDControl)respCtls[i];
+ System.out.println(cctl.getChangeID());
+ }
+ }
+}
+</pre></blockquote>
+The vendor might supply the following <tt>ChangeIDControl</tt> and
+<tt>VendorXControlFactory</tt> classes. The <tt>VendorXControlFactory</tt>
+will be used by the service provider when the provider receives response
+controls from the LDAP server.
+<blockquote><pre>
+public class ChangeIDControl implements Control {
+ long id;
+
+ // Constructor used by ControlFactory
+ public ChangeIDControl(String OID, byte[] berVal) throws NamingException {
+ // check validity of OID
+ id = // extract change ID from berVal
+ };
+
+ // Type-safe and User-friendly method
+ public long getChangeID() {
+ return id;
+ }
+
+ // Low-level methods
+ public String getID() {
+ return CHANGEID_OID;
+ }
+ public byte[] getEncodedValue() {
+ return // original berVal
+ }
+ ...
+}
+public class VendorXControlFactory extends ControlFactory {
+ public VendorXControlFactory () {
+ }
+
+ public Control getControlInstance(Control orig) throws NamingException {
+ if (isOneOfMyControls(orig.getID())) {
+ ...
+
+ // determine which of ours it is and call its constructor
+ return (new ChangeIDControl(orig.getID(), orig.getEncodedValue()));
+ }
+ return null; // not one of ours
+ }
+}
+</pre></blockquote>
+
+<p>
+
+<h2>Package Specification</h2>
+
+The JNDI API Specification and related documents can be found in the
+<a href="../../../../technotes/guides/jndi/index.html">JNDI documentation</a>.
+
+@since 1.3
+
+</body>
+</html>