+ * This package defines the directory operations of the Java Naming and + * Directory Interface (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. + * + *
+ * This package allows applications to retrieve and update attributes + * associated with objects stored in a directory, and to search for + * objects using specified attributes. + * + *
+ * You use {@code getAttributes()} to retrieve the attributes + * associated with a directory object (for which you supply the name). + * Attributes are modified using {@code modifyAttributes()}. + * You can add, replace, or remove attributes and/or attribute values + * using this operation. + *
+ * {@code DirContext} also behaves as a naming context + * by extending the {@code Context} interface in the {@code javax.naming} package. + * This means that any directory object can also provide + * a naming context. + * For example, the directory object for a person might contain + * the attributes of that person, and at the same time provide + * a context for naming objects relative to that person + * such as his printers and home directory. + * + *
javax.naming package to provide functionality
-for accessing directory services.
-
--This package defines the directory operations of the Java Naming and -Directory Interface (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. - -
-This package allows applications to retrieve and update attributes -associated with objects stored in a directory, and to search for -objects using specified attributes. - -
DirContext
-interface represents a directory context.
-It defines methods for examining and updating attributes associated with a
-directory object, or directory entry as it is sometimes
-called.
-
-You use getAttributes() to retrieve the attributes
-associated with a directory object (for which you supply the name).
-Attributes are modified using modifyAttributes().
-You can add, replace, or remove attributes and/or attribute values
-using this operation.
-
-DirContext also behaves as a naming context
-by extending the Context interface in the javax.naming package.
-This means that any directory object can also provide
-a naming context.
-For example, the directory object for a person might contain
-the attributes of that person, and at the same time provide
-a context for naming objects relative to that person
-such as his printers and home directory.
-
-
DirContext contains methods for
-performing content-based searching of the directory.
-In the simplest and most common form of usage, the application
-specifies a set of attributes--possibly with specific
-values--to match, and submits this attribute set, to the
-search() method.
-There are other overloaded forms of search()
-that support more sophisticated search filters.
-
-
-+ * This package defines the event notification operations of the Java Naming + * and Directory Interface (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. + * + *
+ * This package defines a {@code NamingEvent} class to represent an event + * that is generated by a naming/directory service. + * It also defines subinterfaces of {@code Context} and {@code DirContext}, + * called {@code EventContext} and {@code EventDirContext}, + * through which applications can register their interest in events + * fired by the context. + *
+ * {@code NamingEvent} represents an event that occurs in a + * naming or directory service. There are two categories of naming events: + *
+ * An application, for example, can register its interest in changes to + * objects in a context as follows: + * {@snippet : + * EventContext src = + * (EventContext)(new InitialContext()).lookup("o=wiz,c=us"); + * src.addNamingListener("ou=users", EventContext.ONELEVEL_SCOPE, + * new ChangeHandler()); + * ... + * class ChangeHandler implements ObjectChangeListener { + * public void objectChanged(NamingEvent evt) { + * System.out.println(evt.getNewBinding()); + * } + * public void namingExceptionThrown(NamingExceptionEvent evt) { + * System.out.println(evt.getException()); + * } + * } + * } + * + * + *
+ * When a listener instance invokes {@code NamingEvent.getEventContext()}, + * it must take into account the possibility that other threads will be + * working with that context concurrently. Likewise, when a listener is + * registered via {@code addNamingListener()}, the registering thread + * must take into account the likely possibility that the service provider + * will later invoke the listeners in newly-created threads. As {@code Context} + * instances are not guaranteed to be thread-safe in general, all context + * operations must be synchronized as needed. + * + *
-This package defines the event notification operations of the Java Naming -and Directory Interface (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. - -
-This package defines a NamingEvent class to represent an event
-that is generated by a naming/directory service.
-It also defines subinterfaces of Context and DirContext,
-called EventContext and EventDirContext,
-through which applications can register their interest in events
-fired by the context.
-
-NamingEvent represents an event that occurs in a
-naming or directory service. There are two categories of naming events:
-
NamespaceChangeListener, ObjectChangeListener.
--An application, for example, can register its interest in changes to -objects in a context as follows: -
-
-EventContext src =
- (EventContext)(new InitialContext()).lookup("o=wiz,c=us");
-src.addNamingListener("ou=users", EventContext.ONELEVEL_SCOPE,
- new ChangeHandler());
-...
-class ChangeHandler implements ObjectChangeListener {
- public void objectChanged(NamingEvent evt) {
- System.out.println(evt.getNewBinding());
- }
- public void namingExceptionThrown(NamingExceptionEvent evt) {
- System.out.println(evt.getException());
- }
-}
-
-
-
-
-objectChanged()) may be executed in a thread other than the
-one in which the call to addNamingListener() was executed.
-The choice of which thread to use is made by the service provider.
-When an event is dispatched to multiple listeners, the service provider
-may choose (and is generally encouraged) to execute the listener methods
-concurrently in separate threads.
-
-When a listener instance invokes NamingEvent.getEventContext(),
-it must take into account the possibility that other threads will be
-working with that context concurrently. Likewise, when a listener is
-registered via addNamingListener(), the registering thread
-must take into account the likely possibility that the service provider
-will later invoke the listeners in newly-created threads. As Context
-instances are not guaranteed to be thread-safe in general, all context
-operations must be synchronized as needed.
-
-
NamingExceptionEvent is
-fired to notify the listener. The listener's
-namingExceptionThrown() method is invoked, as shown in the
-sample code above,
-and the listener is automatically deregistered.
-
-+ * This package extends the directory operations of the Java Naming and + * Directory Interface (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. + * + *
+ * This package is for applications and service providers that deal with + * LDAPv3 extended operations and controls, as defined by + * RFC 2251. + * The core interface in this package is {@code LdapContext}, which defines + * methods on a context for performing extended operations and handling + * controls. + * + *
+ * This package defines the interface {@code ExtendedRequest} + * to represent the argument to an extended operation, + * and the interface {@code ExtendedResponse} 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. + *
+ * An application typically does not deal directly with these interfaces. + * Instead, it deals with classes that implement 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. + *
+ * For example, suppose an LDAP server supports a "get time" extended operation. + * It would supply classes such as + * {@code GetTimeRequest} and {@code GetTimeResponse}, + * so that applications can use this feature. + * An application would use these classes as follows: + * {@snippet : + * GetTimeResponse resp = + * (GetTimeResponse) ectx.extendedOperation(new GetTimeRequest()); + * long time = resp.getTime(); + * } + *
+ * The {@code GetTimeRequest} and {@code GetTimeResponse} classes might + * be defined as follows: + * {@snippet : + * 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; + * } + * } + * } + * + *
+ * An application typically does not deal directly with this interface. + * Instead, it deals with classes that implement 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. + *
+ * 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 {@code SignedResultsControl} so that applications + * can use this feature. + * An application would use this class as follows: + * {@snippet : + * Control[] reqCtls = new Control[] {new SignedResultsControl(Control.CRITICAL)}; + * ectx.setRequestControls(reqCtls); + * NamingEnumeration enum = ectx.search(...); + * } + * The {@code SignedResultsControl} class might be defined as follows: + * {@snippet : + * 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 + * } + * ... + * } + * } + *
+ * When a service provider receives response controls, it uses + * the {@code ControlFactory} class to produce specific classes + * that implement the {@code Control} interface. + *
+ * 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 {@code LdapContext} provides a method ({@code getResponseControls()}) + * for getting the response controls sent with an LDAP operation, + * while the {@code HasControls} interface is used to retrieve + * response controls associated with enumeration results. + *
+ * For example, suppose an LDAP server sends back a "change ID" control in response + * to a successful modification. It would supply a class {@code ChangeIDControl} + * so that the application can use this feature. + * An application would perform an update, and then try to get the change ID. + * {@snippet : + * // 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.length; i++) { + * if(respCtls[i] instanceof ChangeIDControl) { + * ChangeIDControl cctl = (ChangeIDControl)respCtls[i]; + * System.out.println(cctl.getChangeID()); + * } + * } + * } + * } + * The vendor might supply the following {@code ChangeIDControl} and + * {@code VendorXControlFactory} classes. The {@code VendorXControlFactory} + * will be used by the service provider when the provider receives response + * controls from the LDAP server. + * {@snippet : + * 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 + * } + * } + * } + * + *
-This package extends the directory operations of the Java Naming and -Directory Interface (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. - -
-This package is for applications and service providers that deal with
-LDAPv3 extended operations and controls, as defined by
-RFC 2251.
-The core interface in this package is LdapContext, which defines
-methods on a context for performing extended operations and handling
-controls.
-
-
-This package defines the interface ExtendedRequest
-to represent the argument to an extended operation,
-and the interface ExtendedResponse 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.
-
-An application typically does not deal directly with these interfaces. -Instead, it deals with classes that implement 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. -
-For example, suppose an LDAP server supports a "get time" extended operation.
-It would supply classes such as
-GetTimeRequest and GetTimeResponse,
-so that applications can use this feature.
-An application would use these classes as follows:
-
--GetTimeResponse resp = - (GetTimeResponse) ectx.extendedOperation(new GetTimeRequest()); -long time = resp.getTime(); -
-The GetTimeRequest and GetTimeResponse classes might
-be defined as follows:
-
-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;
- }
-}
-Control to represent an LDAPv3
-control. It can be a control that is sent to an LDAP server
-(request control) or a control returned by an LDAP server
-(response control). 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.
--An application typically does not deal directly with this interface. -Instead, it deals with classes that implement 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. -
-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 SignedResultsControl so that applications
-can use this feature.
-An application would use this class as follows:
-
-
-Control[] reqCtls = new Control[] {new SignedResultsControl(Control.CRITICAL)};
-ectx.setRequestControls(reqCtls);
-NamingEnumeration enum = ectx.search(...);
-
-
-The SignedResultsControl class might be defined as follows:
-
-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
- }
- ...
-}
-
-When a service provider receives response controls, it uses
-the ControlFactory class to produce specific classes
-that implement the Control interface.
-
-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 LdapContext provides a method (getResponseControls())
-for getting the response controls sent with an LDAP operation,
-while the HasControls interface is used to retrieve
-response controls associated with enumeration results.
-
-For example, suppose an LDAP server sends back a "change ID" control in response
-to a successful modification. It would supply a class ChangeIDControl
-so that the application can use this feature.
-An application would perform an update, and then try to get the change ID.
-
-// 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());
- }
- }
-}
-ChangeIDControl and
-VendorXControlFactory classes. The VendorXControlFactory
-will be used by the service provider when the provider receives response
-controls from the LDAP server.
-
-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
- }
-}
-+ * This package defines the naming operations of the Java Naming and + * Directory Interface (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. + * + * + *
+ * This package defines the notion of a context, represented + * by the {@code Context} interface. + * A context consists of a set of name-to-object bindings. + * {@code Context} is the core interface for looking up, binding, unbinding, + * and renaming objects, and for creating and destroying subcontexts. + *
+ * {@code lookup()} is the most commonly used operation. + * You supply {@code lookup()} + * the name of the object you want + * to look up, and it returns the object bound to that name. + * For example, the following code fragment looks up + * a printer and sends a document to the printer object + * to be printed: + * + * {@snippet : + * Printer printer = (Printer)ctx.lookup("treekiller"); + * printer.print(report); + * } + * + *
+ * Every naming method in the {@code Context} + * interface has two + * overloads: one that accepts a + * {@code Name} argument and one that accepts a string name. + * {@code Name} is an interface that represents a generic + * name--an ordered sequence of zero of more components. + * For these methods, {@code Name} can be used to represent a + * composite name ({@code CompositeName}) + * so that you can name an object using a name which spans multiple namespaces. + *
+ * The overloads that accept {@code Name} + * are useful for applications that need to manipulate names: composing + * them, comparing components, and so on. + * The overloads that accept string names are likely to be more useful + * for simple applications, such as those that simply read in a name + * and look up the corresponding object. + * + *
+ * The {@code Binding} class is actually a subclass of + * {@code NameClassPair}, which consists + * simply of the object's name and the object's class name. + * The {@code NameClassPair} is useful when you only want + * information about the object's class and do not want to + * pay the extra cost of getting the object. + * + *
-This package defines the naming operations of the Java Naming and -Directory Interface (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. - - -
-This package defines the notion of a context, represented
-by the Context interface.
-A context consists of a set of name-to-object bindings.
-Context is the core interface for looking up, binding, unbinding,
-and renaming objects, and for creating and destroying subcontexts.
-
-lookup() is the most commonly used operation.
-You supply lookup()
-the name of the object you want
-to look up, and it returns the object bound to that name.
-For example, the following code fragment looks up
-a printer and sends a document to the printer object
-to be printed:
-
-
-
-Printer printer = (Printer)ctx.lookup("treekiller");
-printer.print(report);
-
-
-
-
-Every naming method in the Context
-interface has two
-overloads: one that accepts a
-Name argument and one that accepts a string name.
-Name is an interface that represents a generic
-name--an ordered sequence of zero of more components.
-For these methods, Name can be used to represent a
-composite name (CompositeName)
-so that you can name an object using a name which spans multiple namespaces.
-
-The overloads that accept Name
-are useful for applications that need to manipulate names: composing
-them, comparing components, and so on.
-The overloads that accept string names are likely to be more useful
-for simple applications, such as those that simply read in a name
-and look up the corresponding object.
-
-
Binding class represents a name-to-object binding.
-It is a tuple containing the name of the bound object,
-the name of the object's class, and the object itself.
-
-The Binding class is actually a subclass of
-NameClassPair, which consists
-simply of the object's name and the object's class name.
-The NameClassPair is useful when you only want
-information about the object's class and do not want to
-pay the extra cost of getting the object.
-
-
Reference
-class, which contains information on how to construct a copy of the object.
-JNDI will attempt to turn references looked up from the directory
-into the Java objects they represent, so that
-JNDI clients have the illusion that what
-is stored in the directory are Java objects.
-
-
-InitialContext,
-which provides a starting point for naming and directory operations.
-Once you have an initial context, you can use it to
-look up other contexts and objects.
-
-NamingException.
-Programs interested in dealing with a particular exception
-can catch the corresponding subclass of the exception.
-Otherwise, programs should catch NamingException.
-
-
-+ * This package defines the service provider interface (SPI) of the Java Naming + * and Directory Interface (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. + * + *
+ * The JNDI SPI provides the means for creating JNDI service providers, + * through which JNDI applications access different naming and + * directory services. + * + * + *
javax.naming
-and related packages.
-
--This package defines the service provider interface (SPI) of the Java Naming -and Directory Interface (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. - -
-The JNDI SPI provides the means for creating JNDI service providers, -through which JNDI applications access different naming and -directory services. - - -
javax.naming.Context.lookup()
-method and related methods to return Java objects that are natural
-and intuitive for the Java programmer.
-For example, when looking up a printer name from the directory,
-it is natural for you to expect to get
-back a printer object on which to operate.
-
-
-