All Packages Class Hierarchy This Package Previous Next Index
Interface javax.naming.directory.DirContext
- public interface DirContext
- extends Context
DirContext is the directory service interface.
It contains methods for examining and updating attributes
associated with objects, and methods for searching the directory.
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.
Most of the methods have overloaded versions with one taking a
Name
parameter and one taking a String
.
In the documentation below only one version is documented.
The second version instead has a link to the first: the same
documentation applies to both.
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.
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.
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.
-
ADD_ATTRIBUTE
- This constant specifies to add an attribute with the specified values.
-
REMOVE_ATTRIBUTE
-
This constant specifies to delete
the specified attribute values from the attribute.
-
REPLACE_ATTRIBUTE
- This constant specifies to replace an attribute with specified values.
-
bind(Name, Object, Attributes)
- Binds 'name' to the object 'obj' and associate the attributes 'attrs'
with the named object.
-
bind(String, Object, Attributes)
- Binds 'name' to the object 'obj' and associate the attributes 'attrs'
with the named object.
-
createSubcontext(Name, Attributes)
- Creates a new context with given attributes, and binds it in
the target context.
-
createSubcontext(String, Attributes)
- Creates a new context with given attributes, and binds it in
the target context.
-
getAttributes(Name)
- Retrieves all of the attributes associated with a named object.
-
getAttributes(Name, String[])
- Retrieves selected attributes associated with a named object.
-
getAttributes(String)
- Retrieves all of the attributes associated with a string-named object.
-
getAttributes(String, String[])
- Retrieves selected attributes associated with a string-named object.
-
getSchema(Name)
- Retrieves the schema associated with the named object.
-
getSchema(String)
- Retrieves the schema associated with the string-named object.
-
getSchemaClassDefinition(Name)
- Retrieves the schema object class definition for the
named object.
-
getSchemaClassDefinition(String)
- Retrieves the schema object class definition associated with the
(string-) named object.
-
modifyAttributes(Name, int, Attributes)
- Modifies the attributes associated with a named object.
-
modifyAttributes(Name, ModificationItem[])
- Modifies the attributes associated with a named object using an
an ordered list of modifications.
-
modifyAttributes(String, int, Attributes)
- Modifies the attributes associated with a string-named object.
-
modifyAttributes(String, ModificationItem[])
- Modifies the attributes associated with a string-named object using an
an ordered list of modifications.
-
rebind(Name, Object, Attributes)
- Binds 'name' to the object 'obj' and associates the attributes
'attrs' with the named object, overwriting any existing binding.
-
rebind(String, Object, Attributes)
- Binds 'name' to the object 'obj' and associates the attributes
'attrs' with the (string-) named object, overwriting any existing binding.
-
search(Name, Attributes)
-
Searches in a single context for objects that contain a
specified set of attributes.
-
search(Name, Attributes, String[])
-
Searches in a single context for objects that contain a
specified set of attributes and retrieve their attributes.
-
search(Name, String, Object[], SearchControls)
- Searches in the named context or object for entries that satisfy the
given search filter.
-
search(Name, String, SearchControls)
- Searches in the named context or object for entries that satisfy the
given search filter.
-
search(String, Attributes)
-
Searches in a single context for objects that contain a
specified set of attributes.
-
search(String, Attributes, String[])
-
Searches in a single context for objects that contain a
specified set of attributes and return their specified attributes.
-
search(String, String, Object[], SearchControls)
- Searches in the named context or object for entries that satisfy the
given search filter.
-
search(String, String, SearchControls)
- Searches in the named context or named object for entries that satisfy the
given search filter.
ADD_ATTRIBUTE
public static final int ADD_ATTRIBUTE
- This constant specifies to add an attribute with the specified values.
If attribute does not exist,
create the attribute. The resulting attribute has a union of the
specified value set and the prior value set.
Adding an attribute with no value will throw
InvalidAttributeValueException
if the attribute must have
at least one value. For a single-valued attribute where that attribute
already exists, throws AttributeInUseException
.
If attempting to add more than one value to a single-valued attribute,
throws InvalidAttributeValueException
.
- See Also:
- ModificationItem, modifyAttributes
REPLACE_ATTRIBUTE
public static final int REPLACE_ATTRIBUTE
- This constant specifies to replace an attribute with specified values.
If attribute already exists,
replaces all existing values with new specified values. If the
attribute does not exist, creates it. If no value is specified,
deletes all the values of the attribute.
Removal of the last value will remove the attribute if the attribute
is required to have at least one value. If
attempting to add more than one value to a single-valued attribute,
throws InvalidAttributeValueException
.
- See Also:
- ModificationItem, modifyAttributes
REMOVE_ATTRIBUTE
public static final int REMOVE_ATTRIBUTE
- This constant specifies to delete
the specified attribute values from the attribute.
The resulting attribute has the set difference of its prior value set
and the specified value set.
If no values are specified, deletes the entire attribute.
If the attribute does not exist, or if some or all members of the
specified value set do not exist, they are ignored silently
and this operation still succeeds.
Removal of the last value will remove the attribute if the
attribute is required to have at least one value.
- See Also:
- ModificationItem, modifyAttributes
getAttributes
public abstract Attributes getAttributes(Name name) throws NamingException
- Retrieves all of the attributes associated with a named object.
- Parameters:
- name - The non-null name of the object from which to retrieve
attributes.
- Returns:
- The non-null set of attributes associated
with
name
. If name has no attributes
return an empty attribute set.
- Throws: NamingException
- If a naming exception was encountered
while attempting to get the attributes.
- See Also:
- getAttributes
getAttributes
public abstract Attributes getAttributes(String name) throws NamingException
- Retrieves all of the attributes associated with a string-named object.
- Parameters:
- name - The non-null name of the object from which to retrieve
attributes.
- Returns:
- The non-null set of attributes associated
with
name
. If name has no attributes
return an empty attribute set.
- Throws: NamingException
- If a naming exception was encountered
while attempting to get the attributes.
- See Also:
- getAttributes
getAttributes
public abstract Attributes getAttributes(Name name,
String attrIds[]) throws NamingException
- Retrieves selected attributes associated with a named object.
- Parameters:
- name - The non-null name of the object from which to retrieve
attributes.
- attrIds - The identifiers of the attributes to retrieve;
null indicates that all attributes should be retrieved.
An empty array indicates no attributes are to be returned.
- Returns:
- The non-null attributes identified by attrIds (or a subset
thereof if some attributes cannot be retrieved).
This can be an empty attribute set.
- Throws: NamingException
- If a naming exception was encountered
while retrieving the attributes.
getAttributes
public abstract Attributes getAttributes(String name,
String attrIds[]) throws NamingException
- Retrieves selected attributes associated with a string-named object.
- Parameters:
- name - The non-null name of the object from which to retrieve
attributes.
- attrIds - The identifiers of the attributes to retrieve;
null indicates that all attributes should be retrieved.
An empty array indicates no attributes are to be returned.
- Returns:
- The non-null attributes identified by attrIds (or a subset
thereof if some attributes cannot be retrieved).
This can be an empty attribute set.
- Throws: NamingException
- If a naming exception was encountered
while retrieving the attributes.
- See Also:
- getAttributes
modifyAttributes
public abstract void modifyAttributes(Name name,
int mod_op,
Attributes attrs) throws NamingException
- Modifies the attributes associated with a named object.
The order of the modifications is not specified. Where
possible, the modifications are performed atomically. If
the operation fails to complete,
AttributeModificationException
is thrown.
- Parameters:
- name - The non-null name of the object whose attributes will be
updated.
- mod_op - The modification operation, one of:
ADD_ATTRIBUTE
,
REPLACE_ATTRIBUTE
,
REMOVE_ATTRIBUTE
.
- attrs - The non-null attributes to be used for the modification.
- Throws: AttributeModificationException
- If modification could
not be completed successfully.
- Throws: NamingException
- If a naming exception occurred.
- See Also:
- modifyAttributes
modifyAttributes
public abstract void modifyAttributes(String name,
int mod_op,
Attributes attrs) throws NamingException
- Modifies the attributes associated with a string-named object.
- Parameters:
- name - The non-null name of the object whose attributes will be
updated.
- mod_op - The modification operation, one of:
ADD_ATTRIBUTE
,
REPLACE_ATTRIBUTE
,
REMOVE_ATTRIBUTE
.
- attrs - The non-null attributes to be used for the modification.
- Throws: AttributeModificationException
- If modification could
not be completed successfully.
- Throws: NamingException
- If a naming exception occurred.
- See Also:
- modifyAttributes
modifyAttributes
public abstract void modifyAttributes(Name name,
ModificationItem mods[]) throws NamingException
- Modifies the attributes associated with a named object using an
an ordered list of modifications.
The modifications are performed
in the order specified. Each modification specifies a
modification operation code and an attribute on which to
operate. Where possible, the modifications are
performed atomically. If the operation fails to
complete,
AttributeModificationException
is thrown.
- Parameters:
- name - The non-null name of the object whose attributes will be
updated.
- mods - A non-null ordered sequence of modifications that are to be
performed.
- Throws: AttributeModificationException
- If the modifications could not be completed successfully.
- Throws: NamingException
- If a naming exception occurred.
- See Also:
- modifyAttributes, ModificationItem
modifyAttributes
public abstract void modifyAttributes(String name,
ModificationItem mods[]) throws NamingException
- Modifies the attributes associated with a string-named object using an
an ordered list of modifications.
- Parameters:
- name - The non-null name of the object whose attributes will be
updated.
- mods - A non-null ordered sequence of modifications that are to be
performed.
- Throws: AttributeModificationException
- If the modifications could not be completed successfully.
- Throws: NamingException
- If a naming exception occurred.
- See Also:
- modifyAttributes
bind
public abstract void bind(Name name,
Object obj,
Attributes attrs) throws NamingException
- Binds 'name' to the object 'obj' and associate the attributes 'attrs'
with the named object. If 'attrs' is null, the resulting binding
will have the attributes associated with 'obj' if 'obj' is a
DirContext. If 'obj' is not a DirContext and 'attrs' is null,
the resulting binding will have no attributes.
If 'attrs' is non-null, the resulting binding will have 'attrs'
as its attributes and any attributes associated with 'obj'
are ignored.
- Parameters:
- name - The non-null name to bind. It cannot be empty.
- obj - The possibly null object to bind.
- attrs - The possibly null attributes to associate with the bound object.
- Throws: NameAlreadyBoundException
- If name is already bound.
- Throws: InvalidAttributesException
- If the attributes specified
by
attrs
or obj
do not comprise the "mandatory" attributes required
for binding the object.
- Throws: NamingException
- If a naming exception was encountered.
- See Also:
- bind, rebind
bind
public abstract void bind(String name,
Object obj,
Attributes attrs) throws NamingException
- Binds 'name' to the object 'obj' and associate the attributes 'attrs'
with the named object.
- Parameters:
- name - The non-null name to bind. It cannot be empty.
- obj - The possibly null object to bind.
- attrs - The possibly null attributes to associate with the bound object.
- Throws: NameAlreadyBoundException
- If name is already bound.
- Throws: InvalidAttributesException
- If the attributes specified
by
attrs
or obj
do not comprise the "mandatory" attributes required
for binding the object.
- Throws: NamingException
- If a naming exception was encountered.
- See Also:
- bind
rebind
public abstract void rebind(Name name,
Object obj,
Attributes attrs) throws NamingException
- Binds 'name' to the object 'obj' and associates the attributes
'attrs' with the named object, overwriting any existing binding.
If 'name' is already bound, 'obj' overwrites the existing binding.
If 'attrs' is null and 'obj' is a DirContext,
the attributes from 'obj' are used.
If 'attrs' is null and 'obj' is not a DirContext,
any existing attributes associated with the object already bound
in the directory remain unchanged.
If 'attrs' is non-null, any existing attributes associated with
the object already bound in the directory are removed and 'attrs'
is associated with the named object. If 'obj' is a DirContext
and 'attrs' is non-null, obj's attributes are ignored.
- Parameters:
- name - The non-null name to bind.
- obj - The possibly null object to bind.
- attrs - The possibly null attributes to associate with
the bound object.
- Throws: InvalidAttributesException
- If attrs or obj does not supply
all mandatory attributes required to create the binding.
- Throws: NamingException
- If a naming exception occurs.
- See Also:
- bind, bind
rebind
public abstract void rebind(String name,
Object obj,
Attributes attrs) throws NamingException
- Binds 'name' to the object 'obj' and associates the attributes
'attrs' with the (string-) named object, overwriting any existing binding.
- Parameters:
- name - The non-null name to bind.
- obj - The possibly null object to bind.
- attrs - The possibly null attributes to associate with
the bound object.
- Throws: InvalidAttributesException
- If attrs or obj does not supply
all mandatory attributes required to create the binding.
- Throws: NamingException
- If a naming exception occurs.
- See Also:
- rebind
createSubcontext
public abstract DirContext createSubcontext(Name name,
Attributes attrs) throws NamingException
- Creates a new context with given attributes, and binds it in
the target context.
This method creates a new subcontext with the given name, binds it in
the target context (that named by all but terminal atomic
component of the name), and associates the supplied attributes
with the newly created object.
All intermediate and target contexts must already exist.
- Parameters:
- name - The non-null name to use when creating the new context.
It cannot be empty.
- attrs - The possibly null attributes to associate with the
newly created
context.
- Returns:
- The non-null newly created context.
- Throws: NameAlreadyBoundException
- If name is already bound.
- Throws: InvalidAttributesException
- If
attrs
does not
contain all the mandatory attributes required for creation.
- Throws: NamingException
- If a naming exception occurs.
- See Also:
- createSubcontext
createSubcontext
public abstract DirContext createSubcontext(String name,
Attributes attrs) throws NamingException
- Creates a new context with given attributes, and binds it in
the target context.
- Parameters:
- name - The non-null name to use when creating the new context.
It cannot be empty.
- attrs - The possibly null attributes to associate with the
newly created
context.
- Returns:
- The non-null newly created context.
- Throws: NameAlreadyBoundException
- If name is already bound.
- Throws: InvalidAttributesException
- If
attrs
does not
contain all the mandatory attributes required for creation.
- Throws: NamingException
- If a naming exception occurs.
- See Also:
- createSubcontext
getSchema
public abstract DirContext getSchema(Name name) throws NamingException
- Retrieves the schema associated with the named object.
The schema describes rules regarding the structure of the namespace
and the attributes stored within it. The schema
specifies what types of objects can be added to the directory and where
they can be added; what mandatory and optional attributes an object
can have. The range of support for schemas is directory-specific.
This method returns the root of the schema information tree
that is applicable to the named object. Several named objects
(or even an entire directory) might share the same schema.
Issues such as structure and contents of the schema tree,
permission to modify to the contents of the schema
tree, and the effect of such modifications on the directory
are dependent on the underlying directory.
- Parameters:
- name - The non-null name of the object whose schema is to be retrieved.
- Returns:
- The non-null schema associated with the DirContext.
- Throws: OperationNotSupportedException
- Schema not supported.
- Throws: NamingException
- If a naming exception occurs.
getSchema
public abstract DirContext getSchema(String name) throws NamingException
- Retrieves the schema associated with the string-named object.
- Parameters:
- name - The non-null name of the object whose schema is to be retrieved.
- Returns:
- The non-null schema associated with the DirContext.
- Throws: OperationNotSupportedException
- Schema not supported.
- Throws: NamingException
- If a naming exception occurs.
- See Also:
- getSchema
getSchemaClassDefinition
public abstract DirContext getSchemaClassDefinition(Name name) throws NamingException
- Retrieves the schema object class definition for the
named object.
One category of information found in directory schemas is
class definitions. An "object class" definition
specifies the object's type and what attributes (mandatory
and optional) the object must/can have. Note that the term
"object class" being referred to here is in the directory sense
rather than in the Java sense.
For example, if the named object is a directory object of
"Person" class, getSchemaClassDefinition() would return a DirContext
representing the (directory's) object class definition of "Person".
The information that you can retrieve from a object class definition
is directory-dependent.
- Parameters:
- name - The non-null name of the object whose object class
definition is to be retrieved.
- Returns:
- The non-null schema object class definition associated with
name
.
- Throws: OperationNotSupportedException
- Schema not supported.
- Throws: NamingException
- If a naming exception occurs.
getSchemaClassDefinition
public abstract DirContext getSchemaClassDefinition(String name) throws NamingException
- Retrieves the schema object class definition associated with the
(string-) named object.
- Parameters:
- name - The non-null name of the object whose object class
definition is to be retrieved.
- Returns:
- The non-null schema object class definition associated with
name
.
- Throws: OperationNotSupportedException
- Schema not supported.
- Throws: NamingException
- If a naming exception occurs.
search
public abstract NamingEnumeration search(Name name,
Attributes matchingAttributes,
String attributesToReturn[]) throws NamingException
- Searches in a single context for objects that contain a
specified set of attributes and retrieve their attributes.
The search is performed using the default
SearchControls
settings.
For an object to be selected, each attribute in
matchingAttributes
must match some attribute of the
object. If matchingAttributes
is empty or
null
, all objects in the target context are returned.
An attribute A1 in
matchingAttributes
is considered to match an
attribute A2 of an object if
A1 and A2 have the same
identifier, and each value of A1 is equal
to some value of A2. This implies that the
order of values is not significant, and that
A2 may contain "extra" values not found in
A1 without affecting the comparison. It
also implies that if A1 has no values, then
testing for a match is equivalent to testing for the presence
of an attribute A2 with the same
identifier.
The precise definition of "equality" used in comparing attribute values
is definied by the underlying directory service. It might use the
Object.equals
method, for example, or might use a schema
to specify a different equality operation.
When changes are made to this DirContext,
the effect on the enumeration returned by a prior call to this method
is undefined.
- Parameters:
- name
- The non-null name of the context to search.
- matchingAttributes
- The attributes to search for. If empty or
null
,
all objects in the target context are returned.
- attributesToReturn
- The attributes to return.
null
indicates that
all attributes should be returned.
An empty array indicates that no attributes are to be returned.
- Returns:
- A non-null enumeration of SearchResults.
Each SearchResult contains the attributes
identified by
attributesToReturn
and the name of the corresponding entry, named relative
to the context named by name
.
- Throws: NamingException
- If a naming exception occurs.
- See Also:
- SearchControls, SearchResult, search
search
public abstract NamingEnumeration search(String name,
Attributes matchingAttributes,
String attributesToReturn[]) throws NamingException
- Searches in a single context for objects that contain a
specified set of attributes and return their specified attributes.
See search(Name, Attributes, String[]) for full description.
- Parameters:
- name - The non-null name of the context to search.
- matchingAttributes - The possibly null attributes to search for.
- attributesToReturn - The possibly null attributes to return.
- Returns:
- A non-null enumeration of SearchResult>s.
- Throws: NamingException
- If a naming exception occurs.
- See Also:
- search
search
public abstract NamingEnumeration search(Name name,
Attributes matchingAttributes) throws NamingException
- Searches in a single context for objects that contain a
specified set of attributes. This method returns all the attributes
of such objects. It is equivalent to
supplying null for the atributesToReturn parameter for the method
search(Name, Attributes, String[])
.
See search(Name, Attributes, String[]) for full description.
- Parameters:
- name - The non-null name of the context to search.
- matchingAttributes - The possibly null attributes to search for.
- attributesToReturn - The possibly null attributes to return.
- Returns:
- A non-null enumeration of SearchResults.
- Throws: NamingException
- If a naming exception occurs.
- See Also:
- search
search
public abstract NamingEnumeration search(String name,
Attributes matchingAttributes) throws NamingException
- Searches in a single context for objects that contain a
specified set of attributes.
Equivalent to: search(name, matchingAttributes, null)
See search(Name, Attributes, String[]) for full description.
- Parameters:
- name - The non-null name of the context to search.
- matchingAttributes - The possibly null attributes to search for.
- attributesToReturn - The possibly null attributes to return.
- Returns:
- A non-null enumeration of SearchResults.
- Throws: NamingException
- If a naming exception occurs.
- See Also:
- search
search
public abstract NamingEnumeration search(Name name,
String filter,
SearchControls cons) throws NamingException
- Searches in the named context or object for entries that satisfy the
given search filter. Performs the search as specified by
the search controls.
The format and interpretation of 'filter' follows RFC 1960, with
following interpretations for attr
and value
mentioned in the RFC.
attr
is a string representing the attribute's
attribute identifier. (This is equivalent to the id parameter passed
to the constructor of Attribute).
value
is the string represention the attribute's value.
The translation of this string representation into the attribute's value
is directory-specific.
For example, for the assertion "someCount=127", attr
is "someCount" and value
is "127".
The provider determines, based on the attribute ID ("someCount")
(and possibly its schema), that the attribute's value is an integer
parses the string "127" into an appropriate value it can use.
If the directory does support translation of string representation of
some or all of its attributes, the form of search() that accepts
filter arguments in the form of Objects can be used.
The service provider for such a directory would then translate
the filter arguments to its service-specific representation
for filter evaluation.
See search(Name, String, Object[], SearchControls)
.
RFC 1960 defines certain operators for the filter, including substring
matches, equality, approximate match, greater than, less than. These
operators are mapped to operators with corresponding semantics in the
underlying directory. For example, for the equals operator, suppose
the directory has a matching rule defining "equality" of the
attributes in the filter. This rule would be used for checking
equality of the attributes specified in the filter with the attributes
of objects in the directory. Similarly, if the directory has a
matching rule for ordering, this rule would be used for
making "greater than" and "less than" comparisons.
Not all of operators defined in RFC 1960 are applicable to all attributes.
When an operator is not applicable, the exception
InvalidSearchFilterException
is thrown.
The result is returned in an enumeration of SearchResults.
Each SearchResult contains the name of the object
and other information about the object (see SearchResult).
The name is either relative to the target context of the search
(which is named by the name
parameter), or
it is a URL string. If the target context is included in
the enumeration (as is possible when
cons
specifies a search scope of
SearchControls.OBJECT_SCOPE
or
SearchControls.SUBSTREE_SCOPE
), its name is the empty string.
- Parameters:
- name - The non-null name of the context or object at which
to perform the search.
- filter - The non-null filter expression to use for the search.
- cons - The possibly null search controls that
control the search. If null, equivalent to using
the null SearchControls constructor (i.e.
uses the defaults specified by the null constructor).
- Returns:
- A non-null enumeration of SearchResults for
the objects that satisfy the filter.
- Throws: InvalidSearchFilterException
- The search filter specified is
not supported or understood by the underlying directoy.
- Throws: InvalidSearchControlsException
- The search controls
contains invalid settings.
- Throws: NamingException
- If a naming exception occurs.
- See Also:
- search, SearchControls, SearchResult
search
public abstract NamingEnumeration search(String name,
String filter,
SearchControls cons) throws NamingException
- Searches in the named context or named object for entries that satisfy the
given search filter.
See
search(javax.naming.Name, java.lang.String, javax.naming.directory.SearchControls)
for details.
- Parameters:
- name - The non-null name of the context or object at which
to perform the search.
- filter - The non-null filter expression to use for the search.
Filter is specified by RFC 1960.
- cons - The possibly null search controls that
control the search. If null, equivalent to using
the null SearchControls constructor (i.e.
uses the defaults specified by the null constructor).
- Returns:
- A non-null enumeration of SearchResults.
- Throws: InvalidSearchFilterException
- The search filter specified is
not supported or understood by the underlying directoy.
- Throws: InvalidSearchControlsException
- If
cons
contains invalid settings.
- Throws: NamingException
- If a naming exception occurs.
- See Also:
- search
search
public abstract NamingEnumeration search(Name name,
String filterExpr,
Object filterArgs[],
SearchControls cons) throws NamingException
- Searches in the named context or object for entries that satisfy the
given search filter. Performs the search as specified by
the search controls.
When changes are made to this DirContext,
the effects of those changes on the enumeration returned by
this method are undefined.
filterExpr is interpreted according to RFC 1960, with the exception that
it may contain variables of the form {i}
where
i
is an integer.
Interpretation of filterExpr is otherwise
identical to how filter
is interpreted in the form of search
search(Name, String, SearchControls)
.
{i}
specifies the i
'th element from
the array filterArgs
is to be substituted for the
string "{i}
". It is provider-specific whether
the substitution requires that the element's string representation be used.
This method returns an enumeration of the results.
Each element in the enumeration contains the name of the object
and other information about the object (see SearchResult).
The name is either relative to the target context of the search
(which is named by the name
parameter), or
it is a URL string. If the target context is included in
the enumeration (as is possible when
cons
specifies a search scope of
SearchControls.OBJECT_SCOPE
or
SearchControls.SUBSTREE_SCOPE
), its name is the empty string.
- Parameters:
- name - The non-null name of the context or object at which to
perform the search.
- filterExpr - The non-null filter expression to use for the search.
The expression may contain variables of the
form "
{i}
" where i
is an integer.
- filterArgs - The possibly null array of arguments to
substitute for the variables
in
filterExpr
. The value of
filterArgs[i]
will replace each
occurrence of "{i}
".
- cons - The possibly null search controls that
control the search. If null, equivalent to using
the null SearchControls constructor (i.e.
uses the defaults specified by the null constructor).
- Returns:
- A non-null enumeration of SearchResults.
- Throws: ArrayIndexOutOfBoundsException
- If filterExpr contains
{i}
expressions where i
is outside the
bounds of the array filterArgs
.
- Throws: InvalidSearchControlsException
- If cons contains invalid settings.
- Throws: InvalidSearchFilterException
- If filterExpr and filterArgs
expresses an invalid search filter.
- Throws: NamingException
- If a naming exception occurs.
- See Also:
- search, MessageFormat
search
public abstract NamingEnumeration search(String name,
String filterExpr,
Object filterArgs[],
SearchControls cons) throws NamingException
- Searches in the named context or object for entries that satisfy the
given search filter. See the name form of this method for details.
- Parameters:
- name - The non-null name of the context or object at which to
perform the search.
- filterExpr - The non-null filter expression to use for the search.
The expression may contain variables of the
form "
{i}
" where i
is an integer.
- filterArgs - The possibly null array of arguments to
substitute for the variables
in
filterExpr
. The value of
filterArgs[i]
will replace each
occurrence of "{i}
".
- cons - The possibly null search controls that
control the search. If null, equivalent to using
the null SearchControls constructor (i.e.
uses the defaults specified by the null constructor).
- Returns:
- A non-null enumeration of SearchResults.
- Throws: ArrayIndexOutOfBoundsException
- If filterExpr contains
{i}
expressions where i
is outside the
bounds of the array filterArgs
.
- Throws: InvalidSearchControlsException
- If cons contains invalid settings.
- Throws: InvalidSearchFilterException
- If filterExpr and filterArgs
expresses an invalid search filter.
- Throws: NamingException
- If a naming exception occurs.
- See Also:
- search
All Packages Class Hierarchy This Package Previous Next Index