h2. Value

The *Value* object is used to store attribute's values. Basically, we manage two kinds of *Value*s, *H/R* (*H{*}uman *R{*}eatable) and binary values. In the near future, we will add streamed values (ie, values storing a reference to a file on disk).

h3. StringValue
This is the most frequently used type of *Value*. It stores an _UTF-8_ String. Every *[Attribute]* or [DIRAPI:Ava]* associated with an *HR* *[AttributeType (...)]* will use such a *Value*.

h3. BinaryValue
More rarely, one would like to store some binary value into an *[Attribute]*, for instance to store a _userCertificate_ or a _jpegPhoto_, or even an _OctetString_ *[AttributeType (...)]*. In this case, the way to go is to use a *BinaryValue*. It stores an array of bytes.

h3. Creating a Value
First, a *Value* is immutable. That means the value *must* be stored while calling the constructor. In fact, we don't provide any constructor which does not take a value as a parameter (or they are package protected).

Bottom line, you have two constructor per Class, whether the class is schema aware or not :
* StringValue( String ) and BinaryValue( byte[] )
* StringValue( AttributeType, String ) and BinaryValue( AttributeType, byte[] )

The first constructor creates a simple Value storing some data without associating it with an *[AttributeType (...)]*. This is probably useful on the client side when dealing with data coming from a Ldap Server which does not exhibit the Schema.
The second constructor creates Schema aware values, and the stored value *must* comply with the associated attributeType (ie, the *[AttributeType (...)]* syntax). Here are some example of both constructors :

{code:java}
    @Test
    public void testCreateStringValue()
    {
        Value<String> value = new StringValue( "  A  test  " );
        
        assertNotNull( value );
        assertEquals( "  A  test  ", value.getValue() );
        assertEquals( "  A  test  ", value.getNormValue() );
    }

    
    @Test
    public void testCreateShemaAwareStringValue() throws LdapInvalidAttributeValueException
    {
        Value<String> value = new StringValue( atCn, "  A  test  " );
        
        assertNotNull( value );
        assertEquals( "  A  test  ", value.getValue() );
        assertEquals( "a test", value.getNormValue() );
    }
{code}

As we can see, the biggest difference is the normalized value.

If we use a schema aware *Value*, then the injected value will be checked against the associated *[AttributeType (...)]*, and normalized accordingly.

Here is an example of the creation of an invalid value :

{code:java}
    @Test
    public void testCreateShemaAwareBadStringValue()
    {
        try
        {
            new StringValue( telephoneNumber, "  A  test  " );
            fail();
        }
        catch ( LdapInvalidAttributeValueException liave )
        {
            System.out.println( liave.getMessage() );
        }
    }
{code}

This test will print the following message :

{code:java}
ERR_04447_CANNOT_NORMALIZE_VALUE Cannot normalize the wrapped value ERR_04473_NOT_VALID_VALUE Not a valid value '  A  test  ' for the AttributeType 'ATTRIBUTE_TYPE ( 2.5.4.20
 NAME 'telephoneNumber'
 DESC RFC2256: Telephone Number
 EQUALITY telephoneNumberMatch
 SUBSTR telephoneNumberSubstringsMatch
 SYNTAX 1.3.6.1.4.1.1466.115.121.1.50
 USAGE userApplications
 )
'
{code}

The _BinaryValue_ creation is no different, except that its constructors only accept _byte[]_.

h3. Value status methods

There are a few status flags you may want to be interested in. Here are the list of methods available that give back some information about an instance :

h5. isHumanReadable()
This method tells if the *Value* contains a String or a byte[].

h5. isNull()
This method tells if the *Value* is null. Note that a schema aware *Value* can be null only if the *[AttributeType (...)]*'s syntax allows it.

h5. isSchemaAware()
Tells if the *Value* has an associated *[AttributeType (...)]*.

h5. isValid( SyntaxChecker )
Checks if the *Value* is valid. Note that if the *Value* is schema aware, calling this method does not make any sense, as the interned value has already been checked when the instance has been created.

h5. isInstanceOf( AttributeType )
Tells, for a schema aware *Value*, if the given *[AttributeType (...)]* is contained - or is a parent - of the interned *[AttributeType (...)]*.

h3. Getters
It's really a basic set of methods : 

h5. getValue()
Returns the interned user provided value. If we are dealing with a _StringValue_, returns a _String_. Of it's a _BinaryValue_, returns a _byte[]_.

h5. getNormValue()
Returns the normalized value, if the *Value* is schema aware. Otherwise, returns the exact same value than the _get()_ method.

h5. getAttributeType()
Return the interned *[AttributeType (...)]*, if the *Value* is schema aware.

h5. getString()
Returns the interned value as a _String_, if the *Value* contains a _String_.

h5. getBytes()
Returns the interned value as a _byte[]_, if the *Value* contains a _byte[]_.