org.apache.directory.shared.ldap.entry
Interface EntryAttribute

All Superinterfaces:
java.lang.Cloneable, java.io.Externalizable, java.lang.Iterable<Value<?>>, java.io.Serializable
All Known Subinterfaces:
ClientAttribute
All Known Implementing Classes:
DefaultClientAttribute

public interface EntryAttribute
extends java.lang.Iterable<Value<?>>, java.lang.Cloneable, java.io.Externalizable

A generic interface mocking the Attribute JNDI interface. This interface will be the base interface for the ServerAttribute and ClientAttribute.

Version:
$Rev$, $Date$
Author:
Apache Directory Project

Method Summary
 int add(byte[]... vals)
          Adds some values to this attribute.
 int add(java.lang.String... vals)
          Adds some values to this attribute.
 int add(Value<?>... val)
          Adds some values to this attribute.
 void clear()
          Remove all the values from this attribute.
 EntryAttribute clone()
           
 boolean contains(byte[]... vals)
           Indicates whether the specified values are some of the attribute's values.
 boolean contains(java.lang.String... vals)
           Indicates whether the specified values are some of the attribute's values.
 boolean contains(Value<?>... vals)
           Indicates whether the specified values are some of the attribute's values.
 Value<?> get()
           Get the first value of this attribute.
 Value<?> get(int i)
           Get the nth value of this attribute.
 java.util.Iterator<Value<?>> getAll()
          Returns an iterator over all the attribute's values.
 byte[] getBytes()
           Get the byte[] value, if and only if the value is known to be Binary, otherwise a InvalidAttributeValueException will be thrown
 java.lang.String getId()
          Get's the attribute identifier for this entry.
 java.lang.String getString()
           Get the String value, if and only if the value is known to be a String, otherwise a InvalidAttributeValueException will be thrown
 java.lang.String getUpId()
          Get's the user provided identifier for this entry.
 boolean isHR()
           Tells if the attribute is Human Readable.
 int put(byte[]... vals)
          Puts some values to this attribute.
 int put(java.util.List<Value<?>> vals)
           Puts a list of values into this attribute.
 int put(java.lang.String... vals)
          Puts some values to this attribute.
 int put(Value<?>... vals)
          Puts some values to this attribute.
 boolean remove(byte[]... val)
           Removes all the values that are equal to the given values.
 boolean remove(java.lang.String... vals)
           Removes all the values that are equal to the given values.
 boolean remove(Value<?>... vals)
           Removes all the values that are equal to the given values.
 void setHR(boolean isHR)
           Set the attribute to Human Readable or to Binary.
 void setId(java.lang.String id)
          Set the normalized ID.
 void setUpId(java.lang.String upId)
          Set the user provided ID.
 int size()
          Retrieves the number of values in this attribute.
 
Methods inherited from interface java.lang.Iterable
iterator
 
Methods inherited from interface java.io.Externalizable
readExternal, writeExternal
 

Method Detail

add

int add(java.lang.String... vals)
Adds some values to this attribute. If the new values are already present in the attribute values, the method has no effect.

The new values are added at the end of list of values.

This method returns the number of values that were added.

If the value's type is different from the attribute's type, a conversion is done. For instance, if we try to set some String into a Binary attribute, we just store the UTF-8 byte array encoding for this String.

If we try to store some byte[] in a HR attribute, we try to convert those byte[] assuming they represent an UTF-8 encoded String. Of course, if it's not the case, the stored value will be incorrect.

It's the responsibility of the caller to check if the stored values are consistent with the attribute's type.

The caller can set the HR flag in order to enforce a type for the current attribute, otherwise this type will be set while adding the first value, using the value's type to set the flag.

Parameters:
vals - some new values to be added which may be null
Returns:
the number of added values, or 0 if none has been added

add

int add(byte[]... vals)
Adds some values to this attribute. If the new values are already present in the attribute values, the method has no effect.

The new values are added at the end of list of values.

This method returns the number of values that were added.

If the value's type is different from the attribute's type, a conversion is done. For instance, if we try to set some String into a Binary attribute, we just store the UTF-8 byte array encoding for this String. If we try to store some byte[] in a HR attribute, we try to convert those byte[] assuming they represent an UTF-8 encoded String. Of course, if it's not the case, the stored value will be incorrect.
It's the responsibility of the caller to check if the stored values are consistent with the attribute's type.
The caller can set the HR flag in order to enforce a type for the current attribute, otherwise this type will be set while adding the first value, using the value's type to set the flag.

Parameters:
vals - some new values to be added which may be null
Returns:
the number of added values, or 0 if none has been added

add

int add(Value<?>... val)
Adds some values to this attribute. If the new values are already present in the attribute values, the method has no effect.

The new values are added at the end of list of values.

This method returns the number of values that were added.

If the value's type is different from the attribute's type, a conversion is done. For instance, if we try to set some StringValue into a Binary attribute, we just store the UTF-8 byte array encoding for this StringValue.

If we try to store some BinaryValue in a HR attribute, we try to convert those BinaryValue assuming they represent an UTF-8 encoded String. Of course, if it's not the case, the stored value will be incorrect.

It's the responsibility of the caller to check if the stored values are consistent with the attribute's type.

The caller can set the HR flag in order to enforce a type for the current attribute, otherwise this type will be set while adding the first value, using the value's type to set the flag.

Note : If the entry contains no value, and the unique added value is a null length value, then this value will be considered as a binary value.

Parameters:
vals - some new values to be added which may be null
Returns:
the number of added values, or 0 if none has been added

clear

void clear()
Remove all the values from this attribute.


clone

EntryAttribute clone()
Returns:
A clone of the current object

contains

boolean contains(java.lang.String... vals)

Indicates whether the specified values are some of the attribute's values.

If the Attribute is not HR, the values will be converted to byte[]

Parameters:
vals - the values
Returns:
true if this attribute contains all the values, otherwise false

contains

boolean contains(byte[]... vals)

Indicates whether the specified values are some of the attribute's values.

If the Attribute is HR, the values will be converted to String

Parameters:
vals - the values
Returns:
true if this attribute contains all the values, otherwise false

contains

boolean contains(Value<?>... vals)

Indicates whether the specified values are some of the attribute's values.

If the Attribute is HR, the binary values will be converted to String before being checked.

Parameters:
vals - the values
Returns:
true if this attribute contains all the values, otherwise false

get

Value<?> get()

Get the first value of this attribute. If there is none, null is returned.

Note : even if we are storing values into a Set, one can assume the values are ordered following the insertion order.

This method is meant to be used if the attribute hold only one value.

Returns:
The first value for this attribute.

getAll

java.util.Iterator<Value<?>> getAll()
Returns an iterator over all the attribute's values.

The effect on the returned enumeration of adding or removing values of the attribute is not specified.

This method will throw any NamingException that occurs.

Returns:
an enumeration of all values of the attribute

get

Value<?> get(int i)

Get the nth value of this attribute. If there is none, null is returned.

Note : even if we are storing values into a Set, one can assume the values are ordered following the insertion order.

Parameters:
i - the index of the value to get
Returns:
The nth value for this attribute.

getBytes

byte[] getBytes()
                throws javax.naming.directory.InvalidAttributeValueException

Get the byte[] value, if and only if the value is known to be Binary, otherwise a InvalidAttributeValueException will be thrown

Note that this method returns the first value only.

Returns:
The value as a byte[]
Throws:
javax.naming.directory.InvalidAttributeValueException - If the value is a String

getId

java.lang.String getId()
Get's the attribute identifier for this entry. This is the value that will be used as the identifier for the attribute within the entry.

Returns:
the identifier for this attribute

getUpId

java.lang.String getUpId()
Get's the user provided identifier for this entry. This is the value that will be used as the identifier for the attribute within the entry. If this is a commonName attribute for example and the user provides "COMMONname" instead when adding the entry then this is the format the user will have that entry returned by the directory server. To do so we store this value as it was given and track it in the attribute using this property.

Returns:
the user provided identifier for this attribute

isHR

boolean isHR()

Tells if the attribute is Human Readable.

This flag is set by the caller, or implicitly when adding String values into an attribute which is not yet declared as Binary.

Returns:

getString

java.lang.String getString()
                           throws javax.naming.directory.InvalidAttributeValueException

Get the String value, if and only if the value is known to be a String, otherwise a InvalidAttributeValueException will be thrown

Note that this method returns the first value only.

Returns:
The value as a String
Throws:
javax.naming.directory.InvalidAttributeValueException - If the value is a byte[]

put

int put(java.lang.String... vals)
Puts some values to this attribute.

The new values will replace the previous values.

This method returns the number of values that were put.

Parameters:
val - some values to be put which may be null
Returns:
the number of added values, or 0 if none has been added

put

int put(byte[]... vals)
Puts some values to this attribute.

The new values will replace the previous values.

This method returns the number of values that were put.

Parameters:
val - some values to be put which may be null
Returns:
the number of added values, or 0 if none has been added

put

int put(Value<?>... vals)
Puts some values to this attribute.

The new values are replace the previous values.

This method returns the number of values that were put.

Parameters:
val - some values to be put which may be null
Returns:
the number of added values, or 0 if none has been added

put

int put(java.util.List<Value<?>> vals)

Puts a list of values into this attribute.

The new values will replace the previous values.

This method returns the number of values that were put.

Parameters:
vals - the values to be put
Returns:
the number of added values, or 0 if none has been added

remove

boolean remove(java.lang.String... vals)

Removes all the values that are equal to the given values.

Returns true if all the values are removed.

If the attribute type is not HR, then the values will be first converted to byte[]

Parameters:
vals - the values to be removed
Returns:
true if all the values are removed, otherwise false

remove

boolean remove(byte[]... val)

Removes all the values that are equal to the given values.

Returns true if all the values are removed.

If the attribute type is HR, then the values will be first converted to String

Parameters:
vals - the values to be removed
Returns:
true if all the values are removed, otherwise false

remove

boolean remove(Value<?>... vals)

Removes all the values that are equal to the given values.

Returns true if all the values are removed.

If the attribute type is HR and some value which are not String, we will convert the values first (same thing for a non-HR attribute).

Parameters:
vals - the values to be removed
Returns:
true if all the values are removed, otherwise false

setHR

void setHR(boolean isHR)

Set the attribute to Human Readable or to Binary.

Parameters:
isHR - true for a Human Readable attribute, false for a Binary attribute.

setId

void setId(java.lang.String id)
Set the normalized ID. The ID will be lowercased, and spaces will be trimmed.

Parameters:
id - The attribute ID
Throws:
java.lang.IllegalArgumentException - If the ID is empty or null or resolve to an empty value after being trimmed

setUpId

void setUpId(java.lang.String upId)
Set the user provided ID. It will also set the ID, normalizing the upId (removing spaces before and after, and lowercasing it)

Parameters:
upId - The attribute ID
Throws:
java.lang.IllegalArgumentException - If the ID is empty or null or resolve to an empty value after being trimmed

size

int size()
Retrieves the number of values in this attribute.

Returns:
the number of values in this attribute, including any values wrapping a null value if there is one


Copyright © 2003-2011 Apache Software Foundation. All Rights Reserved.