ojluni/src/main/java/javax/naming/ldap/package.html - platform/libcore.git - Git at Google

 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
 <html>
 <head>
 <!--
 Copyright (c) 1999, 2006, Oracle and/or its affiliates. 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.  Oracle designates this
 particular file as subject to the "Classpath" exception as provided
 by Oracle 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 Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 or visit www.oracle.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). &nbsp;
 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>
	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
	<html>
	<head>
	<!--
	Copyright (c) 1999, 2006, Oracle and/or its affiliates. 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. Oracle designates this
	particular file as subject to the "Classpath" exception as provided
	by Oracle 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 Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
	or visit www.oracle.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>