javax.naming.directory
Class InitialDirContext

java.lang.Object
  |
  +--javax.naming.InitialContext
        |
        +--javax.naming.directory.InitialDirContext

public class InitialDirContext

extends InitialContext

implements DirContext

This class is the starting context for performing directory operations. The documentation in the class description of InitialContext (including those for synchronization) apply here.

See Also:

InitialContext

Fields inherited from class javax.naming.InitialContext

defaultInitCtx, gotDefault, myProps

Constructor Summary

InitialDirContext()
Constructs an initial DirContext.

InitialDirContext(java.util.Hashtable environment)
Constructs an initial DirContext using information supplied in 'environment'.

Method Summary

void	bind(Name name, java.lang.Object obj, Attributes attrs) Binds 'name' to the object 'obj' and associate the attributes 'attrs' with the named object.
void	bind(java.lang.String name, java.lang.Object obj, Attributes attrs) Binds 'name' to the object 'obj' and associate the attributes 'attrs' with the named object.
DirContext	createSubcontext(Name name, Attributes attrs) Creates a new subcontext with the given name resolved relative to the initial context, and associates the attributes 'attrs' with the named object.
DirContext	createSubcontext(java.lang.String name, Attributes attrs) Creates a new subcontext with the given name resolved relative to the initial context, and associates the attributes 'attrs' with the named object.
Attributes	getAttributes(Name name) Retrieves all the attributes associated with named object.
Attributes	getAttributes(Name name, java.lang.String[] attrIds) Retrieves the attributes listed in attrIds associated with named object.
Attributes	getAttributes(java.lang.String name) Retrieves all the attributes associated with named object.
Attributes	getAttributes(java.lang.String name, java.lang.String[] attrIds) Retrieves the attributes listed in attrIds associated with named object.
DirContext	getSchema(Name name) Retrieves the schema associated with this initial DirContext.
DirContext	getSchema(java.lang.String name) Retrieves the schema associated with this initial DirContext.
DirContext	getSchemaClassDefinition(Name name) Retrieves the schema class definition associated with this initial context.
DirContext	getSchemaClassDefinition(java.lang.String name) Retrieves the schema class definition associated with this initial context.
void	modifyAttributes(Name name, int mod_op, Attributes attrs) Modifies according to mod_op and attrs the attributes associated with the named object.
void	modifyAttributes(Name name, ModificationItem[] mods) Modifies according to mods the attributes associated with the named object.
void	modifyAttributes(java.lang.String name, int mod_op, Attributes attrs) Modifies according to mod_op and attrs the attributes associated with the named object.
void	modifyAttributes(java.lang.String name, ModificationItem[] mods) Modifies according to mods the attributes associated with the named object.
void	rebind(Name name, java.lang.Object obj, Attributes attrs) Binds 'name' to the object 'obj' and associates the attributes 'attrs' with the named object.
void	rebind(java.lang.String name, java.lang.Object obj, Attributes attrs) Binds 'name' to the object 'obj' and associates the attributes 'attrs' with the named object.
NamingEnumeration	search(Name name, Attributes matchingAttributes) Searches for named objects that contain a set of attributes in a single context.
NamingEnumeration	search(Name name, Attributes matchingAttributes, java.lang.String[] attributesToReturn) Searches for named objects that contain a set of attributes in a single context.
NamingEnumeration	search(Name name, java.lang.String filterExpr, java.lang.Object[] filterArgs, SearchControls cons) Search in the context named by 'name' entries with that satisfies the given 'filter'.
NamingEnumeration	search(Name name, java.lang.String filter, SearchControls cons) Search in the context named by 'name' entries with that satisfies the given string 'filter'.
NamingEnumeration	search(java.lang.String name, Attributes matchingAttributes) Searches for named objects that contain a set of attributes in a single context.
NamingEnumeration	search(java.lang.String name, Attributes matchingAttributes, java.lang.String[] attributesToReturn) Searches for named objects that contain a set of attributes in a single context.
NamingEnumeration	search(java.lang.String name, java.lang.String filterExpr, java.lang.Object[] filterArgs, SearchControls cons) Search in the context named by 'name' entries with that satisfies the given 'filter'.
NamingEnumeration	search(java.lang.String name, java.lang.String filter, SearchControls cons) Search in the context named by 'name' entries with that satisfies the given string 'filter'.

Methods inherited from class javax.naming.InitialContext

addToEnvironment, bind, bind, close, composeName, composeName, createSubcontext, createSubcontext, destroySubcontext, destroySubcontext, getDefaultInitCtx, getEnvironment, getNameParser, getNameParser, getURLOrDefaultInitCtx, getURLOrDefaultInitCtx, 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

Constructor Detail

InitialDirContext

public InitialDirContext()
                  throws NamingException

Constructs an initial DirContext. The environment of the new context are set to null.

Throws:

NamingException - If a problem was encountered while creating the initial context.

InitialDirContext

public InitialDirContext(java.util.Hashtable environment)
                  throws NamingException

Constructs an initial DirContext using information supplied in 'environment'.

Parameters:

environment - The possibly null environment used for creating the initial context (such as user name, password, etc.)

Throws:

NamingException - If a problem was encountered while creating the initial context.

Method Detail

getAttributes

public Attributes getAttributes(java.lang.String name)
                         throws NamingException

Retrieves all the attributes associated with named object.

Specified by:

getAttributes in interface DirContext

Parameters:

name - The non-null string name of the object for which to retrieve the attributes. name is resolved relative to the initial context.

Returns:

The attributes associated with 'name'.

Throws:

NamingException - If a naming exception occurs.

See Also:

DirContext.getAttributes(javax.naming.Name)

getAttributes

public Attributes getAttributes(java.lang.String name,
                                java.lang.String[] attrIds)
                         throws NamingException

Retrieves the attributes listed in attrIds associated with named object.

Specified by:

getAttributes in interface DirContext

Parameters:

name - The non-null string name of the object for which to retrieve the attributes. name is resolved relative to the initial context.

attrIds - The attribute ids of the attributes to retrieve. Possibly null.

Returns:

The attributes identified by attrIds (or a subset thereof if some attributes are not found). Can be empty but not null.

Throws:

NamingException - If a naming exception occurs.

getAttributes

public Attributes getAttributes(Name name)
                         throws NamingException

Retrieves all the attributes associated with named object.

Specified by:

getAttributes in interface DirContext

Parameters:

name - The non-null name of the object for which to retrieve the attributes. name is resolved relative to the initial context.

Returns:

The attributes associated with 'name'. Can be empty but not null.

Throws:

NamingException - If a naming exception occurs.

getAttributes

public Attributes getAttributes(Name name,
                                java.lang.String[] attrIds)
                         throws NamingException

Retrieves the attributes listed in attrIds associated with named object.

Specified by:

getAttributes in interface DirContext

Parameters:

name - The non-null name of the object for which to retrieve the attributes. name is resolved relative to the initial context.

attrIds - The attribute ids of the attributes to retrieve. Can be null.

Returns:

The attributes identified by attrIds (or a subset thereof if some attributes are not found). Can be empty but not null.

Throws:

NamingException - If a naming exception occurs.

modifyAttributes

public void modifyAttributes(java.lang.String name,
                             int mod_op,
                             Attributes attrs)
                      throws NamingException

Modifies according to mod_op and attrs the attributes associated with the named object. The order of the modifications within attrs are not specified. Where possible, the modifications are performed atomically. If the operation fails to complete, AttributeModificationException or another subclass of NamingException is thrown containing details of the failure.

Specified by:

modifyAttributes in interface DirContext

Parameters:

name - The string name of the object whose attributes will be updated. name is resolved relative to the initial context.

mod_op - The modification operation. It is one of ADD_ATTRIBUTE, REPLACE_ATTRIBUTE, DELETE_ATTRIBUTE.

attrs - The non-null set of attributes to use for the modification.

Throws:

NamingException - If a naming exception occurs.

modifyAttributes

public void modifyAttributes(Name name,
                             int mod_op,
                             Attributes attrs)
                      throws NamingException

Modifies according to mod_op and attrs the attributes associated with the named object. The order of the modifications within attrs are not specified. Where possible, the modifications are performed atomically. If the operation fails to complete, AttributeModificationException or another subclass of NamingException is thrown containing details of the failure.

Specified by:

modifyAttributes in interface DirContext

Parameters:

name - The non-null name of the object whose attributes will be updated. name is resolved relative to the initial context.

attrs - The non-null attributes to use for the modification.

mod_op - The modification code.

Throws:

AttributeModificationException - If modification could not be completed successfully.

NamingException - If a naming exception occurred.

modifyAttributes

public void modifyAttributes(java.lang.String name,
                             ModificationItem[] mods)
                      throws NamingException

Modifies according to mods the attributes associated with the named object. Where possible, the modifications are performed atomically. If the operation fails to complete, AttributeModificationException or another subclass of NamingException is thrown containing details of the failure.

Specified by:

modifyAttributes in interface DirContext

Parameters:

name - The non-null string name of the object whose attributes will be updated. name is resolved relative to the initial context.

mods - The non-null list of modifications to apply.

Throws:

AttributeModificationException - If modification could not be completed successfully.

NamingException - If a naming exception occurred.

modifyAttributes

public void modifyAttributes(Name name,
                             ModificationItem[] mods)
                      throws NamingException

Modifies according to mods the attributes associated with the named object. Where possible, the modifications are performed atomically. If the operation fails to complete, AttributeModificationException or another subclass of NamingException is thrown containing details of the failure.

Specified by:

modifyAttributes in interface DirContext

Parameters:

name - The non-null name of the object whose attributes will be updated. name is resolved relative to the initial context.

mods - The non-null list of modifications to apply.

Throws:

AttributeModificationException - If modification could not be completed successfully.

NamingException - If a naming exception occurred.

bind

public void bind(java.lang.String name,
                 java.lang.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.

Specified by:

bind in interface DirContext

Parameters:

name - The non-null name to bind, resolved relative to the initial context. It cannot be empty.

obj - The possibly null object to bind.

attrs - The possibly null set of attributes to associate with the bound object.

Throws:

NameAlreadyBoundException - If name is already bound.

InvalidAttributesException - If the attributes specified by 'attrs', or 'obj' if 'attrs' is null, are not sufficient to create the binding.

NamingException - If a naming exception occurs.

bind

public void bind(Name name,
                 java.lang.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.

Specified by:

bind in interface DirContext

Parameters:

name - The non-null name to bind, resolved relative to the initial context. It cannot be empty.

obj - The possibly null object to bind.

attrs - The possibly null set of attributes to associate with the bound object.

Throws:

NameAlreadyBoundException - If name is already bound.

InvalidAttributesException - If the attributes specified by 'attrs', or 'obj' if 'attrs' is null, are not sufficient to create the binding.

NamingException - If a naming exception occurs.

rebind

public void rebind(java.lang.String name,
                   java.lang.Object obj,
                   Attributes attrs)
            throws NamingException

Binds 'name' to the object 'obj' and associates the attributes 'attrs' with the named object. 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 already bound object remain unchanged. If 'attrs' is non-null, any existing attributes associated with the already bound object 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.

Specified by:

rebind in interface DirContext

Parameters:

name - The non-null name to bind, resolved relative to the initial context.

obj - The possibly null object to bind.

attrs - The possibly null set of attributes to associate with the bound object.

Throws:

NamingException - If a naming exception occurs.

rebind

public void rebind(Name name,
                   java.lang.Object obj,
                   Attributes attrs)
            throws NamingException

Binds 'name' to the object 'obj' and associates the attributes 'attrs' with the named object. 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. any existing attributes associated with the already bound object remain unchanged. If 'attrs' is non-null, any existing attributes associated with the already bound object 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.

Specified by:

rebind in interface DirContext

Parameters:

name - The non-null name to bind, resolved relative to the initial context.

obj - The possibly null object to bind.

attrs - The possibly null attributes to associate with the bound object.

Throws:

NamingException - If a naming exception occurs.

createSubcontext

public DirContext createSubcontext(java.lang.String name,
                                   Attributes attrs)
                            throws NamingException

Creates a new subcontext with the given name resolved relative to the initial context, and associates the attributes 'attrs' with the named object. If 'name' is already bound, throws NameAlreadyBoundException.

Specified by:

createSubcontext in interface DirContext

Parameters:

name - The non-null string name to use when creating the new context. name is resolved relative to the initial context.

attrs - The attributes to associate with the newly created context. Can be null.

Returns:

The non-null newly created context.

Throws:

NameAlreadyBoundException - name is already bound.

InvalidAttributesException - If 'attrs' does not contain all the mandatory attributes required for creation.

NamingException - If a naming exception occurs.

createSubcontext

public DirContext createSubcontext(Name name,
                                   Attributes attrs)
                            throws NamingException

Creates a new subcontext with the given name resolved relative to the initial context, and associates the attributes 'attrs' with the named object.

Specified by:

createSubcontext in interface DirContext

Parameters:

name - The non-null name to use when creating the new context. name is resolved relative to the initial context.

attrs - The attributes to associate with the newly created context. Can be null.

Returns:

The non-null newly created context.

Throws:

NameAlreadyBoundException - If name is already bound.

InvalidAttributesException - If 'attrs' does not contain all the mandatory attributes required for creation.

NamingException - If a naming exception occurs.

getSchema

public DirContext getSchema(java.lang.String name)
                     throws NamingException

Retrieves the schema associated with this initial DirContext.

Specified by:

getSchema in interface DirContext

Parameters:

name - The non-null name of context.

Returns:

The non-null schema associated with this initial DirContext.

Throws:

NamingException - If a naming exception occurs.

getSchema

public DirContext getSchema(Name name)
                     throws NamingException

Retrieves the schema associated with this initial DirContext.

Specified by:

getSchema in interface DirContext

Parameters:

name - The non-null name of context.

Returns:

The non-null schema associated with this initial DirContext.

Throws:

NamingException - If a naming exception occurs.

getSchemaClassDefinition

public DirContext getSchemaClassDefinition(java.lang.String name)
                                    throws NamingException

Retrieves the schema class definition associated with this initial context.

Specified by:

getSchemaClassDefinition in interface DirContext

Parameters:

name - The non-null name of context.

Returns:

The schema class definition associated with this initial context.

Throws:

NamingException - If a naming exception occurs.

getSchemaClassDefinition

public DirContext getSchemaClassDefinition(Name name)
                                    throws NamingException

Retrieves the schema class definition associated with this initial context.

Specified by:

getSchemaClassDefinition in interface DirContext

Parameters:

name - The non-null name of context.

Returns:

The schema class definition associated with this initial context.

Throws:

NamingException - If a naming exception occurs.

search

public NamingEnumeration search(java.lang.String name,
                                Attributes matchingAttributes)
                         throws NamingException

Searches for named objects that contain a set of attributes in a single context. See descriptions in DirContext for details.

Specified by:

search in interface DirContext

Parameters:

name - The non-null string name of the context to search. name is resolved relative to the initial context.

matchingAttributes - The possibly null set of attributes to search for.

Returns:

A non-null enumeration of SearchResults.

Throws:

NamingException - If a naming exception occurs.

search

public NamingEnumeration search(Name name,
                                Attributes matchingAttributes)
                         throws NamingException

Searches for named objects that contain a set of attributes in a single context. See descriptions in DirContext for details.

Specified by:

search in interface DirContext

Parameters:

name - The non-null name of the context to search. name is resolved relative to the initial context.

matchingAttributes - The possibly null set of attributes to search for.

Returns:

A non-null enumeration of SearchResult.

Throws:

NamingException - If a naming exception occurs.

search

public NamingEnumeration search(java.lang.String name,
                                Attributes matchingAttributes,
                                java.lang.String[] attributesToReturn)
                         throws NamingException

Searches for named objects that contain a set of attributes in a single context. See descriptions in DirContext for details.

Specified by:

search in interface DirContext

Parameters:

name - The non-null name of the context to search. name is resolved relative to the initial context.

matchingAttributes - The attributes to search for. Possibly null.

attributesToReturn - The attributes to return. Possibly null.

Returns:

A non-null enumeration of SearchResults.

Throws:

NamingException - If a naming exception occurs.

search

public NamingEnumeration search(Name name,
                                Attributes matchingAttributes,
                                java.lang.String[] attributesToReturn)
                         throws NamingException

Searches for named objects that contain a set of attributes in a single context. See descriptions in DirContext for details.

Specified by:

search in interface DirContext

Parameters:

name - The non-null name of the context to search. name is resolved relative to the initial context.

matchingAttributes - The attributes to search for. Possibly null.

attributesToReturn - The attributes to return. Possibly null.

Returns:

A non-null enumeration of SearchResults.

Throws:

NamingException - If a naming exception occurs.

search

public NamingEnumeration search(java.lang.String name,
                                java.lang.String filter,
                                SearchControls cons)
                         throws NamingException

Search in the context named by 'name' entries with that satisfies the given string 'filter'. Perform the search according to parameters specified in the search constraints 'cons'. See descriptions in DirContext for details.

Specified by:

search in interface DirContext

Parameters:

name - The non-null string name of the context/object to start the search. name is resolved relative to the initial context.

filter - The non-null string filter to use for the search. The syntax used for the filter is the LDAP filter syntax (RFC 2254).

cons - The search constraints to be applied to this search. Can be null.

Returns:

A non-null enumeration of SearchResults.

Throws:

NamingException - If a naming exception occurs.

search

public NamingEnumeration search(Name name,
                                java.lang.String filter,
                                SearchControls cons)
                         throws NamingException

Search in the context named by 'name' entries with that satisfies the given string 'filter'. Perform the search according to parameters specified in the search constraints 'cons'.

Specified by:

search in interface DirContext

Parameters:

name - The non-null name of the context/object to start the search. name is resolved relative to the initial context.

filter - The non-null string filter to use for the search. The syntax used for the filter is the LDAP filter syntax (RFC 2254).

cons - The possibly null search constraints to be applied to this search.

Returns:

A non-null enumeration of SearchResults.

Throws:

NamingException - If a naming exception occurs.

search

public NamingEnumeration search(java.lang.String name,
                                java.lang.String filterExpr,
                                java.lang.Object[] filterArgs,
                                SearchControls cons)
                         throws NamingException

Search in the context named by 'name' entries with that satisfies the given 'filter'. Perform the search according to parameters specified in the search constraints 'cons'. See descriptions in DirContext for details.

Specified by:

search in interface DirContext

Parameters:

name - The non-null string name of the context/object to start the search. name is resolved relative to the initial context.

filter - The non-null filter to use for the search.

cons - The possibly null search constraints to be applied to this search.

Returns:

A non-null enumeration of SearchResults.

Throws:

NamingException - If a naming exception occurs.

search

public NamingEnumeration search(Name name,
                                java.lang.String filterExpr,
                                java.lang.Object[] filterArgs,
                                SearchControls cons)
                         throws NamingException

Search in the context named by 'name' entries with that satisfies the given 'filter'. Perform the search according to parameters specified in the search constraints 'cons'. See descriptions in DirContext for details.

Specified by:

search in interface DirContext

Parameters:

name - The non-null name of the context/object to start the search. name is resolved relative to the initial context.

filter - The non-null filter to use for the search.

cons - The possibly null search constraints to be applied to this search.

Returns:

A non null enumeration of SearchResults.

Throws:

NamingException - If a naming exception occurs.