| javax.naming.directory.DirContext
All known Subclasses: javax.naming.directory.InitialDirContext,
| DirContext | | public interface DirContext extends Context(Code) | | This is the main interface to a directory service.
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.
Attribute storage models
JNDI supports two logical models of attribute storage:
The directory service provider can implement either of these logical models,
and the client is expected to know which model it is dealing with.
Attribute Name aliasing
Directory service providers are free to implement attribute name aliasing. If
the service employs aliasing 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. Implementations should not rely on the preservation of attribute names.
Searching and operational attributes
Some 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.
|
| Field Summary | |
| final public static int | ADD_ATTRIBUTE
Constant value indicating the addition of an attribute. | | final public static int | REMOVE_ATTRIBUTE
Constant field indicating the removal of an attribute. | | final public static int | REPLACE_ATTRIBUTE
Constant value indicating the replacement of an attribute value.
If the attribute does not exist then it is created with the given
attribute identifier and attribute. |
| Method Summary | |
| void | bind(Name name, Object obj, Attributes attributes)
Binds a Name to an Object in this directory
to produce a binding.
This binding can have attributes, which are specified by the
attributes parameter if it is non-null. | | void | bind(String s, Object obj, Attributes attributes)
Binds a string name to an Object in this directory to
produce a binding. | | DirContext | createSubcontext(Name name, Attributes attributes)
Creates and binds a new subcontext.
The new subcontext might not be an immediate subcontext of this one. | | DirContext | createSubcontext(String s, Attributes attributes)
Creates and binds a new subcontext. | | Attributes | getAttributes(Name name)
Gets all attributes of name. | | Attributes | getAttributes(Name name, String as)
Gets the attributes for name that match the strings in
array as.
If any string in as is not matched it is skipped. | | Attributes | getAttributes(String s)
Gets all attributes of name represented by s. | | Attributes | getAttributes(String s, String as)
Gets the attributes for name represented by s that match
the strings in array as. | | DirContext | getSchema(Name name)
Gets the top level of the schema for object name. | | DirContext | getSchema(String s)
Gets the top level of the schema for name represented by s. | | DirContext | getSchemaClassDefinition(Name name)
Gets the class definition for name from its schema.
A class definition from a schema specifies a type and its mandatory and
optional attributes. | | DirContext | getSchemaClassDefinition(String s)
Gets the class definition for name represented by s from
its schema. | | void | modifyAttributes(Name name, int i, Attributes attributes)
Modifies the attributes of name.
Parameter i is modification operation type and is
constrained to be one of ADD_ATTRIBUTE,
REPLACE_ATTRIBUTE, REMOVE_ATTRIBUTE. | | void | modifyAttributes(Name name, ModificationItem[] modificationItems)
Modifies the attributes of name in the order given by the
array parameter amodificationitem. | | void | modifyAttributes(String s, int i, Attributes attributes)
Modifies the attributes of name represented by s. | | void | modifyAttributes(String s, ModificationItem[] modificationItems)
Modifies the attributes of name represented by s in the
order given by the array parameter modificationItems. | | void | rebind(Name name, Object obj, Attributes attributes)
Rebinds name to obj.
If the attributes parameter is non-null, the attributes it specifies
become the only attributes of the binding. | | void | rebind(String s, Object obj, Attributes attributes)
Rebinds name represented by s to obj. | | NamingEnumeration<SearchResult> | search(Name name, Attributes attributes)
Searches in the context specified by name only, for any
objects that have attributes that match the attributes
parameter. | | NamingEnumeration<SearchResult> | search(Name name, Attributes attributes, String as)
This method searches in the context specified by name
only, for any objects that have attributes that match the
attributes parameter.
It uses default SearchControls. | | NamingEnumeration<SearchResult> | search(Name name, String filter, Object[] objs, SearchControls searchControls)
This method searches in the context specified by name
only, using the filter specified by parameter filter and
controlled by searchControls.
The parameter filter is an RFC2254 filter. | | NamingEnumeration<SearchResult> | search(Name name, String filter, SearchControls searchControls)
This method searches in the context specified by name
only, using the filter specified by parameter filter and
controlled by searchControls. | | NamingEnumeration<SearchResult> | search(String name, Attributes attributes)
Searches in the context specified by name represented by
name only, for any objects that have attributes that match
the attributes parameter. | | NamingEnumeration<SearchResult> | search(String name, Attributes attributes, String as)
This method searches in the context specified by name represented by
name only, for any objects that have attributes that match
the attributes parameter. | | NamingEnumeration<SearchResult> | search(String name, String filter, Object[] objs, SearchControls searchControls)
This method searches in the context specified by name represented by
name only, using the filter specified by parameter
filter and controlled by searchControls. | | NamingEnumeration<SearchResult> | search(String name, String filter, SearchControls searchControls)
This method searches in the context specified by name represented by
name only, using the filter specified by parameter
filter and controlled by searchControls. |
| ADD_ATTRIBUTE | | final public static int ADD_ATTRIBUTE(Code) | | Constant value indicating the addition of an attribute.
The new value is added to the existing attributes at that identifier
subject to the following constraints:
- If the attribute is being created and the value is empty, an
InvalidAttributeValueException is thrown if the attribute
must have a value.
- If the attribute already exists with a single value and the schema
requires that the attribute can only have a single value, an
AttributeInUseException is thrown.
- If the attribute is being created with a multi-value and the schema
requires that the attribute can only have a single value, an
InvalidAttributeValueException is thrown.
|
| REMOVE_ATTRIBUTE | | final public static int REMOVE_ATTRIBUTE(Code) | | Constant field indicating the removal of an attribute.
If the attribute exists then the resulting values of the attribute is the
set of values given by removing all values in the given set from the
existing attribute set.
If the given set of attributes is null that should be
interpreted as a request to remove all values from the existing attribute
set.
If the attribute does not exist, or a value in the given set does not
appear in the existing attribute set then the service provider is free to
either ignore the fact it does not exist, or throw a
NamingException.
|
| REPLACE_ATTRIBUTE | | final public static int REPLACE_ATTRIBUTE(Code) | | Constant value indicating the replacement of an attribute value.
If the attribute does not exist then it is created with the given
attribute identifier and attribute. If the value contravenes the schema,
an
InvalidAttributeValueException is thrown.
If the attribute exists then all of its values are replaced by the given
values. If the attribute is defined to take a single value and the new
value is a multi-value then an
InvalidAttributeValueException is thrown. If no value is
given then all of the values are removed from the attribute.
If an attribute is defined as requiring at least one value, then removing
values results in the removal of the attribute itself.
|
| bind | | void bind(Name name, Object obj, Attributes attributes) throws NamingException(Code) | | Binds a Name to an Object in this directory
to produce a binding.
This binding can have attributes, which are specified by the
attributes parameter if it is non-null. If the
attributes parameter is null and obj is a
DirContext with attributes, the binding will have the
attributes of obj.
Note that null is not a valid value for name. Neither is
the empty Name because this is reserved to refer to the
context.
If name is already bound in this DirContext
this method throws a NameAlreadyBoundException.
If there are mandatory attributes for this binding in this
DirContext, and they are not specified, this method
throws an InvalidAttributesException.
This method throws any NamingException that occurs.
Parameters:
name - the name to be bound
Parameters:
obj - the object to be bound
Parameters:
attributes - the attributes of this binding, can be null
throws:
NamingException - If any occurs. |
| createSubcontext | | DirContext createSubcontext(Name name, Attributes attributes) throws NamingException(Code) | | Creates and binds a new subcontext.
The new subcontext might not be an immediate subcontext of this one. If
it is not an immediate subcontext, all the intervening subcontexts
specified in name must already exist. If the attributes
parameter is non-null the specified attributes are added to the new
subcontext.
Possible exceptions are NameAlreadyBoundException and
InvalidAttributesException.
This method throws any NamingException that occurs.
Parameters:
name - the name bound to the new subcontext
Parameters:
attributes - the attributes of the new subcontxt, can be null the new subcontext
throws:
NamingException - If any occurs. |
| getAttributes | | Attributes getAttributes(Name name) throws NamingException(Code) | | Gets all attributes of name.
See note in description about operational attributes.
The returned set of attributes is empty if name has no
attributes.
This method throws any NamingException that occurs.
Parameters:
name - name to be searched for attributes all attributes of name
throws:
NamingException - If any occurs. |
| getAttributes | | Attributes getAttributes(Name name, String as) throws NamingException(Code) | | Gets the attributes for name that match the strings in
array as.
If any string in as is not matched it is skipped. More
attributes may be returned than the number of strings in as -
see notes on attribute aliasing.
This method throws any NamingException that occurs.
Parameters:
name - name to be searched for attributes
Parameters:
as - the array of strings to match attributes all attributes for name that match the strings inarray as.
throws:
NamingException - If any occurs. |
| getSchema | | DirContext getSchema(Name name) throws NamingException(Code) | | Gets the top level of the schema for object name.
If name does not support a schema this method throws an
OperationNotSupportedException.
This method throws any NamingException that occurs.
Parameters:
name - the object to be searched for schema the top level of the schema for object name
throws:
NamingException - If any occurs. |
| getSchemaClassDefinition | | DirContext getSchemaClassDefinition(Name name) throws NamingException(Code) | | Gets the class definition for name from its schema.
A class definition from a schema specifies a type and its mandatory and
optional attributes. Note that the term "class" here refers to the
general concept of a data type, not a Java class.
If name does not support a schema this method throws an
OperationNotSupportedException.
This method throws any NamingException that occurs.
Parameters:
name - the name to searched for the class definition from its schema the class definition for name from its schema.
throws:
NamingException - If any occurs. |
| modifyAttributes | | void modifyAttributes(Name name, int i, Attributes attributes) throws NamingException(Code) | | Modifies the attributes of name.
Parameter i is modification operation type and is
constrained to be one of ADD_ATTRIBUTE,
REPLACE_ATTRIBUTE, REMOVE_ATTRIBUTE. The
implementation should try to make the modifications atomic.
This method throws an AttributeModificationException if
there is a problem completing the modification.
This method throws any NamingException that occurs.
Parameters:
name - the name which attributes will be modified
Parameters:
i - the modification operation type
Parameters:
attributes - the modified attributes
throws:
NamingException - If any occurs. |
| modifyAttributes | | void modifyAttributes(Name name, ModificationItem[] modificationItems) throws NamingException(Code) | | Modifies the attributes of name in the order given by the
array parameter amodificationitem.
The required operations are specified by the elements of
modificationItems.
This method throws an AttributeModificationException if
there is a problem completing the modifications.
This method throws any NamingException that occurs.
Parameters:
name - the name which attributes will be modified
Parameters:
modificationItems - the array of modification item
throws:
NamingException - If any occurs. |
| rebind | | void rebind(Name name, Object obj, Attributes attributes) throws NamingException(Code) | | Rebinds name to obj.
If the attributes parameter is non-null, the attributes it specifies
become the only attributes of the binding. If the attributes parameter is
null but obj is an instance of DirContext
then the attributes of obj become the only attributes of
the binding. If the attributes parameter is null and
obj is not an instance of DirContext then
any attributes of the previous binding remain.
If a schema defines mandatory attributes for the binding but they are not
all present this method throws an InvalidAttributesException.
This method throws any NamingException that occurs.
Parameters:
name - the name to be bound
Parameters:
obj - the object to be bound
Parameters:
attributes - the attributes of the binding
throws:
NamingException - If any occurs. |
| search | | NamingEnumeration<SearchResult> search(Name name, Attributes attributes) throws NamingException(Code) | | Searches in the context specified by name only, for any
objects that have attributes that match the attributes
parameter.
This method is equivalent to passing a null as parameter
to search(Name name, Attributes attributes, String[] as).
Objects with attributes that match the attributes
parameter are selected and all attributes are returned for selected
objects.
This method throws any NamingException that occurs.
Parameters:
name - the name specifies the context to be searched
Parameters:
attributes - the attributes to be matched when search NamingEnumeration of SearchResult
throws:
NamingException - If any occurs.
See Also: DirContext.search(Name name,Attributes attributes,String[] as) |
| search | | NamingEnumeration<SearchResult> search(Name name, Attributes attributes, String as) throws NamingException(Code) | | This method searches in the context specified by name
only, for any objects that have attributes that match the
attributes parameter.
It uses default SearchControls. An object is selected if
it has every attribute in the attributes parameter,
regardless of whether it has extra attributes. If the
attributes parameter is null or empty then every object in
the context is a match.
The definition of attribute matching is
- both attributes have the same identifier;
- all values of the attribute from the attributes parameter are found
in the attribute from the target object.
Attribute ordering is ignored. If an attribute from the
attributes parameter has no values it is matched by any
attribute that has the same identifier. The definition of attribute value
equality is left to the directory service - it could be
Object.equals(Object obj), or a test defined by a schema.
For each of the selected objects, this method collects and returns the
attributes with identifiers listed in parameter as. Note
that these may be different to those in the attributes
parameter. If a selected object does not have one of the attributes
listed in as, the missing attribute is simply skipped for
that object. Attribute aliasing may mean that an attribute in the
as parameter list maps to more than one returned
attribute. If parameter as is empty, no attributes are
returned, but if as is null all attributes are returned.
The return value is an enumeration of SearchResult
objects, which is empty if no matches are found. It is not specified how
subsequent changes to context specified by name will
affect an enumeration that this method returns.
This method throws any NamingException that occurs.
Parameters:
name - the name specifies the context to be searched
Parameters:
attributes - the attributes to be matched when search
Parameters:
as - the array of string representative of attributes to bereturned NamingEnumeration of SearchResult
throws:
NamingException - If any occurs. |
| search | | NamingEnumeration<SearchResult> search(Name name, String filter, Object[] objs, SearchControls searchControls) throws NamingException(Code) | | This method searches in the context specified by name
only, using the filter specified by parameter filter and
controlled by searchControls.
The parameter filter is an RFC2254 filter. It may contain
variables such as "{N}", which refer to element N of the
objs array.
The "{N}" variables can be used in place of "attr", "value", or
"matchingrule" from RFC2254 section 4. If an "{N}" variable refers to a
String object, that string becomes part of the filter
string, but with any special characters escaped as defined by RFC 2254.
The directory service implementation decides how to interpret filter
arguments with types other than String. The result of
giving invalid variable substitutions is not specified.
If searchControls is null, the default
SearchControls object is used: i.e. the object created by
the no-args SearchControls() constructor.
The return value is an enumeration of SearchResult
objects. The object names used may be relative to the context specified
in the name parameter, or a URL string. If the
name context itself is referred to in the results, the
empty string is used. It is not specified how subsequent changes to
context specified by name will affect an enumeration that
this method returns.
If an "{N}" variable in s references a position outside
the bounds of array objs this method will throw an
ArrayIndexOutOfBoundsException.
If searchControls is invalid this method will throw
InvalidSearchControlsException.
If the filter specified by filter and objs
is invalid this method will throw an
InvalidSearchFilterException.
This method throws any NamingException that occurs.
Parameters:
name - the name specifies the context to be searched
Parameters:
filter - the search filter
Parameters:
objs - array of objects referred by search filter
Parameters:
searchControls - the search controls NamingEnumeration of SearchResult
throws:
NamingException - If any occurs.
See Also: SearchControls |
|
|