Referrals

Creating and Updating Referrals

---

Note: The following discussion assumes that the LDAP server supports referrals as described in draft-ietf-ldapext-namedref-00.txt. If the server does not support referrals in this way, then the examples in this section won't work.

---

Representation in the Directory

A referral is represented in the LDAP directory as an object of class "referral". It contains a "ref" attribute, which is a multivalued attribute that contains one or more URLs. Each URL represents equivalent alternatives for following the referral. See draft-ietf-ldapext-namedref-00.txt for the schema definition of the "referral" object class and the "ref" attribute.

Disabling Following Referrals

You must ensure that the LDAP server will return referral entries as plain LDAP entries. You can do this by setting the Context.REFERRAL environment property to "ignore" or by unsetting it. "ignore" is the default if the property is not set. This is required if you are updating or deleting referrals and is optional if you are simply creating them. However, it is good practice to do this so that all programs that manage referrals are consistent.

Creating a Referral

You create a referral entry like you do any other type of entry: by using DirContext.bind() or DirContext.createSubcontext() and by supplying the appropriate attributes. The referral entry must have as one of its object classes "referral", and it must have a "ref" attribute that has at least one URL string.

Here's an example that creates a referral called "cn=NewReferral" that points to the "cn=J. Duke, ou=NewHires, o=JNDITutorial" entry on another server.

// The object classes
Attribute objclass = new BasicAttribute("objectclass");
objclass.add("top");
objclass.add("referral");
objclass.add("extensibleObject"); // So that you can use cn as name

// The referral itself
Attribute ref = new BasicAttribute("ref",
    "ldap://localhost:389/cn=J. Duke, ou=NewHires, o=JNDITutorial");

// The name
Attribute cn = new BasicAttribute("cn", "NewReferral");

// Create the attributes to be associated with the new context
Attributes attrs = new BasicAttributes(true); // Case-ignore
attrs.put(objclass);
attrs.put(ref);
attrs.put(cn);

// Create the context
Context result = ctx.createSubcontext("cn=NewReferral", attrs);

You can use the CheckReferral.java sample program to examine the referral entry's attributes. If you run it without command line arguments, then it displays the referral entry itself. If you run it with a command line argument, then it displays the referred entry's attributes.

# java CheckReferral
ref: ldap://localhost:389/cn=J. Duke, ou=NewHires, o=JNDITutorial 
objectclass: top, referral, extensibleObject 
cn: NewReferral

# java CheckReferral follow
sn: Duke 
objectclass: top, person, organizationalPerson, inetOrgPerson
mail: newbie@JNDITutorial.com 
cn: J. Duke

Updating a Referral

You update a referral entry like any other type of entry, by using DirContext.modifyAttributes(). Here's an example that changes the referral's URL to "ldap://localhost:389/cn=C. User, ou=NewHires, o=JNDITutorial".

// Set up new referral attribute
Attributes attrs = new BasicAttributes("ref",
    "ldap://localhost:389/cn=C. User, ou=NewHires, o=JNDITutorial", 
    true); // Case-ignore

// Update the "ref" attribute
ctx.modifyAttributes(
    "cn=NewReferral", DirContext.REPLACE_ATTRIBUTE, attrs);

After running this program, if you reexamine the entry by using CheckReferral, then you will see the following.

# java CheckReferral
ref: ldap://localhost:389/cn=C. User, ou=NewHires, o=JNDITutorial 
objectclass: top, referral, extensibleObject 
cn: NewReferral

# java CheckReferral follow
sn: User 
objectclass: top, person, organizationalPerson, inetOrgPerson 
mail: cuser@JNDITutorial.com 
userpassword: [B@1dacd887 
cn: C. User

Deleting a Referral

You delete a referral entry like any other type of entry, by using Context.unbind() or Context.destroySubcontext(). Here's an example that removes the referral entry "cn=NewReferral".

// Remove the entry
ctx.destroySubcontext("cn=NewReferral");

Referrals: End of Lesson

What's next? Now you can:

• Continue on to the next lesson in this trail for tips on accessing the schema.
• Go to the Frequently Asked Questions lesson to read about questions that LDAP users have when using the JNDI.

Referrals