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.