- *
- * @param val some new values to be added which may be null
- * @return the number of added values, or 0 if none has been added
- */
- int add( String... vals ) throws InvalidAttributeValueException, NamingException;
-
-
- /**
- * Puts some values to this attribute.
*

- * The new values will replace the previous values.
+ * 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.
*

*

- * This method returns the number of values that were put.
+ * 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.
*

- *
- * @param val some values to be put which may be null
- * @return the number of added values, or 0 if none has been added
- * @throws InvalidAttributeValueException If we try to add some values
- * which conflicts with the AttributeType for this attribute
- * @throws NamingException If the attributeType does not have a syntax
- */
- int put( String... vals ) throws InvalidAttributeValueException, NamingException;
-
-
- /**
- * Puts some values to this attribute.
*

- * The new values will replace the previous values.
+ * It's the responsibility of the caller to check if the stored
+ * values are consistent with the attribute's type.
*

*

- * This method returns the number of values that were put.
+ * 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.
*

*
- * @param vals some values to be put which may be null
+ * @param val some new values to be added which may be null
* @return the number of added values, or 0 if none has been added
- * @throws InvalidAttributeValueException If we try to add some values
- * which conflicts with the AttributeType for this attribute
- * @throws NamingException If the attributeType does not have a syntax
*/
- int put( List> vals ) throws InvalidAttributeValueException, NamingException;
+ int add( String... vals );
/**
@@ -95,109 +78,172 @@
*

* 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.
*
* @param val some new values to be added which may be null
* @return the number of added values, or 0 if none has been added
*/
- int add( byte[]... vals ) throws InvalidAttributeValueException, NamingException;
+ int add( byte[]... vals );
/**
- * Puts some values to this attribute.
+ * 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 will replace the previous values.
+ * The new values are added at the end of list of values.
*

*

- * This method returns the number of values that were put.
+ * This method returns the number of values that were added.
*

- *
- * @param val some values to be put which may be null
+ *

+ * 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.
+ *

- * If the attribute has no values this method throws
- * NoSuchElementException.
+ * 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.
*

*
- * @return a value of this attribute
+ * @return The value as a byte[]
+ * @throws InvalidAttributeValueException If the value is a String
*/
- T get();
-
-
+ byte[] getBytes() throws InvalidAttributeValueException;
+
+
/**
* Get's the attribute identifier for this entry. This is the value
* that will be used as the identifier for the attribute within the
@@ -220,80 +266,188 @@
* @return the user provided identifier for this attribute
*/
String getUpId();
+
+
+ /**
+ *

+ * 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.
+ *

- * The effect on the returned enumeration of adding or removing values of
- * the attribute is not specified.
+ * Get the String value, if and only if the value is known to be a String,
+ * otherwise a InvalidAttributeValueException will be thrown
*

*

- * This method will throw any NamingException that occurs.
+ * Note that this method returns the first value only.
*

+ *
+ * @param val some values to be put which may be null
+ * @return the number of added values, or 0 if none has been added
*/
- Iterator getAll();
+ int put( String... vals );
/**
- * Removes all the values that are equal to the given values.
+ * Puts some values to this attribute.
+ *

+ * The new values will replace the previous values.
+ *

*

- * Returns true if a value is removed. If there is no value equal to
- * val this method simply returns false.
+ * This method returns the number of values that were put.
*

*
- * @param vals the values to be removed
- * @return true if all the values are removed, otherwise false
+ * @param val some values to be put which may be null
+ * @return the number of added values, or 0 if none has been added
*/
- boolean remove( T... vals );
+ int put( byte[]... vals );
/**
- * Indicates whether the specified values are some of the attribute's values.
+ * Puts some values to this attribute.
+ *

+ * The new values are replace the previous values.
+ *

+ *

+ * This method returns the number of values that were put.
+ *

*
- * @param vals the values
- * @return true if this attribute contains all the values, otherwise false
+ * @param val some values to be put which may be null
+ * @return the number of added values, or 0 if none has been added
*/
- boolean contains( T... vals ) throws NamingException;
+ int put( Value>... 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.
+ * Puts a list of values into this attribute.
*

*

- * This method returns the number of values that were added.
+ * The new values will replace the previous values.
+ *

+ * 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.
+ *

* Get the first value of this attribute. If there is none,
* null is returned.
- *
- * Note : as we are storing values into a Set, one can't assume
- * the values to be ordered in any way. This method is meant to
- * be used if the attribute hold only one value.
+ *

+ *

+ * 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.
+ *

*
* @return The first value for this attribute.
*/
@@ -547,9 +915,16 @@
/**
- * Get all the stored values.
- *
- * @return An iterator over the values stored into the attribute
+ * 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.
+ *

+ *
+ * @return an enumeration of all values of the attribute
*/
public Iterator> getAll()
{
@@ -558,10 +933,10 @@
/**
- * Get the number or values stored in the attribute
- *
- * @return the number of stored values. As 'null' can be a valid
- * value, it is counted as one result, not 0.
+ * Retrieves the number of values in this attribute.
+ *
+ * @return the number of values in this attribute, including any values
+ * wrapping a null value if there is one
*/
public int size()
{
@@ -570,26 +945,60 @@
/**
- * @see EntryAttribute#remove(org.apache.directory.shared.ldap.entry.Value)
- */
- public boolean remove( Value> val )
- {
- return values.remove( val );
- }
-
-
- /**
- * @see EntryAttribute#remove(org.apache.directory.shared.ldap.entry.Value...)
+ *

+ * 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).
+ *