A DirContext is the interface through which a client interacts with a particular concrete directory service provider. The API provides methods for searching, reading and writing attributes of directory entries.
The name of a directory entry is taken as relative to the context receiving the method invocation. Names cannot be null and the empty name has a special meaning of the context itself.
In this interface there are duplicated methods that take either a String or Name parameter. This is simply a convenience and the behavior of each method is identical.
The semantics of a name in a DirContext is exactly equivalent to that of a name in a regular naming Context.
JNDI supports two logical models of attribute storage:
DirContext on the given name followed by application of the operation to the resulting empty DirContext. Think of this as attributes being stored on the object itself.DirContext followed by application of the operation on the parent DirContext providing the name as an argument. Think of this as the attributes being stored in the parent context. In this model objects that are not DirContext can have attributes, provided their parents are DirContext.
The directory service provider can implement either of these logical models, and the client is expeced to know which model it is dealing with.
Attribute Name aliasingDirectory service providers are free to implement attribute name alising. If the service employs alising then the list of attribute names that are returned as a result of API calls to get a named attribute, or search for a set of attributes may include attributes whose name was not in the search list. Implmentations should not rely on the preservation of attribute names.
Searching and operational attributesSome directory service providers support "operational attributes" on objects. These are attributes that are computed by the provider, or have other special semantics to the directory service. The directory service defines which attributes are operational.
The API calls for searching for attributes, and those for getting named attributes using a list of names are defined to interpret the null argument to match all non-operational attributes.
It is therefore possible to get a specific named attribute that is not returned in a global retrieval of all object attributes.
Conditions Some APIs require that the name resolves to another DirContext and not an object. In such cases, if this postcondition is not met then the method should throw a NotContextException. Other methods can resolve to be either objects or DirContext.
Service providers must not modify collection parameters such as Attribute, SearchControl or arrays. Similarly, clients are expected not to modify the collections while the service provider iterates over such collections -- the service provider should be given exclusive control of the collection until the method returns.
APIs that return collections are safe -- that is, the service provider will not modify collections that are returned to clients.
Exceptions Any method may throw a NamingException (or subclass) as defined by the exception descriptions.
| |