<!--

Copyright 2000-2007 Sun Microsystems, Inc. All Rights Reserved.
Portions copyright 1999 Netscape Communications Corporation. All
Rights Reserved.

The contents of this document are subject to the terms of the
Creative Commons Attribution-ShareAlike 2.5 license or any later
version (the "License"). You may not use this document except in
compliance with the License.

See the License for the specific language governing
permissions and limitations under the License. You can obtain
a copy of the License at
http://creativecommons.org/licenses/by-sa/2.5/legalcode.

-->
<chapter id="adding"><title>Adding, Updating, and Deleting Entries With &DirectorySDKForJava;</title>
<highlights>
<para>This chapter explains how to use the LDAP Java classes to add, modify,
delete, and rename entries in the directory.</para>
<itemizedlist>
<para>This chapter covers the following topics:</para>
<listitem><para><olink targetptr="add-entry">Adding an Entry With Directory
SDK for Java</olink></para></listitem>
<listitem><para><olink targetptr="mod-entry">Modifying an Entry With Directory SDK for Java</olink></para></listitem>
<listitem><para><olink targetptr="del-entry">Deleting an Entry With Directory
SDK for Java</olink></para></listitem>
<listitem><para><olink targetptr="rename-entry">Renaming an Entry With Directory
SDK for Java</olink></para></listitem>
</itemizedlist>
</highlights>
<sect1 id="add-entry"><title>Adding an Entry With &DirectorySDKForJava;</title>
<indexterm>
<primary>adding</primary>
<secondary>entries</secondary>
</indexterm><indexterm>
<primary>entries</primary>
<secondary>adding</secondary>
</indexterm>
<orderedlist>
<para>To add an entry to the directory, follow this general procedure:</para>
<listitem><para>Create individual attributes for the entry.</para></listitem>
<listitem><para>Create the set of attributes that make up the entry and add
each of the attributes to this set.</para></listitem>
<listitem><para>Create the new entry, specifying a unique distinguished name
(DN) to identify the entry and the set of attributes that make up the entry.</para>
</listitem>
<listitem><para>Add the new entry to directory.</para></listitem></orderedlist>
<sect2 id="add-new-attr"><title>Creating a New Attribute</title>
<para>An attribute can have a single value or multiple values. An attribute
can contain string values or binary data. In the LDAP Java classes, an attribute
is represented by an <classname>LDAPAttribute</classname> object.</para>
<para>To create a new attribute, use the <classname>LDAPAttribute</classname> constructor.
You can specify a single string value, multiple string values, or a binary
value when constructing the object.</para>
<para>For example, the following section of code creates a new object for
the attribute <literal>cn</literal> with the value <literal>Jane St. Clair</literal>.
</para>
<programlisting>LDAPAttribute attr = new LDAPAttribute("cn", "Jane St. Clair");</programlisting>
<para>The following section of code creates an attribute <literal>objectclass</literal> with
the values <literal>top</literal>, <literal>person</literal>, <literal>organizationalPerson
</literal>, and <literal>inetOrgPerson</literal>.</para>
<programlisting>String objectclasses[] = {"top", "person", "organizationalPerson",
    "inetOrgPerson"};
LDAPAttribute attr = new LDAPAttribute("objectclass", objectclasses);</programlisting>
<para>You can also add string or binary values to an <classname>LDAPAttribute</classname> object
by invoking the <literal>addValue</literal> method.</para></sect2>
<sect2 id="add-new-set"><title>Creating a New Attribute Set</title>
<para>To specify the set of attributes in an entry, you need to create an
attribute set. In the LDAP Java classes, a set of one or more attributes is
represented by an <classname>LDAPAttributeSet</classname> object.</para>
<para>To create a new attribute set, use the <classname>LDAPAttributeSet</classname> constructor.
Invoke the <literal>add</literal> method to add <classname>LDAPAttribute</classname> objects
to the set.</para>
<programlisting>LDAPAttribute attr1 = new LDAPAttribute("cn", "Jane St. Clair");
String objectclasses[] = {"top", "person", "organizationalPerson",
    "inetOrgPerson"};
LDAPAttribute attr2 = new LDAPAttribute("objectclass", objectclasses);
LDAPAttributeSet attrSet = new LDAPAttributeSet();
attrSet.add(attr1);
attrSet.add(attr2);</programlisting>
</sect2>
<sect2 id="add-new-entry"><title>Creating a New Entry</title>
<para>An entry contains a distinguished name (DN), which identifies the entry
in the directory, and a set of attributes. In the LDAP Java classes, an entry
is represented by an <classname>LDAPEntry</classname> object.</para>
<para>To create a new entry, use the <literal>LDAPEntry</literal> constructor.</para>
<programlisting>LDAPAttribute attr1 = new LDAPAttribute("cn", "Jane St. Clair");
String objectclasses[] = {"top", "person", "organizationalPerson",
    "inetOrgPerson"};
LDAPAttribute attr2 = new LDAPAttribute("objectclass", objectclasses);
LDAPAttributeSet attrSet = new LDAPAttributeSet();
attrSet.add(attr1);
attrSet.add(attr2);
String dn = "uid=jsclair,ou=People,dc=example,dc=com"; 
LDAPEntry newEntry = new LDAPEntry(dn, attrs);</programlisting>
</sect2>
<sect2 id="add-entry-dir"><title>Adding the New Entry to the Directory</title>
<itemizedlist>
<para>Before you add an entry to the directory, make sure that you have done
the following:</para>
<listitem><para>You have specified the object classes of the entry using the <literal>
objectclass</literal> attribute, and have specified the required attributes
for those object classes.</para>
<itemizedlist>
<para>For example, organizational units might be represented by entries of
the <literal>organizationalUnit</literal> object class. To add an entry for
an organizational unit, you need to specify the following attributes in the
entry:</para>
<listitem><para><literal>objectclass</literal> with value <literal>top</literal></para>
</listitem>
<listitem><para><literal>objectclass</literal> with value <literal>organizationalUnit
</literal></para></listitem>
<listitem><para><literal>ou</literal> with the value for the organizational
unit, such as <literal>People</literal></para></listitem>
</itemizedlist>
</listitem>
<listitem><para>You have authenticated as a user who has the access permissions
to add the entry to the directory.</para><para>If you do not have permission
to add the entry, an <classname>LDAPException</classname> is returned with
result code <constant>LDAPException.INSUFFICIENT_ACCESS_RIGHTS</constant>.</para>
</listitem>
</itemizedlist>
<para>To add the entry to the directory, invoke the <literal>add</literal> method
of the <classname>LDAPConnection</classname> object.</para>
<programlisting>try {
    LDAPConnection ld = new LDAPConnection();
    ld.connect("localhost", LDAPv3.DEFAULT_PORT); 
    ld.authenticate(bindDNWithWriteAccess, bindPassword);
    LDAPEntry newEntry = new LDAPEntry(dn, attrs);
    ld.add(newEntry);
} catch (LDAPException e) {
    System.err.println("Could not add " + dn + ":" + e.toString());
}</programlisting>
</sect2>
<sect2 id="add-entry-example"><title>Example of Adding an Entry</title>
<para>The following example adds a new entry to the directory for the user
who is named William Jensen.</para>
<programlisting>import netscape.ldap.*;
import java.util.*;

public class Add {
    public static void main(String[] args) {
        /* Specify the DN to add */
        String dn = "uid=wbjensen, ou=People, dc=example,dc=com";

        /* Specify the attributes of the entry */
        String objectclass_values[] =
            {"top", "person", "organizationalPerson", "inetOrgPerson"};
        String cn_values[] =
            {"William B Jensen", "William Jensen", "Bill Jensen"};
        String sn_values[] = {"Jensen"};
        String givenname_values[] = {"William", "Bill"};
        String telephonenumber_values[] = {"+1 800 555 1212"};

        LDAPAttributeSet attrs = new LDAPAttributeSet();
        LDAPAttribute attr = new LDAPAttribute("objectclass");
        for (int i = 0; i &lt; objectclass_values.length; i++) {
            attr.addValue(objectclass_values[i]);
        }
        attrs.add(attr);
        attr = new LDAPAttribute("cn");
        for (int i = 0; i &lt; cn_values.length; i++) {
            attr.addValue(cn_values[i]);
        }
        attrs.add(attr);
        attr = new LDAPAttribute("sn");
        for (int i = 0; i &lt; sn_values.length; i++) {
            attr.addValue(sn_values[i]);
        }
        attrs.add(attr);
        attr = new LDAPAttribute("givenname");
        for (int i = 0; i &lt; givenname_values.length; i++) {
            attr.addValue(givenname_values[i]);
        }
        attrs.add(attr);
        attr = new LDAPAttribute("telephonenumber");
        for (int i = 0; i &lt; telephonenumber_values.length; i++) {
            attr.addValue(telephonenumber_values[i]);
        }
        attrs.add(attr);
        attrs.add(new LDAPAttribute("uid", "wbjensen"));

        /* Create an entry with this DN and these attributes */
        LDAPEntry myEntry = new LDAPEntry(dn, attrs);

        try {
            /* Connect and authenticate as a user with write access. */
            UserArgs userArgs = new UserArgs("Add", args, true);
            LDAPConnection ld = new LDAPConnection();
            ld.connect(userArgs.getHost(), userArgs.getPort());
            ld.authenticate(userArgs.getBindDN(), userArgs.getPassword());

            /* Now add the entry to the directory */
            ld.add(myEntry);
            System.out.println("Entry added");

            ld.disconnect();
        } catch(LDAPException e) {
            if (e.getLDAPResultCode() ==
                LDAPException.ENTRY_ALREADY_EXISTS) {
                System.out.println("Error: Entry already present");
            } else {
                System.out.println("Error: " + e.toString());
            }
        }
    }
}</programlisting>
</sect2>
</sect1>
<sect1 id="mod-entry"><title>Modifying an Entry With &DirectorySDKForJava;</title>
<indexterm>
<primary>modifying</primary>
<secondary>entries</secondary>
</indexterm><indexterm>
<primary>entries</primary>
<secondary>modifying</secondary>
</indexterm><indexterm>
<primary>attributes</primary>
<secondary>modifying</secondary>
</indexterm>
<orderedlist>
<para>To modify an entry in the directory, follow this general procedure:</para>
<listitem><para>Specify each attribute change to make.</para>
<itemizedlist>
<listitem><para>If you are making only one change to the entry, construct
an <classname>LDAPModification</classname> object that specifies the change
that needs to be made.</para></listitem>
<listitem><para>If you are making more than one change, you need to construct
an <classname>LDAPModificationSet</classname> object that specifies the changes
that need to be made.</para></listitem>
</itemizedlist>
</listitem>
<listitem><para>Use the DN of the entry to find and update the
entry in the directory.</para></listitem></orderedlist>
<sect2 id="mod-entry-spec-changes"><title>Specifying Attribute Changes</title>
<para>You can add new values to an attribute, remove existing attribute values,
or change the values of an existing attribute. You can also remove an attribute
by removing all values for the attribute or by not providing values for the
attribute.</para>
<sect3 id="mod-entry-new-values"><title>Adding New Attribute Values</title>
<indexterm>
<primary>attributes</primary>
<secondary>adding values to</secondary>
</indexterm><indexterm>
<primary>adding</primary>
<secondary>values to an attribute</secondary>
</indexterm>
<itemizedlist>
<para>To add new values to an attribute in an entry, construct a new <classname>LDAPAttribute
</classname> object. Specify the name of the attribute. Also, specify the
values to add. Then, perform one of the following operations:</para>
<listitem><para>If you are making a single change to the entry, construct
a new <classname>LDAPModification</classname> object to specify that change.
Pass <constant>LDAPModification.ADD</constant> and the <classname>LDAPAttribute</classname> object
as arguments to the <literal>LDAPModification</literal> constructor.</para>
</listitem>
<listitem><para>If you are collecting multiple changes to an entry in an <classname>
LDAPModificationSet</classname> object, invoke the <literal>add</literal> method.
This method adds the change to the set of modifications. Pass <constant>LDAPModification.ADD
</constant> and the <classname>LDAPAttribute</classname> object as arguments
to this method.</para></listitem>
</itemizedlist>
<para>For example, the following code excerpt adds the value <literal>babs@example.com
</literal> to the <literal>mail</literal> attribute:</para>
<programlisting>LDAPModificationSet mods = new LDAPModificationSet();
LDAPAttribute attrMail = new LDAPAttribute("mail", "babs@example.com");
mods.add(LDAPModification.ADD, attrMail);</programlisting>
<para>If the specified attribute does not exist in the entry, the attribute
is created for the entry.</para></sect3>
<sect3 id="mod-entry-del-values"><title>Deleting Attribute Values</title>
<indexterm>
<primary>attributes</primary>
<secondary>removing values from</secondary>
</indexterm><indexterm>
<primary>deleting</primary>
<secondary>values from an attribute</secondary>
</indexterm><indexterm>
<primary>removing</primary>
<secondary>values from an attribute</secondary>
</indexterm>
<itemizedlist>
<para>To remove values from an attribute in an entry, construct a new <classname>
LDAPAttribute</classname> object, specifying the name of the attribute and
the values to remove. Then, perform one of the following operations:</para>
<listitem><para>If you are making a single change to the entry, construct
a new <classname>LDAPModification</classname> object to specify that change.
Pass <constant>LDAPModification.DELETE</constant> and the <classname>LDAPAttribute
</classname> object as arguments to the <literal>LDAPModification</literal> constructor.
</para></listitem>
<listitem><para>If you are collecting multiple changes to an entry in an <classname>
LDAPModificationSet</classname> object, invoke the <literal>add</literal> method.
The method adds the change to the set of modifications. Pass <constant>LDAPModification.DELETE
</constant> and the <classname>LDAPAttribute</classname> object as arguments
to this method.</para></listitem>
</itemizedlist>
<para>For example, the following code excerpt removes the value <literal>babs@example.com
</literal> from the <literal>mail</literal> attribute:</para>
<programlisting>LDAPModificationSet mods = new LDAPModificationSet();
LDAPAttribute attrMail = new LDAPAttribute("mail", "babs@example.com");
mods.add(LDAPModification.DELETE, attrMail);</programlisting>
<para>If you remove all values from an attribute, the attribute is removed
from the entry. If you do not specify any values in the <classname>LDAPAttribute</classname> object,
the attribute is also removed from the entry.</para></sect3>
<sect3 id="mod-entry-replace-values"><title>Replacing Attribute Values</title>
<indexterm>
<primary>attributes</primary>
<secondary>replacing values of</secondary>
</indexterm><indexterm>
<primary>changing</primary>
<secondary>values of an attribute</secondary>
</indexterm><indexterm>
<primary>modifying</primary>
<secondary>values of an attribute</secondary>
</indexterm><indexterm>
<primary>replacing</primary>
<secondary>values of an attribute</secondary>
</indexterm>
<itemizedlist>
<para>To replace values for an attribute in an entry, construct a new <classname>
LDAPAttribute</classname> object, specifying the name of the attribute and
the values to replace. Then, perform one of the following operations:</para>
<listitem><para>If you are making a single change to the entry, construct
a new <classname>LDAPModification</classname> object to specify that change.
Pass <constant>LDAPModification.REPLACE</constant> and the <classname>LDAPAttribute
</classname> object as arguments to the <literal>LDAPModification</literal> constructor.
</para></listitem>
<listitem><para>If you are collecting multiple changes to an entry in an <classname>
LDAPModificationSet</classname> object, invoke the <literal>add</literal> method.
The method adds the change to the set of modifications. Pass <constant>LDAPModification.REPLACE
</constant> and the <classname>LDAPAttribute</classname> object as arguments
to this method.</para></listitem>
</itemizedlist>
<para>For example, the following code excerpt replaces the existing value
of the <literal>mail</literal> attribute with <literal>babs@example.com</literal>:
</para>
<programlisting>LDAPModificationSet mods = new LDAPModificationSet();
LDAPAttribute attrMail = new LDAPAttribute("mail", "babs@example.com");
mods.add(LDAPModification.REPLACE, attrMail);</programlisting>
<para>If the specified attribute does not exist in the entry, the attribute
is created for the entry. If you do not specify any values in the <classname>LDAPAttribute
</classname> object, the attribute is removed from the entry.</para></sect3>
<sect3 id="mode-entry-del-attr"><title>Removing an Attribute</title>
<indexterm>
<primary>attributes</primary>
<secondary>removing from an entry</secondary>
</indexterm><indexterm>
<primary>entries</primary>
<secondary>removing attributes from</secondary>
</indexterm>
<itemizedlist>
<para>To remove an attribute from an entry, perform one of the following operations:
</para>
<listitem><para>Replace the values of the attribute with an <classname>LDAPAttribute
</classname> object that contains no values.</para></listitem>
<listitem><para>Remove the values of the attribute with an <classname>LDAPAttribute
</classname> object that contains no values.</para></listitem>
<listitem><para>Remove all values for the attribute.</para></listitem>
</itemizedlist>
<para>For example, the following code excerpt demonstrates the first two options
by preparing an <classname>LDAPModificationSet</classname> object to remove
the <literal>mail</literal> and <literal>description</literal> attributes:</para>
<programlisting>LDAPModificationSet mods = new LDAPModificationSet();
LDAPAttribute attrMail = new LDAPAttribute("mail");
LDAPAttribute attrDesc = new LDAPAttribute("description");
mods.add(LDAPModification.REPLACE, attrMail);
mods.add(LDAPModification.DELETE, attrDesc);</programlisting>
</sect3>
</sect2>
<sect2 id="mod-entry-dir"><title>Modifying the Entry in the Directory</title>
<itemizedlist>
<para>Before you modify an entry, make sure of the following:</para>
<listitem><para>You have not removed any of the required attributes for that
object class.</para></listitem>
<listitem><para>You have authenticated as a user who has the access permissions
to modify the entry in the directory.</para><para>If you do not have permission
to modify the entry, an <classname>LDAPException</classname> is returned with
the result code <constant>LDAPException.INSUFFICIENT_ACCESS_RIGHTS</constant>.</para>
</listitem>
</itemizedlist>
<para>You specify the change with an <classname>LDAPModification</classname> object.
You specify a list of changes with an <classname>LDAPModificationSet</classname> object.
When finished specifying the change, pass the object with the DN of the entry
to the <literal>modify</literal> method of the <classname>LDAPConnection</classname> object.
</para></sect2>
<sect2 id="mod-entry-example"><title>Example of Modifying an Entry</title>
<para>The following example modifies an entry in the directory.</para>
<programlisting>import netscape.ldap.*;
import java.util.*;

public class ModAttrs {
    public static void main(String[] args) {
        String ENTRYDN = "uid=bjensen, ou=People, dc=example,dc=com";

        LDAPModificationSet mods = new LDAPModificationSet();
        LDAPAttribute attrEmail =
            new LDAPAttribute("mail", "babs@example.com");
        mods.add(LDAPModification.REPLACE, attrEmail);
        LDAPAttribute attrDesc = new LDAPAttribute("description",
            "This entry was modified with the ModAttrs program");
        mods.add(LDAPModification.ADD, attrDesc);

        try {
            /* Connect and authenticate as a user with write access. */
            UserArgs userArgs = new UserArgs("ModAttrs", args, true);
            LDAPConnection ld = new LDAPConnection();
            ld.connect(userArgs.getHost(), userArgs.getPort());
            ld.authenticate(userArgs.getBindDN(), userArgs.getPassword());

            /* Now modify the entry in the directory */
            ld.modify(ENTRYDN, mods);
            System.out.println("Entry modified" );

            ld.disconnect();
        } catch(LDAPException e) {
            if (e.getLDAPResultCode() == LDAPException.NO_SUCH_OBJECT) {
                System.out.println("Error: No such entry");
            } else if (e.getLDAPResultCode() ==
                LDAPException.INSUFFICIENT_ACCESS_RIGHTS) {
                System.out.println("Error: Insufficient rights");
            } else if (e.getLDAPResultCode() ==
                LDAPException.ATTRIBUTE_OR_VALUE_EXISTS) {
                System.out.println("Error: Attribute or value exists");
            } else {
                System.out.println("Error: " + e.toString());
            }
        }
    }
}</programlisting>
</sect2>
</sect1>
<sect1 id="del-entry"><title>Deleting an Entry With &DirectorySDKForJava;</title>
<indexterm>
<primary>deleting an entry</primary>
</indexterm><indexterm>
<primary>entries</primary>
<secondary>deleting</secondary>
</indexterm>
<para>Before you delete an entry, authenticate as a user who has the access
permissions to remove the entry from the directory. If you do not have permission
to delete the entry, an <classname>LDAPException</classname> is returned with
result code <constant>LDAPException.INSUFFICIENT_ACCESS_RIGHTS</constant>.</para>
<para>To remove an entry from the directory, invoke the <literal>delete</literal> method
of the <classname>LDAPConnection</classname> object. Specify the DN of the
entry that you want to remove.</para>
<para>The following example deletes the entry that is added in <olink type="auto-generated" targetptr="add-entry-example">Example of Adding an Entry</olink>.
</para>
<programlisting>import netscape.ldap.*;
import java.util.*;

public class Del {
    public static void main(String[] args) {
        try {
            /* Connect and authenticate as a user with write access. */
            UserArgs userArgs = new UserArgs("Del", args, true);
            LDAPConnection ld = new LDAPConnection();
            ld.connect(userArgs.getHost(), userArgs.getPort());
            ld.authenticate(userArgs.getBindDN(), userArgs.getPassword());

            /* Specify the DN we're deleting */
            String dn = "uid=wbjensen, ou=People, dc=example,dc=com";

            ld.delete(dn);
            System.out.println("Entry deleted");

            ld.disconnect();
        } catch(LDAPException e) {
            if (e.getLDAPResultCode() == LDAPException.NO_SUCH_OBJECT) {
                System.out.println("Error: No such entry");
            } else if (e.getLDAPResultCode() ==
                LDAPException.INSUFFICIENT_ACCESS_RIGHTS) {
                System.out.println("Error: Insufficient rights");
            } else {
                System.out.println("Error: " + e.toString());
            }
        }
    }
}</programlisting>
</sect1>
<sect1 id="rename-entry"><title>Renaming an Entry With &DirectorySDKForJava;</title>
<indexterm>
<primary>changing the name of an entry</primary>
</indexterm><indexterm>
<primary>moving an entry</primary>
</indexterm><indexterm>
<primary>renaming an entry</primary>
</indexterm><indexterm>
<primary>entries</primary>
<secondary>renaming</secondary>
</indexterm>
<para>Before you rename an entry, authenticate as a user who has the access
permissions to perform the operation. If you do not have permission to rename
the entry, an <classname>LDAPException</classname> is returned with result
code <constant>LDAPException.INSUFFICIENT_ACCESS_RIGHTS</constant>.</para>
<itemizedlist>
<para>To rename an entry, invoke the <literal>rename</literal> method of the <classname>
LDAPConnection</classname> object. With this method, you can change the following:
</para>
<listitem><para>The relative distinguished name (RDN) of the entry</para>
</listitem>
<listitem><para>The location of the entry in the directory by changing the
DN and not just the RDN</para><para>Some LDAP servers do not support moving
entries by changing their DNs. Check your LDAP server documentation for further
information.</para></listitem>
</itemizedlist>
<sect2 id="rename-entry-newrdn"><title>Changing the Relative Distinguished
Name</title>
<para>When invoking the <literal>rename</literal> method of the <classname>LDAPConnection
</classname> object, you can specify a <parameter>deleteoldrdn</parameter> parameter.
The parameter allows you to remove the old RDN from the entry. Suppose an
entry has the following values for the <literal>uid</literal> attribute:</para>
<programlisting>uid: wbjensen
uid: wbj</programlisting>
<para>The following code excerpt changes the user ID value <literal>wbjensen</literal> to <literal>
wjensen</literal> and removes the <literal>wbjensen</literal> value:</para>
<programlisting>ld.rename("uid=wbjensen,ou=People,dc=example,dc=com", "uid=wjensen", true);
</programlisting>
<para>The resulting values in the entry do not include the old RDN:</para>
<programlisting>uid: wbjensen
uid: wbj</programlisting>
<para>The following code excerpt retains the existing user ID value after
the rename operation:</para>
<programlisting>ld.rename("uid=wbjensen,ou=People,dc=example,dc=com", "uid=wjensen", false);
</programlisting>
<para>In this case, the resulting values in the entry <emphasis>do</emphasis> include
the old RDN:</para>
<programlisting>uid: wbjensen
uid: wjensen
uid: wbj</programlisting>
<para>The DN after the rename operation is, however, <literal>uid=wjensen,ou=People,dc=example,dc=com
</literal>.</para>
<para>The following example creates an entry and then renames it:</para>
<programlisting>import netscape.ldap.*;
import java.util.*;

public class ModRdn {
    public static void main(String[] args) {
        /* Values for creating the entry */
        String objectclass_values[] =
            {"top", "person", "organizationalPerson", "inetOrgPerson"};
        String cn_values[] = {"Jacques Smith"};
        String sn_values[] = {"Smith"};
        String givenname_values[] = {"Jacques"};

        /* Specify the DN to add */
        String base = "ou=People, dc=example,dc=com";
        String dn = "uid=jsmith" + "," + base;
        String nrdn = "uid=jmsmith";    // The new RDN
        String ndn = nrdn + "," + base; // The target DN

        /* Create an attribute set with all desired attributes */
        LDAPAttributeSet attrs = new LDAPAttributeSet();
        LDAPAttribute attr =
            new LDAPAttribute("objectclass", objectclass_values);
        attrs.add(attr);
        attr = new LDAPAttribute("cn", cn_values);
        attrs.add(attr);
        attr = new LDAPAttribute("sn", sn_values);
        attrs.add(attr);
        attr = new LDAPAttribute("givenname", givenname_values);
        attrs.add(attr);
        attrs.add(new LDAPAttribute("uid", nrdn));

        /* Create an entry with this DN and these attributes */
        LDAPEntry myEntry = new LDAPEntry(dn, attrs);

        try {
            /* Connect and authenticate as a user with write access. */
            UserArgs userArgs = new UserArgs("ModRdn", args, true);
            LDAPConnection ld = new LDAPConnection();
            ld.connect(userArgs.getHost(), userArgs.getPort());
            ld.authenticate(userArgs.getBindDN(), userArgs.getPassword());

            /* Add the entry */
            try {
                ld.add(myEntry);
            } catch(LDAPException e) {
                /* If entry exists already, fine.  Ignore this error. */
                if (e.getLDAPResultCode() !=
                    LDAPException.ENTRY_ALREADY_EXISTS) throw e;
            }

            /* Delete the destination entry, for this example */
            try {
                ld.delete(ndn);
            }
            catch(LDAPException e) {
                /* If entry does not exist, fine.  Ignore this error. */
                if (e.getLDAPResultCode() != LDAPException.NO_SUCH_OBJECT)
                    throw e;
            }

            /* Do the modrdn operation */
            ld.rename(dn, nrdn, false);
            System.out.println("The modrdn operation was successful. ");
            System.out.println(
                "Entry " + dn + " has been changed to " + ndn);

            ld.disconnect();
        }
        catch(LDAPException e) {
            if (e.getLDAPResultCode() == LDAPException.NO_SUCH_OBJECT) {
                System.out.println("Error: No such entry");
            } else if (e.getLDAPResultCode() ==
                LDAPException.INSUFFICIENT_ACCESS_RIGHTS) {
                System.out.println("Error: Insufficient rights");
            } else if (e.getLDAPResultCode() ==
                LDAPException.ATTRIBUTE_OR_VALUE_EXISTS) {
                System.out.println("Error: Attribute or value exists");
            } else {
                System.out.println("Error: " + e.toString());
            }
        }
    }
}</programlisting>
</sect2>
<sect2 id="rename-entry-newdn"><title>Changing the Distinguished Name</title>
<para>When invoking the <literal>rename</literal> method of the <classname>LDAPConnection
</classname> object, you can specify a <parameter>newParentDN</parameter> parameter.
The parameter allows you to move the entry from one part of the directory
to another part by changing its DN. You can use the parameter even if the
RDN does not change.</para>
<para>The following example moves Sam Carter's entry from the organizational
unit People, to the organizational unit Special Users:</para>
<programlisting>import netscape.ldap.*;
import java.util.*;

public class ModDn {
    public static void main(String[] args) {
        try {
            /* Connect and authenticate as a user with write access. */
            UserArgs userArgs = new UserArgs("ModDn", args, true);
            LDAPConnection ld = new LDAPConnection();
            ld.connect(userArgs.getHost(), userArgs.getPort());
            ld.authenticate(3, userArgs.getBindDN(),userArgs.getPassword());

            /* Elevate Sam Carter from mere person to Special User. */
            String rdn = "uid=scarter";
            String oldParent = "ou=people,dc=example,dc=com";
            String newParent = "ou=special users,dc=example,dc=com";
            String dn = rdn + "," + oldParent;
            String ndn = rdn + "," + newParent;

            /* Read Sam's entry to make sure it exists before moving it. */
            try {
                LDAPEntry le = ld.read(dn);
            }
            catch(LDAPException e) {
                System.err.println(
                    "Cannot read " + dn + ": " + e.toString());
                throw e;
            }

            /* Delete the moved entry if it already exists. */
            try {
                ld.delete(ndn);
            }
            catch(LDAPException e) {
                /* Ignore notification that the new entry is not there. */
                if (e.getLDAPResultCode() != e.NO_SUCH_OBJECT) throw e;
            }

            /* Move Sam's entry. */
            ld.rename(dn, rdn, newParent, false);
            System.out.println("Entry " + dn + " has moved to " + ndn);

            ld.disconnect();
        }
        catch(LDAPException e) {
            System.err.println("Error: " + e.toString());
        }
    }
}</programlisting>
</sect2>
</sect1>
</chapter>
