|
JavaTM 2 Platform Std. Ed. v1.4.1 |
||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||||
java.lang.Object
|
+--javax.naming.InitialContext
|
+--javax.naming.directory.InitialDirContext
This class is the starting context for performing directory operations. The documentation in the class description of InitialContext (including those for synchronization) apply here.
InitialContext| Field Summary |
| Fields inherited from class javax.naming.InitialContext |
defaultInitCtx, gotDefault, myProps |
| Fields inherited from interface javax.naming.directory.DirContext |
ADD_ATTRIBUTE, REMOVE_ATTRIBUTE, REPLACE_ATTRIBUTE |
| Fields inherited from interface javax.naming.Context |
APPLET, 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 |
| Constructor Summary | |
|
InitialDirContext()
Constructs 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 | |
void |
bind(Name name,
Object obj,
Attributes attrs)
Binds a name to an object, along with associated attributes. |
void |
bind(String name,
Object obj,
Attributes attrs)
Binds a name to an object, along with associated attributes. |
DirContext |
createSubcontext(Name name,
Attributes attrs)
Creates and binds a new context, along with associated attributes. |
DirContext |
createSubcontext(String name,
Attributes attrs)
Creates and binds a new context, along with associated attributes. |
Attributes |
getAttributes(Name name)
Retrieves all of the attributes associated with a named object. |
Attributes |
getAttributes(Name name,
String[] attrIds)
Retrieves selected attributes associated with a named object. |
Attributes |
getAttributes(String name)
Retrieves all of the attributes associated with a named object. |
Attributes |
getAttributes(String name,
String[] attrIds)
Retrieves selected attributes associated with a named object. |
DirContext |
getSchema(Name name)
Retrieves the schema associated with the named object. |
DirContext |
getSchema(String name)
Retrieves the schema associated with the named object. |
DirContext |
getSchemaClassDefinition(Name name)
Retrieves a context containing the schema objects of the named object's class definitions. |
DirContext |
getSchemaClassDefinition(String name)
Retrieves a context containing the schema objects of the named object's class definitions. |
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 |
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 |
rebind(Name name,
Object obj,
Attributes attrs)
Binds a name to an object, along with associated attributes, overwriting any existing binding. |
void |
rebind(String name,
Object obj,
Attributes attrs)
Binds a name to an object, along with associated attributes, overwriting any existing binding. |
NamingEnumeration |
search(Name name,
Attributes matchingAttributes)
Searches in a single context for objects that contain a specified set of attributes. |
NamingEnumeration |
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. |
NamingEnumeration |
search(Name name,
String filterExpr,
Object[] filterArgs,
SearchControls cons)
Searches in the named context or object for entries that satisfy the given search filter. |
NamingEnumeration |
search(Name name,
String filter,
SearchControls cons)
Searches in the named context or object for entries that satisfy the given search filter. |
NamingEnumeration |
search(String name,
Attributes matchingAttributes)
Searches in a single context for objects that contain a specified set of attributes. |
NamingEnumeration |
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. |
NamingEnumeration |
search(String name,
String filterExpr,
Object[] filterArgs,
SearchControls cons)
Searches in the named context or object for entries that satisfy the given search filter. |
NamingEnumeration |
search(String name,
String filter,
SearchControls cons)
Searches in the named context or object for entries that satisfy the given search filter. |
| Methods inherited from class javax.naming.InitialContext |
addToEnvironment, bind, bind, close, composeName, composeName, createSubcontext, createSubcontext, destroySubcontext, destroySubcontext, getDefaultInitCtx, getEnvironment, getNameInNamespace, getNameParser, getNameParser, getURLOrDefaultInitCtx, getURLOrDefaultInitCtx, init, list, list, listBindings, listBindings, lookup, lookup, lookupLink, lookupLink, rebind, rebind, removeFromEnvironment, rename, rename, unbind, unbind |
| Methods inherited from class java.lang.Object |
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
| Methods inherited from interface javax.naming.Context |
addToEnvironment, bind, bind, close, composeName, composeName, createSubcontext, createSubcontext, destroySubcontext, destroySubcontext, getEnvironment, getNameInNamespace, getNameParser, getNameParser, list, list, listBindings, listBindings, lookup, lookup, lookupLink, lookupLink, rebind, rebind, removeFromEnvironment, rename, rename, unbind, unbind |
| Constructor Detail |
protected InitialDirContext(boolean lazy)
throws NamingException
lazy - true means do not initialize the initial DirContext; false
is equivalent to calling new InitialDirContext()
NamingException - if a naming exception is encounteredInitialContext.init(Hashtable)
public InitialDirContext()
throws NamingException
NamingException - if a naming exception is encounteredInitialDirContext(Hashtable)
public InitialDirContext(Hashtable environment)
throws NamingException
This constructor will not modify environment or save a reference to it, but may save a clone.
environment - environment used to create the initial DirContext.
Null indicates an empty environment.
NamingException - if a naming exception is encountered| Method Detail |
public Attributes getAttributes(String name)
throws NamingException
DirContextDirContext.getAttributes(Name) for details.
getAttributes in interface DirContextname - the name of the object from which to retrieve attributes
name
NamingException - if a naming exception is encountered
public Attributes getAttributes(String name,
String[] attrIds)
throws NamingException
DirContextDirContext.getAttributes(Name, String[]) for details.
getAttributes in interface DirContextname - 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.
NamingException - if a naming exception is encountered
public Attributes getAttributes(Name name)
throws NamingException
DirContext
getAttributes in interface DirContextname - the name of the object from which to retrieve attributes
name.
Returns an empty attribute set if name has no attributes;
never null.
NamingException - if a naming exception is encounteredDirContext.getAttributes(String),
DirContext.getAttributes(Name, String[])
public Attributes getAttributes(Name name,
String[] attrIds)
throws NamingException
DirContextIf 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.
getAttributes in interface DirContextname - 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.
NamingException - if a naming exception is encountered
public void modifyAttributes(String name,
int mod_op,
Attributes attrs)
throws NamingException
DirContextDirContext.modifyAttributes(Name, int, Attributes) for details.
modifyAttributes in interface DirContextname - 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; map not be null
NamingException - if a naming exception is encountered
public void modifyAttributes(Name name,
int mod_op,
Attributes attrs)
throws NamingException
DirContext
modifyAttributes in interface DirContextname - 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
NamingException - if a naming exception is encounteredDirContext.modifyAttributes(Name, ModificationItem[])
public void modifyAttributes(String name,
ModificationItem[] mods)
throws NamingException
DirContextDirContext.modifyAttributes(Name, ModificationItem[]) for details.
modifyAttributes in interface DirContextname - the name of the object whose attributes will be updatedmods - an ordered sequence of modifications to be performed;
may not be null
NamingException - if a naming exception is encountered
public void modifyAttributes(Name name,
ModificationItem[] mods)
throws NamingException
DirContext
modifyAttributes in interface DirContextname - the name of the object whose attributes will be updatedmods - an ordered sequence of modifications to be performed;
may not be null
NamingException - if a naming exception is encounteredDirContext.modifyAttributes(Name, int, Attributes),
ModificationItem
public void bind(String name,
Object obj,
Attributes attrs)
throws NamingException
DirContextDirContext.bind(Name, Object, Attributes) for details.
bind in interface DirContextname - the name to bind; may not be emptyobj - the object to bind; possibly nullattrs - the attributes to associate with the binding
NamingException - if a naming exception is encountered
public void bind(Name name,
Object obj,
Attributes attrs)
throws NamingException
DirContext
bind in interface DirContextname - the name to bind; may not be emptyobj - the object to bind; possibly nullattrs - the attributes to associate with the binding
NamingException - if a naming exception is encounteredContext.bind(Name, Object),
DirContext.rebind(Name, Object, Attributes)
public void rebind(String name,
Object obj,
Attributes attrs)
throws NamingException
DirContextDirContext.rebind(Name, Object, Attributes) for details.
rebind in interface DirContextname - the name to bind; may not be emptyobj - the object to bind; possibly nullattrs - the attributes to associate with the binding
NamingException - if a naming exception is encountered
public void rebind(Name name,
Object obj,
Attributes attrs)
throws NamingException
DirContext
rebind in interface DirContextname - the name to bind; may not be emptyobj - the object to bind; possibly nullattrs - the attributes to associate with the binding
NamingException - if a naming exception is encounteredContext.bind(Name, Object),
DirContext.bind(Name, Object, Attributes)
public DirContext createSubcontext(String name,
Attributes attrs)
throws NamingException
DirContextDirContext.createSubcontext(Name, Attributes) for details.
createSubcontext in interface DirContextname - the name of the context to create; may not be emptyattrs - the attributes to associate with the newly created context
NamingException - if a naming exception is encountered
public DirContext createSubcontext(Name name,
Attributes attrs)
throws NamingException
DirContext
createSubcontext in interface DirContextname - the name of the context to create; may not be emptyattrs - the attributes to associate with the newly created context
NamingException - if a naming exception is encounteredContext.createSubcontext(Name)
public DirContext getSchema(String name)
throws NamingException
DirContextDirContext.getSchema(Name) for details.
getSchema in interface DirContextname - the name of the object whose schema is to be retrieved
NamingException - if a naming exception is encountered
public DirContext getSchema(Name name)
throws NamingException
DirContextThis 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.
getSchema in interface DirContextname - the name of the object whose schema is to be retrieved
NamingException - if a naming exception is encountered
public DirContext getSchemaClassDefinition(String name)
throws NamingException
DirContextDirContext.getSchemaClassDefinition(Name) for details.
getSchemaClassDefinition in interface DirContextname - the name of the object whose object class
definition is to be retrieved
NamingException - if a naming exception is encountered
public DirContext getSchemaClassDefinition(Name name)
throws NamingException
DirContextOne 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 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.
getSchemaClassDefinition in interface DirContextname - the name of the object whose object class
definition is to be retrieved
NamingException - if a naming exception is encountered
public NamingEnumeration search(String name,
Attributes matchingAttributes)
throws NamingException
DirContextDirContext.search(Name, Attributes) for details.
search in interface DirContextname - the name of the context to searchmatchingAttributes - the attributes to search for
NamingException - if a naming exception is encountered
public NamingEnumeration search(Name name,
Attributes matchingAttributes)
throws NamingException
DirContextsearch(Name, Attributes, String[]).
DirContext.search(Name, Attributes, String[]) for a full description.
search in interface DirContextname - the name of the context to searchmatchingAttributes - the attributes to search for
NamingException - if a naming exception is encounteredDirContext.search(Name, Attributes, String[])
public NamingEnumeration search(String name,
Attributes matchingAttributes,
String[] attributesToReturn)
throws NamingException
DirContextDirContext.search(Name, Attributes, String[]) for details.
search in interface DirContextname - the name of the context to searchmatchingAttributes - the attributes to search forattributesToReturn - the attributes to return
NamingException - if a naming exception is encountered
public NamingEnumeration search(Name name,
Attributes matchingAttributes,
String[] attributesToReturn)
throws NamingException
DirContextSearchControls 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 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 the search
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.
search in interface DirContextname - 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.
attributesToReturn
and the name of the corresponding object, named relative
to the context named by name.
NamingException - if a naming exception is encounteredSearchControls,
SearchResult,
DirContext.search(Name, String, Object[], SearchControls)
public NamingEnumeration search(String name,
String filter,
SearchControls cons)
throws NamingException
DirContextDirContext.search(Name, String, SearchControls) for details.
search in interface DirContextname - 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())).
NamingException - if a naming exception is encountered
public NamingEnumeration search(Name name,
String filter,
SearchControls cons)
throws NamingException
DirContext
The format and interpretation of filter follows RFC 2254
with the
following interpretations for attr and value
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" 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.
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.
See search(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 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. The SearchResult may also contain attributes of the
matching object if the cons 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.
search in interface DirContextname - 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())).
NamingException - if a naming exception is encounteredDirContext.search(Name, String, Object[], SearchControls),
SearchControls,
SearchResult
public NamingEnumeration search(String name,
String filterExpr,
Object[] filterArgs,
SearchControls cons)
throws NamingException
DirContextDirContext.search(Name, String, Object[], SearchControls) for details.
search in interface DirContextname - 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}" where i
is a nonnegative integer. May not be null.filterArgs - the array of arguments to substitute for the variables
in filterExpr. The value of
filterArgs[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())).
NamingException - if a naming exception is encountered
public NamingEnumeration search(Name name,
String filterExpr,
Object[] filterArgs,
SearchControls cons)
throws NamingException
DirContext
The interpretation of filterExpr is based on RFC
2254. It may additionally contain variables of the form
{i} -- where i is an integer -- that
refer to objects in the filterArgs array. The
interpretation of filterExpr is otherwise
identical to that of the filter parameter of the
method search(Name, String, SearchControls).
When a variable {i} appears in a search filter, it
indicates that the filter argument filterArgs[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 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.
The SearchResult may also contain attributes of the matching object if the cons 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.
search in interface DirContextname - 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}" where i
is a nonnegative integer. May not be null.filterArgs - the array of arguments to substitute for the variables
in filterExpr. The value of
filterArgs[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())).
NamingException - if a naming exception is encounteredDirContext.search(Name, Attributes, String[]),
MessageFormat
|
JavaTM 2 Platform Std. Ed. v1.4.1 |
||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||||
Copyright 2002 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms.