APIdia Launch Partner
Top Description Inners Fields Constructors Methods
javax.naming.directory

public Class BasicAttribute

extends Object
implements Attribute
Class Inheritance
All Implemented Interfaces
javax.naming.directory.Attribute, java.io.Serializable, java.lang.Cloneable
Known Direct Subclasses
com.sun.jndi.ldap.LdapAttribute
Imports
java.util.Vector, .Enumeration, .NoSuchElementException, java.lang.reflect.Array, javax.naming.NamingException, .NamingEnumeration, .OperationNotSupportedException
This class provides a basic implementation of the Attribute interface.

This implementation does not support the schema methods getAttributeDefinition() and getAttributeSyntaxDefinition(). They simply throw OperationNotSupportedException. Subclasses of BasicAttribute should override these methods if they support them.

The BasicAttribute class by default uses Object.equals() to determine equality of attribute values when testing for equality or when searching for values, except when the value is an array. For an array, each element of the array is checked using Object.equals(). Subclasses of BasicAttribute can make use of schema information when doing similar equality checks by overriding methods in which such use of schema is meaningful. Similarly, the BasicAttribute class by default returns the values passed to its constructor and/or manipulated using the add/remove methods. Subclasses of BasicAttribute can override get() and getAll() to get the values dynamically from the directory (or implement the Attribute interface directly instead of subclassing BasicAttribute).

Note that updates to BasicAttribute (such as adding or removing a value) does not affect the corresponding representation of the attribute in the directory. Updates to the directory can only be effected using operations in the DirContext interface.

A BasicAttribute instance is not synchronized against concurrent multithreaded access. Multiple threads trying to access and modify a BasicAttribute should lock the object.

Authors
Rosanna Lee, Scott Seligman
Since
1.3

Nested and Inner Type Summary

Modifier and TypeClass and Description
pack-priv class
BasicAttribute.ValuesEnumImpl

Field Summary

Modifier and TypeField and Description
protected String
attrID

Holds the attribute's id. It is initialized by the public constructor and cannot be null unless methods in BasicAttribute that use attrID have been overridden.

protected boolean
ordered

A flag for recording whether this attribute's values are ordered.

private static final long
serialVersionUID

Hides javax.naming.directory.Attribute.serialVersionUID.

Use serialVersionUID from JNDI 1.1.1 for interoperability.
protected transient Vector<Object>
values

Holds the attribute's values.

Constructor Summary

AccessConstructor and Description
public
BasicAttribute(String
The attribute's id. It cannot be null.
id)

Constructs a new instance of an unordered attribute with no value.

public
BasicAttribute(String
The attribute's id. It cannot be null.
id, Object
The attribute's value. If null, a null value is added to the attribute.
value)

Constructs a new instance of an unordered attribute with a single value.

public
BasicAttribute(String
The attribute's id. It cannot be null.
id, boolean
true means the attribute's values will be ordered; false otherwise.
ordered)

Constructs a new instance of a possibly ordered attribute with no value.

public
BasicAttribute(String
The attribute's id. It cannot be null.
id, Object
The attribute's value. If null, a null value is added to the attribute.
value, boolean
true means the attribute's values will be ordered; false otherwise.
ordered)

Constructs a new instance of a possibly ordered attribute with a single value.

Method Summary

Modifier and TypeMethod and Description
public boolean
add(Object attrVal)

Implements javax.naming.directory.Attribute.add.

Adds a new value to this attribute.

public void
add(int ix, Object attrVal)

Implements javax.naming.directory.Attribute.add.

Adds an attribute value to the ordered list of attribute values.

private static boolean
arrayEquals(Object a1, Object a2)

Determines whether two arrays are equal by comparing each of their elements using Object.equals().

public void
clear()

Implements javax.naming.directory.Attribute.clear.

Removes all values from this attribute.

public Object
clone()

Overrides java.lang.Object.clone.

Implements javax.naming.directory.Attribute.clone.

Makes a copy of the attribute.

public boolean
contains(Object attrVal)

Implements javax.naming.directory.Attribute.contains.

Determines whether a value is in this attribute.

public boolean

Returns:

true if obj is equal to this attribute; false otherwise.
equals(Object
The possibly null object to check.
obj)

Overrides java.lang.Object.equals.

Determines whether obj is equal to this attribute.

private int
find(Object target)

public Object
get()

Implements javax.naming.directory.Attribute.get.

Retrieves one of this attribute's values.

public Object
get(int ix)

Implements javax.naming.directory.Attribute.get.

Retrieves the attribute value from the ordered list of attribute values.

public NamingEnumeration<?>
getAll()

Implements javax.naming.directory.Attribute.getAll.

Retrieves an enumeration of this attribute's values.

public DirContext
getAttributeDefinition()

Implements javax.naming.directory.Attribute.getAttributeDefinition.

Retrieves this attribute's schema definition.

public DirContext
getAttributeSyntaxDefinition()

Implements javax.naming.directory.Attribute.getAttributeSyntaxDefinition.

Retrieves the syntax definition associated with this attribute.

public String
getID()

Implements javax.naming.directory.Attribute.getID.

Retrieves the id of this attribute.

public int

Returns:

an int representing the hash code of this attribute.
hashCode()

Overrides java.lang.Object.hashCode.

Calculates the hash code of this attribute.

public boolean
isOrdered()

Implements javax.naming.directory.Attribute.isOrdered.

Determines whether this attribute's values are ordered.

private void
readObject(ObjectInputStream
the ObjectInputStream to read from
s)

The readObject method is called to restore the state of the BasicAttribute from a stream.

public boolean
remove(Object attrval)

Implements javax.naming.directory.Attribute.remove.

Removes a specified value from this attribute.

public Object
remove(int ix)

Implements javax.naming.directory.Attribute.remove.

Removes an attribute value from the ordered list of attribute values.

public Object
set(int ix, Object attrVal)

Implements javax.naming.directory.Attribute.set.

Sets an attribute value in the ordered list of attribute values.

public int
size()

Implements javax.naming.directory.Attribute.size.

Retrieves the number of values in this attribute.

public String

Returns:

The non-null string representation of this attribute.
toString()

Overrides java.lang.Object.toString.

Generates the string representation of this attribute.

private static boolean
valueEquals(Object obj1, Object obj2)

Determines whether two attribute values are equal.

private void
writeObject(ObjectOutputStream
the ObjectOutputStream to write to
s)

The writeObject method is called to save the state of the BasicAttribute to a stream.

Inherited from java.lang.Object:
finalizegetClassnotifynotifyAllwaitwaitwait

Field Detail

attrIDback to summary
protected String attrID

Holds the attribute's id. It is initialized by the public constructor and cannot be null unless methods in BasicAttribute that use attrID have been overridden.

orderedback to summary
protected boolean ordered

A flag for recording whether this attribute's values are ordered.

serialVersionUIDback to summary
private static final long serialVersionUID

Hides javax.naming.directory.Attribute.serialVersionUID.

Use serialVersionUID from JNDI 1.1.1 for interoperability.

Annotations
@Serial
valuesback to summary
protected transient Vector<Object> values

Holds the attribute's values. Initialized by public constructors. Cannot be null unless methods in BasicAttribute that use values have been overridden.

Constructor Detail

BasicAttributeback to summary
public BasicAttribute(String id)

Constructs a new instance of an unordered attribute with no value.

Parameters
id:String

The attribute's id. It cannot be null.

BasicAttributeback to summary
public BasicAttribute(String id, Object value)

Constructs a new instance of an unordered attribute with a single value.

Parameters
id:String

The attribute's id. It cannot be null.

value:Object

The attribute's value. If null, a null value is added to the attribute.

BasicAttributeback to summary
public BasicAttribute(String id, boolean ordered)

Constructs a new instance of a possibly ordered attribute with no value.

Parameters
id:String

The attribute's id. It cannot be null.

ordered:boolean

true means the attribute's values will be ordered; false otherwise.

BasicAttributeback to summary
public BasicAttribute(String id, Object value, boolean ordered)

Constructs a new instance of a possibly ordered attribute with a single value.

Parameters
id:String

The attribute's id. It cannot be null.

value:Object

The attribute's value. If null, a null value is added to the attribute.

ordered:boolean

true means the attribute's values will be ordered; false otherwise.

Method Detail

addback to summary
public boolean add(Object attrVal)

Implements javax.naming.directory.Attribute.add.

Adds a new value to this attribute.

By default, Object.equals() is used when comparing attrVal with this attribute's values except when attrVal is an array. For an array, each element of the array is checked using Object.equals(). A subclass may use schema information to determine equality.

addback to summary
public void add(int ix, Object attrVal)

Implements javax.naming.directory.Attribute.add.

Doc from javax.naming.directory.Attribute.add.

Adds an attribute value to the ordered list of attribute values. This method adds attrVal to the list of attribute values at index ix. Values located at indices at or greater than ix are shifted down towards the end of the list (and their indices incremented by one). If the attribute values are unordered and already have attrVal, IllegalStateException is thrown.

arrayEqualsback to summary
private static boolean arrayEquals(Object a1, Object a2)

Determines whether two arrays are equal by comparing each of their elements using Object.equals().

clearback to summary
public void clear()

Implements javax.naming.directory.Attribute.clear.

Doc from javax.naming.directory.Attribute.clear.

Removes all values from this attribute.

cloneback to summary
public Object clone()

Overrides java.lang.Object.clone.

Implements javax.naming.directory.Attribute.clone.

Doc from javax.naming.directory.Attribute.clone.

Makes a copy of the attribute. The copy contains the same attribute values as the original attribute: the attribute values are not themselves cloned. Changes to the copy will not affect the original and vice versa.

Annotations
@SuppressWarnings:unchecked
containsback to summary
public boolean contains(Object attrVal)

Implements javax.naming.directory.Attribute.contains.

Determines whether a value is in this attribute.

By default, Object.equals() is used when comparing attrVal with this attribute's values except when attrVal is an array. For an array, each element of the array is checked using Object.equals(). A subclass may use schema information to determine equality.

equalsback to summary
public boolean equals(Object obj)

Overrides java.lang.Object.equals.

Determines whether obj is equal to this attribute. Two attributes are equal if their attribute-ids, syntaxes and values are equal. If the attribute values are unordered, the order that the values were added are irrelevant. If the attribute values are ordered, then the order the values must match. If obj is null or not an Attribute, false is returned.

By default Object.equals() is used when comparing the attribute id and its values except when a value is an array. For an array, each element of the array is checked using Object.equals(). A subclass may override this to make use of schema syntax information and matching rules, which define what it means for two attributes to be equal. How and whether a subclass makes use of the schema information is determined by the subclass. If a subclass overrides equals(), it should also override hashCode() such that two attributes that are equal have the same hash code.

Parameters
obj:Object

The possibly null object to check.

Returns:boolean

true if obj is equal to this attribute; false otherwise.

See Also
hashCode, contains
findback to summary
private int find(Object target)
getback to summary
public Object get() throws NamingException

Implements javax.naming.directory.Attribute.get.

Retrieves one of this attribute's values.

By default, the value returned is one of those passed to the constructor and/or manipulated using the add/replace/remove methods. A subclass may override this to retrieve the value dynamically from the directory.

Exceptions
NamingException:

Doc from javax.naming.directory.Attribute.get.

If a naming exception was encountered while retrieving the value.

getback to summary
public Object get(int ix) throws NamingException

Implements javax.naming.directory.Attribute.get.

Doc from javax.naming.directory.Attribute.get.

Retrieves the attribute value from the ordered list of attribute values. This method returns the value at the ix index of the list of attribute values. If the attribute values are unordered, this method returns the value that happens to be at that index.

Exceptions
NamingException:
If a naming exception was encountered while retrieving the value.
getAllback to summary
public NamingEnumeration<?> getAll() throws NamingException

Implements javax.naming.directory.Attribute.getAll.

Retrieves an enumeration of this attribute's values.

By default, the values returned are those passed to the constructor and/or manipulated using the add/replace/remove methods. A subclass may override this to retrieve the values dynamically from the directory.

Exceptions
NamingException:

Doc from javax.naming.directory.Attribute.getAll.

If a naming exception was encountered while retrieving the values.

getAttributeDefinitionback to summary
public DirContext getAttributeDefinition() throws NamingException

Implements javax.naming.directory.Attribute.getAttributeDefinition.

Retrieves this attribute's schema definition.

This method by default throws OperationNotSupportedException. A subclass should override this method if it supports schema.

Exceptions
NamingException:

Doc from javax.naming.directory.Attribute.getAttributeDefinition.

If a naming exception occurs while getting the schema.

OperationNotSupportedException:
If getting the schema is not supported.
getAttributeSyntaxDefinitionback to summary
public DirContext getAttributeSyntaxDefinition() throws NamingException

Implements javax.naming.directory.Attribute.getAttributeSyntaxDefinition.

Retrieves the syntax definition associated with this attribute.

This method by default throws OperationNotSupportedException. A subclass should override this method if it supports schema.

Exceptions
NamingException:

Doc from javax.naming.directory.Attribute.getAttributeSyntaxDefinition.

If a naming exception occurs while getting the schema.

OperationNotSupportedException:
If getting the schema is not supported.
getIDback to summary
public String getID()

Implements javax.naming.directory.Attribute.getID.

Doc from javax.naming.directory.Attribute.getID.

Retrieves the id of this attribute.

hashCodeback to summary
public int hashCode()

Overrides java.lang.Object.hashCode.

Calculates the hash code of this attribute.

The hash code is computed by adding the hash code of the attribute's id and that of all of its values except for values that are arrays. For an array, the hash code of each element of the array is summed. If a subclass overrides hashCode(), it should override equals() as well so that two attributes that are equal have the same hash code.

Returns:int

an int representing the hash code of this attribute.

See Also
equals
isOrderedback to summary
public boolean isOrdered()

Implements javax.naming.directory.Attribute.isOrdered.

Doc from javax.naming.directory.Attribute.isOrdered.

Determines whether this attribute's values are ordered. If an attribute's values are ordered, duplicate values are allowed. If an attribute's values are unordered, they are presented in any order and there are no duplicate values.

readObjectback to summary
private void readObject(ObjectInputStream s) throws IOException, ClassNotFoundException

The readObject method is called to restore the state of the BasicAttribute from a stream. See writeObject for a description of the serial form.

Parameters
s:ObjectInputStream

the ObjectInputStream to read from

Annotations
@Serial
Exceptions
IOException:
if an I/O error occurs
ClassNotFoundException:
if the class of a serialized object could not be found
removeback to summary
public boolean remove(Object attrval)

Implements javax.naming.directory.Attribute.remove.

Removes a specified value from this attribute.

By default, Object.equals() is used when comparing attrVal with this attribute's values except when attrVal is an array. For an array, each element of the array is checked using Object.equals(). A subclass may use schema information to determine equality.

removeback to summary
public Object remove(int ix)

Implements javax.naming.directory.Attribute.remove.

Doc from javax.naming.directory.Attribute.remove.

Removes an attribute value from the ordered list of attribute values. This method removes the value at the ix index of the list of attribute values. If the attribute values are unordered, this method removes the value that happens to be at that index. Values located at indices greater than ix are shifted up towards the front of the list (and their indices decremented by one).

setback to summary
public Object set(int ix, Object attrVal)

Implements javax.naming.directory.Attribute.set.

Doc from javax.naming.directory.Attribute.set.

Sets an attribute value in the ordered list of attribute values. This method sets the value at the ix index of the list of attribute values to be attrVal. The old value is removed. If the attribute values are unordered, this method sets the value that happens to be at that index to attrVal, unless attrVal is already one of the values. In that case, IllegalStateException is thrown.

sizeback to summary
public int size()

Implements javax.naming.directory.Attribute.size.

Doc from javax.naming.directory.Attribute.size.

Retrieves the number of values in this attribute.

toStringback to summary
public String toString()

Overrides java.lang.Object.toString.

Generates the string representation of this attribute. The string consists of the attribute's id and its values. This string is meant for debugging and not meant to be interpreted programmatically.

Returns:String

The non-null string representation of this attribute.

valueEqualsback to summary
private static boolean valueEquals(Object obj1, Object obj2)

Determines whether two attribute values are equal. Use arrayEquals for arrays and Object.equals() otherwise.

writeObjectback to summary
private void writeObject(ObjectOutputStream s) throws IOException

The writeObject method is called to save the state of the BasicAttribute to a stream.

Parameters
s:ObjectOutputStream

the ObjectOutputStream to write to

Annotations
@Serial
Exceptions
IOException:
if an I/O error occurs
Serial data
Default field (the attribute ID - a String), followed by the number of values (an int), and the individual values.
javax.naming.directory back to summary

pack-priv Class BasicAttribute.ValuesEnumImpl

extends Object
implements NamingEnumeration<Object>
Class Inheritance
All Implemented Interfaces
javax.naming.NamingEnumeration, java.util.Enumeration

Field Summary

Modifier and TypeField and Description
pack-priv Enumeration<Object>
list

Constructor Summary

AccessConstructor and Description
pack-priv
ValuesEnumImpl()

Method Summary

Modifier and TypeMethod and Description
public void
close()

Implements javax.naming.NamingEnumeration.close.

Closes this enumeration.

public boolean
hasMore()

Implements javax.naming.NamingEnumeration.hasMore.

Determines whether there are any more elements in the enumeration.

public boolean
hasMoreElements()

Implements java.util.Enumeration.hasMoreElements.

Tests if this enumeration contains more elements.

public Object
next()

Implements javax.naming.NamingEnumeration.next.

Retrieves the next element in the enumeration.

public Object
nextElement()

Implements java.util.Enumeration.nextElement.

Returns the next element of this enumeration if this enumeration object has at least one more element to provide.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

listback to summary
pack-priv Enumeration<Object> list

Constructor Detail

ValuesEnumImplback to summary
pack-priv ValuesEnumImpl()

Method Detail

closeback to summary
public void close() throws NamingException

Implements javax.naming.NamingEnumeration.close.

Doc from javax.naming.NamingEnumeration.close.

Closes this enumeration. After this method has been invoked on this enumeration, the enumeration becomes invalid and subsequent invocation of any of its methods will yield undefined results. This method is intended for aborting an enumeration to free up resources. If an enumeration proceeds to the end--that is, until hasMoreElements() or hasMore() returns false-- resources will be freed up automatically and there is no need to explicitly call close().

This method indicates to the service provider that it is free to release resources associated with the enumeration, and can notify servers to cancel any outstanding requests. The close() method is a hint to implementations for managing their resources. Implementations are encouraged to use appropriate algorithms to manage their resources when client omits the close() calls.

Exceptions
NamingException:
If a naming exception is encountered while closing the enumeration.
hasMoreback to summary
public boolean hasMore() throws NamingException

Implements javax.naming.NamingEnumeration.hasMore.

Doc from javax.naming.NamingEnumeration.hasMore.

Determines whether there are any more elements in the enumeration. This method allows naming exceptions encountered while determining whether there are more elements to be caught and handled by the application.

Exceptions
NamingException:
If a naming exception is encountered while attempting to determine whether there is another element in the enumeration. See NamingException and its subclasses for the possible naming exceptions.
hasMoreElementsback to summary
public boolean hasMoreElements()

Implements java.util.Enumeration.hasMoreElements.

Doc from java.util.Enumeration.hasMoreElements.

Tests if this enumeration contains more elements.

nextback to summary
public Object next() throws NamingException

Implements javax.naming.NamingEnumeration.next.

Doc from javax.naming.NamingEnumeration.next.

Retrieves the next element in the enumeration. This method allows naming exceptions encountered while retrieving the next element to be caught and handled by the application.

Note that next() can also throw the runtime exception NoSuchElementException to indicate that the caller is attempting to enumerate beyond the end of the enumeration. This is different from a NamingException, which indicates that there was a problem in obtaining the next element, for example, due to a referral or server unavailability, etc.

Exceptions
NamingException:
If a naming exception is encountered while attempting to retrieve the next element. See NamingException and its subclasses for the possible naming exceptions.
nextElementback to summary
public Object nextElement()

Implements java.util.Enumeration.nextElement.

Doc from java.util.Enumeration.nextElement.

Returns the next element of this enumeration if this enumeration object has at least one more element to provide.