"Directory SDK for Java 4.0 Programmer's Guide": Adding, Updating, and Deleting Entries

Contents

Index

Chapter 8 Adding, Updating, and Deleting Entries

This chapter explains how to use the LDAP Java classes to add, modify, delete, and rename entries in the directory.

The chapter includes the following sections:

"Adding a New Entry"

"Modifying an Entry"

"Deleting an Entry"

"Changing the Name of an Entry"

Adding a New Entry

To add an entry to the directory, you need to follow this general procedure:

Create each individual attribute that will be in the entry. (See "Creating a New Attribute".)

Create the set of attributes that make up the entry, and add each of the attributes to this set. (See "Creating a New Attribute Set".)

Create the new entry, specifying a unique distinguished name (DN) to identify the entry and the set of attributes that make up the entry. (See "Creating a New Entry".)

Add the new entry to directory. (See "Adding the Entry to the Directory".)

For a complete example, see "Example of Adding an Entry".

Creating a New Attribute
An attribute can have a single value or multiple values and can contain string values or binary data. In the LDAP Java classes, an attribute is represented by an LDAPAttribute object.

To create a new attribute, use the LDAPAttribute constructor. You can specify a single string value, multiple string values, or a binary value when constructing the object.

For example, the following section of code creates a new object for the attribute "cn" with the value "Jane St. Clair".

...

LDAPAttribute attr = new LDAPAttribute( "cn", "Jane St. Clair" );

...

The following section of code creates an attribute "objectclass" with the values "top", "person", "organizationalPerson", and "inetOrgPerson".

...

String objectclasses[] = { "top",

   "person", "organizationalPerson", "inetOrgPerson" };

LDAPAttribute attr = new LDAPAttribute( "objectclass", objectclasses );

...

You can also add string or binary values to an LDAPAttribute object by invoking the addValue method.

Creating a New Attribute Set
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 LDAPAttributeSet object.

To create a new attribute set, use the LDAPAttributeSet constructor and invoke the add methodto add LDAPAttribute objects to the set.

For example:

...

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 );

...

Creating a New Entry
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 LDAPEntry object.

To create a new entry, use the LDAPEntry constructor. For example:

...

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,o=Airius.com"; 

LDAPEntry newEntry = new LDAPEntry( dn, attrs );

...

Adding the Entry to the Directory
To add the entry to the directory, invoke the add methodof the LDAPConnection object. For example:

...

try {

   LDAPConnection ld = new LDAPConnection();

   ld.connect( "localhost", LDAPv2.DEFAULT_PORT ); 

   ld.authenticate( "cn=Directory Manager", "23skidoo" );

   LDAPEntry newEntry = new LDAPEntry( dn, attrs );

   ld.add( newEntry );

...

Before you add an entry, make sure of the following:

You have specified the object classes of the entry (use the "objectclass" attribute to specify these) and the required attributes for that object class.

For example, in the Netscape Directory Server, organizational units are represented by entries of the "organizationalUnit" object class. To add an entry for a person, you need to specify the following attributes in the entry:

objectclass (this attribute should have the values "top" and "organizationalUnit")

ou (this is a required attribute)

For a listing of object classes and their required attributes, see the Directory Server Administrator's Guide.

Make sure that you authenticate as a user who has the access permissions to add the entry to the directory. (If you do not have permission to add the entry, an LDAPException is thrown with the result code LDAPException.INSUFFICIENT_ACCESS_RIGHTS.)

Example of Adding an Entry
The following example adds a new entry to the directory for the user named William Jensen.

import netscape.ldap.*;

import java.util.*;

public class Add {

   public static void main( String[] args ) {

      /* Specify the DN of the new entry. */

      String dn = "uid=wbjensen, ou=People, o=Airius.com";



      /* Create a new attribute set for the entry. */

      LDAPAttributeSet attrs = new LDAPAttributeSet();



      /* Create and add attributes to the attribute set. */

      String objectclass_values[] = { "top", "person", 

         "organizationalPerson", "inetOrgPerson" };

      LDAPAttribute attr = new LDAPAttribute( "objectclass", 

         objectclass_values );

      attrs.add( attr );



      String cn_values[] = { "William B Jensen", "William Jensen", 

         "Bill Jensen" };

      attr = new LDAPAttribute( "cn", cn_values );

      attrs.add( attr );



      String givenname_values[] = { "William", "Bill" };

      attr = new LDAPAttribute( "givenname", givenname_values );

      attrs.add( attr );



      attrs.add( new LDAPAttribute( "sn", "Jensen" ) );

      attrs.add( new LDAPAttribute( "telephonenumber", 

         "+1 415 555 1212" ) );

      attrs.add( new LDAPAttribute( "uid", "wbjensen" ) );



      /* Create an entry with this DN and these attributes . */

      LDAPEntry myEntry = new LDAPEntry( dn, attrs );



      /* Connect to the server and add the entry. */

      LDAPConnection ld = null;

      int status = -1;

      try {

         ld = new LDAPConnection();



         /* Connect to the server. */

         String HOSTNAME= "localhost";

         ld.connect( HOSTNAME, LDAPv2.DEFAULT_PORT );



         /* Authenticate to the server as the directory manager. */

         String MGR_DN = "cn=Directory Manager";

         String MGR_PW = "23skidoo";

         ld.authenticate( MGR_DN, MGR_PW );



         /* Add the entry to the directory. */

         ld.add( myEntry );

         System.out.println( "Added entry successfully."  );



      }

      catch( LDAPException e ) {

         if (e.getLDAPResultCode() == 

            LDAPException.ENTRY_ALREADY_EXISTS )

            System.out.println( "Error: Entry already present" );

         else

            System.out.println( "Error: " + e.toString() );

      }



      /* When done, disconnect from the server. */

      if ( (ld != null) && ld.isConnected() ) {

         try {

            ld.disconnect();

         } catch ( LDAPException e ) {

            System.out.println( "Error: " + e.toString() );

         }

      }

      System.exit(status);

   }

}

Modifying an Entry

To modify an entry in the directory, you need to follow this general procedure:

Specify each change to an attribute that needs to be made. You can do one of the following:

If you are making only one change to the entry, you need to construct an LDAPModification object specifying the change that needs to be made.

If you are making more than one change, you need to construct an LDAPModificationSet object specifying the changes that need to be made.

See "Specifying the Changes" for details.

Use the distinguished name of the entry to find and update the entry in the directory. (See "Modifying the Entry in the Directory".)

For a complete example, see "Example of Modifying an Entry".

Specifying the Changes
You can add a new attribute, removing an existing attribute, or changing the values of an existing attribute. This section describes the process of specifying these changes.

Adding New Values to an Attribute

Removing Values to an Attribute

Replacing the Values of an Attribute

Adding a New Attribute

Removing an Attribute

Adding New Values to an Attribute
To add new values to an attribute in an entry, construct a new LDAPAttribute object, specifying the name of the attribute and the values that you want to add. Then, do one of the following:

If you are only making a single change to the entry, construct a new LDAPModification objectto specify that change. Pass LDAPModification.ADD and the LDAPAttribute object as arguments to the LDAPModification constructor.

If you are collecting multiple changes to an entry in an LDAPModificationSet object, invoke the add method to add this change to the list. Pass LDAPModification.ADD and the LDAPAttribute object as arguments to this method.

For example, the following section of code prepares to add the value "babs@airius.com" to the "mail" attribute to an entry.

...

LDAPModificationSet mods = new LDAPModificationSet();

LDAPAttribute attrMail = new LDAPAttribute( "mail",

   "babs@airius.com" );

mods.add( LDAPModification.ADD, attrMail );

...

Note that if the specified attribute does not exist in the entry, the attribute will be added to the entry. For example, if the "mail" attribute does not exist in the entry, adding the value "babs@airius.com" will add the "mail" attribute to the entry.

Removing Values to an Attribute
To remove values from an attribute in an entry, construct a new LDAPAttribute object, specifying the name of the attribute and the values that you want to remove. Then, do one of the following:

If you are only making a single change to the entry, construct a new LDAPModification object to specify that change. Pass LDAPModification.DELETE and the LDAPAttribute object as arguments to the LDAPModification constructor.

If you are collecting multiple changes to an entry in an LDAPModificationSet object, invoke the add method to add this change to the list. Pass LDAPModification.DELETE and the LDAPAttribute object as arguments to this method.

For example, the following section of code prepares to remove the value "babs@airius.com" from the "mail" attribute to an entry.

...

LDAPModificationSet mods = new LDAPModificationSet();

LDAPAttribute attrMail = new LDAPAttribute( "mail",

   "babs@airius.com" );

mods.add( LDAPModification.DELETE, attrMail );

...

Note that if you are removing all values in the attribute, the attribute will be removed. For example, if "babs@airius.com" is the only value of the "mail" attribute, removing this value will remove the "mail" attribute from the entry.

Also note that if you do not specify any values in the LDAPAttribute object, the attribute will be removed. For example, if you construct the object by invoking LDAPAttribute( "mail" ), the "mail" attribute will be removed.

Replacing the Values of an Attribute
To replace all of the values of an attribute in an entry, construct a new LDAPAttribute object, specifying the name of the attribute and the new values that should replace all of the existing values of the attribute. Then, do one of the following:

If you are only making a single change to the entry, construct a new LDAPModification object to specify that change. Pass LDAPModification.REPLACE and the LDAPAttribute object as arguments to the LDAPModification constructor.

If you are collecting multiple changes to an entry in an LDAPModificationSet object, invoke the add method to add this change to the list. Pass LDAPModification.REPLACE and the LDAPAttribute object as arguments to this method.

For example, the following section of code prepares to replace the existing values of the "mail" attribute with the values "bjensen@airius.com" and "babs@airius.com".

...

LDAPModificationSet mods = new LDAPModificationSet();

String attrValues = { "bjensen@airius.com", "babs@airius.com" }

LDAPAttribute attrMail = new LDAPAttribute( "mail", attrValues );

mods.add( LDAPModification.REPLACE, attrMail );

...

Note that if the specified attribute does not exist in the entry, the attribute will be added to the entry. For example, if the "mail" attribute does not exist in the entry, replacing the values "bjensen@airius.com" and "babs@airius.com" will add the "mail" attribute to the entry.

Adding a New Attribute
To add a new attribute to an entry, follow the instructions under "Adding New Values to an Attribute" or "Replacing the Values of an Attribute". If you add or replace values for an attribute that does not exist in the entry, the attribute will be added to the entry.

Removing an Attribute
To remove an attribute from an entry, you can do one of the following:

replace the values of the attribute with no values (construct the LDAPAttribute object with no values)

specify that you want to remove a value from the attribute, and specify no value (construct the LDAPAttribute object with no values)

remove all values of the attribute

For example, the following section of code prepares to remove the "mail" and "description" attributes from an entry. This example demonstrates how you can use either LDAPModification.REPLACE or LDAPModification.DELETE to remove the attribute.

...

LDAPModificationSet mods = new LDAPModificationSet();

LDAPAttribute attrMail = new LDAPAttribute( "mail" );

LDAPAttribute attrDesc = new LDAPAttribute( "description" );

mods.add( LDAPModification.REPLACE, attrMail );

mods.add( LDAPModification.DELETE, attrDesc );

...

For more information on removing or replacing values, see "Removing Values to an Attribute" or "Replacing the Values of an Attribute".

Modifying the Entry in the Directory
When you are done specifying the change (an LDAPModification object) or list of changes (LDAPModificationSet) that you want made, you can pass this object with the distinguished name of the entry that you want modified to the modify method of the LDAPConnection object.

Before you modify an entry, make sure of the following:

You are not removing any of the required attributes for that object class.

For example, in the Netscape Directory Server, organizational units are represented by entries of the "organizationalUnit" object class. The "ou" attribute is a required attribute of the object class and should not be removed.

For a listing of object classes and their required attributes, see the Directory Server Administrator's Guide.

Make sure that you authenticate as a user who has the access permissions to modify the entry in the directory. (If you do not have permission to modify the entry, an LDAPException is thrown with the result code LDAPException.INSUFFICIENT_ACCESS_RIGHTS.)

Example of Modifying an Entry
The following example modifies the entry in the directory for the user named William Jensen.

import netscape.ldap.*;

import java.util.*;

public class ModAttrs {

   public static void main( String[] args ) {

      /* Specify the entry to be modified. */

      String ENTRYDN = "uid=wbjensen, ou=People, o=Airius.com";



      /* Create a new set of modifications. */

      LDAPModificationSet mods = new LDAPModificationSet();



      /* Add each change to an attribute to the set of modifications. */

      LDAPAttribute attrEmail = new LDAPAttribute( "mail", 

         "willj@airius.com" );

      mods.add( LDAPModification.REPLACE, attrEmail );



      LDAPAttribute attrDesc = new LDAPAttribute( "description", 

         "This entry was modified with the modattrs program" );

      mods.add( LDAPModification.ADD, attrDesc );



      LDAPAttribute attrPhone = new 

         LDAPAttribute("telephoneNumber");

      mods.add( LDAPModification.DELETE, attrPhone );



      /* Connect to the server and modify the entry. */

      LDAPConnection ld = null;

      int status = -1;

      try {

         ld = new LDAPConnection();



         /* Connect to the server. */

         String HOSTNAME = "localhost";

         ld.connect( HOSTNAME, LDAPv2.DEFAULT_PORT );



         /* Authenticate to the server as directory manager */

         String MGR_DN = "cn=Directory Manager";

         String MGR_PW = "23skidoo";

         ld.authenticate( MGR_DN, MGR_PW );



         /* Now modify the entry in the directory */

         ld.modify( ENTRYDN, mods );

         System.out.println( "Successfully modified the entry." );

      } 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() );

      }



      /* Disconnect when done. */

      if ( (ld != null) && ld.isConnected() ) {

         try {

            ld.disconnect();

         } catch ( LDAPException e ) {

            System.out.println( "Error: " + e.toString() );

         }

      }

      System.exit(status);

   }

}

Deleting an Entry

To remove an entry from the directory, invoke the delete method of the LDAPConnection object and specify the distinguished name (DN) of the entry that you want to remove.

Before you delete an entry, make sure that you authenticate as a user who has the access permissions to remove the entry from the directory. (If you do not have permission to remove the entry, an LDAPException is thrown with the result code LDAPException.INSUFFICIENT_ACCESS_RIGHTS.)

Example of Deleting an Entry
The following section of code deletes the entry for the user named William Jensen.

import netscape.ldap.*;

import java.util.*;

public class Del {

   public static void main( String[] args ) {



      /* Connect to the server and delete the entry. */

      LDAPConnection ld = null;

      int status = -1;

      try {

         ld = new LDAPConnection();



         /* Connect to the server. */

         String HOSTNAME = "localhost";

         ld.connect( HOSTNAME, LDAPv2.DEFAULT_PORT );



         /* Authenticate to the server as the directory manager. */

         String MGR_DN = "cn=Directory Manager";

         String MGR_PW = "23skidoo";

         ld.authenticate( MGR_DN, MGR_PW );



         /* Delete the entry. */

         String dn = "uid=wbjensen, ou=People, o=Airius.com";

         ld.delete( dn );

         System.out.println( "Entry deleted" );

      }



      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() );

      }

      /* When done, disconnect from the server. */

      if ( (ld != null) && ld.isConnected() ) {

         try {

            ld.disconnect();

         } catch ( LDAPException e ) {

            System.out.println( "Error: " + e.toString() );

         }

      }

      System.exit(status);

   }

}

Changing the Name of an Entry

To rename an entry, invoke the rename method of the LDAPConnection object. Using this method, you can do the following:

Change the relative distinguished name (RDN) of an entry. For example, you can

Change the location of an entry in the directory tree (in other words, change the distinguished name of an entry)

Note that not all LDAP servers support the ability to change the location of an entry in the directory tree. (The Netscape Directory Server does not yet support this capability.)

For a complete example, see "Example of Renaming an Entry".

Removing the Attribute for the Old RDN
When invoking the rename method of the LDAPConnection object, you can specify a deleteoldrdn parameter that allows you to remove the old RDN from the entry. The deleteoldrdn parameter is best explained through this example. Suppose an entry has the following values for the uid attribute:

   uid: wbjensen

   uid: wbj

The following method adds "wjensen" to this list of values and removes the "wbjensen" value:

   ld.rename( "uid=wbjensen,ou=People,o=Airius.com", "uid=wjensen", 

      true );

The resulting entry has the following values:

   uid: wjensen

   uid: wbj

If instead false is passed for the deleteoldrdn parameter:

   ld.rename( "uid=wbjensen,ou=People,o=Airius.com", "uid=wjensen", 

      false );

the "Barbara Jensen" value is not removed from the entry:

   uid: wjensen

   uid: wbjensen

   uid: wbj

Before you rename an entry, make sure that you authenticate as a user who has the access permissions to rename the entry in the directory. (If you do not have permission to rename the entry, an LDAPException is thrown with the result code LDAPException.INSUFFICIENT_ACCESS_RIGHTS.)

Example of Renaming an Entry
The following example changes the RDN of an entry from uid=wbjensen to uid=wjensen.

import netscape.ldap.*;

import java.util.*;

public class Rename {

   public static void main( String[] args ) {

      /* Connect to the server and rename the entry. */

      LDAPConnection ld = null;

      int status = -1;

      try {

         ld = new LDAPConnection();



         /* Connect to the server. */

         String HOSTNAME = "localhost";

         ld.connect( HOSTNAME, LDAPv2.DEFAULT_PORT );



         /* Authenticate to the server as the directory manager. */

         String MGR_DN = "cn=Directory Manager";

         String MGR_PW = "23skidoo";

         ld.authenticate( MGR_DN, MGR_PW );



         /* Change the RDN of the entry. */

         String dn = "uid=wbjensen,ou=People,o=Airius.com";

         String nrdn = "uid=wjensen";

         ld.rename( dn, nrdn, true );

         System.out.println( "Entry " + dn + " has been renamed." );

      }

      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() );

      }

      /* Done, so disconnect */

      if ( (ld != null) && ld.isConnected() ) {

         try {

            ld.disconnect();

         } catch ( LDAPException e ) {

            System.out.println( "Error: " + e.toString() );

         }

      }

      System.exit(status);

   }

}