Generated by
JDiff

javax.naming.directory Documentation Differences

This file contains all the changes in documentation in the package javax.naming.directory as colored differences. Deletions are shown like this, and additions are shown like this.
If no deletions or additions are shown in an entry, the HTML tags will be what has changed. The new HTML tags are shown in the differences. If no documentation existed, and then some was added in a later version, this change is noted in the appropriate class pages of differences, but the change is not shown on this page. Only changes in existing text are shown here. Similarly, documentation which was inherited from another class or interface is not shown here.
Note that an HTML error in the new documentation may cause the display of other documentation changes to be presented incorrectly. For instance, failure to close a <code> tag will cause all subsequent paragraphs to be displayed differently.

Class Attribute

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. @author Rosanna Lee @author Scott Seligman @version 1.9 01/0212/0903 @see BasicAttribute @since 1.3


Class AttributeInUseException

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. @author Rosanna Lee @author Scott Seligman @version 1.4 005 01/0212/0203 @see DirContext#modifyAttributes @since 1.3


Class AttributeModificationException

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. @author Rosanna Lee @author Scott Seligman @version 1.7 01/0212/0903 @see DirContext#modifyAttributes @since 1.3


Class Attributes

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. @author Rosanna Lee @author Scott Seligman @version 1.7 01/0212/0903 @see DirContext#getAttributes @see DirContext#modifyAttributes @see DirContext#bind @see DirContext#rebind @see DirContext#createSubcontext @see DirContext#search @see BasicAttributes @since 1.3


Class BasicAttribute

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. @author Rosanna Lee @author Scott Seligman @version 1.910 01/0212/0903 @since 1.3


Class BasicAttributes

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. @author Rosanna Lee @author Scott Seligman @version 1.7 009 01/0212/0203 @see DirContext#getAttributes @see DirContext#modifyAttributes @see DirContext#bind @see DirContext#rebind @see DirContext#createSubcontext @see DirContext#search @since 1.3


Class DirContext

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:

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. @author Rosanna Lee @author Scott Seligman @author R. Vasudevan @version 1.8 01/0212/0903 @see javax.naming.Context @since 1.3


Class InitialDirContext

This class is the starting context for performing directory operations. The documentation in the class description of InitialContext (including those for synchronization) apply here. @author Rosanna Lee @author Scott Seligman @version 1.6 007 01/0212/0203 @see javax.naming.InitialContext @since 1.3

Class InvalidAttributeIdentifierException

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. @author Rosanna Lee @author Scott Seligman @version 1.4 005 01/0212/0203 @since 1.3


Class InvalidAttributeValueException

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. @author Rosanna Lee @author Scott Seligman @version 1.4 005 01/0212/0203 @since 1.3


Class InvalidAttributesException

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. @author Rosanna Lee @author Scott Seligman @version 1.4 005 01/0212/0203 @since 1.3


Class InvalidSearchControlsException

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. @author Rosanna Lee @author Scott Seligman @version 1.4 005 01/0212/0203 @since 1.3


Class InvalidSearchFilterException

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. @author Rosanna Lee @author Scott Seligman @version 1.4 005 01/0212/0203 @since 1.3


Class ModificationItem

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. @author Rosanna Lee @author Scott Seligman @version 1.4 005 01/0212/0203 @since 1.3


Class NoSuchAttributeException

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. @author Rosanna Lee @author Scott Seligman @version 1.4 005 01/0212/0203 @since 1.3


Class SchemaViolationException

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. @author Rosanna Lee @author Scott Seligman @version 1.4 005 01/0212/0203 @see javax.naming.Context#bind @see DirContext#bind @see javax.naming.Context#rebind @see DirContext#rebind @see DirContext#createSubcontext @see javax.naming.Context#createSubcontext @see DirContext#modifyAttributes @since 1.3


Class SearchControls

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. @author Rosanna Lee @author Scott Seligman @version 1.8 01/0212/0903 @since 1.3


Class SearchResult

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. @author Rosanna Lee @author Scott Seligman @version 1.7 01/0212/0903 @see DirContext#search @since 1.3