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, 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.

Disable Following Referrals

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

Creating a Referral

You create a referral entry just 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 with 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 we 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 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, it displays the referral entry itself. If you run it with an argument, 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 using CheckReferral, 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

Deleteing 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 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