Chapter 23. The javax.naming.directory Package

The javax.naming.directory package contains the core interfaces, classes, and exceptions for performing directory operations with JNDI. DirContext defines the interface to directory services, while Attribute represents an attribute that is associated with a directory entry. Figure 23-1 shows the hierarchy of this package.

Figure 23-1. The javax.naming.directory package

Attribute

JNDI 1.1

javax.naming.directory

cloneable serializable

This interface represents an attribute associated with a directory entry. The directory schema determines the classes of attributes that a directory entry with a certain object class definition is permitted to have. The class of a particular attribute is called the attribute type definition. The name of an attribute, called the attribute ID, is determined by the attribute type definition and has a String representation that refers to that particular attribute. Each attribute can have zero or more values of a particular class. The class of values an attribute is permitted to have is called the attribute syntax definition.

The directory schema, and therefore the attribute type and syntax definitions, depend on the underlying directory your JNDI application is using. You can use getAttributeDefinition() to determine the type definition for a particular attribute and getAttributeSyntaxDefinition() to determine the attribute syntax definition.

The get() method returns a single attribute value as a java.lang.Object, while getAll() returns multiple attribute values as a javax.naming.NamingEnumeration of objects. If the attribute has only a single value, get() returns that value. If the attribute has multiple values, the service provider determines the value that is returned.

Updates performed on Attribute do not affect the directory entry. To modify the directory entry, you must call the modifyAttributes() method of DirContext with an Attributes object that contains a modified Attribute.

public abstract interface Attribute extends Cloneable, Serializable {
//	Public Instance Methods
	public abstract boolean add (Object attrVal);
	public abstract void clear ();
	public abstract Object clone ();
	public abstract boolean contains (Object attrVal);
	public abstract Object get () throws NamingException;
	public abstract NamingEnumeration getAll () throws NamingException;
	public abstract DirContext getAttributeDefinition () throws NamingException;
	public abstract DirContext getAttributeSyntaxDefinition () throws NamingException;
	public abstract String getID ();
	public abstract boolean remove (Object attrval);
	public abstract int size ();
}

Hierarchy: (Attribute(Cloneable,Serializable))

Implementations: BasicAttribute

Passed To: Attributes.put(), BasicAttributes.put(), ModificationItem.ModificationItem()

Returned By: Attributes.{get(), put(), remove()}, BasicAttributes.{get(), put(), remove()}, ModificationItem.getAttribute()

AttributeInUseException

JNDI 1.1

javax.naming.directory

serializable checked

Thrown when there is an attempt to add an attribute already present in the directory entry.

public class AttributeInUseException extends NamingException {
//	Public Constructors
	public AttributeInUseException ();
	public AttributeInUseException (String explanation);
}

Hierarchy: Object-->Throwable(Serializable)-->Exception-->NamingException-->AttributeInUseException

AttributeModificationException

JNDI 1.1

javax.naming.directory

serializable checked

Thrown when modifyAttributes() method of DirContext cannot be executed because the operation contradicts the directory schema. You can retrieve an array of modification items JNDI could not perform using getUnexecutedModifications().

public class AttributeModificationException extends NamingException {
//	Public Constructors
	public AttributeModificationException ();
	public AttributeModificationException (String explanation);
//	Public Instance Methods
	public ModificationItem[ ] getUnexecutedModifications ();	default:null
	public void setUnexecutedModifications (ModificationItem[ ] e);
//	Public methods overriding NamingException
	public String toString ();
}

Hierarchy: Object-->Throwable(Serializable)-->Exception-->NamingException-->AttributeModificationException

Attributes

JNDI 1.1

javax.naming.directory

cloneable serializable

This interface represents a collection of attributes associated with a directory entry. Individual attributes are unordered, and the Attributes object can have zero or more attributes. The getAll() method returns an enumeration of Attribute objects, while getIDs() returns an enumeration of just the attribute names (or IDs) for the directory entry. If you know the attribute you want, you can specify the attribute name in a call to the get() method, which returns a single Attribute object.

An Attributes object can be case-sensitive or insensitive. In an LDAP or NDS directory, a case-insensitive attribute corresponds to "case ignore string." This means when searching for a particular attribute or comparing two attributes, case sensitivity can affect the results.

Updates performed on an Attributes object do not affect the directory entry. To modify the directory entry, you must call the modifyAttributes() method of DirContext using the updated Attributes object.

When creating a set of attributes for use in an application, you typically use a BasicAttributes object.

public abstract interface Attributes extends Cloneable, Serializable {
//	Public Instance Methods
	public abstract Object clone ();
	public abstract Attribute get (String attrID);
	public abstract NamingEnumeration getAll ();
	public abstract NamingEnumeration getIDs ();
	public abstract boolean isCaseIgnored ();
	public abstract Attribute put (Attribute attr);
	public abstract Attribute put (String attrID, Object val);
	public abstract Attribute remove (String attrID);
	public abstract int size ();
}

Hierarchy: (Attributes(Cloneable,Serializable))

Implementations: BasicAttributes

Passed To: Too many methods to list.

Returned By: DirContext.getAttributes(), InitialDirContext.getAttributes(), SearchResult.getAttributes()

BasicAttribute

JNDI 1.1

javax.naming.directory

cloneable serializable

This class is a basic implementation of the Attribute interface. BasicAttribute has a convenience constructor that enables you to create the object with attribute data by using a string that represents the attribute ID and a java.lang.Object that represents the attribute value. This constructor is equivalent to creating a BasicAttribute object with the attribute ID as a parameter and then calling the add() method.

public class BasicAttribute implements Attribute {
//	Public Constructors
	public BasicAttribute (String id);
	public BasicAttribute (String id, Object value);
//	Methods implementing Attribute
	public boolean add (Object attrVal);
	public void clear ();
	public Object clone ();
	public boolean contains (Object attrVal);
	public Object get () throws NamingException;
	public NamingEnumeration getAll () throws NamingException;
	public DirContext getAttributeDefinition () throws NamingException;
	public DirContext getAttributeSyntaxDefinition () throws NamingException;
	public String getID ();
	public boolean remove (Object attrval);
	public int size ();
//	Public methods overriding Object
	public boolean equals (Object obj);
	public int hashCode ();
	public String toString ();
//	Protected Instance Fields
	protected String attrID ;
	protected transient java.util.Vector values ;
}

Hierarchy: Object-->BasicAttribute(Attribute(Cloneable,Serializable))

BasicAttributes

JNDI 1.1

javax.naming.directory

cloneable serializable

This class is a basic implementation of the Attributes interface. BasicAttributes has a convenience constructor that enables you to create the set of attributes with attribute data by using a string that represents an attribute ID, and a java.lang.Object that represents an attribute value. This constructor is equivalent to creating a BasicAttributes object with an empty constructor and then calling the two-argument put() method.

You can construct a BasicAttributes object as case-sensitive or insensitive. In an LDAP or NDS directory, a case-insensitive attribute corresponds to "case ignore string."

public class BasicAttributes implements Attributes {
//	Public Constructors
	public BasicAttributes ();
	public BasicAttributes (boolean ignoreCase);
	public BasicAttributes (String attrID, Object val);
	public BasicAttributes (String attrID, Object val, boolean ignoreCase);
//	Methods implementing Attributes
	public Object clone ();
	public Attribute get (String attrID);
	public NamingEnumeration getAll ();
	public NamingEnumeration getIDs ();
	public boolean isCaseIgnored ();	default:false
	public Attribute put (Attribute attr);
	public Attribute put (String attrID, Object val);
	public Attribute remove (String attrID);
	public int size ();
//	Public methods overriding Object
	public String toString ();
}

Hierarchy: Object-->BasicAttributes(Attributes(Cloneable,Serializable))

DirContext

JNDI 1.1

javax.naming.directory

This interface provides a Java representation of a directory entry and is a subclass of javax.naming.Context. The practical difference between a Context and a DirContext is the association of attributes with a DirContext and the consequent methods for retrieving and modifying attribute data.

The directory schema determines the classes of directory entries that can be present in a directory. You can access the directory schema using getSchema(). The class of a directory entry is its object class definition. You can access the object class definition using the getSchemaClassDefinition() method. Most directory providers distribute documents that describe their directory schemae. Consult your directory service provider for a schema definition.

The getAttributes() method returns an Attributes object that contains either all the attributes of an entry or just those attributes specified in a String array. createSubcontext() creates a new directory entry, while modifyAttributes() changes attributes values. The various search() methods allow you to search directory entries, using optional search filters and SearchControls objects.

public abstract interface DirContext extends javax.naming.Context {
//	Public Constants
	public static final int ADD_ATTRIBUTE ;	=1
	public static final int REMOVE_ATTRIBUTE ;	=3
	public static final int REPLACE_ATTRIBUTE ;	=2
//	Public Instance Methods
	public abstract void bind (Name name, Object obj, Attributes attrs) throws NamingException;
	public abstract void bind (String name, Object obj, Attributes attrs) throws NamingException;
	public abstract DirContext createSubcontext (Name name, Attributes attrs) throws NamingException;
	public abstract DirContext createSubcontext (String name, Attributes attrs) throws NamingException;
	public abstract Attributes getAttributes (Name name) throws NamingException;
	public abstract Attributes getAttributes (String name) throws NamingException;
	public abstract Attributes getAttributes (Name name, String[ ] attrIds) throws NamingException;
	public abstract Attributes getAttributes (String name, String[ ] attrIds) throws NamingException;
	public abstract DirContext getSchema (Name name) throws NamingException;
	public abstract DirContext getSchema (String name) throws NamingException;
	public abstract DirContext getSchemaClassDefinition (Name name) throws NamingException;
	public abstract DirContext getSchemaClassDefinition (String name) throws NamingException;
	public abstract void modifyAttributes (String name, ModificationItem[ ] mods) throws NamingException;
	public abstract void modifyAttributes (Name name, ModificationItem[ ] mods) throws NamingException;
	public abstract void modifyAttributes (Name name, int mod_op, Attributes attrs) throws NamingException;
	public abstract void modifyAttributes (String name, int mod_op, Attributes attrs) throws NamingException;
	public abstract void rebind (Name name, Object obj, Attributes attrs) throws NamingException;
	public abstract void rebind (String name, Object obj, Attributes attrs) throws NamingException;
	public abstract NamingEnumeration search (String name, Attributes matchingAttributes) throws NamingException;
	public abstract NamingEnumeration search (Name name, Attributes matchingAttributes) throws NamingException;
	public abstract NamingEnumeration search (String name, String filter, SearchControls cons) throws NamingException;
	public abstract NamingEnumeration search (Name name, Attributes matchingAttributes, String[ ] attributesToReturn) throws NamingException;
	public abstract NamingEnumeration search (Name name, String filter, SearchControls cons) throws NamingException;
	public abstract NamingEnumeration search (String name, Attributes matchingAttributes, String[ ] attributesToReturn) throws NamingException;
	public abstract NamingEnumeration search (String name, String filterExpr, Object[ ] filterArgs, SearchControls cons) throws NamingException;
	public abstract NamingEnumeration search (Name name, String filterExpr, Object[ ] filterArgs, SearchControls cons) throws NamingException;
}

Hierarchy: (DirContext(javax.naming.Context))

Implementations: InitialDirContext

Returned By: Attribute.{getAttributeDefinition(), getAttributeSyntaxDefinition()}, BasicAttribute.{getAttributeDefinition(), getAttributeSyntaxDefinition()}, DirContext.{createSubcontext(), getSchema(), getSchemaClassDefinition()}, InitialDirContext.{createSubcontext(), getSchema(), getSchemaClassDefinition()}, javax.naming.spi.DirectoryManager.getContinuationDirContext()

InitialDirContext

JNDI 1.1

javax.naming.directory

This class represents the starting context for performing directory operations and is a subclass of javax.naming.InitialContext. Use this class when your application must perform directory operations on an initial context.

public class InitialDirContext extends InitialContextimplements DirContext {
//	Public Constructors
	public InitialDirContext () throws NamingException;
	public InitialDirContext (java.util.Hashtable environment) throws NamingException;
//	Methods implementing DirContext
	public void bind (String name, Object obj, Attributes attrs) throws NamingException;
	public void bind (Name name, Object obj, Attributes attrs) throws NamingException;
	public DirContext createSubcontext (String name, Attributes attrs) throws NamingException;
	public DirContext createSubcontext (Name name, Attributes attrs) throws NamingException;
	public Attributes getAttributes (String name) throws NamingException;
	public Attributes getAttributes (Name name) throws NamingException;
	public Attributes getAttributes (Name name, String[ ] attrIds) throws NamingException;
	public Attributes getAttributes (String name, String[ ] attrIds) throws NamingException;
	public DirContext getSchema (String name) throws NamingException;
	public DirContext getSchema (Name name) throws NamingException;
	public DirContext getSchemaClassDefinition (String name) throws NamingException;
	public DirContext getSchemaClassDefinition (Name name) throws NamingException;
	public void modifyAttributes (Name name, ModificationItem[ ] mods) throws NamingException;
	public void modifyAttributes (String name, ModificationItem[ ] mods) throws NamingException;
	public void modifyAttributes (String name, int mod_op, Attributes attrs) throws NamingException;
	public void modifyAttributes (Name name, int mod_op, Attributes attrs) throws NamingException;
	public void rebind (Name name, Object obj, Attributes attrs) throws NamingException;
	public void rebind (String name, Object obj, Attributes attrs) throws NamingException;
	public NamingEnumeration search (String name, Attributes matchingAttributes) throws NamingException;
	public NamingEnumeration search (Name name, Attributes matchingAttributes) throws NamingException;
	public NamingEnumeration search (Name name, String filter, SearchControls cons) throws NamingException;
	public NamingEnumeration search (Name name, Attributes matchingAttributes, String[ ] attributesToReturn) throws NamingException;
	public NamingEnumeration search (String name, String filter, SearchControls cons) throws NamingException;
	public NamingEnumeration search (String name, Attributes matchingAttributes, String[ ] attributesToReturn) throws NamingException;
	public NamingEnumeration search (String name, String filterExpr, Object[ ] filterArgs, SearchControls cons) throws NamingException;
	public NamingEnumeration search (Name name, String filterExpr, Object[ ] filterArgs, SearchControls cons) throws NamingException;
}

Hierarchy: Object-->InitialContext(javax.naming.Context)-->InitialDirContext(DirContext(javax.naming.Context))

InvalidAttributeIdentifierException

JNDI 1.1

javax.naming.directory

serializable checked

Thrown when there is an attempt to create an attribute with an attribute ID that doesn't exist in the directory's schema.

public class InvalidAttributeIdentifierException extends NamingException {
//	Public Constructors
	public InvalidAttributeIdentifierException ();
	public InvalidAttributeIdentifierException (String explanation);
}

Hierarchy: Object-->Throwable(Serializable)-->Exception-->NamingException-->InvalidAttributeIdentifierException

InvalidAttributesException

JNDI 1.1

javax.naming.directory

serializable checked

Thrown when an add or modification operation has specified an inappropriate attribute type for the object class specified by the directory's schema.

public class InvalidAttributesException extends NamingException {
//	Public Constructors
	public InvalidAttributesException ();
	public InvalidAttributesException (String explanation);
}

Hierarchy: Object-->Throwable(Serializable)-->Exception-->NamingException-->InvalidAttributesException

InvalidAttributeValueException

JNDI 1.1

javax.naming.directory

serializable checked

Thrown when an add or modification operation has specified an inappropriate value for the attribute type specified by the directory's schema.

public class InvalidAttributeValueException extends NamingException {
//	Public Constructors
	public InvalidAttributeValueException ();
	public InvalidAttributeValueException (String explanation);
}

Hierarchy: Object-->Throwable(Serializable)-->Exception-->NamingException-->InvalidAttributeValueException

InvalidSearchControlsException

JNDI 1.1

javax.naming.directory

serializable checked

Thrown when a SearchControls object is invalid.

public class InvalidSearchControlsException extends NamingException {
//	Public Constructors
	public InvalidSearchControlsException ();
	public InvalidSearchControlsException (String msg);
}

Hierarchy: Object-->Throwable(Serializable)-->Exception-->NamingException-->InvalidSearchControlsException

InvalidSearchFilterException

JNDI 1.1

javax.naming.directory

serializable checked

Thrown when a search filter is invalid.

public class InvalidSearchFilterException extends NamingException {
//	Public Constructors
	public InvalidSearchFilterException ();
	public InvalidSearchFilterException (String msg);
}

Hierarchy: Object-->Throwable(Serializable)-->Exception-->NamingException-->InvalidSearchFilterException

ModificationItem

JNDI 1.1

javax.naming.directory

serializable

This class encapsulates an attribute that is to be modified and a code that determines the type of modification being performed.

public class ModificationItem implements Serializable {
//	Public Constructors
	public ModificationItem (int mod_op, Attribute attr);
//	Public Instance Methods
	public Attribute getAttribute ();
	public int getModificationOp ();
//	Public methods overriding Object
	public String toString ();
}

Hierarchy: Object-->ModificationItem(Serializable)

Passed To: AttributeModificationException.setUnexecutedModifications(), DirContext.modifyAttributes(), InitialDirContext.modifyAttributes()

Returned By: AttributeModificationException.getUnexecutedModifications()

NoSuchAttributeException

JNDI 1.1

javax.naming.directory

serializable checked

Thrown when a method attempts to access a nonexistent attribute.

public class NoSuchAttributeException extends NamingException {
//	Public Constructors
	public NoSuchAttributeException ();
	public NoSuchAttributeException (String explanation);
}

Hierarchy: Object-->Throwable(Serializable)-->Exception-->NamingException-->NoSuchAttributeException

SchemaViolationException

JNDI 1.1

javax.naming.directory

serializable checked

Thrown when a method violates schema rules.

public class SchemaViolationException extends NamingException {
//	Public Constructors
	public SchemaViolationException ();
	public SchemaViolationException (String explanation);
}

Hierarchy: Object-->Throwable(Serializable)-->Exception-->NamingException-->SchemaViolationException

SearchControls

JNDI 1.1

javax.naming.directory

serializable

This class represents the information needed to control the behavior of the search() method of DirContext. Contains information that determines the scope of search, the maximum number of results returned by a search, the maximum amount of time permitted to return search results, and other data you can use to fine-tune the behavior of search operations.

public class SearchControls implements Serializable {
//	Public Constructors
	public SearchControls ();
	public SearchControls (int scope, long countlim, int timelim, String[ ] attrs, boolean retobj, boolean deref);
//	Public Constants
	public static final int OBJECT_SCOPE ;	=0
	public static final int ONELEVEL_SCOPE ;	=1
	public static final int SUBTREE_SCOPE ;	=2
//	Public Instance Methods
	public long getCountLimit ();	default:0
	public boolean getDerefLinkFlag ();	default:false
	public String[ ] getReturningAttributes ();	default:null
	public boolean getReturningObjFlag ();	default:false
	public int getSearchScope ();	default:1
	public int getTimeLimit ();	default:0
	public void setCountLimit (long limit);
	public void setDerefLinkFlag (boolean on);
	public void setReturningAttributes (String[ ] attrs);
	public void setReturningObjFlag (boolean on);
	public void setSearchScope (int scope);
	public void setTimeLimit (int ms);
}

Hierarchy: Object-->SearchControls(Serializable)

Passed To: DirContext.search(), InitialDirContext.search()

SearchResult

JNDI 1.1

javax.naming.directory

serializable

This class represents a result of performing a search() method on a DirContext. It is a subclass of javax.naming.Binding. You can perform directory operations on a SearchResult without first having to look up the object in the directory. Each search() method actually returns an NamingEnumeration of SearchResults objects.

public class SearchResult extends javax.naming.Binding {
//	Public Constructors
	public SearchResult (String name, Object obj, Attributes attrs);
	public SearchResult (String name, String className, Object obj, Attributes attrs);
	public SearchResult (String name, Object obj, Attributes attrs, boolean isRelative);
	public SearchResult (String name, String className, Object obj, Attributes attrs, boolean isRelative);
//	Public Instance Methods
	public Attributes getAttributes ();
	public void setAttributes (Attributes attrs);
//	Public methods overriding Binding
	public String toString ();
}

Hierarchy: Object-->NameClassPair(Serializable)-->javax.naming.Binding-->SearchResult