This exception is thrown when an authentication error occurs while
accessing the naming or directory service.
An authentication error can happen, for example, when the credentials
supplied by the user program is invalid or otherwise fails to
authenticate the user to the naming/directory service.

If the program wants to handle this exception in particular, it
should catch AuthenticationException explicitly before attempting to
catch NamingException. After catching AuthenticationException, the
program could reattempt the authentication by updating
the resolved context's environment properties with the appropriate
appropriate credentials.

Synchronization and serialization issues that apply to NamingException
apply directly here.

This exception is thrown when
the particular flavor of authentication requested is not supported.
For example, if the program
is attempting to use strong authentication but the directory/naming
supports only simple authentication, this exception would be thrown.
Identification of a particular flavor of authentication is
provider- and server-specific. It may be specified using
specific authentication schemes such
those identified using SASL, or a generic authentication specifier
(such as "simple" and "strong").

If the program wants to handle this exception in particular, it
should catch AuthenticationNotSupportedException explicitly before
attempting to catch NamingException. After catching
AuthenticationNotSupportedException, the program could
reattempt the authentication using a different authentication flavor
by updating the resolved context's environment properties accordingly.

Synchronization and serialization issues that apply to NamingException
apply directly here.

This class represents the binary form of the address of
a communications end-point.

A BinaryRefAddr consists of a type that describes the communication mechanism
and an opaque buffer containing the address description
specific to that communication mechanism. The format and interpretation of
the address type and the contents of the opaque buffer are based on
the agreement of three parties: the client that uses the address,
the object/server that can be reached using the address,
and the administrator or program that creates the address.

An example of a binary reference address is an BER X.500 presentation address.
Another example of a binary reference address is a serialized form of
a service's object handle.

A binary reference address is immutable in the sense that its fields
once created, cannot be replaced. However, it is possible to access
the byte array used to hold the opaque buffer. Programs are strongly
recommended against changing this byte array. Changes to this
byte array need to be explicitly synchronized.

This class represents a name-to-object binding found in a context.

A context consists of name-to-object bindings.
The Binding class represents such a binding.  It consists
of a name and an object. The Context.listBindings()
method returns an enumeration of Binding.

Use subclassing for naming systems that generate contents of
a binding dynamically.

A Binding instance is not synchronized against concurrent access by multiple
threads. Threads that need to access a Binding concurrently should
synchronize amongst themselves and provide the necessary locking.

This exception is thrown to indicate that the operation reached
a point in the name where the operation cannot proceed any further.
When performing an operation on a composite name, a naming service
provider may reach a part of the name that does not belong to its
namespace.  At that point, it can construct a
CannotProceedException and then invoke methods provided by
javax.naming.spi.NamingManager (such as getContinuationContext())
to locate another provider to continue the operation.  If this is
not possible, this exception is raised to the caller of the
context operation.

If the program wants to handle this exception in particular, it
should catch CannotProceedException explicitly before attempting to
catch NamingException.

A CannotProceedException instance is not synchronized against concurrent
multithreaded access. Multiple threads trying to access and modify
CannotProceedException should lock the object.

This exception is thrown when the client is
unable to communicate with the directory or naming service.
The inability to communicate with the service might be a result
of many factors, such as network partitioning, hardware or interface problems,
failures on either the client or server side.
This exception is meant to be used to capture such communication problems.

Synchronization and serialization issues that apply to NamingException
apply directly here.

This class represents a composite name -- a sequence of
 component names spanning multiple namespaces.
 Each component is a string name from the namespace of a
 naming system. If the component comes from a hierarchical
 namespace, that component can be further parsed into
 its atomic parts by using the CompoundName class.

 The components of a composite name are numbered.  The indexes of a
 composite name with N components range from 0 up to, but not including, N.
 This range may be written as [0,N).
 The most significant component is at index 0.
 An empty composite name has no components.

 JNDI Composite Name Syntax
 JNDI defines a standard string representation for composite names. This
 representation is the concatenation of the components of a composite name
 from left to right using the component separator (a forward
 slash character (/)) to separate each component.
 The JNDI syntax defines the following meta characters:

 escape (backward slash \),
 quote characters  (single (') and double quotes (")), and
 component separator (forward slash character (/)).

 Any occurrence of a leading quote, an escape preceding any meta character,
 an escape at the end of a component, or a component separator character
 in an unquoted component must be preceded by an escape character when
 that component is being composed into a composite name string.
 Alternatively, to avoid adding escape characters as described,
 the entire component can be quoted using matching single quotes
 or matching double quotes. A single quote occurring within a double-quoted
 component is not considered a meta character (and need not be escaped),
 and vice versa.

 When two composite names are compared, the case of the characters
 is significant.

 A leading component separator (the composite name string begins with
 a separator) denotes a leading empty component (a component consisting
 of an empty string).
 A trailing component separator (the composite name string ends with
 a separator) denotes a trailing empty component.
 Adjacent component separators denote an empty component.

Composite Name Examples
This table shows examples of some composite names. Each row shows
the string form of a composite name and its corresponding structural form
(CompositeName).




String Name
CompositeName




""

{} (the empty name == new CompositeName("") == new CompositeName())





"x"

{"x"}





"x/y"

{"x", "y"}



"x/"
{"x", ""}



"/x"
{"", "x"}



"/"
{""}



"//"
{"", ""}


"/x/"
{"", "x", ""}


"x//y"
{"x", "", "y"}



Composition Examples
 Here are some composition examples.  The right column shows composing
 string composite names while the left column shows composing the
 corresponding CompositeNames.  Notice that composing the
 string forms of two composite names simply involves concatenating
 their string forms together.




String Names
CompositeNames




"x/y"            "/"   = x/y/


{"x", "y"}       {""}  = {"x", "y", ""}





""               "x"   = "x"


{}               {"x"} = {"x"}





"/"              "x"   = "/x"


{""}             {"x"} = {"", "x"}





"x"    ""       ""    = "x"


{"x"}  {}       {}    = {"x"}





Multithreaded Access
 A CompositeName instance is not synchronized against concurrent
 multithreaded access. Multiple threads trying to access and modify a
 CompositeName should lock the object.

This class represents a compound name -- a name from
 a hierarchical name space.
 Each component in a compound name is an atomic name.

 The components of a compound name are numbered.  The indexes of a
 compound name with N components range from 0 up to, but not including, N.
 This range may be written as [0,N).
 The most significant component is at index 0.
 An empty compound name has no components.

 Compound Name Syntax
 The syntax of a compound name is specified using a set of properties:

  jndi.syntax.direction
  Direction for parsing ("right_to_left", "left_to_right", "flat").
      If unspecified, defaults to "flat", which means the namespace is flat
      with no hierarchical structure.

  jndi.syntax.separator
  Separator between atomic name components.
      Required unless direction is "flat".

  jndi.syntax.ignorecase
  If present, "true" means ignore the case when comparing name
      components. If its value is not "true", or if the property is not
      present, case is considered when comparing name components.

  jndi.syntax.escape
  If present, specifies the escape string for overriding separator,
      escapes and quotes.

  jndi.syntax.beginquote
  If present, specifies the string delimiting start of a quoted string.

  jndi.syntax.endquote
  String delimiting end of quoted string.
      If present, specifies the string delimiting the end of a quoted string.
      If not present, use syntax.beginquote as end quote.
  jndi.syntax.beginquote2
  Alternative set of begin/end quotes.

  jndi.syntax.endquote2
  Alternative set of begin/end quotes.

  jndi.syntax.trimblanks
  If present, "true" means trim any leading and trailing whitespaces
      in a name component for comparison purposes. If its value is not
      "true", or if the property is not present, blanks are significant.
  jndi.syntax.separator.ava
  If present, specifies the string that separates
      attribute-value-assertions when specifying multiple attribute/value
      pairs. (e.g. ","  in age=65,gender=male).
  jndi.syntax.separator.typeval
  If present, specifies the string that separators attribute
              from value (e.g. "=" in "age=65")

 These properties are interpreted according to the following rules:


 In a string without quotes or escapes, any instance of the
 separator delimits two atomic names. Each atomic name is referred
 to as a component.

 A separator, quote or escape is escaped if preceded immediately
 (on the left) by the escape.

 If there are two sets of quotes, a specific begin-quote must be matched
 by its corresponding end-quote.

 A non-escaped begin-quote which precedes a component must be
 matched by a non-escaped end-quote at the end of the component.
 A component thus quoted is referred to as a
 quoted component. It is parsed by
 removing the being- and end- quotes, and by treating the intervening
 characters as ordinary characters unless one of the rules involving
 quoted components listed below applies.

 Quotes embedded in non-quoted components are treated as ordinary strings
 and need not be matched.

 A separator that is escaped or appears between non-escaped
 quotes is treated as an ordinary string and not a separator.

 An escape string within a quoted component acts as an escape only when
 followed by the corresponding end-quote string.
 This can be used to embed an escaped quote within a quoted component.

 An escaped escape string is not treated as an escape string.

 An escape string that does not precede a meta string (quotes or separator)
 and is not at the end of a component is treated as an ordinary string.

 A leading separator (the compound name string begins with
 a separator) denotes a leading empty atomic component (consisting
 of an empty string).
 A trailing separator (the compound name string ends with
 a separator) denotes a trailing empty atomic component.
 Adjacent separators denote an empty atomic component.


 The string form of the compound name follows the syntax described above.
 When the components of the compound name are turned into their
 string representation, the reserved syntax rules described above are
 applied (e.g. embedded separators are escaped or quoted)
 so that when the same string is parsed, it will yield the same components
 of the original compound name.

Multithreaded Access
 A CompoundName instance is not synchronized against concurrent
 multithreaded access. Multiple threads trying to access and modify a
 CompoundName should lock the object.

This exception is thrown when there is a configuration problem.
This can arise when installation of a provider was
not done correctly, or if there are configuration problems with the
server, or if configuration information required to access
the provider or service is malformed or missing.
For example, a request to use SSL as the security protocol when
the service provider software was not configured with the SSL
component would cause such an exception. Another example is
if the provider requires that a URL be specified as one of the
environment properties but the client failed to provide it.

Synchronization and serialization issues that apply to NamingException
apply directly here.

This interface represents a naming context, which
 consists of a set of name-to-object bindings.
 It contains methods for examining and updating these bindings.

 Names
 Each name passed as an argument to a Context method is relative
 to that context.  The empty name is used to name the context itself.
 A name parameter may never be null.

 Most of the methods have overloaded versions with one taking a
 Name parameter and one taking a String.
 These overloaded versions are equivalent in that if
 the Name and String parameters are just
 different representations of the same name, then the overloaded
 versions of the same methods behave the same.
 In the method descriptions below, only one version is fully documented.
 The second version instead has a link to the first:  the same
 documentation applies to both.

 For systems that support federation, String name arguments to
 Context methods are composite names. Name arguments that are
 instances of CompositeName are treated as composite names,
 while Name arguments that are not instances of
 CompositeName are treated as compound names (which might be
 instances of CompoundName or other implementations of compound
 names). This allows the results of NameParser.parse() to be used as
 arguments to the Context methods.
 Prior to JNDI 1.2, all name arguments were treated as composite names.

 Furthermore, for systems that support federation, all names returned
 in a NamingEnumeration
 from list() and listBindings() are composite names
 represented as strings.
 See CompositeName for the string syntax of names.

 For systems that do not support federation, the name arguments (in
 either Name or String forms) and the names returned in
 NamingEnumeration may be names in their own namespace rather than
 names in a composite namespace, at the discretion of the service
 provider.

Exceptions
 All the methods in this interface can throw a NamingException or
 any of its subclasses. See NamingException and their subclasses
 for details on each exception.

Concurrent Access
 A Context instance is not guaranteed to be synchronized against
 concurrent access by multiple threads.  Threads that need to access
 a single Context instance concurrently should synchronize amongst
 themselves and provide the necessary locking.  Multiple threads
 each manipulating a different Context instance need not
 synchronize.  Note that the lookup
 method, when passed an empty name, will return a new Context instance
 representing the same naming context.

 For purposes of concurrency control,
 a Context operation that returns a NamingEnumeration is
 not considered to have completed while the enumeration is still in
 use, or while any referrals generated by that operation are still
 being followed.


Parameters
 A Name parameter passed to any method of the
 Context interface or one of its subinterfaces
 will not be modified by the service provider.
 The service provider may keep a reference to it
 for the duration of the operation, including any enumeration of the
 method's results and the processing of any referrals generated.
 The caller should not modify the object during this time.
 A Name returned by any such method is owned by the caller.
 The caller may subsequently modify it; the service provider may not.


Environment Properties

 JNDI applications need a way to communicate various preferences
 and properties that define the environment in which naming and
 directory services are accessed. For example, a context might
 require specification of security credentials in order to access
 the service. Another context might require that server configuration
 information be supplied. These are referred to as the environment
 of a context. The Context interface provides methods for
 retrieving and updating this environment.

 The environment is inherited from the parent context as
 context methods proceed from one context to the next. Changes to
 the environment of one context do not directly affect those
 of other contexts.

 It is implementation-dependent when environment properties are used
 and/or verified for validity.  For example, some of the
 security-related properties are used by service providers to "log in"
 to the directory.  This login process might occur at the time the
 context is created, or the first time a method is invoked on the
 context.  When, and whether this occurs at all, is
 implementation-dependent.  When environment properties are added or
 removed from the context, verifying the validity of the changes is again
 implementation-dependent. For example, verification of some properties
 might occur at the time the change is made, or at the time the next
 operation is performed on the context, or not at all.

 Any object with a reference to a context may examine that context's
 environment.  Sensitive information such as clear-text
 passwords should not be stored there unless the implementation is
 known to protect it.



Resource Files

 To simplify the task of setting up the environment
 required by a JNDI application,
 application components and service providers may be distributed
 along with resource files.
 A JNDI resource file is a file in the properties file format (see
 java.util.Properties),
 containing a list of key/value pairs.
 The key is the name of the property (e.g. "java.naming.factory.object")
 and the value is a string in the format defined
 for that property.  Here is an example of a JNDI resource file:

 java.naming.factory.object=com.sun.jndi.ldap.AttrsToCorba:com.wiz.from.Person
 java.naming.factory.state=com.sun.jndi.ldap.CorbaToAttrs:com.wiz.from.Person
 java.naming.factory.control=com.sun.jndi.ldap.ResponseControlFactory


 The JNDI class library reads the resource files and makes the property
 values freely available.  Thus JNDI resource files should be considered
 to be "world readable", and sensitive information such as clear-text
 passwords should not be stored there.

 There are two kinds of JNDI resource files:
 provider and application.

 Provider Resource Files

 Each service provider has an optional resource that lists properties
 specific to that provider.  The name of this resource is:

 [prefix/]jndiprovider.properties

 where prefix is
 the package name of the provider's context implementation(s),
 with each period (".") converted to a slash ("/").

 For example, suppose a service provider defines a context
 implementation with class name com.sun.jndi.ldap.LdapCtx.
 The provider resource for this provider is named
 com/sun/jndi/ldap/jndiprovider.properties.  If the class is
 not in a package, the resource's name is simply
 jndiprovider.properties.



 Certain methods in the JNDI class library make use of the standard
 JNDI properties that specify lists of JNDI factories:

 java.naming.factory.object
 java.naming.factory.state
 java.naming.factory.control
 java.naming.factory.url.pkgs

 The JNDI library will consult the provider resource file
 when determining the values of these properties.
 Properties other than these may be set in the provider
 resource file at the discretion of the service provider.
 The service provider's documentation should clearly state which
 properties are allowed; other properties in the file will be ignored.

 Application Resource Files

 When an application is deployed, it will generally have several
 codebase directories and JARs in its classpath.  Similarly, when an
 applet is deployed, it will have a codebase and archives specifying
 where to find the applet's classes.  JNDI locates (using
 ClassLoader.getResources())
 all application resource files named jndi.properties
 in the classpath.
 In addition, if the file java.home/lib/jndi.properties
 exists and is readable,
 JNDI treats it as an additional application resource file.
 (java.home indicates the
 directory named by the java.home system property.)
 All of the properties contained in these files are placed
 into the environment of the initial context.  This environment
 is then inherited by other contexts.


 For each property found in more than one application resource file,
 JNDI uses the first value found or, in a few cases where it makes
 sense to do so, it concatenates all of the values (details are given
 below).
 For example, if the "java.naming.factory.object" property is found in
 three jndi.properties resource files, the
 list of object factories is a concatenation of the property
 values from all three files.
 Using this scheme, each deployable component is responsible for
 listing the factories that it exports.  JNDI automatically
 collects and uses all of these export lists when searching for factory
 classes.

 Search Algorithm for Properties

 When JNDI constructs an initial context, the context's environment
 is initialized with properties defined in the environment parameter
 passed to the constructor, the system properties, the applet parameters,
 and the application resource files.  See
 InitialContext
 for details.
 This initial environment is then inherited by other context instances.


 When the JNDI class library needs to determine
 the value of a property, it does so by merging
 the values from the following two sources, in order:

 The environment of the context being operated on.
 The provider resource file (jndiprovider.properties)
 for the context being operated on.

 For each property found in both of these two sources,
 JNDI determines the property's value as follows.  If the property is
 one of the standard JNDI properties that specify a list of JNDI
 factories (listed above), the values are
 concatenated into a single colon-separated list.  For other
 properties, only the first value found is used.


 When a service provider needs to determine the value of a property,
 it will generally take that value directly from the environment.
 A service provider may define provider-specific properties
 to be placed in its own provider resource file.  In that
 case it should merge values as described in the previous paragraph.


 In this way, each service provider developer can specify a list of
 factories to use with that service provider. These can be modified by
 the application resources specified by the deployer of the application
 or applet, which in turn can be modified by the user.

This exception is thrown when attempting to destroy a context that
is not empty.

If the program wants to handle this exception in particular, it
should catch ContextNotEmptyException explicitly before attempting to
catch NamingException. For example, after catching ContextNotEmptyException,
the program might try to remove the contents of the context before
reattempting the destroy.

Synchronization and serialization issues that apply to NamingException
apply directly here.

This interface represents an attribute associated with a named object.

In a directory, named objects can have associated with them
attributes.  The Attribute interface represents an attribute associated
with a named object.  An attribute contains 0 or more, possibly null, values.
The attribute values can be ordered or unordered (see isOrdered()).
If the values are unordered, no duplicates are allowed.
If the values are ordered, duplicates are allowed.

The content and representation of an attribute and its values is defined by
the attribute's schema. The schema contains information
about the attribute's syntax and other properties about the attribute.
See getAttributeDefinition() and
getAttributeSyntaxDefinition()
for details regarding how to get schema information about an attribute
if the underlying directory service supports schemas.

Equality of two attributes is determined by the implementation class.
A simple implementation can use Object.equals() to determine equality
of attribute values, while a more sophisticated implementation might
make use of schema information to determine equality.
Similarly, one implementation might provide a static storage
structure which simply returns the values passed to its
constructor, while another implementation might define get() and
getAll().
to get the values dynamically from the directory.

Note that updates to Attribute (such as adding or removing a
value) do not affect the corresponding representation of the attribute
in the directory.  Updates to the directory can only be effected
using operations in the DirContext interface.

This exception is thrown when an operation attempts
to add an attribute that already exists.

Synchronization and serialization issues that apply to NamingException
apply directly here.

This exception is thrown when an attempt is
made to add, or remove, or modify an attribute, its identifier,
or its values that conflicts with the attribute's (schema) definition
or the attribute's state.
It is thrown in response to DirContext.modifyAttributes().
It contains a list of modifications that have not been performed, in the
order that they were supplied to modifyAttributes().
If the list is null, none of the modifications were performed successfully.

An AttributeModificationException instance is not synchronized
against concurrent multithreaded access. Multiple threads trying
to access and modify a single AttributeModification instance
should lock the object.

This interface represents a collection of attributes.

In a directory, named objects can have associated with them
attributes.  The Attributes interface represents a collection of attributes.
For example, you can request from the directory the attributes
associated with an object.  Those attributes are returned in
an object that implements the Attributes interface.

Attributes in an object that implements the  Attributes interface are
unordered. The object can have zero or more attributes.
Attributes is either case-sensitive or case-insensitive (case-ignore).
This property is determined at the time the Attributes object is
created. (see BasicAttributes constructor for example).
In a case-insensitive Attributes, the case of its attribute identifiers
is ignored when searching for an attribute, or adding attributes.
In a case-sensitive Attributes, the case is significant.

Note that updates to Attributes (such as adding or removing an attribute)
do not affect the corresponding representation in the directory.
Updates to the directory can only be effected
using operations in the DirContext interface.

This class provides a basic implementation of the Attribute interface.

This implementation does not support the schema methods
getAttributeDefinition() and getAttributeSyntaxDefinition().
They simply throw OperationNotSupportedException.
Subclasses of BasicAttribute should override these methods if they
support them.

The BasicAttribute class by default uses Object.equals() to
determine equality of attribute values when testing for equality or
when searching for values, except when the value is an array.
For an array, each element of the array is checked using Object.equals().
Subclasses of BasicAttribute can make use of schema information
when doing similar equality checks by overriding methods
in which such use of schema is meaningful.
Similarly, the BasicAttribute class by default returns the values passed to its
constructor and/or manipulated using the add/remove methods.
Subclasses of BasicAttribute can override get() and getAll()
to get the values dynamically from the directory (or implement
the Attribute interface directly instead of subclassing BasicAttribute).

Note that updates to BasicAttribute (such as adding or removing a value)
does not affect the corresponding representation of the attribute
in the directory.  Updates to the directory can only be effected
using operations in the DirContext interface.

A BasicAttribute instance is not synchronized against concurrent
multithreaded access. Multiple threads trying to access and modify a
BasicAttribute should lock the object.

This class provides a basic implementation
of the Attributes interface.

BasicAttributes is either case-sensitive or case-insensitive (case-ignore).
This property is determined at the time the BasicAttributes constructor
is called.
In a case-insensitive BasicAttributes, the case of its attribute identifiers
is ignored when searching for an attribute, or adding attributes.
In a case-sensitive BasicAttributes, the case is significant.

When the BasicAttributes class needs to create an Attribute, it
uses BasicAttribute. There is no other dependency on BasicAttribute.

Note that updates to BasicAttributes (such as adding or removing an attribute)
does not affect the corresponding representation in the directory.
Updates to the directory can only be effected
using operations in the DirContext interface.

A BasicAttributes instance is not synchronized against concurrent
multithreaded access. Multiple threads trying to access and modify
a single BasicAttributes instance should lock the object.

The directory service interface, containing
 methods for examining and updating attributes
 associated with objects, and for searching the directory.

 Names
 Each name passed as an argument to a DirContext method is relative
 to that context.  The empty name is used to name the context itself.
 The name parameter may never be null.

 Most of the methods have overloaded versions with one taking a
 Name parameter and one taking a String.
 These overloaded versions are equivalent in that if
 the Name and String parameters are just
 different representations of the same name, then the overloaded
 versions of the same methods behave the same.
 In the method descriptions below, only one version is documented.
 The second version instead has a link to the first:  the same
 documentation applies to both.

 See Context for a discussion on the interpretation of the
 name argument to the Context methods. These same rules
 apply to the name argument to the DirContext methods.

 Attribute Models
 There are two basic models of what attributes should be
 associated with.  First, attributes may be directly associated with a
 DirContext object.
 In this model, an attribute operation on the named object is
 roughly equivalent
 to a lookup on the name (which returns the DirContext object),
 followed by the attribute operation invoked on the DirContext object
 in which the caller supplies an empty name. The attributes can be viewed
 as being stored along with the object (note that this does not imply that
 the implementation must do so).

 The second model is that attributes are associated with a
 name (typically an atomic name) in a DirContext.
 In this model, an attribute operation on the named object is
 roughly equivalent to a lookup on the name of the parent DirContext of the
 named object, followed by the attribute operation invoked on the parent
 in which the caller supplies the terminal atomic name.
 The attributes can be viewed as being stored in the parent DirContext
 (again, this does not imply that the implementation must do so).
 Objects that are not DirContexts can have attributes, as long as
 their parents are DirContexts.

 JNDI support both of these models.
 It is up to the individual service providers to decide where to
 "store" attributes.
 JNDI clients are safest when they do not make assumptions about
 whether an object's attributes are stored as part of the object, or stored
 within the parent object and associated with the object's name.

 Attribute Type Names
 In the getAttributes() and search() methods,
 you can supply the attributes to return by supplying a list of
 attribute names (strings).
 The attributes that you get back might not have the same names as the
 attribute names you have specified. This is because some directories
 support features that cause them to return other attributes.  Such
 features include attribute subclassing, attribute name synonyms, and
 attribute language codes.

 In attribute subclassing, attributes are defined in a class hierarchy.
 In some directories, for example, the "name" attribute might be the
 superclass of all name-related attributes, including "commonName" and
 "surName".  Asking for the "name" attribute might return both the
 "commonName" and "surName" attributes.

 With attribute type synonyms, a directory can assign multiple names to
 the same attribute. For example, "cn" and "commonName" might both
 refer to the same attribute. Asking for "cn" might return the
 "commonName" attribute.

 Some directories support the language codes for attributes.
 Asking such a directory for the "description" attribute, for example,
 might return all of the following attributes:

 description
 description;lang-en
 description;lang-de
 description;lang-fr



Operational Attributes

 Some directories have the notion of "operational attributes" which are
 attributes associated with a directory object for administrative
 purposes. An example of operational attributes is the access control
 list for an object.

 In the getAttributes() and search() methods,
 you can specify that all attributes associated with the requested objects
 be returned by supply null as the list of attributes to return.
 The attributes returned do not include operational attributes.
 In order to retrieve operational attributes, you must name them explicitly.


 Named Context

 There are certain methods in which the name must resolve to a context
 (for example, when searching a single level context). The documentation
 of such methods
 use the term named context to describe their name parameter.
 For these methods, if the named object is not a DirContext,
 NotContextException is thrown.
 Aside from these methods, there is no requirement that the
 named object be a DirContext.

Parameters

 An Attributes, SearchControls, or array object
 passed as a parameter to any method will not be modified by the
 service provider.  The service provider may keep a reference to it
 for the duration of the operation, including any enumeration of the
 method's results and the processing of any referrals generated.
 The caller should not modify the object during this time.
 An Attributes object returned by any method is owned by
 the caller.  The caller may subsequently modify it; the service
 provider will not.

Exceptions

 All the methods in this interface can throw a NamingException or
 any of its subclasses. See NamingException and their subclasses
 for details on each exception.

This class is the starting context for performing
directory operations. The documentation in the class description
of InitialContext (including those for synchronization) apply here.

This exception is thrown when an attempt is
made to add to create an attribute with an invalid attribute identifier.
The validity of an attribute identifier is directory-specific.

Synchronization and serialization issues that apply to NamingException
apply directly here.

This exception is thrown when an attempt is
made to add or modify an attribute set that has been specified
incompletely or incorrectly. This could happen, for example,
when attempting to add or modify a binding, or to create a new
subcontext without specifying all the mandatory attributes
required for creation of the object.  Another situation in
which this exception is thrown is by specification of incompatible
attributes within the same attribute set, or attributes in conflict
with that specified by the object's schema.

Synchronization and serialization issues that apply to NamingException
apply directly here.

This class is thrown when an attempt is
made to add to an attribute a value that conflicts with the attribute's
schema definition.  This could happen, for example, if attempting
to add an attribute with no value when the attribute is required
to have at least one value, or if attempting to add more than
one value to a single valued-attribute, or if attempting to
add a value that conflicts with the syntax of the attribute.

Synchronization and serialization issues that apply to NamingException
apply directly here.

This exception is thrown when the specification of
the SearchControls for a search operation is invalid. For example, if the scope is
set to a value other than OBJECT_SCOPE, ONELEVEL_SCOPE, SUBTREE_SCOPE,
this exception is thrown.

Synchronization and serialization issues that apply to NamingException
apply directly here.

This exception is thrown when the specification of
a search filter is invalid.  The expression of the filter may
be invalid, or there may be a problem with one of the parameters
passed to the filter.

Synchronization and serialization issues that apply to NamingException
apply directly here.

This class represents a modification item.
It consists of a modification code and an attribute on which to operate.

A ModificationItem instance is not synchronized against concurrent
multithreaded access. Multiple threads trying to access and modify
a single ModificationItem instance should lock the object.

This exception is thrown when attempting to access
an attribute that does not exist.

Synchronization and serialization issues that apply to NamingException
apply directly here.

This exception is thrown when a method
in some ways violates the schema. An example of schema violation
is modifying attributes of an object that violates the object's
schema definition. Another example is renaming or moving an object
to a part of the namespace that violates the namespace's
schema definition.

Synchronization and serialization issues that apply to NamingException
apply directly here.

This class encapsulates
factors that determine scope of search and what gets returned
as a result of the search.

A SearchControls instance is not synchronized against concurrent
multithreaded access. Multiple threads trying to access and modify
a single SearchControls instance should lock the object.

This class represents an item in the NamingEnumeration returned as a
result of the DirContext.search() methods.

A SearchResult instance is not synchronized against concurrent
multithreaded access. Multiple threads trying to access and modify
a single SearchResult instance should lock the object.

  NamespaceChangeListener listener = ...;
  src.addNamingListener("x", SUBTREE_SCOPE, listener);

  evt.getEventContext() == src
  evt.getOldBinding().getName().equals("x/y")

Contains methods for registering/deregistering listeners to be notified of
 events fired when objects named in a context changes.

Target
 The name parameter in the addNamingListener() methods is referred
 to as the target. The target, along with the scope, identify
 the object(s) that the listener is interested in.
 It is possible to register interest in a target that does not exist, but
 there might be limitations in the extent to which this can be
 supported by the service provider and underlying protocol/service.

 If a service only supports registration for existing
 targets, an attempt to register for a nonexistent target
 results in a NameNotFoundException being thrown as early as possible,
 preferably at the time addNamingListener() is called, or if that is
 not possible, the listener will receive the exception through the
 NamingExceptionEvent.

 Also, for service providers that only support registration for existing
 targets, when the target that a listener has registered for is
 subsequently removed from the namespace, the listener is notified
 via a NamingExceptionEvent (containing a
NameNotFoundException).

 An application can use the method targetMustExist() to check
 whether a EventContext supports registration
 of nonexistent targets.

Event Source
 The EventContext instance on which you invoke the
 registration methods is the event source of the events that are
 (potentially) generated.
 The source is not necessarily the object named by the target.
 Only when the target is the empty name is the object named by the target
 the source.
 In other words, the target,
 along with the scope parameter, are used to identify
 the object(s) that the listener is interested in, but the event source
 is the EventContext instance with which the listener
 has registered.

 For example, suppose a listener makes the following registration:


      NamespaceChangeListener listener = ...;
      src.addNamingListener("x", SUBTREE_SCOPE, listener);
 When an object named "x/y" is subsequently deleted, the corresponding
 NamingEvent (evt)  must contain:


      evt.getEventContext() == src
      evt.getOldBinding().getName().equals("x/y")

 Furthermore, listener registration/deregistration is with
 the EventContext
 instance, and not with the corresponding object in the namespace.
 If the program intends at some point to remove a listener, then it needs to
 keep a reference to the EventContext instance on
 which it invoked addNamingListener() (just as
 it needs to keep a reference to the listener in order to remove it
 later). It cannot expect to do a lookup() and get another instance of
 a EventContext on which to perform the deregistration.
Lifetime of Registration
 A registered listener becomes deregistered when:

It is removed using removeNamingListener().
An exception is thrown while collecting information about the events.
  That is, when the listener receives a NamingExceptionEvent.
Context.close() is invoked on the EventContext
 instance with which it has registered.

 Until that point, a EventContext instance that has outstanding
 listeners will continue to exist and be maintained by the service provider.

Listener Implementations
 The registration/deregistration methods accept an instance of
 NamingListener. There are subinterfaces of NamingListener
 for different of event types of NamingEvent.
 For example, the ObjectChangeListener
 interface is for the NamingEvent.OBJECT_CHANGED event type.
 To register interest in multiple event types, the listener implementation
 should implement multiple NamingListener subinterfaces and use a
 single invocation of addNamingListener().
 In addition to reducing the number of method calls and possibly the code size
 of the listeners, this allows some service providers to optimize the
 registration.

Threading Issues

 Like Context instances in general, instances of
 EventContext are not guaranteed to be thread-safe.
 Care must be taken when multiple threads are accessing the same
 EventContext concurrently.
 See the
 package description
 for more information on threading issues.

Contains methods for registering listeners to be notified
 of events fired when objects named in a directory context changes.

 The methods in this interface support identification of objects by
 RFC 2254
 search filters.

Using the search filter, it is possible to register interest in objects
 that do not exist at the time of registration but later come into existence and
 satisfy the filter.  However, there might be limitations in the extent
 to which this can be supported by the service provider and underlying
 protocol/service.  If the caller submits a filter that cannot be
 supported in this way, addNamingListener() throws an
 InvalidSearchFilterException.

 See EventContext for a description of event source
 and target, and information about listener registration/deregistration
 that are also applicable to methods in this interface.
 See the
 package description
 for information on threading issues.

 A SearchControls or array object
 passed as a parameter to any method is owned by the caller.
 The service provider will not modify the object or keep a reference to it.

Specifies the methods that a listener interested in namespace changes
 must implement.
 Specifically, the listener is interested in NamingEvents
 with event types of OBJECT_ADDED, OBJECT_RENAMED, or
 OBJECT_REMOVED.

 Such a listener must:

Implement this interface and its methods.
Implement NamingListener.namingExceptionThrown() so that
 it will be notified of exceptions thrown while attempting to
 collect information about the events.
Register with the source using the source's addNamingListener()
    method.

 A listener that wants to be notified of OBJECT_CHANGED event types
 should also implement the ObjectChangeListener
 interface.

NamespaceChangeListener listener = ...;
src.addNamingListener("x", SUBTREE_SCOPE, listener);

evt.getEventContext() == src
evt.getOldBinding().getName().equals("x/y")

This class represents an event fired by a naming/directory service.

The NamingEvent's state consists of

The event source: the EventContext which fired this event.
The event type.
The new binding: information about the object after the change.
The old binding: information about the object before the change.
Change information: information about the change
that triggered this event; usually service provider-specific or server-specific
information.


Note that the event source is always the same EventContext
instance  that the listener has registered with.
Furthermore, the names of the bindings in
the NamingEvent are always relative to that instance.
For example, suppose a listener makes the following registration:


    NamespaceChangeListener listener = ...;
    src.addNamingListener("x", SUBTREE_SCOPE, listener);
When an object named "x/y" is subsequently deleted, the corresponding
NamingEvent (evt) must contain:


    evt.getEventContext() == src
    evt.getOldBinding().getName().equals("x/y")

Care must be taken when multiple threads are accessing the same
EventContext concurrently.
See the
package description
for more information on threading issues.

This class represents an event fired when the procedures/processes
used to collect information for notifying listeners of
NamingEvents threw a NamingException.
This can happen, for example, if the server which the listener is using
aborts subsequent to the addNamingListener() call.

This interface is the root of listener interfaces that
handle NamingEvents.
It does not make sense for a listener to implement just this interface.
A listener typically implements a subinterface of NamingListener,
such as ObjectChangeListener or NamespaceChangeListener.

This interface contains a single method, namingExceptionThrown(),
that must be implemented so that the listener can be notified of
exceptions that are thrown (by the service provider) while gathering
information about the events that they're interested in.
When this method is invoked, the listener has been automatically deregistered
from the EventContext with which it has registered.

For example, suppose a listener implements ObjectChangeListener and
registers with a EventContext.
Then, if the connection to the server is subsequently broken,
the listener will receive a NamingExceptionEvent and may
take some corrective action, such as notifying the user of the application.

Specifies the method that a listener of a NamingEvent
 with event type of OBJECT_CHANGED must implement.

 An OBJECT_CHANGED event type is fired when (the contents of)
 an object has changed. This might mean that its attributes have been modified,
 added, or removed, and/or that the object itself has been replaced.
 How the object has changed can be determined by examining the
 NamingEvent's old and new bindings.

 A listener interested in OBJECT_CHANGED event types must:


Implement this interface and its method (objectChanged())
Implement NamingListener.namingExceptionThrown() so that
 it will be notified of exceptions thrown while attempting to
 collect information about the events.
Register with the source using the source's addNamingListener()
    method.

 A listener that wants to be notified of namespace change events
 should also implement the NamespaceChangeListener
 interface.

This class is the starting context for performing naming operations.

All naming operations are relative to a context.
The initial context implements the Context interface and
provides the starting point for resolution of names.


When the initial context is constructed, its environment
is initialized with properties defined in the environment parameter
passed to the constructor, and in any
application resource files.
In addition, a small number of standard JNDI properties may
be specified as system properties or as applet parameters
(through the use of Context.APPLET).
These special properties are listed in the field detail sections of the
Context and
LdapContext
interface documentation.

JNDI determines each property's value by merging
the values from the following two sources, in order:


The first occurrence of the property from the constructor's
environment parameter and (for appropriate properties) the applet
parameters and system properties.

The application resource files (jndi.properties).

For each property found in both of these two sources, or in
more than one application resource file, the property's value
is determined as follows.  If the property is
one of the standard JNDI properties that specify a list of JNDI
factories (see Context),
all of the values are
concatenated into a single colon-separated list.  For other
properties, only the first value found is used.


The initial context implementation is determined at runtime.
The default policy uses the environment property
"java.naming.factory.initial",
which contains the class name of the initial context factory.
An exception to this policy is made when resolving URL strings, as described
below.

When a URL string (a String of the form
scheme_id:rest_of_name) is passed as a name parameter to
any method, a URL context factory for handling that scheme is
located and used to resolve the URL.  If no such factory is found,
the initial context specified by
"java.naming.factory.initial" is used.  Similarly, when a
CompositeName object whose first component is a URL string is
passed as a name parameter to any method, a URL context factory is
located and used to resolve the first name component.
See NamingManager.getURLContext() for a description of how URL
context factories are located.

This default policy of locating the initial context and URL context
factories may be overridden
by calling
NamingManager.setInitialContextFactoryBuilder().

NoInitialContextException is thrown when an initial context cannot
be instantiated. This exception can be thrown during any interaction
with the InitialContext, not only when the InitialContext is constructed.
For example, the implementation of the initial context might lazily
retrieve the context only when actual methods are invoked on it.
The application should not have any dependency on when the existence
of an initial context is determined.

When the environment property "java.naming.factory.initial" is
non-null, the InitialContext constructor will attempt to create the
initial context specified therein. At that time, the initial context factory
involved might throw an exception if a problem is encountered. However,
it is provider implementation-dependent when it verifies and indicates
to the users of the initial context any environment property- or
connection- related problems. It can do so lazily--delaying until
an operation is performed on the context, or eagerly, at the time
the context is constructed.

An InitialContext instance is not synchronized against concurrent
access by multiple threads. Multiple threads each manipulating a
different InitialContext instance need not synchronize.
Threads that need to access a single InitialContext instance
concurrently should synchronize amongst themselves and provide the
necessary locking.

This exception is thrown when resources are not available to complete
the requested operation. This might due to a lack of resources on
the server or on the client. There are no restrictions to resource types,
as different services might make use of different resources. Such
restrictions might be due to physical limits and/or administrative quotas.
Examples of limited resources are internal buffers, memory, network bandwidth.

InsufficientResourcesException is different from LimitExceededException in that
the latter is due to user/system specified limits. See LimitExceededException
for details.

Synchronization and serialization issues that apply to NamingException
apply directly here.

This exception is thrown when the naming operation
being invoked has been interrupted. For example, an application
might interrupt a thread that is performing a search. If the
search supports being interrupted, it will throw
InterruptedNamingException. Whether an operation is interruptible
and when depends on its implementation (as provided by the
service providers). Different implementations have different ways
of protecting their resources and objects from being damaged
due to unexpected interrupts.

Synchronization and serialization issues that apply to NamingException
apply directly here.

This exception indicates that the name being specified does
not conform to the naming syntax of a naming system.
This exception is thrown by any of the methods that does name
parsing (such as those in Context, DirContext, CompositeName and CompoundName).

Synchronization and serialization issues that apply to NamingException
apply directly here.

This class provides a basic implementation of the Control
interface. It represents an LDAPv3 Control as defined in
RFC 2251.

This interface represents an LDAPv3 control as defined in
RFC 2251.

The LDAPv3 protocol uses controls to send and receive additional data
to affect the behavior of predefined operations.
Controls can be sent along with any LDAP operation to the server.
These are referred to as request controls. For example, a
"sort" control can be sent with an LDAP search operation to
request that the results be returned in a particular order.
Solicited and unsolicited controls can also be returned with
responses from the server. Such controls are referred to as
response controls. For example, an LDAP server might
define a special control to return change notifications.

This interface is used to represent both request and response controls.

This abstract class represents a factory for creating LDAPv3 controls.
LDAPv3 controls are defined in
RFC 2251.

When a service provider receives a response control, it uses control
factories to return the specific/appropriate control class implementation.

ExtendedRequest ::= [APPLICATION 23] SEQUENCE {
         requestName      [0] LDAPOID,
         requestValue     [1] OCTET STRING OPTIONAL }

This interface represents an LDAPv3 extended operation request as defined in
RFC 2251.


    ExtendedRequest ::= [APPLICATION 23] SEQUENCE {
             requestName      [0] LDAPOID,
             requestValue     [1] OCTET STRING OPTIONAL }
It comprises an object identifier string and an optional ASN.1 BER
encoded value.

The methods in this class are used by the service provider to construct
the bits to send to the LDAP server. Applications typically only deal with
the classes that implement this interface, supplying them with
any information required for a particular extended operation request.
It would then pass such a class as an argument to the
LdapContext.extendedOperation() method for performing the
LDAPv3 extended operation.

For example, suppose the LDAP server supported a 'get time' extended operation.
It would supply GetTimeRequest and GetTimeResponse classes:


public class GetTimeRequest implements ExtendedRequest {
    public GetTimeRequest() {... };
    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;
    public GetTimeResponse(String id, byte[] berValue, int offset,
        int length) throws NamingException {
        time =      ... // decode berValue to get time
    }
    public java.util.Date getDate() { return new java.util.Date(time) };
    public long getTime() { return time };
    ...
}
A program would use then these classes as follows:


GetTimeResponse resp =
    (GetTimeResponse) ectx.extendedOperation(new GetTimeRequest());
long time = resp.getTime();

ExtendedResponse ::= [APPLICATION 24] SEQUENCE {
     COMPONENTS OF LDAPResult,
     responseName     [10] LDAPOID OPTIONAL,
     response         [11] OCTET STRING OPTIONAL }

This interface represents an LDAP extended operation response as defined in
RFC 2251.


    ExtendedResponse ::= [APPLICATION 24] SEQUENCE {
         COMPONENTS OF LDAPResult,
         responseName     [10] LDAPOID OPTIONAL,
         response         [11] OCTET STRING OPTIONAL }
It comprises an optional object identifier and an optional ASN.1 BER
encoded value.


The methods in this class can be used by the application to get low
level information about the extended operation response. However, typically,
the application will be using methods specific to the class that
implements this interface. Such a class should have decoded the BER buffer
in the response and should provide methods that allow the user to
access that data in the response in a type-safe and friendly manner.

For example, suppose the LDAP server supported a 'get time' extended operation.
It would supply GetTimeRequest and GetTimeResponse classes.
The GetTimeResponse class might look like:


public class GetTimeResponse implements ExtendedResponse {
    public java.util.Date getDate() {...};
    public long getTime() {...};
    ....
}
A program would use then these classes as follows:


GetTimeResponse resp =
    (GetTimeResponse) ectx.extendedOperation(new GetTimeRequest());
java.util.Date now = resp.getDate();

// Get search result
SearchResult res = (SearchResult)entry;
// do something with it

// Get entry controls
if (entry instanceof HasControls) {
    Control[] entryCtls = ((HasControls)entry).getControls();
    // do something with controls
}

This interface is for returning controls with objects returned
in NamingEnumerations.
For example, suppose a server sends back controls with the results
of a search operation, the service provider would return a NamingEnumeration of
objects that are both SearchResult and implement HasControls.


  NamingEnumeration elts = ectx.search((Name)name, filter, sctls);
  while (elts.hasMore()) {
    Object entry = elts.next();

    // Get search result
    SearchResult res = (SearchResult)entry;
    // do something with it

    // Get entry controls
    if (entry instanceof HasControls) {
        Control[] entryCtls = ((HasControls)entry).getControls();
        // do something with controls
    }
  }

This class is the starting context for performing
LDAPv3-style extended operations and controls.

See javax.naming.InitialContext and
javax.naming.InitialDirContext for details on synchronization,
and the policy for how an initial context is created.

Request Controls
When you create an initial context (InitialLdapContext),
you can specify a list of request controls.
These controls will be used as the request controls for any
implicit LDAP "bind" operation performed by the context or contexts
derived from the context. These are called connection request controls.
Use getConnectControls() to get a context's connection request
controls.

The request controls supplied to the initial context constructor
are not used as the context request controls
for subsequent context operations such as searches and lookups.
Context request controls are set and updated by using
setRequestControls().

As shown, there can be two different sets of request controls
associated with a context: connection request controls and context
request controls.
This is required for those applications needing to send critical
controls that might not be applicable to both the context operation and
any implicit LDAP "bind" operation.
A typical user program would do the following:


InitialLdapContext lctx = new InitialLdapContext(env, critConnCtls);
lctx.setRequestControls(critModCtls);
lctx.modifyAttributes(name, mods);
Controls[] respCtls =  lctx.getResponseControls();
It specifies first the critical controls for creating the initial context
(critConnCtls), and then sets the context's request controls
(critModCtls) for the context operation. If for some reason
lctx needs to reconnect to the server, it will use
critConnCtls. See the LdapContext interface for
more discussion about request controls.

Service provider implementors should read the "Service Provider" section
in the LdapContext class description for implementation details.

This interface represents a context in which you can perform
 operations with LDAPv3-style controls and perform LDAPv3-style
 extended operations.

 For applications that do not require such controls or extended
 operations, the more generic javax.naming.directory.DirContext
 should be used instead.

 Usage Details About Controls

 This interface provides support for LDAP v3 controls.
 At a high level, this support allows a user
 program to set request controls for LDAP operations that are executed
 in the course of the user program's invocation of
 Context/DirContext
 methods, and read response controls resulting from LDAP operations.
 At the implementation level, there are some details that developers of
 both the user program and service providers need to understand in order
 to correctly use request and response controls.

 Request Controls

 There are two types of request controls:

 Request controls that affect how a connection is created
 Request controls that affect context methods


 The former is used whenever a connection needs to be established or
 re-established with an LDAP server. The latter is used when all other
 LDAP operations are sent to the LDAP server.  The reason why a
 distinction between these two types of request controls is necessary
 is because JNDI is a high-level API that does not deal directly with
 connections.  It is the job of service providers to do any necessary
 connection management. Consequently, a single
 connection may be shared by multiple context instances, and a service provider
 is free to use its own algorithms to conserve connection and network
 usage. Thus, when a method is invoked on the context instance, the service
 provider might need to do some connection management in addition to
 performing the corresponding LDAP operations. For connection management,
 it uses the connection request controls, while for the normal
 LDAP operations, it uses the context request controls.
Unless explicitly qualified, the term "request controls" refers to
 context request controls.

 Context Request Controls
 There are two ways in which a context instance gets its request controls:

 ldapContext.newInstance(reqCtls)
 ldapContext.setRequestControls(reqCtls)

 where ldapContext is an instance of LdapContext.
 Specifying null or an empty array for reqCtls
 means no request controls.
 newInstance() creates a new instance of a context using
 reqCtls, while setRequestControls()
 updates an existing context instance's request controls to reqCtls.

 Unlike environment properties, request controls of a context instance
 are not inherited by context instances that are derived from
 it.  Derived context instances have null as their context
 request controls.  You must set the request controls of a derived context
 instance explicitly using setRequestControls().

 A context instance's request controls are retrieved using
 the method getRequestControls().

 Connection Request Controls
 There are three ways in which connection request controls are set:


 new InitialLdapContext(env, connCtls)
 refException.getReferralContext(env, connCtls)
 ldapContext.reconnect(connCtls);

 where refException is an instance of
 LdapReferralException, and ldapContext is an
 instance of LdapContext.
 Specifying null or an empty array for connCtls
 means no connection request controls.

 Like environment properties, connection request controls of a context
 are inherited by contexts that are derived from it.
 Typically, you initialize the connection request controls using the
 InitialLdapContext constructor or
 LdapReferralContext.getReferralContext(). These connection
 request controls are inherited by contexts that share the same
 connection--that is, contexts derived from the initial or referral
 contexts.

 Use reconnect() to change the connection request controls of
 a context.
 Invoking ldapContext.reconnect() affects only the
 connection used by ldapContext and any new contexts instances that are
 derived form ldapContext. Contexts that previously shared the
 connection with ldapContext remain unchanged. That is, a context's
 connection request controls must be explicitly changed and is not
 affected by changes to another context's connection request
 controls.

 A context instance's connection request controls are retrieved using
 the method getConnectControls().

 Service Provider Requirements

 A service provider supports connection and context request controls
 in the following ways.  Context request controls must be associated on
 a per context instance basis while connection request controls must be
 associated on a per connection instance basis.  The service provider
 must look for the connection request controls in the environment
 property "java.naming.ldap.control.connect" and pass this environment
 property on to context instances that it creates.

 Response Controls

 The method LdapContext.getResponseControls() is used to
 retrieve the response controls generated by LDAP operations executed
 as the result of invoking a Context/DirContext
 operation. The result is all of the responses controls generated
 by the underlying LDAP operations, including any implicit reconnection.
 To get only the reconnection response controls,
 use reconnect() followed by getResponseControls().

 Parameters

 A Control[] array
 passed as a parameter to any method is owned by the caller.
 The service provider will not modify the array or keep a reference to it,
 although it may keep references to the individual Control objects
 in the array.
 A Control[] array returned by any method is immutable, and may
 not subsequently be modified by either the caller or the service provider.

This class represents a distinguished name as specified by
RFC 2253.
A distinguished name, or DN, is composed of an ordered list of
components called relative distinguished names, or RDNs.
Details of a DN's syntax are described in RFC 2253.

This class resolves a few ambiguities found in RFC 2253
as follows:

 RFC 2253 leaves the term "whitespace" undefined. The
     ASCII space character 0x20 (" ") is used in its place.
 Whitespace is allowed on either side of ',', ';', '=', and '+'.
     Such whitespace is accepted but not generated by this code,
     and is ignored when comparing names.
 AttributeValue strings containing '=' or non-leading '#'
     characters (unescaped) are accepted.


String names passed to LdapName or returned by it
use the full Unicode character set. They may also contain
characters encoded into UTF-8 with each octet represented by a
three-character substring such as "\\B4".
They may not, however, contain characters encoded into UTF-8 with
each octet represented by a single character in the string:  the
meaning would be ambiguous.

LdapName will properly parse all valid names, but
does not attempt to detect all possible violations when parsing
invalid names.  It is "generous" in accepting invalid names.
The "validity" of a name is determined ultimately when it
is supplied to an LDAP server, which may accept or
reject the name based on factors such as its schema information
and interoperability considerations.

When names are tested for equality, attribute types, both binary
and string values, are case-insensitive.
String values with different but equivalent usage of quoting,
escaping, or UTF8-hex-encoding are considered equal.  The order of
components in multi-valued RDNs (such as "ou=Sales+cn=Bob") is not
significant.

The components of a LDAP name, that is, RDNs, are numbered. The
indexes of a LDAP name with n RDNs range from 0 to n-1.
This range may be written as [0,n).
The right most RDN is at index 0, and the left most RDN is at
index n-1. For example, the distinguished name:
"CN=Steve Kille, O=Isode Limited, C=GB" is numbered in the following
sequence ranging from 0 to 2: {C=GB, O=Isode Limited, CN=Steve Kille}. An
empty LDAP name is represented by an empty RDN list.

Concurrent multithreaded read-only access of an instance of
LdapName need not be synchronized.

Unless otherwise noted, the behavior of passing a null argument
to a constructor or method in this class will cause a
NullPointerException to be thrown.

This abstract class is used to represent an LDAP referral exception.
It extends the base ReferralException by providing a
getReferralContext() method that accepts request controls.
LdapReferralException is an abstract class. Concrete implementations of it
determine its synchronization and serialization properties.

A Control[] array passed as a parameter to
the getReferralContext() method is owned by the caller.
The service provider will not modify the array or keep a reference to it,
although it may keep references to the individual Control objects
in the array.

Requests that referral and other special LDAP objects be manipulated
as normal LDAP objects. It enables the requestor to interrogate or
update such objects.

This class implements the LDAPv3 Request Control for ManageDsaIT
as defined in
RFC 3296.

The control has no control value.

// Open an LDAP association
LdapContext ctx = new InitialLdapContext();

// Activate paged results
int pageSize = 20; // 20 entries per page
byte[] cookie = null;
int total;
ctx.setRequestControls(new Control[]{
    new PagedResultsControl(pageSize, Control.CRITICAL) });

do {
    // Perform the search
    NamingEnumeration results =
        ctx.search("", "(objectclass=*)", new SearchControls());

    // Iterate over a batch of search results
    while (results != null && results.hasMore()) {
        // Display an entry
        SearchResult entry = (SearchResult)results.next();
        System.out.println(entry.getName());
        System.out.println(entry.getAttributes());

        // Handle the entry's response controls (if any)
        if (entry instanceof HasControls) {
            // ((HasControls)entry).getControls();
        }
    }
    // Examine the paged results control response
    Control[] controls = ctx.getResponseControls();
    if (controls != null) {
        for (int i = 0; i < controls.length; i++) {
            if (controls[i] instanceof PagedResultsResponseControl) {
                PagedResultsResponseControl prrc =
                    (PagedResultsResponseControl)controls[i];
                total = prrc.getResultSize();
                cookie = prrc.getCookie();
            } else {
                // Handle other response controls (if any)
            }
        }
    }

    // Re-activate paged results
    ctx.setRequestControls(new Control[]{
        new PagedResultsControl(pageSize, cookie, Control.CRITICAL) });
} while (cookie != null);

// Close the LDAP association
ctx.close();
...

realSearchControlValue ::= SEQUENCE {
    size      INTEGER (0..maxInt),
                      -- requested page size from client
                      -- result set size estimate from server
    cookie    OCTET STRING
}

Requests that the results of a search operation be returned by the LDAP
server in batches of a specified size.
The requestor controls the rate at which batches are returned by the rate
at which it invokes search operations.

The following code sample shows how the class may be used:


    // Open an LDAP association
    LdapContext ctx = new InitialLdapContext();

    // Activate paged results
    int pageSize = 20; // 20 entries per page
    byte[] cookie = null;
    int total;
    ctx.setRequestControls(new Control[]{
        new PagedResultsControl(pageSize, Control.CRITICAL) });

    do {
        // Perform the search
        NamingEnumeration results =
            ctx.search("", "(objectclass=*)", new SearchControls());

        // Iterate over a batch of search results
        while (results != null && results.hasMore()) {
            // Display an entry
            SearchResult entry = (SearchResult)results.next();
            System.out.println(entry.getName());
            System.out.println(entry.getAttributes());

            // Handle the entry's response controls (if any)
            if (entry instanceof HasControls) {
                // ((HasControls)entry).getControls();
            }
        }
        // Examine the paged results control response
        Control[] controls = ctx.getResponseControls();
        if (controls != null) {
            for (int i = 0; i < controls.length; i++) {
                if (controls[i] instanceof PagedResultsResponseControl) {
                    PagedResultsResponseControl prrc =
                        (PagedResultsResponseControl)controls[i];
                    total = prrc.getResultSize();
                    cookie = prrc.getCookie();
                } else {
                    // Handle other response controls (if any)
                }
            }
        }

        // Re-activate paged results
        ctx.setRequestControls(new Control[]{
            new PagedResultsControl(pageSize, cookie, Control.CRITICAL) });
    } while (cookie != null);

    // Close the LDAP association
    ctx.close();
    ...

This class implements the LDAPv3 Control for paged-results as defined in
RFC 2696.

The control's value has the following ASN.1 definition:


    realSearchControlValue ::= SEQUENCE {
        size      INTEGER (0..maxInt),
                          -- requested page size from client
                          -- result set size estimate from server
        cookie    OCTET STRING
    }

realSearchControlValue ::= SEQUENCE {
    size      INTEGER (0..maxInt),
                      -- requested page size from client
                      -- result set size estimate from server
    cookie    OCTET STRING
}

Indicates the end of a batch of search results.
Contains an estimate of the total number of entries in the result set
and an opaque cookie. The cookie must be supplied to the next search
operation in order to get the next batch of results.

The code sample in PagedResultsControl shows how this class may
be used.

This class implements the LDAPv3 Response Control for
paged-results as defined in
RFC 2696.

The control's value has the following ASN.1 definition:


    realSearchControlValue ::= SEQUENCE {
        size      INTEGER (0..maxInt),
                          -- requested page size from client
                          -- result set size estimate from server
        cookie    OCTET STRING
    }

 Rdn rdn = new Rdn("cn", "Juicy, Fruit");
 System.out.println(rdn.toString());

 Rdn rdn = new Rdn("cn=Juicy\\, Fruit");
 System.out.println(rdn.toString());

This class represents a relative distinguished name, or RDN, which is a
component of a distinguished name as specified by
RFC 2253.
An example of an RDN is "OU=Sales+CN=J.Smith". In this example,
the RDN consist of multiple attribute type/value pairs. The
RDN is parsed as described in the class description for
LdapName.

The Rdn class represents an RDN as attribute type/value mappings,
which can be viewed using
Attributes.
In addition, it contains convenience methods that allow easy retrieval
of type and value when the Rdn consist of a single type/value pair,
which is how it appears in a typical usage.
It also contains helper methods that allow escaping of the unformatted
attribute value and unescaping of the value formatted according to the
escaping syntax defined in RFC2253. For methods that take or return
attribute value as an Object, the value is either a String
(in unescaped form) or a byte array.

Rdn will properly parse all valid RDNs, but
does not attempt to detect all possible violations when parsing
invalid RDNs. It is "generous" in accepting invalid RDNs.
The "validity" of a name is determined ultimately when it
is supplied to an LDAP server, which may accept or
reject the name based on factors such as its schema information
and interoperability considerations.


The following code example shows how to construct an Rdn using the
constructor that takes type and value as arguments:


     Rdn rdn = new Rdn("cn", "Juicy, Fruit");
     System.out.println(rdn.toString());
The last line will print cn=Juicy\, Fruit. The
unescapeValue() method can be
used to unescape the escaped comma resulting in the original
value "Juicy, Fruit". The escapeValue() method adds the escape back preceding the comma.

This class can be instantiated by a string representation
of the RDN defined in RFC 2253 as shown in the following code example:


     Rdn rdn = new Rdn("cn=Juicy\\, Fruit");
     System.out.println(rdn.toString());
The last line will print cn=Juicy\, Fruit.

Concurrent multithreaded read-only access of an instance of
Rdn need not be synchronized.

Unless otherwise noted, the behavior of passing a null argument
to a constructor or method in this class will cause NullPointerException
to be thrown.

// Open an LDAP association
LdapContext ctx = new InitialLdapContext();

// Activate sorting
String sortKey = "cn";
ctx.setRequestControls(new Control[]{
    new SortControl(sortKey, Control.CRITICAL) });

// Perform a search
NamingEnumeration results =
    ctx.search("", "(objectclass=*)", new SearchControls());

// Iterate over search results
while (results != null && results.hasMore()) {
    // Display an entry
    SearchResult entry = (SearchResult)results.next();
    System.out.println(entry.getName());
    System.out.println(entry.getAttributes());

    // Handle the entry's response controls (if any)
    if (entry instanceof HasControls) {
        // ((HasControls)entry).getControls();
    }
}
// Examine the sort control response
Control[] controls = ctx.getResponseControls();
if (controls != null) {
    for (int i = 0; i < controls.length; i++) {
        if (controls[i] instanceof SortResponseControl) {
            SortResponseControl src = (SortResponseControl)controls[i];
            if (! src.isSorted()) {
                throw src.getException();
            }
        } else {
            // Handle other response controls (if any)
        }
    }
}

// Close the LDAP association
ctx.close();
...

SortKeyList ::= SEQUENCE OF SEQUENCE {
    attributeType     AttributeDescription,
    orderingRule  [0] MatchingRuleId OPTIONAL,
    reverseOrder  [1] BOOLEAN DEFAULT FALSE }

Requests that the results of a search operation be sorted by the LDAP server
before being returned.
The sort criteria are specified using an ordered list of one or more sort
keys, with associated sort parameters.
Search results are sorted at the LDAP server according to the parameters
supplied in the sort control and then returned to the requestor. If sorting
is not supported at the server (and the sort control is marked as critical)
then the search operation is not performed and an error is returned.

The following code sample shows how the class may be used:


    // Open an LDAP association
    LdapContext ctx = new InitialLdapContext();

    // Activate sorting
    String sortKey = "cn";
    ctx.setRequestControls(new Control[]{
        new SortControl(sortKey, Control.CRITICAL) });

    // Perform a search
    NamingEnumeration results =
        ctx.search("", "(objectclass=*)", new SearchControls());

    // Iterate over search results
    while (results != null && results.hasMore()) {
        // Display an entry
        SearchResult entry = (SearchResult)results.next();
        System.out.println(entry.getName());
        System.out.println(entry.getAttributes());

        // Handle the entry's response controls (if any)
        if (entry instanceof HasControls) {
            // ((HasControls)entry).getControls();
        }
    }
    // Examine the sort control response
    Control[] controls = ctx.getResponseControls();
    if (controls != null) {
        for (int i = 0; i < controls.length; i++) {
            if (controls[i] instanceof SortResponseControl) {
                SortResponseControl src = (SortResponseControl)controls[i];
                if (! src.isSorted()) {
                    throw src.getException();
                }
            } else {
                // Handle other response controls (if any)
            }
        }
    }

    // Close the LDAP association
    ctx.close();
    ...

This class implements the LDAPv3 Request Control for server-side sorting
as defined in
RFC 2891.

The control's value has the following ASN.1 definition:


    SortKeyList ::= SEQUENCE OF SEQUENCE {
        attributeType     AttributeDescription,
        orderingRule  [0] MatchingRuleId OPTIONAL,
        reverseOrder  [1] BOOLEAN DEFAULT FALSE }

A sort key and its associated sort parameters.
This class implements a sort key which is used by the LDAPv3
Control for server-side sorting of search results as defined in
RFC 2891.

SortResult ::= SEQUENCE {
   sortResult  ENUMERATED {
       success                   (0), -- results are sorted
       operationsError           (1), -- server internal failure
       timeLimitExceeded         (3), -- timelimit reached before
                                      -- sorting was completed
       strongAuthRequired        (8), -- refused to return sorted
                                      -- results via insecure
                                      -- protocol
       adminLimitExceeded       (11), -- too many matching entries
                                      -- for the server to sort
       noSuchAttribute          (16), -- unrecognized attribute
                                      -- type in sort key
       inappropriateMatching    (18), -- unrecognized or inappro-
                                      -- priate matching rule in
                                      -- sort key
       insufficientAccessRights (50), -- refused to return sorted
                                      -- results to this client
       busy                     (51), -- too busy to process
       unwillingToPerform       (53), -- unable to sort
       other                    (80)
       },
 attributeType [0] AttributeType OPTIONAL }

Indicates whether the requested sort of search results was successful or not.
When the result code indicates success then the results have been sorted as
requested. Otherwise the sort was unsuccessful and additional details
regarding the cause of the error may have been provided by the server.

The code sample in SortControl shows how this class may be used.

This class implements the LDAPv3 Response Control for server-side sorting
as defined in
RFC 2891.

The control's value has the following ASN.1 definition:


    SortResult ::= SEQUENCE {
       sortResult  ENUMERATED {
           success                   (0), -- results are sorted
           operationsError           (1), -- server internal failure
           timeLimitExceeded         (3), -- timelimit reached before
                                          -- sorting was completed
           strongAuthRequired        (8), -- refused to return sorted
                                          -- results via insecure
                                          -- protocol
           adminLimitExceeded       (11), -- too many matching entries
                                          -- for the server to sort
           noSuchAttribute          (16), -- unrecognized attribute
                                          -- type in sort key
           inappropriateMatching    (18), -- unrecognized or inappro-
                                          -- priate matching rule in
                                          -- sort key
           insufficientAccessRights (50), -- refused to return sorted
                                          -- results to this client
           busy                     (51), -- too busy to process
           unwillingToPerform       (53), -- unable to sort
           other                    (80)
           },
     attributeType [0] AttributeType OPTIONAL }

This class implements the LDAPv3 Extended Request for StartTLS as
defined in
Lightweight Directory
Access Protocol (v3): Extension for Transport Layer Security

The object identifier for StartTLS is 1.3.6.1.4.1.1466.20037
and no extended request value is defined.

StartTlsRequest/StartTlsResponse are used to establish
a TLS connection over the existing LDAP connection associated with
the JNDI context on which extendedOperation() is invoked.
Typically, a JNDI program uses these classes as follows.


import javax.naming.ldap.*;

// Open an LDAP association
LdapContext ctx = new InitialLdapContext();

// Perform a StartTLS extended operation
StartTlsResponse tls =
    (StartTlsResponse) ctx.extendedOperation(new StartTlsRequest());

// Open a TLS connection (over the existing LDAP association) and get details
// of the negotiated TLS session: cipher suite, peer certificate, etc.
SSLSession session = tls.negotiate();

// ... use ctx to perform protected LDAP operations

// Close the TLS connection (revert back to the underlying LDAP association)
tls.close();

// ... use ctx to perform unprotected LDAP operations

// Close the LDAP association
ctx.close;

This class implements the LDAPv3 Extended Response for StartTLS as
defined in
Lightweight Directory
Access Protocol (v3): Extension for Transport Layer Security

The object identifier for StartTLS is 1.3.6.1.4.1.1466.20037
and no extended response value is defined.


The Start TLS extended request and response are used to establish
a TLS connection over the existing LDAP connection associated with
the JNDI context on which extendedOperation() is invoked.
Typically, a JNDI program uses the StartTLS extended request and response
classes as follows.


import javax.naming.ldap.*;

// Open an LDAP association
LdapContext ctx = new InitialLdapContext();

// Perform a StartTLS extended operation
StartTlsResponse tls =
    (StartTlsResponse) ctx.extendedOperation(new StartTlsRequest());

// Open a TLS connection (over the existing LDAP association) and get details
// of the negotiated TLS session: cipher suite, peer certificate, ...
SSLSession session = tls.negotiate();

// ... use ctx to perform protected LDAP operations

// Close the TLS connection (revert back to the underlying LDAP association)
tls.close();

// ... use ctx to perform unprotected LDAP operations

// Close the LDAP association
ctx.close;

This interface represents an unsolicited notification as defined in
RFC 2251.
An unsolicited notification is sent by the LDAP server to the LDAP
client without any provocation from the client.
Its format is that of an extended response (ExtendedResponse).

This class represents an event fired in response to an unsolicited
notification sent by the LDAP server.

This interface is for handling UnsolicitedNotificationEvent.
"Unsolicited notification" is defined in
RFC 2251.
It allows the server to send unsolicited notifications to the client.
A UnsolicitedNotificationListener must:

Implement this interface and its method
Implement NamingListener.namingExceptionThrown() so
that it will be notified of exceptions thrown while attempting to
collect unsolicited notification events.
Register with the context using one of the addNamingListener()
methods from EventContext or EventDirContext.
Only the NamingListener argument of these methods are applicable;
the rest are ignored for a UnsolicitedNotificationListener.
(These arguments might be applicable to the listener if it implements
other listener interfaces).

This exception is thrown when a method
terminates abnormally due to a user or system specified limit.
This is different from a InsufficientResourceException in that
LimitExceededException is due to a user/system specified limit.
For example, running out of memory to complete the request would
be an insufficient resource. The client asking for 10 answers and
getting back 11 is a size limit exception.

Examples of these limits include client and server configuration
limits such as size, time, number of hops, etc.

Synchronization and serialization issues that apply to NamingException
apply directly here.

This exception is used to describe problems encounter while resolving links.
Addition information is added to the base NamingException for pinpointing
the problem with the link.

Analogous to how NamingException captures name resolution information,
LinkException captures "link"-name resolution information pinpointing
the problem encountered while resolving a link. All these fields may
be null.

 Link Resolved Name. Portion of link name that has been resolved.
 Link Resolved Object. Object to which resolution of link name proceeded.
 Link Remaining Name. Portion of link name that has not been resolved.
 Link Explanation. Detail explaining why link resolution failed.



A LinkException instance is not synchronized against concurrent
multithreaded access. Multiple threads trying to access and modify
a single LinkException instance should lock the object.

This exception is thrown when
a loop was detected will attempting to resolve a link, or an implementation
specific limit on link counts has been reached.

Synchronization and serialization issues that apply to LinkException
apply directly here.

This class represents a Reference whose contents is a name, called the link name,
that is bound to an atomic name in a context.

The name is a URL, or a name to be resolved relative to the initial
context, or if the first character of the name is ".", the name
is relative to the context in which the link is bound.

Normal resolution of names in context operations always follow links.
Resolution of the link name itself may cause resolution to pass through
other  links. This gives rise to the possibility of a cycle of links whose
resolution could not terminate normally. As a simple means to avoid such
non-terminating resolutions, service providers may define limits on the
number of links that may be involved in any single operation invoked
by the caller.

A LinkRef contains a single StringRefAddr, whose type is "LinkAddress",
and whose contents is the link name. The class name field of the
Reference is that of this (LinkRef) class.

LinkRef is bound to a name using the normal Context.bind()/rebind(), and
DirContext.bind()/rebind(). Context.lookupLink() is used to retrieve the link
itself if the terminal atomic name is bound to a link.

Many naming systems support a native notion of link that may be used
within the naming system itself. JNDI does not specify whether
there is any relationship between such native links and JNDI links.

A LinkRef instance is not synchronized against concurrent access by multiple
threads. Threads that need to access a LinkRef instance concurrently should
synchronize amongst themselves and provide the necessary locking.

This exception is thrown when a malformed link was encountered while
resolving or constructing a link.

Synchronization and serialization issues that apply to LinkException
apply directly here.

The Name interface represents a generic name -- an ordered
sequence of components.  It can be a composite name (names that
span multiple namespaces), or a compound name (names that are
used within individual hierarchical naming systems).

 There can be different implementations of Name; for example,
composite names, URLs, or namespace-specific compound names.

 The components of a name are numbered.  The indexes of a name
with N components range from 0 up to, but not including, N.  This
range may be written as [0,N).
The most significant component is at index 0.
An empty name has no components.

 None of the methods in this interface accept null as a valid
value for a parameter that is a name or a name component.
Likewise, methods that return a name or name component never return null.

 An instance of a Name may not be synchronized against
concurrent multithreaded access if that access is not read-only.

This exception is thrown by methods to indicate that
a binding cannot be added because the name is already bound to
another object.

Synchronization and serialization issues that apply to NamingException
apply directly here.

This class represents the object name and class name pair of a binding
found in a context.

A context consists of name-to-object bindings.
The NameClassPair class represents the name and the
class of the bound object. It consists
of a name and a string representing the
package-qualified class name.

Use subclassing for naming systems that generate contents of
a name/class pair dynamically.

A NameClassPair instance is not synchronized against concurrent
access by multiple threads. Threads that need to access a NameClassPair
concurrently should synchronize amongst themselves and provide
the necessary locking.

This exception is thrown when a component of the name cannot be resolved
because it is not bound.

Synchronization and serialization issues that apply to NamingException
apply directly here.

This interface is used for parsing names from a hierarchical
namespace.  The NameParser contains knowledge of the syntactic
information (like left-to-right orientation, name separator, etc.)
needed to parse names.

The equals() method, when used to compare two NameParsers, returns
true if and only if they serve the same namespace.

This interface is for enumerating lists returned by
methods in the javax.naming and javax.naming.directory packages.
It extends Enumeration to allow as exceptions to be thrown during
the enumeration.

When a method such as list(), listBindings(), or search() returns
a NamingEnumeration, any exceptions encountered are reserved until
all results have been returned. At the end of the enumeration, the
exception is thrown (by hasMore());

For example, if the list() is
returning only a partial answer, the corresponding exception would
be PartialResultException. list() would first return a NamingEnumeration.
When the last of the results has been returned by the NamingEnumeration's
next(), invoking hasMore() would result in PartialResultException being thrown.

In another example, if a search() method was invoked with a specified
size limit of 'n'. If the answer consists of more than 'n' results,
search() would first return a NamingEnumeration.
When the n'th result has been returned by invoking next() on the
NamingEnumeration, a SizeLimitExceedException would then thrown when
hasMore() is invoked.

Note that if the program uses hasMoreElements() and nextElement() instead
to iterate through the NamingEnumeration, because these methods
cannot throw exceptions, no exception will be thrown. Instead,
in the previous example, after the n'th result has been returned by
nextElement(), invoking hasMoreElements() would return false.

Note also that NoSuchElementException is thrown if the program invokes
next() or nextElement() when there are no elements left in the enumeration.
The program can always avoid this exception by using hasMore() and
hasMoreElements() to check whether the end of the enumeration has been reached.

If an exception is thrown during an enumeration,
the enumeration becomes invalid.
Subsequent invocation of any method on that enumeration
will yield undefined results.

This is the superclass of all exceptions thrown by
operations in the Context and DirContext interfaces.
The nature of the failure is described by the name of the subclass.
This exception captures the information pinpointing where the operation
failed, such as where resolution last proceeded to.

 Resolved Name. Portion of name that has been resolved.
 Resolved Object. Object to which resolution of name proceeded.
 Remaining Name. Portion of name that has not been resolved.
 Explanation. Detail explaining why name resolution failed.
 Root Exception. The exception that caused this naming exception
                    to be thrown.

null is an acceptable value for any of these fields. When null,
it means that no such information has been recorded for that field.

A NamingException instance is not synchronized against concurrent
multithreaded access. Multiple threads trying to access and modify
a single NamingException instance should lock the object.

This exception has been retrofitted to conform to
the general purpose exception-chaining mechanism.  The
root exception (or root cause) is the same object as the
cause returned by the Throwable.getCause() method.

This is the superclass of security-related exceptions
thrown by operations in the Context and DirContext interfaces.
The nature of the failure is described by the name of the subclass.

If the program wants to handle this exception in particular, it
should catch NamingSecurityException explicitly before attempting to
catch NamingException. A program might want to do this, for example,
if it wants to treat security-related exceptions specially from
other sorts of naming exception.

Synchronization and serialization issues that apply to NamingException
apply directly here.

This exception is thrown when no initial context implementation
can be created.  The policy of how an initial context implementation
is selected is described in the documentation of the InitialContext class.

This exception can be thrown during any interaction with the
InitialContext, not only when the InitialContext is constructed.
For example, the implementation of the initial context might lazily
retrieve the context only when actual methods are invoked on it.
The application should not have any dependency on when the existence
of an initial context is determined.

Synchronization and serialization issues that apply to NamingException
apply directly here.

This exception is thrown when attempting to perform an operation
for which the client has no permission. The access control/permission
model is dictated by the directory/naming server.


Synchronization and serialization issues that apply to NamingException
apply directly here.

This exception is thrown when a naming operation proceeds to a point
where a context is required to continue the operation, but the
resolved object is not a context. For example, Context.destroy() requires
that the named object be a context. If it is not, NotContextException
is thrown. Another example is a non-context being encountered during
the resolution phase of the Context methods.

It is also thrown when a particular subtype of context is required,
such as a DirContext, and the resolved object is a context but not of
the required subtype.

Synchronization and serialization issues that apply to NamingException
apply directly here.

This exception is thrown when a context implementation does not support
the operation being invoked.
For example, if a server does not support the Context.bind() method
it would throw OperationNotSupportedException when the bind() method
is invoked on it.

Synchronization and serialization issues that apply to NamingException
apply directly here.

This exception is thrown to indicate that the result being returned
or returned so far is partial, and that the operation cannot
be completed.  For example, when listing a context, this exception
indicates that returned results only represents some of the bindings
in the context.

Synchronization and serialization issues that apply to NamingException
apply directly here.

This class represents the address of a communications end-point.
It consists of a type that describes the communication mechanism
and an address contents determined by an RefAddr subclass.

For example, an address type could be "BSD Printer Address",
which specifies that it is an address to be used with the BSD printing
protocol. Its contents could be the machine name identifying the
location of the printer server that understands this protocol.

A RefAddr is contained within a Reference.

RefAddr is an abstract class. Concrete implementations of it
determine its synchronization properties.

This class represents a reference to an object that is found outside of
the naming/directory system.

Reference provides a way of recording address information about
objects which themselves are not directly bound to the naming/directory system.

A Reference consists of an ordered list of addresses and class information
about the object being referenced.
Each address in the list identifies a communications endpoint
for the same conceptual object.  The "communications endpoint"
is information that indicates how to contact the object. It could
be, for example, a network address, a location in memory on the
local machine, another process on the same machine, etc.
The order of the addresses in the list may be of significance
to object factories that interpret the reference.

Multiple addresses may arise for
various reasons, such as replication or the object offering interfaces
over more than one communication mechanism.  The addresses are indexed
starting with zero.

A Reference also contains information to assist in creating an instance
of the object to which this Reference refers.  It contains the class name
of that object, and the class name and location of the factory to be used
to create the object.
The class factory location is a space-separated list of URLs representing
the class path used to load the factory.  When the factory class (or
any class or resource upon which it depends) needs to be loaded,
each URL is used (in order) to attempt to load the class.

A Reference instance is not synchronized against concurrent access by multiple
threads. Threads that need to access a single Reference concurrently should
synchronize amongst themselves and provide the necessary locking.

This interface is implemented by an object that can provide a
Reference to itself.

A Reference represents a way of recording address information about
objects which themselves are not directly bound to the naming system.
Such objects can implement the Referenceable interface as a way
for programs that use that object to determine what its Reference is.
For example, when binding a object, if an object implements the
Referenceable interface, getReference() can be invoked on the object to
get its Reference to use for binding.

This abstract class is used to represent a referral exception,
which is generated in response to a referral
such as that returned by LDAP v3 servers.

A service provider provides
a subclass of ReferralException by providing implementations
for getReferralInfo() and getReferralContext() (and appropriate
constructors and/or corresponding "set" methods).

The following code sample shows how ReferralException can be used.
while (true) {
         try {
             bindings = ctx.listBindings(name);
             while (bindings.hasMore()) {
                 b = bindings.next();
                 ...
             }
             break;
         } catch (ReferralException e) {
             ctx = e.getReferralContext();
         }
     }


ReferralException is an abstract class. Concrete implementations
determine its synchronization and serialization properties.

An environment parameter passed to the getReferralContext()
method is owned by the caller.
The service provider will not modify the object or keep a reference to it,
but may keep a reference to a clone of it.

This exception is thrown when attempting to communicate with a
directory or naming service and that service is not available.
It might be unavailable for different reasons. For example,
the server might be too busy to service the request, or the server
might not be registered to service any requests, etc.

Synchronization and serialization issues that apply to NamingException
apply directly here.

This exception is thrown when a method
produces a result that exceeds a size-related limit.
This can happen, for example, if the result contains
more objects than the user requested, or when the size
of the result exceeds some implementation-specific limit.

Synchronization and serialization issues that apply to NamingException
apply directly here.

This class contains methods for supporting DirContext
implementations.

This class is an extension of NamingManager.  It contains methods
for use by service providers for accessing object factories and
state factories, and for getting continuation contexts for
supporting federation.

DirectoryManager is safe for concurrent access by multiple threads.

Except as otherwise noted,
a Name, Attributes, or environment parameter
passed to any method is owned by the caller.
The implementation will not modify the object or keep a reference
to it, although it may keep a reference to a clone or copy.

This interface represents a factory for creating an object given
an object and attributes about the object.

The JNDI framework allows for object implementations to
be loaded in dynamically via object factories. See
ObjectFactory for details.

A DirObjectFactory extends ObjectFactory by allowing
an Attributes instance
to be supplied to the getObjectInstance() method.
DirObjectFactory implementations are intended to be used by DirContext
service providers. The service provider, in addition reading an
object from the directory, might already have attributes that
are useful for the object factory to check to see whether the
factory is supposed to process the object. For instance, an LDAP-style
service provider might have read the "objectclass" of the object.
A CORBA object factory might be interested only in LDAP entries
with "objectclass=corbaObject". By using the attributes supplied by
the LDAP service provider, the CORBA object factory can quickly
eliminate objects that it need not worry about, and non-CORBA object
factories can quickly eliminate CORBA-related LDAP entries.

This interface represents a factory for obtaining the state of an
object and corresponding attributes for binding.

The JNDI framework allows for object implementations to
be loaded in dynamically via object factories.

A DirStateFactory extends StateFactory
by allowing an Attributes instance
to be supplied to and be returned by the getStateToBind() method.
DirStateFactory implementations are intended to be used by
DirContext service providers.
When a caller binds an object using DirContext.bind(),
he might also specify a set of attributes to be bound with the object.
The object and attributes to be bound are passed to
the getStateToBind() method of a factory.
If the factory processes the object and attributes, it returns
a corresponding pair of object and attributes to be bound.
If the factory does not process the object, it must return null.

For example, a caller might bind a printer object with some printer-related
attributes.


ctx.rebind("inky", printer, printerAttrs);
An LDAP service provider for ctx uses a DirStateFactory
(indirectly via DirectoryManager.getStateToBind())
and gives it printer and printerAttrs. A factory for
an LDAP directory might turn printer into a set of attributes
and merge that with printerAttrs. The service provider then
uses the resulting attributes to create an LDAP entry and updates
the directory.

 Since DirStateFactory extends StateFactory, it
has two getStateToBind() methods, where one
differs from the other by the attributes
argument. DirectoryManager.getStateToBind() will only use
the form that accepts the attributes argument, while
NamingManager.getStateToBind() will only use the form that
does not accept the attributes argument.

 Either form of the getStateToBind() method of a
DirStateFactory may be invoked multiple times, possibly using different
parameters.  The implementation is thread-safe.

An object/attributes pair for returning the result of
DirStateFactory.getStateToBind().

This interface represents a factory that creates an initial context.

The JNDI framework allows for different initial context implementations
to be specified at runtime.  The initial context is created using
an initial context factory.
An initial context factory must implement the InitialContextFactory
interface, which provides a method for creating instances of initial
context that implement the Context interface.
In addition, the factory class must be public and must have a public
constructor that accepts no arguments.

This interface represents a builder that creates initial context factories.

The JNDI framework allows for different initial context implementations
to be specified at runtime.  An initial context is created using
an initial context factory. A program can install its own builder
that creates initial context factories, thereby overriding the
default policies used by the framework, by calling
NamingManager.setInitialContextFactoryBuilder().
The InitialContextFactoryBuilder interface must be implemented by
such a builder.

This class contains methods for creating context objects
and objects referred to by location information in the naming
or directory service.

This class cannot be instantiated.  It has only static methods.

The mention of URL in the documentation for this class refers to
a URL string as defined by RFC 1738 and its related RFCs. It is
any string that conforms to the syntax described therein, and
may not always have corresponding support in the java.net.URL
class or Web browsers.

NamingManager is safe for concurrent access by multiple threads.

Except as otherwise noted,
a Name or environment parameter
passed to any method is owned by the caller.
The implementation will not modify the object or keep a reference
to it, although it may keep a reference to a clone or copy.

This interface represents a factory for creating an object.

The JNDI framework allows for object implementations to
be loaded in dynamically via object factories.
For example, when looking up a printer bound in the name space,
if the print service binds printer names to References, the printer
Reference could be used to create a printer object, so that
the caller of lookup can directly operate on the printer object
after the lookup.
An ObjectFactory is responsible
for creating objects of a specific type.  In the above example,
you may have a PrinterObjectFactory for creating Printer objects.

An object factory must implement the ObjectFactory interface.
In addition, the factory class must be public and must have a
public constructor that accepts no parameters.

The getObjectInstance() method of an object factory may
be invoked multiple times, possibly using different parameters.
The implementation is thread-safe.

The mention of URL in the documentation for this class refers to
a URL string as defined by RFC 1738 and its related RFCs. It is
any string that conforms to the syntax described therein, and
may not always have corresponding support in the java.net.URL
class or Web browsers.

This interface represents a builder that creates object factories.

The JNDI framework allows for object implementations to
be loaded in dynamically via object factories.
For example, when looking up a printer bound in the name space,
if the print service binds printer names to References, the printer
Reference could be used to create a printer object, so that
the caller of lookup can directly operate on the printer object
after the lookup.  An ObjectFactory is responsible for creating
objects of a specific type.  JNDI uses a default policy for using
and loading object factories.  You can override this default policy
by calling NamingManager.setObjectFactoryBuilder() with an ObjectFactoryBuilder,
which contains the program-defined way of creating/loading
object factories.
Any ObjectFactoryBuilder implementation must implement this
interface that for creating object factories.

This interface represents an "intermediate context" for name resolution.

The Resolver interface contains methods that are implemented by contexts
that do not support subtypes of Context, but which can act as
intermediate contexts for resolution purposes.

A Name parameter passed to any method is owned
by the caller.  The service provider will not modify the object
or keep a reference to it.
A ResolveResult object returned by any
method is owned by the caller.  The caller may subsequently modify it;
the service provider may not.

This class represents the result of resolution of a name.
It contains the object to which name was resolved, and the portion
of the name that has not been resolved.

A ResolveResult instance is not synchronized against concurrent
multithreaded access. Multiple threads trying to access and modify
a single ResolveResult instance should lock the object.

This interface represents a factory for obtaining the state of an
object for binding.

The JNDI framework allows for object implementations to
be loaded in dynamically via object factories.
For example, when looking up a printer bound in the name space,
if the print service binds printer names to References, the printer
Reference could be used to create a printer object, so that
the caller of lookup can directly operate on the printer object
after the lookup.
An ObjectFactory is responsible
for creating objects of a specific type.  In the above example,
you may have a PrinterObjectFactory for creating
Printer objects.

For the reverse process, when an object is bound into the namespace,
JNDI provides state factories.
Continuing with the printer example, suppose the printer object is
updated and rebound:


ctx.rebind("inky", printer);
The service provider for ctx uses a state factory
to obtain the state of printer for binding into its namespace.
A state factory for the Printer type object might return
a more compact object for storage in the naming system.

A state factory must implement the StateFactory interface.
In addition, the factory class must be public and must have a
public constructor that accepts no parameters.

The getStateToBind() method of a state factory may
be invoked multiple times, possibly using different parameters.
The implementation is thread-safe.

StateFactory is intended for use with service providers
that implement only the Context interface.
DirStateFactory is intended for use with service providers
that implement the DirContext interface.

This class represents the string form of the address of
a communications end-point.
It consists of a type that describes the communication mechanism
and a string contents specific to that communication mechanism.
The format and interpretation of
the address type and the contents of the address are based on
the agreement of three parties: the client that uses the address,
the object/server that can be reached using the address, and the
administrator or program that creates the address.

 An example of a string reference address is a host name.
Another example of a string reference address is a URL.

 A string reference address is immutable:
once created, it cannot be changed.  Multithreaded access to
a single StringRefAddr need not be synchronized.

This exception is thrown when a method
does not terminate within the specified time limit.
This can happen, for example, if the user specifies that
the method should take no longer than 10 seconds, and the
method fails to complete with 10 seconds.

 Synchronization and serialization issues that apply to NamingException
apply directly here.