Class InitialDirContext
- All Implemented Interfaces:
Context, DirContext
- Direct Known Subclasses:
InitialLdapContext
- Since:
- 1.3
- See Also:
-
Field Summary
Fields declared in class InitialContext
defaultInitCtx, gotDefault, myProps
Modifier and TypeFieldDescriptionprotected Context
Field holding the result of calling NamingManager.getInitialContext().protected boolean
Field indicating whether the initial context has been obtained by calling NamingManager.getInitialContext().The environment associated with this InitialContext.Fields declared in interface Context
AUTHORITATIVE, BATCHSIZE, DNS_URL, INITIAL_CONTEXT_FACTORY, LANGUAGE, OBJECT_FACTORIES, PROVIDER_URL, REFERRAL, SECURITY_AUTHENTICATION, SECURITY_CREDENTIALS, SECURITY_PRINCIPAL, SECURITY_PROTOCOL, STATE_FACTORIES, URL_PKG_PREFIXES
Modifier and TypeFieldDescriptionstatic final String
Constant that holds the name of the environment property for specifying the authoritativeness of the service requested.static final String
Constant that holds the name of the environment property for specifying the batch size to use when returning data via the service's protocol.static final String
Constant that holds the name of the environment property for specifying the DNS host and domain names to use for the JNDI URL context (for example, "dns://somehost/wiz.com").static final String
Constant that holds the name of the environment property for specifying the initial context factory to use.static final String
Constant that holds the name of the environment property for specifying the preferred language to use with the service.static final String
Constant that holds the name of the environment property for specifying the list of object factories to use.static final String
Constant that holds the name of the environment property for specifying configuration information for the service provider to use.static final String
Constant that holds the name of the environment property for specifying how referrals encountered by the service provider are to be processed.static final String
Constant that holds the name of the environment property for specifying the security level to use.static final String
Constant that holds the name of the environment property for specifying the credentials of the principal for authenticating the caller to the service.static final String
Constant that holds the name of the environment property for specifying the identity of the principal for authenticating the caller to the service.static final String
Constant that holds the name of the environment property for specifying the security protocol to use.static final String
Constant that holds the name of the environment property for specifying the list of state factories to use.static final String
Constant that holds the name of the environment property for specifying the list of package prefixes to use when loading in URL context factories.Fields declared in interface DirContext
ADD_ATTRIBUTE, REMOVE_ATTRIBUTE, REPLACE_ATTRIBUTE
Modifier and TypeFieldDescriptionstatic final int
This constant specifies to add an attribute with the specified values.static final int
This constant specifies to delete the specified attribute values from the attribute.static final int
This constant specifies to replace an attribute with specified values. -
Constructor Summary
ConstructorsModifierConstructorDescriptionConstructs an initial DirContext.protected
InitialDirContext
(boolean lazy) Constructs an initial DirContext with the option of not initializing it.InitialDirContext
(Hashtable<?, ?> environment) Constructs an initial DirContext using the supplied environment. -
Method Summary
Modifier and TypeMethodDescriptionvoid
bind
(String name, Object obj, Attributes attrs) Binds a name to an object, along with associated attributes.void
bind
(Name name, Object obj, Attributes attrs) Binds a name to an object, along with associated attributes.createSubcontext
(String name, Attributes attrs) Creates and binds a new context, along with associated attributes.createSubcontext
(Name name, Attributes attrs) Creates and binds a new context, along with associated attributes.getAttributes
(String name) Retrieves all of the attributes associated with a named object.getAttributes
(String name, String[] attrIds) Retrieves selected attributes associated with a named object.getAttributes
(Name name) Retrieves all of the attributes associated with a named object.getAttributes
(Name name, String[] attrIds) Retrieves selected attributes associated with a named object.Retrieves the schema associated with the named object.Retrieves the schema associated with the named object.Retrieves a context containing the schema objects of the named object's class definitions.getSchemaClassDefinition
(Name name) Retrieves a context containing the schema objects of the named object's class definitions.void
modifyAttributes
(String name, int mod_op, Attributes attrs) Modifies the attributes associated with a named object.void
modifyAttributes
(String name, ModificationItem[] mods) Modifies the attributes associated with a named object using an ordered list of modifications.void
modifyAttributes
(Name name, int mod_op, Attributes attrs) Modifies the attributes associated with a named object.void
modifyAttributes
(Name name, ModificationItem[] mods) Modifies the attributes associated with a named object using an ordered list of modifications.void
rebind
(String name, Object obj, Attributes attrs) Binds a name to an object, along with associated attributes, overwriting any existing binding.void
rebind
(Name name, Object obj, Attributes attrs) Binds a name to an object, along with associated attributes, overwriting any existing binding.search
(String name, String filterExpr, Object[] filterArgs, SearchControls cons) Searches in the named context or object for entries that satisfy the given search filter.search
(String name, String filter, SearchControls cons) Searches in the named context or object for entries that satisfy the given search filter.search
(String name, Attributes matchingAttributes) Searches in a single context for objects that contain a specified set of attributes.search
(String name, Attributes matchingAttributes, String[] attributesToReturn) Searches in a single context for objects that contain a specified set of attributes, and retrieves selected attributes.search
(Name name, String filterExpr, Object[] filterArgs, SearchControls cons) Searches in the named context or object for entries that satisfy the given search filter.search
(Name name, String filter, SearchControls cons) Searches in the named context or object for entries that satisfy the given search filter.search
(Name name, Attributes matchingAttributes) Searches in a single context for objects that contain a specified set of attributes.search
(Name name, Attributes matchingAttributes, String[] attributesToReturn) Searches in a single context for objects that contain a specified set of attributes, and retrieves selected attributes.Methods declared in class InitialContext
addToEnvironment, bind, bind, close, composeName, composeName, createSubcontext, createSubcontext, destroySubcontext, destroySubcontext, doLookup, doLookup, getDefaultInitCtx, getEnvironment, getNameInNamespace, getNameParser, getNameParser, getURLOrDefaultInitCtx, getURLOrDefaultInitCtx, init, list, list, listBindings, listBindings, lookup, lookup, lookupLink, lookupLink, rebind, rebind, removeFromEnvironment, rename, rename, unbind, unbind
Modifier and TypeMethodDescriptionaddToEnvironment
(String propName, Object propVal) Adds a new environment property to the environment of this context.void
Binds a name to an object.void
Binds a name to an object.void
close()
Closes this context.composeName
(String name, String prefix) Composes the name of this context with a name relative to this context.composeName
(Name name, Name prefix) Composes the name of this context with a name relative to this context.createSubcontext
(String name) Creates and binds a new context.createSubcontext
(Name name) Creates and binds a new context.void
destroySubcontext
(String name) Destroys the named context and removes it from the namespace.void
destroySubcontext
(Name name) Destroys the named context and removes it from the namespace.static <T> T
A static method to retrieve the named object.static <T> T
A static method to retrieve the named object.protected Context
Retrieves the initial context by callingNamingManager.getInitialContext()
and cache it in defaultInitCtx.Hashtable
<?, ?> Retrieves the environment in effect for this context.Retrieves the full name of this context within its own namespace.getNameParser
(String name) Retrieves the parser associated with the named context.getNameParser
(Name name) Retrieves the parser associated with the named context.protected Context
getURLOrDefaultInitCtx
(String name) Retrieves a context for resolving the string namename
.protected Context
getURLOrDefaultInitCtx
(Name name) Retrieves a context for resolvingname
.protected void
Initializes the initial context using the supplied environment.Enumerates the names bound in the named context, along with the class names of objects bound to them.Enumerates the names bound in the named context, along with the class names of objects bound to them.listBindings
(String name) Enumerates the names bound in the named context, along with the objects bound to them.listBindings
(Name name) Enumerates the names bound in the named context, along with the objects bound to them.Retrieves the named object.Retrieves the named object.lookupLink
(String name) Retrieves the named object, following links except for the terminal atomic component of the name.lookupLink
(Name name) Retrieves the named object, following links except for the terminal atomic component of the name.void
Binds a name to an object, overwriting any existing binding.void
Binds a name to an object, overwriting any existing binding.removeFromEnvironment
(String propName) Removes an environment property from the environment of this context.void
Binds a new name to the object bound to an old name, and unbinds the old name.void
Binds a new name to the object bound to an old name, and unbinds the old name.void
Unbinds the named object.void
Unbinds the named object.Methods declared in class Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Modifier and TypeMethodDescriptionprotected Object
clone()
Creates and returns a copy of this object.boolean
Indicates whether some other object is "equal to" this one.protected void
finalize()
Deprecated, for removal: This API element is subject to removal in a future version.Finalization is deprecated and subject to removal in a future release.final Class
<?> getClass()
Returns the runtime class of thisObject
.int
hashCode()
Returns a hash code value for this object.final void
notify()
Wakes up a single thread that is waiting on this object's monitor.final void
Wakes up all threads that are waiting on this object's monitor.toString()
Returns a string representation of the object.final void
wait()
Causes the current thread to wait until it is awakened, typically by being notified or interrupted.final void
wait
(long timeoutMillis) Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.final void
wait
(long timeoutMillis, int nanos) Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.
-
Constructor Details
-
InitialDirContext
Constructs an initial DirContext with the option of not initializing it. This may be used by a constructor in a subclass when the value of the environment parameter is not yet known at the time theInitialDirContext
constructor is called. The subclass's constructor will call this constructor, compute the value of the environment, and then callinit()
before returning.- Parameters:
lazy
- true means do not initialize the initial DirContext; false is equivalent to callingnew InitialDirContext()
- Throws:
NamingException
- if a naming exception is encountered- Since:
- 1.3
- See Also:
-
InitialDirContext
Constructs an initial DirContext. No environment properties are supplied. Equivalent tonew InitialDirContext(null)
.- Throws:
NamingException
- if a naming exception is encountered- See Also:
-
InitialDirContext
Constructs an initial DirContext using the supplied environment. Environment properties are discussed in thejavax.naming.InitialContext
class description.If the
java.naming.provider.url
property of the supplied environment consists of a URL (or a list of URLs) using the ldap protocol the resultingLdapContext
will use an LDAP server resolved by the configuredLdapDnsProviders
:- If this is the first
InitialDirContext
created with ajava.naming.provider.url
using the ldap protocol then the ServiceLoader mechanism is used to locate LdapDnsProvider implementations using the system class loader. The order that providers are located is implementation specific and an implementation is free to cache the located providers. - The
lookupEndpoints
method of each provider, if instantiated, is invoked once with a combination of each of the URLs in thejava.naming.provider.url
property and the environment until a provider returns non-empty or all providers have been exhausted. If none of the LdapDnsProviders return a non-empty result then the implementation will make a best-effort attempt to determine an endpoint. A ServiceConfigurationError,Error
orRuntimeException
thrown when loading or calling an LdapDnsProvider, if encountered, will be propagated to the calling thread.
This constructor will not modify
environment
or save a reference to it, but may save a clone. Caller should not modify mutable keys and values inenvironment
after it has been passed to the constructor.- Parameters:
environment
- environment used to create the initial DirContext. Null indicates an empty environment.- Throws:
NamingException
- if a naming exception is encountered
- If this is the first
-
-
Method Details
-
getAttributes
Description copied from interface:DirContext
Retrieves all of the attributes associated with a named object. SeeDirContext.getAttributes(Name)
for details.- Specified by:
getAttributes
in interfaceDirContext
- Parameters:
name
- the name of the object from which to retrieve attributes- Returns:
- the set of attributes associated with
name
- Throws:
NamingException
- if a naming exception is encountered
-
getAttributes
Description copied from interface:DirContext
Retrieves selected attributes associated with a named object. SeeDirContext.getAttributes(Name, String[])
for details.- Specified by:
getAttributes
in interfaceDirContext
- Parameters:
name
- The name of the object from which to retrieve attributesattrIds
- the identifiers of the attributes to retrieve. null indicates that all attributes should be retrieved; an empty array indicates that none should be retrieved.- Returns:
- the requested attributes; never null
- Throws:
NamingException
- if a naming exception is encountered
-
getAttributes
Description copied from interface:DirContext
Retrieves all of the attributes associated with a named object. See the class description regarding attribute models, attribute type names, and operational attributes.- Specified by:
getAttributes
in interfaceDirContext
- Parameters:
name
- the name of the object from which to retrieve attributes- Returns:
- the set of attributes associated with
name
. Returns an empty attribute set if name has no attributes; never null. - Throws:
NamingException
- if a naming exception is encountered- See Also:
-
getAttributes
Description copied from interface:DirContext
Retrieves selected attributes associated with a named object. See the class description regarding attribute models, attribute type names, and operational attributes.If the object does not have an attribute specified, the directory will ignore the nonexistent attribute and return those requested attributes that the object does have.
A directory might return more attributes than was requested (see Attribute Type Names in the class description), but is not allowed to return arbitrary, unrelated attributes.
See also Operational Attributes in the class description.
- Specified by:
getAttributes
in interfaceDirContext
- Parameters:
name
- the name of the object from which to retrieve attributesattrIds
- the identifiers of the attributes to retrieve. null indicates that all attributes should be retrieved; an empty array indicates that none should be retrieved.- Returns:
- the requested attributes; never null
- Throws:
NamingException
- if a naming exception is encountered
-
modifyAttributes
Description copied from interface:DirContext
Modifies the attributes associated with a named object. SeeDirContext.modifyAttributes(Name, int, Attributes)
for details.- Specified by:
modifyAttributes
in interfaceDirContext
- Parameters:
name
- the name of the object whose attributes will be updatedmod_op
- the modification operation, one of:ADD_ATTRIBUTE
,REPLACE_ATTRIBUTE
,REMOVE_ATTRIBUTE
.attrs
- the attributes to be used for the modification; may not be null- Throws:
AttributeModificationException
- if the modification cannot be completed successfullyNamingException
- if a naming exception is encountered
-
modifyAttributes
Description copied from interface:DirContext
Modifies the attributes associated with a named object. The order of the modifications is not specified. Where possible, the modifications are performed atomically.- Specified by:
modifyAttributes
in interfaceDirContext
- Parameters:
name
- the name of the object whose attributes will be updatedmod_op
- the modification operation, one of:ADD_ATTRIBUTE
,REPLACE_ATTRIBUTE
,REMOVE_ATTRIBUTE
.attrs
- the attributes to be used for the modification; may not be null- Throws:
AttributeModificationException
- if the modification cannot be completed successfullyNamingException
- if a naming exception is encountered- See Also:
-
modifyAttributes
Description copied from interface:DirContext
Modifies the attributes associated with a named object using an ordered list of modifications. SeeDirContext.modifyAttributes(Name, ModificationItem[])
for details.- Specified by:
modifyAttributes
in interfaceDirContext
- Parameters:
name
- the name of the object whose attributes will be updatedmods
- an ordered sequence of modifications to be performed; may not be null- Throws:
AttributeModificationException
- if the modifications cannot be completed successfullyNamingException
- if a naming exception is encountered
-
modifyAttributes
Description copied from interface:DirContext
Modifies the attributes associated with a named object using 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.- Specified by:
modifyAttributes
in interfaceDirContext
- Parameters:
name
- the name of the object whose attributes will be updatedmods
- an ordered sequence of modifications to be performed; may not be null- Throws:
AttributeModificationException
- if the modifications cannot be completed successfullyNamingException
- if a naming exception is encountered- See Also:
-
bind
Description copied from interface:DirContext
Binds a name to an object, along with associated attributes. SeeDirContext.bind(Name, Object, Attributes)
for details.- Specified by:
bind
in interfaceDirContext
- Parameters:
name
- the name to bind; may not be emptyobj
- the object to bind; possibly nullattrs
- the attributes to associate with the binding- Throws:
NameAlreadyBoundException
- if name is already boundInvalidAttributesException
- if some "mandatory" attributes of the binding are not suppliedNamingException
- if a naming exception is encountered
-
bind
Description copied from interface:DirContext
Binds a name to an object, along with associated attributes. Ifattrs
is null, the resulting binding will have the attributes associated withobj
ifobj
is aDirContext
, and no attributes otherwise. Ifattrs
is non-null, the resulting binding will haveattrs
as its attributes; any attributes associated withobj
are ignored.- Specified by:
bind
in interfaceDirContext
- Parameters:
name
- the name to bind; may not be emptyobj
- the object to bind; possibly nullattrs
- the attributes to associate with the binding- Throws:
NameAlreadyBoundException
- if name is already boundInvalidAttributesException
- if some "mandatory" attributes of the binding are not suppliedNamingException
- if a naming exception is encountered- See Also:
-
rebind
Description copied from interface:DirContext
Binds a name to an object, along with associated attributes, overwriting any existing binding. SeeDirContext.rebind(Name, Object, Attributes)
for details.- Specified by:
rebind
in interfaceDirContext
- Parameters:
name
- the name to bind; may not be emptyobj
- the object to bind; possibly nullattrs
- the attributes to associate with the binding- Throws:
InvalidAttributesException
- if some "mandatory" attributes of the binding are not suppliedNamingException
- if a naming exception is encountered
-
rebind
Description copied from interface:DirContext
Binds a name to an object, along with associated attributes, overwriting any existing binding. Ifattrs
is null andobj
is aDirContext
, the attributes fromobj
are used. Ifattrs
is null andobj
is not aDirContext
, any existing attributes associated with the object already bound in the directory remain unchanged. Ifattrs
is non-null, any existing attributes associated with the object already bound in the directory are removed andattrs
is associated with the named object. Ifobj
is aDirContext
andattrs
is non-null, the attributes ofobj
are ignored.- Specified by:
rebind
in interfaceDirContext
- Parameters:
name
- the name to bind; may not be emptyobj
- the object to bind; possibly nullattrs
- the attributes to associate with the binding- Throws:
InvalidAttributesException
- if some "mandatory" attributes of the binding are not suppliedNamingException
- if a naming exception is encountered- See Also:
-
createSubcontext
Description copied from interface:DirContext
Creates and binds a new context, along with associated attributes. SeeDirContext.createSubcontext(Name, Attributes)
for details.- Specified by:
createSubcontext
in interfaceDirContext
- Parameters:
name
- the name of the context to create; may not be emptyattrs
- the attributes to associate with the newly created context- Returns:
- the newly created context
- Throws:
NameAlreadyBoundException
- if the name is already boundInvalidAttributesException
- ifattrs
does not contain all the mandatory attributes required for creationNamingException
- if a naming exception is encountered
-
createSubcontext
Description copied from interface:DirContext
Creates and binds a new context, along with associated attributes. 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. Ifattrs
is null, this method is equivalent toContext.createSubcontext()
.- Specified by:
createSubcontext
in interfaceDirContext
- Parameters:
name
- the name of the context to create; may not be emptyattrs
- the attributes to associate with the newly created context- Returns:
- the newly created context
- Throws:
NameAlreadyBoundException
- if the name is already boundInvalidAttributesException
- ifattrs
does not contain all the mandatory attributes required for creationNamingException
- if a naming exception is encountered- See Also:
-
getSchema
Description copied from interface:DirContext
Retrieves the schema associated with the named object. SeeDirContext.getSchema(Name)
for details.- Specified by:
getSchema
in interfaceDirContext
- Parameters:
name
- the name of the object whose schema is to be retrieved- Returns:
- the schema associated with the context; never null
- Throws:
OperationNotSupportedException
- if schema not supportedNamingException
- if a naming exception is encountered
-
getSchema
Description copied from interface:DirContext
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.
- Specified by:
getSchema
in interfaceDirContext
- Parameters:
name
- the name of the object whose schema is to be retrieved- Returns:
- the schema associated with the context; never null
- Throws:
OperationNotSupportedException
- if schema not supportedNamingException
- if a naming exception is encountered
-
getSchemaClassDefinition
Description copied from interface:DirContext
Retrieves a context containing the schema objects of the named object's class definitions. SeeDirContext.getSchemaClassDefinition(Name)
for details.- Specified by:
getSchemaClassDefinition
in interfaceDirContext
- Parameters:
name
- the name of the object whose object class definition is to be retrieved- Returns:
- the
DirContext
containing the named object's class definitions; never null - Throws:
OperationNotSupportedException
- if schema not supportedNamingException
- if a naming exception is encountered
-
getSchemaClassDefinition
Description copied from interface:DirContext
Retrieves a context containing the schema objects of the named object's class definitions.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 aDirContext
representing the (directory's) object class definition of "Person".The information that can be retrieved from an object class definition is directory-dependent.
Prior to JNDI 1.2, this method returned a single schema object representing the class definition of the named object. Since JNDI 1.2, this method returns a
DirContext
containing all of the named object's class definitions.- Specified by:
getSchemaClassDefinition
in interfaceDirContext
- Parameters:
name
- the name of the object whose object class definition is to be retrieved- Returns:
- the
DirContext
containing the named object's class definitions; never null - Throws:
OperationNotSupportedException
- if schema not supportedNamingException
- if a naming exception is encountered
-
search
public NamingEnumeration<SearchResult> search(String name, Attributes matchingAttributes) throws NamingException Description copied from interface:DirContext
Searches in a single context for objects that contain a specified set of attributes. SeeDirContext.search(Name, Attributes)
for details.- Specified by:
search
in interfaceDirContext
- Parameters:
name
- the name of the context to searchmatchingAttributes
- the attributes to search for- Returns:
- an enumeration of
SearchResult
objects - Throws:
NamingException
- if a naming exception is encountered
-
search
public NamingEnumeration<SearchResult> search(Name name, Attributes matchingAttributes) throws NamingException Description copied from interface:DirContext
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 as theattributesToReturn
parameter to the methodsearch(Name, Attributes, String[])
.
SeeDirContext.search(Name, Attributes, String[])
for a full description.- Specified by:
search
in interfaceDirContext
- Parameters:
name
- the name of the context to searchmatchingAttributes
- the attributes to search for- Returns:
- an enumeration of
SearchResult
objects - Throws:
NamingException
- if a naming exception is encountered- See Also:
-
search
public NamingEnumeration<SearchResult> search(String name, Attributes matchingAttributes, String[] attributesToReturn) throws NamingException Description copied from interface:DirContext
Searches in a single context for objects that contain a specified set of attributes, and retrieves selected attributes. SeeDirContext.search(Name, Attributes, String[])
for details.- Specified by:
search
in interfaceDirContext
- Parameters:
name
- the name of the context to searchmatchingAttributes
- the attributes to search forattributesToReturn
- the attributes to return- Returns:
- a non-null enumeration of
SearchResult
objects - Throws:
NamingException
- if a naming exception is encountered
-
search
public NamingEnumeration<SearchResult> search(Name name, Attributes matchingAttributes, String[] attributesToReturn) throws NamingException Description copied from interface:DirContext
Searches in a single context for objects that contain a specified set of attributes, and retrieves selected attributes. The search is performed using the defaultSearchControls
settings.For an object to be selected, each attribute in
matchingAttributes
must match some attribute of the object. IfmatchingAttributes
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 defined 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. For matching based on operations other than equality (such as substring comparison) use the version of thesearch
method that takes a filter argument.When changes are made to this
DirContext
, the effect on enumerations returned by prior calls to this method is undefined.If the object does not have the attribute specified, the directory will ignore the nonexistent attribute and return the requested attributes that the object does have.
A directory might return more attributes than was requested (see Attribute Type Names in the class description), but is not allowed to return arbitrary, unrelated attributes.
See also Operational Attributes in the class description.
- Specified by:
search
in interfaceDirContext
- Parameters:
name
- the name of the context to searchmatchingAttributes
- 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 are to be returned; an empty array indicates that none are to be returned.- Returns:
- a non-null enumeration of
SearchResult
objects. EachSearchResult
contains the attributes identified byattributesToReturn
and the name of the corresponding object, named relative to the context named byname
. - Throws:
NamingException
- if a naming exception is encountered- See Also:
-
search
public NamingEnumeration<SearchResult> search(String name, String filter, SearchControls cons) throws NamingException Description copied from interface:DirContext
Searches in the named context or object for entries that satisfy the given search filter. Performs the search as specified by the search controls. SeeDirContext.search(Name, String, SearchControls)
for details.- Specified by:
search
in interfaceDirContext
- Parameters:
name
- the name of the context or object to searchfilter
- the filter expression to use for the search; may not be nullcons
- the search controls that control the search. If null, the default search controls are used (equivalent to(new SearchControls())
).- Returns:
- an enumeration of
SearchResult
s for the objects that satisfy the filter. - Throws:
InvalidSearchFilterException
- if the search filter specified is not supported or understood by the underlying directoryInvalidSearchControlsException
- if the search controls contain invalid settingsNamingException
- if a naming exception is encountered
-
search
public NamingEnumeration<SearchResult> search(Name name, String filter, SearchControls cons) throws NamingException Description copied from interface:DirContext
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 2254 with the following interpretations forattr
andvalue
mentioned in the RFC.attr
is the attribute's identifier.value
is the string representation the attribute's value. The translation of this string representation into the attribute's value is directory-specific.For the assertion "someCount=127", for example,
attr
is "someCount" andvalue
is "127". The provider determines, based on the attribute ID ("someCount") (and possibly its schema), that the attribute's value is an integer. It then parses the string "127" appropriately.Any non-ASCII characters in the filter string should be represented by the appropriate Java (Unicode) characters, and not encoded as UTF-8 octets. Alternately, the "backslash-hexcode" notation described in RFC 2254 may be used.
If the directory does not support a 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 instead. The service provider for such a directory would then translate the filter arguments to its service-specific representation for filter evaluation. Seesearch(Name, String, Object[], SearchControls)
.RFC 2254 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 the operators defined in RFC 2254 are applicable to all attributes. When an operator is not applicable, the exception
InvalidSearchFilterException
is thrown.The result is returned in an enumeration of
SearchResult
s. EachSearchResult
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 thename
parameter), or it is a URL string. If the target context is included in the enumeration (as is possible whencons
specifies a search scope ofSearchControls.OBJECT_SCOPE
orSearchControls.SUBSTREE_SCOPE
), its name is the empty string. TheSearchResult
may also contain attributes of the matching object if thecons
argument specified that attributes be returned.If the object does not have a requested attribute, that nonexistent attribute will be ignored. Those requested attributes that the object does have will be returned.
A directory might return more attributes than were requested (see Attribute Type Names in the class description) but is not allowed to return arbitrary, unrelated attributes.
See also Operational Attributes in the class description.
- Specified by:
search
in interfaceDirContext
- Parameters:
name
- the name of the context or object to searchfilter
- the filter expression to use for the search; may not be nullcons
- the search controls that control the search. If null, the default search controls are used (equivalent to(new SearchControls())
).- Returns:
- an enumeration of
SearchResult
s of the objects that satisfy the filter; never null - Throws:
InvalidSearchFilterException
- if the search filter specified is not supported or understood by the underlying directoryInvalidSearchControlsException
- if the search controls contain invalid settingsNamingException
- if a naming exception is encountered- See Also:
-
search
public NamingEnumeration<SearchResult> search(String name, String filterExpr, Object[] filterArgs, SearchControls cons) throws NamingException Description copied from interface:DirContext
Searches in the named context or object for entries that satisfy the given search filter. Performs the search as specified by the search controls. SeeDirContext.search(Name, String, Object[], SearchControls)
for details.- Specified by:
search
in interfaceDirContext
- Parameters:
name
- the name of the context or object to searchfilterExpr
- the filter expression to use for the search. The expression may contain variables of the form "{i}
" wherei
is a nonnegative integer. May not be null.filterArgs
- the array of arguments to substitute for the variables infilterExpr
. The value offilterArgs[i]
will replace each occurrence of "{i}
". If null, equivalent to an empty array.cons
- the search controls that control the search. If null, the default search controls are used (equivalent to(new SearchControls())
).- Returns:
- an enumeration of
SearchResult
s of the objects that satisfy the filter; never null - Throws:
InvalidSearchControlsException
- ifcons
contains invalid settingsInvalidSearchFilterException
- iffilterExpr
withfilterArgs
represents an invalid search filterNamingException
- if a naming exception is encountered
-
search
public NamingEnumeration<SearchResult> search(Name name, String filterExpr, Object[] filterArgs, SearchControls cons) throws NamingException Description copied from interface:DirContext
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 interpretation of
filterExpr
is based on RFC 2254. It may additionally contain variables of the form{i}
-- wherei
is an integer -- that refer to objects in thefilterArgs
array. The interpretation offilterExpr
is otherwise identical to that of thefilter
parameter of the methodsearch(Name, String, SearchControls)
.When a variable
{i}
appears in a search filter, it indicates that the filter argumentfilterArgs[i]
is to be used in that place. Such variables may be used wherever an attr, value, or matchingrule production appears in the filter grammar of RFC 2254, section 4. When a string-valued filter argument is substituted for a variable, the filter is interpreted as if the string were given in place of the variable, with any characters having special significance within filters (such as'*'
) having been escaped according to the rules of RFC 2254.For directories that do not use a string representation for some or all of their attributes, the filter argument corresponding to an attribute value may be of a type other than String. Directories that support unstructured binary-valued attributes, for example, should accept byte arrays as filter arguments. The interpretation (if any) of filter arguments of any other type is determined by the service provider for that directory, which maps the filter operations onto operations with corresponding semantics in the underlying directory.
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 thename
parameter), or it is a URL string. If the target context is included in the enumeration (as is possible whencons
specifies a search scope ofSearchControls.OBJECT_SCOPE
orSearchControls.SUBSTREE_SCOPE
), its name is the empty string.The
SearchResult
may also contain attributes of the matching object if thecons
argument specifies that attributes be returned.If the object does not have a requested attribute, that nonexistent attribute will be ignored. Those requested attributes that the object does have will be returned.
A directory might return more attributes than were requested (see Attribute Type Names in the class description) but is not allowed to return arbitrary, unrelated attributes.
If a search filter with invalid variable substitutions is provided to this method, the result is undefined. When changes are made to this DirContext, the effect on enumerations returned by prior calls to this method is undefined.
See also Operational Attributes in the class description.
- Specified by:
search
in interfaceDirContext
- Parameters:
name
- the name of the context or object to searchfilterExpr
- the filter expression to use for the search. The expression may contain variables of the form "{i}
" wherei
is a nonnegative integer. May not be null.filterArgs
- the array of arguments to substitute for the variables infilterExpr
. The value offilterArgs[i]
will replace each occurrence of "{i}
". If null, equivalent to an empty array.cons
- the search controls that control the search. If null, the default search controls are used (equivalent to(new SearchControls())
).- Returns:
- an enumeration of
SearchResult
s of the objects that satisfy the filter; never null - Throws:
InvalidSearchControlsException
- ifcons
contains invalid settingsInvalidSearchFilterException
- iffilterExpr
withfilterArgs
represents an invalid search filterNamingException
- if a naming exception is encountered- See Also:
-