h2. Entry

The *Entry* class is one of the most important one in the *API*. It describes the base element stored into a *LDAP* server, and it associates a *[#Dn]* and some *[#Attribute]s*.

We have two kinds of *Entry* in the *API*, depending on the presence of a *[SchemaManager (...)]* in the *Entry*, or not.

We also provide a few extended classes, like the *ImmutableEntry*, an immutable version of the *Entry*.

h3. Creating an Entry

We have many ways to create an *Entry*. Basically, an *Entry* has a *[DIRAPI:Dn]* and some *[DIRAPI:Attribute]s*. It can be schema aware, or not. We provide constructors to allow a user to create the kind of *Entry* he wants.

The simplest way to create an *Entry* is to call the default constructor. The created entry will have no attributes, and no Dn. We can also make it schema aware by passing a *[SchemaManager (...)]*. Here is an example:

{code:java}
    @Test
    public void testCreateEmptyEntry()
    {
        Entry entry = new DefaultEntry();
        
        assertNotNull( entry.getDn() );
        assertEquals( Dn.EMPTY_DN, entry.getDn() );
        assertNotNull( entry.getAttributeTypes() );
        assertEquals( 0, entry.size() );
        assertFalse( entry.isSchemaAware() );

        Entry entry2 = new DefaultEntry( schemaManager);
        
        assertNotNull( entry2.getDn() );
        assertEquals( Dn.EMPTY_DN, entry2.getDn() );
        assertNotNull( entry2.getAttributeTypes() );
        assertEquals( 0, entry2.size() );
        assertTrue( entry2.isSchemaAware() );
    }
{code}

You can also create an *Entry* passing a *[DIRAPI:Dn]*, but no attribute. We can create schema aware entries this way too, passing a *[SchemaManager (...)]*.

{code:java}
    @Test
    public void testCreateEntryWithDn() throws LdapException
    {
        Dn dn = new Dn( schemaManager, "DomainComponent=example, dc=COM" );
        Entry entry = new DefaultEntry( "dc=example, dc=com" );
        
        assertNotNull( entry.getDn() );
        assertEquals( "dc=example, dc=com", entry.getDn().toString() );
        assertNotNull( entry.getAttributeTypes() );
        assertEquals( 0, entry.size() );
        assertFalse( entry.isSchemaAware() );

        Entry entry2 = new DefaultEntry( schemaManager, "dc=example, dc=com" );
        
        assertNotNull( entry2.getDn() );
        assertEquals( dn, entry2.getDn() );
        assertNotNull( entry2.getAttributeTypes() );
        assertEquals( 0, entry2.size() );
        assertTrue( entry2.isSchemaAware() );
    }
{code}

We can also create an entry by copying an existing entry. The created *Entry* must be schema aware. Here is an example:

{code:java}
    @Test
    public void testCreateEntryCopy() throws LdapException
    {
        Entry entry = new DefaultEntry( schemaManager, "dc=example, dc=com" );
        entry.add( atCn, "test" );
        entry.add( atSn, "Test" );
        entry.add( atObjectClass, "top", "person" );
        
        Entry entry2 = new DefaultEntry( schemaManager, entry );
        
        assertEquals( entry.getDn(), entry2.getDn() );
        
        entry.clear();
        assertTrue( entry2.contains( atCn, "TEST" ) );
        assertTrue( entry2.contains( atSn, "TEST" ) );
        assertTrue( entry2.contains( atObjectClass, "top", "person" ) );
    }
{code}

Last, not least, it's possible to create an *Entry* using a list of LDIF formated attributes. An example worth ten lines of documentation, so let's see what it means.

First, we will create a schema agnostic entry:

{code:java}
    @Test
    public void testCreateEntryLdif() throws Exception
    {
        Entry entry = new DefaultEntry( 
            "dc=example, dc=com",
            "objectClass: top",
            "objectClass: person",
            "cn: test",
            "sn: test"
            );
        
        assertEquals( "dc=example, dc=com", entry.getDn().toString() );
        assertTrue( entry.contains( "cn", "test" ) );
        assertTrue( entry.contains( "sn", "test" ) );
        assertTrue( entry.contains( "objectClass", "top", "person" ) );
    }
{code}

We can also provide a complete LDIF file (except that we can't add the _dn_):

{code:java}
    @Test
    public void testCreateEntryLdifComplete() throws Exception
    {
        String ldif =
            "objectClass: top\n" +           // The \n is mandatory.
            "objectClass: person\n" +
            "cn: test\n" +
            "sn: test";

        Entry entry = new DefaultEntry( "dc=example, dc=com", ldif );
        
        assertEquals( "dc=example, dc=com", entry.getDn().toString() );
        assertTrue( entry.contains( "cn", "test" ) );
        assertTrue( entry.contains( "sn", "test" ) );
        assertTrue( entry.contains( "objectClass", "top", "person" ) );
    }
{code}

One can also combine LDIF and variables like in this example (note that if you use a variable, the attribute must not be followed by the *':'* char):

{code:java}
    @Test
    public void testCreateEntryLdif2() throws Exception
    {
        String name = "test";
        String surname = "test";
        
        Entry entry = new DefaultEntry( 
            "dc=example, dc=com",
            "objectClass: top",
            "objectClass: person",
            "cn", name,             // No ':'
            "sn", surname
            );
        
        assertEquals( "dc=example, dc=com", entry.getDn().toString() );
        assertTrue( entry.contains( "cn", "test" ) );
        assertTrue( entry.contains( "sn", "test" ) );
        assertTrue( entry.contains( "objectClass", "top", "person" ) );
    }
{code}

h3. Modifying an Entry
We have four methods available that modify the *Entry* content : _add_, _remove_, _put_ and _set_. We will review those four methods in the following paragraphs.

h4. Adding Attributes
Two methods can be used to add some attribute into an *Entry*, depending on the fact that we will add some value without replacing an existing attribute with the same name (and we use the _add_ method for that), or replace it with a new attribute (and we use the _put_ method for that).

In any case, we can add either an empty attribute, or an attribute with some values. Those values can be _Strings_, _byte[]_ or *[DIRAPI:Value]s*. The added attributes can be schema aware, and we can also provide a user provided name for the attribute type.

h5. add() methods

The first method makes it possible to add some existing *[DIRAPI:Attribute]* to an *Entry*. Let's see how it works:

{code:java}
    @Test
    public void testEntryAddAttribute() throws LdapException
    {
        Attribute cn = new DefaultAttribute( "cn", "test" );
        Attribute cn2 = new DefaultAttribute( "cn", "test2" );
        
        Entry entry = new DefaultEntry( 
            "dc=example, dc=com",
            "objectClass: top",
            "objectClass: person",
            "sn: test" );
        
        assertFalse( entry.containsAttribute( "cn" ) );
        
        // Add the new attribute
        entry.add( cn );
        
        assertTrue( entry.contains( "cn", "test" ) );
        
        // Try to add a second value
        entry.add( cn2 );

        // Both values must be present
        assertTrue( entry.contains( "cn", "test", "test2" ) );
    }
{code}

Otherwise, we can add a new attribute and values into the *Entry* by passing both parameters. We can also pass an *[AttributeType (...)]* to the _add()_ method, making the added attribute schema aware. Note that if the *Entry* itself is already schema aware, this is not necessary.

Here are some examples, the first one with a schema aware *Entry*, the second one with a schema agnostic *Entry*:

{code:java}
    @Test
    public void testEntryAddAtValue() throws LdapException
    {
        Entry entry = new DefaultEntry( 
            schemaManager,
            "dc=example, dc=com",
            "objectClass: top",
            "objectClass: person",
            "sn: test" );
        
        assertFalse( entry.containsAttribute( "cn" ) );
        
        // Add the new attribute
        entry.add( "cn", "test" );
        
        assertTrue( entry.contains( "CN", "test" ) );
        
        // Try to add a second value
        entry.add( atCn, "A  second test   " );

        // Both values must be present
        assertTrue( entry.contains( "cn", "test", "a second test" ) );
    }
{code}

{note:title=Warning !}
When manipulating a schema agnostic *Entry*, do not expect that the attribute type will be recognized if you inject schema aware attributes.
{note}

{code:java}
    @Test
    public void testEntryAddAtValue() throws LdapException
    {
        Entry entry = new DefaultEntry( 
            "dc=example, dc=com",
            "objectClass: top",
            "objectClass: person",
            "sn: test" );
        
        assertFalse( entry.containsAttribute( "cn" ) );
        
        // Add the new attribute
        entry.add( "cn", "test" );
        
        assertTrue( entry.contains( "cn", "test" ) );
        
        // Try to add a second value
        entry.add( atCn, "A  second  test" );

        // Both values must be present
        assertTrue( entry.contains( "cn", "test" ) );
        assertTrue( entry.contains( "2.5.4.3", "a second test" ) );
        assertFalse( entry.contains( "cn", "A  second  test" ) );
    }
{code}

h5. put() methods

The big difference with the _add_ method is that the attribute is not added, it will replace an existing one. let's see with an example :

{code:java}
    @Test
    public void testEntryPutAttribute() throws LdapException
    {
        Entry entry = new DefaultEntry( 
            schemaManager, 
            "dc=example, dc=com",
            "objectClass: top",
            "objectClass: person",
            "sn: test" );
        
        assertFalse( entry.containsAttribute( "cn" ) );
        
        // Add the new attribute
        entry.put( "cn", "test" );
        
        assertTrue( entry.contains( "cn", "test" ) );
        
        // Try to add a second value
        entry.put( "cn", "test2" );

        // Both values must be present
        assertFalse( entry.contains( "cn", "test", "test2" ) );
        assertFalse( entry.contains( "cn", "test" ) );
        assertTrue( entry.contains( "cn", "test2" ) );
    }
{code}

h4. Removing Attributes

We can remove either an attribute having a specific value, or an entire attribute. In order to remove a complete attribute, you just have to provide the attribute's name, and use the _removeAttributes_ method.

Here are some example for both usages :

{code:java}
    @Test
    public void testRemoveAttribute() throws LdapException
    {
        Entry entry = new DefaultEntry( 
            schemaManager,
            "dc=example, dc=com",
            "objectClass: top",
            "objectClass: person",
            "sn: test",
            "cn: test1",
            "cn: test2",
            "cn: test3" );
        
        assertTrue( entry.contains( "cn", "test1", "test2", "test3" ) );
        
        // Remove the "test2" value
        entry.remove( "cn", "test2" );
        
        assertTrue( entry.contains( "cn", "test1", "test3" ) );
        assertFalse( entry.contains( "cn", "test2" ) );
        
        // Try to remove the full attribute
        entry.removeAttributes( "cn" );

        assertFalse( entry.containsAttribute( "cn" ) );
    }
{code}

h5. Storing a Dn

It's also possible to store a new *[DIRAPI:Dn]* into the Entry, using the _setDn() method. It will replace an existing *[DIRAPI:Dn]*. This method takes either a *[DIRAPI:Dn]* instance, or a _String_.

h3. Attribute data access methods

The *API* provides convenient methods to access the *Entry* content, and to check if it contains some attributes or some values. We will shortly expose those methods in the following paragraphs.

h4. Contains method
The _contains_ and _containsAttributes_ methods check that the *Entry* contain a couple of <attributeType/values> for the first set of methods, and for the existence of a specific attribute for the second method.

One can check for the existence of a specific value for a given attribute, or even for multiple values for a specific attribute. Let's see the _contains_ method in action:

{code:java}
    @Test
    public void testContains() throws LdapException
    {
        Entry entry = new DefaultEntry( 
            schemaManager,
            "dc=example, dc=com",
            "objectClass: top",
            "objectClass: person",
            "sn: test",
            "cn: test1",
            "cn: test2",
            "cn: test3" );
        
        assertTrue( entry.containsAttribute( "cn", "sn" ) );
        assertTrue( entry.contains( "cn", "test1", "test2", "test3" ) );
        assertTrue( entry.contains( "cn", "test1" ) );

        // The value does not exist for the "cn" attribute
        assertFalse( entry.contains( "cn", "test4" ) );
    }
{code}

h5. get(AttributeType) and get(String)

Returns the *[DIRAPI:Attribute]* having the given name if it exists. The following test demonstrates its usage:

{code:java}
    @Test
    public void testGet() throws LdapException
    {
        Entry entry = new DefaultEntry( 
            schemaManager,
            "dc=example, dc=com",
            "objectClass: top",
            "objectClass: person",
            "sn: test",
            "cn: test1",
            "cn: test2",
            "cn: test3" );
        
        // With an attribute's name
        assertNotNull( entry.get( "cn" ) );
        assertTrue( entry.get( "cn" ).contains( "test1", "test2", "test3" ) );

        // With an AttributeType
        assertNotNull( entry.get( atSn ) );
        assertTrue( entry.get( atSn ).contains( "test" ) );
    }
{code}

h5. getAttributeTypes()

This method returns the list of *[AttributeType (...)]s* stored into the *Entry*.

{note:title=Be careful !}
This method is only valuable if the *Entry* is schema aware !
{note}

Here is an example of usage:

{code:java}
    @Test
    public void testGetAttributeTypes() throws LdapException
    {
        Entry entry = new DefaultEntry( 
            schemaManager,
            "cn=example, dc=com", 
            "objectClass: top",
            "objectClass: person",
            "cn: example",
            "sn: test"
            );
        
        for ( AttributeType attr : entry.getAttributeTypes() )
        {
            System.out.println( attr.getName() );
        }
    }
{code}

This code produces the following output:

{code:java}
sn
objectClass
cn
{code}

h5. getDn()

This method returns the *Entry*'s *[DIRAPI:Dn]*.

h5. hasObjectClass methods

The _hasObjectClass()_ methods are used to discover if an *Entry* has a specific _ObjectClass_. This is a convenient method, as it's possible to do the same thing with a _contains()_ call, but with one less parameter (you don't have to provide the _"ObjectClass"_ as a first parameter).

Here is an example using the two existing methods:

{code:java}
    @Test
    public void testHasObjectClass() throws LdapException
    {
        Entry entry = new DefaultEntry( 
            schemaManager,
            "cn=example, dc=com", 
            "objectClass: top",
            "objectClass: person",
            "cn: example",
            "sn: test"
            );
        
        // Test the presence
        assertTrue( entry.hasObjectClass( "person", " TOP " ) );
        assertFalse( entry.hasObjectClass( "domain ", "TOP" ) );
        assertTrue( entry.hasObjectClass( "Person " ) );
        
        // Same test, but with Attributes
        Attribute oc1 = new DefaultAttribute( atObjectClass, "TOP ", "person" );
        Attribute oc2 = new DefaultAttribute( atObjectClass, "person " );
        Attribute oc3 = new DefaultAttribute( atObjectClass, "TOP", "domain" );
        
        assertTrue( entry.hasObjectClass( oc1, oc2 ) );
        assertFalse( entry.hasObjectClass( oc1, oc3 ) );
    }
{code}

Obviously, dealing with a schema agnostic *Entry*, those methods are more strict. You have to use the exact ObjectClasses case sensitive trimmed names (in the previous example, we can use upper cased names, even with spaces around the names).

Also note that the _hasObjectClass_ method used with *[AttributeType (...)]* does not work on a schema agnostic entry.

h3. Miscellaneous methods
We also have some other methods which can be used on an *Entry*. Here is a list of those methods.

h5. clear()
This method removes all the added *[DIRAPI:Attribute]s* from this *Entry*. The *[DIRAPI:Dn]* remains the same.

h5. clone()
Creates a copy of the current *Entry*. All the *[DIRAPI:Attribute]s* are also cloned.

h5. iterator()
Allows an iteration over all the *[DIRAPI:Attribute]s*. The following examples shows how this can be used:

{code:java}
    @Test
    public void testIterator() throws LdapException
    {
        Entry entry = new DefaultEntry( 
            "cn=example, dc=com", 
            "objectClass: top",
            "objectClass: person",
            "cn: example",
            "sn: test"
            );
        
        for ( Attribute attribute : entry )
        {
            System.out.println( "Attribute : \n" + attribute.toString() );
        }
    }
{code}

This produces the following output:

{code:java}
Attribute : 
    sn: test

Attribute : 
    cn: example

Attribute : 
    objectclass: top
    objectclass: person
{code}

Note that the *[DIRAPI:Attribute]* order is not guaranteed.

h5. isSchemaAware()

Tells if the ¬*Entry* has an associated *[SchemaManager (...)]*.

h5. size()
Returns the number of *[DIRAPI:Attribute]* stored in the *Entry*.

h5. equals(Object)
Check if two *Entries* are equal or not. It's important to understand that depending on whether the entry is schema aware or not, the comparison will be processed differently. Typically, the attribute's name must be equals when they have been trimmed and lower cased if the entry is not schema aware, and we can't compare an attribute named 'cn' with another one named '2.5.4.3' in this case (the *Entry* must be schema aware to allow such comparison). More important, the values *must* be identical (same casing, same spaces) in this case.
The attribute's values order is irrelevant.

Here are one example with a schema agnostic *Entry*:

{code:java}
    @Test
    public void testEntryEquals() throws LdapException
    {
        Entry entry = new DefaultEntry( 
            "dc=example, dc=com",
            "objectClass: top",
            "objectClass: person",
            "sn: test",
            "cn: test1",
            "cn: test2",
            "cn: test3" );

        Entry entry2 = new DefaultEntry( 
            "dc=example, dc=com",
            "objectClass: top",
            "objectClass: person",
            "sn: test",
            "cn: test2",
            "CN: test1",
            "cn: test3" );

        assertEquals( entry, entry2 );
    }
{code}

and another example with a schema aware *Entry*:

{code:java}
    @Test
    public void testSchemaAwayeEntryEquals() throws LdapException
    {
        Entry entry = new DefaultEntry( 
            schemaManager,
            "dc=example, dc=com",
            "objectClass: top",
            "objectClass: person",
            "sn: test",
            "cn: test1",
            "cn: test2",
            "cn: test3" );

        Entry entry2 = new DefaultEntry( 
            schemaManager,
            "dc=example,dc=com",
            "objectClass: TOP",
            "objectClass: person",
            "sn: Test",
            "cn: Test2",
            "2.5.4.3: test1",
            "CommonName: test3" );

        assertEquals( entry, entry2 );
    }
{code}