0N/A<!
DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
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/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/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/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. 2365N/APlease contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 0N/A<
body bgcolor="white">
0N/AProvides support for LDAPv3 extended operations and controls.
0N/AThis package extends the directory operations of the Java Naming and
0N/ADirectory Interface<
font size=-
2><
sup>TM</
sup></
font> (JNDI).
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/AThis package is for applications and service providers that deal with
0N/ALDAPv3 extended operations and controls, as defined by
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/A<
h4>Extended Operations</
h4>
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/AAn application typically does not deal directly with these interfaces.
0N/AInstead, it deals with classes that <
em>implement</
em> these
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/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/AGetTimeResponse resp =
0N/AThe <
tt>GetTimeRequest</
tt> and <
tt>GetTimeResponse</
tt> classes might
0N/Abe defined as follows:
0N/Apublic class GetTimeRequest implements ExtendedRequest {
0N/A // User-friendly constructor
0N/A public GetTimeRequest() {
0N/A // Methods used by service providers
0N/A public String getID() {
0N/A return GETTIME_REQ_OID;
0N/A public byte[] getEncodedValue() {
0N/A return null; // no value needed for get time request
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/Apublic class GetTimeResponse() implements ExtendedResponse {
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 // Type-safe and User-friendly methods
0N/A public long getTime() { return time; }
0N/A // Low level methods
0N/A public byte[] getEncodedValue() {
0N/A return // berValue saved;
0N/A public String getID() {
0N/A return GETTIME_RESP_OID;
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/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/Aencoding and decoding BER values.
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/AThe <
tt>SignedResultsControl</
tt> class might be defined as follows:
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 // Methods used by service providers
0N/A public String getID() {
0N/A return // control's object identifier
0N/A public byte[] getEncodedValue() {
0N/A return // ASN.1 BER encoded control value
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/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/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// Get response controls
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/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/Apublic class ChangeIDControl implements Control {
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 // Type-safe and User-friendly method
0N/A public long getChangeID() {
0N/A // Low-level methods
0N/A public String getID() {
0N/A return CHANGEID_OID;
0N/A public byte[] getEncodedValue() {
0N/A return // original berVal
0N/Apublic class VendorXControlFactory extends ControlFactory {
0N/A public VendorXControlFactory () {
0N/A public Control getControlInstance(Control orig) throws NamingException {
0N/A // determine which of ours it is and call its constructor
0N/A return null; // not one of ours
0N/A<
h2>Package Specification</
h2>
0N/AThe JNDI API Specification and related documents can be found in the