Note
The core-JNDI provider does not, at the moment, support the 'follow' property.

Referral Handling Scenarios

Section

Column

width	70%

Here's a slightly modified example DIT used in RFC 3296. We'll also use this to elaborate on the behavior of operations based on the different scenarios outlined in 3296.

Info

title	Legend

Green nodes are actual entries. Red nodes are referrals.

Finding target in non-search operations

The handling for add, compare, delete, modify and modify DN operations to the target entry operated on is the same. The RFC gets a bit confusing when describing different scenarios and it's examples are lacking. They could have picked referrals where the DN is not the same as the reference to better demonstrate what they exactly meant. Regardless there seems to be 3 cases worth considering (whether the added entry is a referral or not is irrelevant) :

target is present, and has no ancestor which is a referral
target is not present, and no ancestor is a referral
target is not present, but an ancestor is a referral

(the special case "target is present, and has an ancestor which is a referral" is impossible...).

If we consider the tree we are using for our samples, those 3 cases can be represented as :

target's DN is "o=MNN,c=WW" or "ou=people, o=MNN, c=WW" (in this last example, the associated entry will be a referral.
target's DN is "o=absent,c=WW"
target's DN is "cn=Alex karasulu,ou=people,o=MNN,c=WW"

Column

width	30%

Code Block

title	OU=People,O=MNN,C=WW

ou: People
ref: ldap://hostb/OU=People,DC=example,DC=com
ref: ldap://hostc/OU=People,O=MNN,C=WW
objectClass: referral
objectClass: extensibleObject

Code Block

title	OU=Roles,O=MNN,C=WW

ou: Roles
ref: ldap://hostd/ou=Roles,dc=apache,dc=org
objectClass: referral
objectClass: extensibleObject

Referrals and LDAP operations

We now will describe the way Referrals are handled, depending on the operation the server will receive. We will consider the three different cases :

through JNDI
through the server own API (CoreAPI)

Add Operation handling

test	target exists	is a referral	has an ancestor	JNDI/Core handling	ManageDsaIT present	Description
1	no	no	no	Irrelevant	Irrelevant	Adds the entry into the server
2			yes	JNDI ignore	Irrelevant	The JNDI provider will throw a PartialResultException
3				JNDI throw	Irrelevant	The JNDI provider will throw a LdapReferralException
4				Core API	no	The Core API will throw a LdapReferralException Equivalent to the JNDI throw handling
5				Core API	yes	The Core API will throw a PartialResultException Equivalent to the JNDI ignore handling
6	yes	irrelevant	no	irrelevant	irrelevant	Throws an EntryAlreadyExists error

...

We should get a LdapReferralException*.*

Test 6

We try to add the following entry twice :

...

As a result, we should get an EntryAlreadyExist exception

...

Delete Operation handling

test	target exists	is a referral	has an ancestor ManageDsaIT present	JNDI/protocol Core handling	ManageDsaIT present	Description
1	no	irrelevant	no no	Irrelevant	JNDI Irrelevant	Returns a NoSuchObject result exception
2	no	irrelevant	yes	JNDI	Irrelevant protocol	Returns a NoSuchObject result	PartialResult exception
3	no	irrelevant	yes	Core API	Irrelevant JNDI	Returns a NoSuchObject result
			protocol	Returns a NoSuchObject result
PartialResult exception
4	yes	no	no	Irrelevant	Irrelevant	Remove the entry from the server
5	yes	yes	no	JNDI	Returns a Referral LdapResult, with the ancestor's URLs
			protocol	Returns a Referral LdapResult, with the ancestor's URLs
		yes	JNDI	Returns an UnwillingToPerform error
			protocol	Returns an UnwillingToPerform error
yes	no	no	JNDI	Compares the object and returns the result
			protocol	Compares the object and returns the result
		yes	JNDI	Compares the object and returns the result
			protocol	Compares the object and returns the result

no	no	no	no	JNDI	Returns a NoSuchObject result
				protocol	Adds the entry
			yes	JNDI	Adds the entry
				protocol	Adds the entry
		yes	no	JNDI	Returns a Referral LdapResult, with the ancestor's URLs
				protocol	Returns a Referral LdapResult, with the ancestor's URLs
			yes	JNDI	Returns a Referral LdapResult, with the ancestor's URLs
				protocol	Returns a Referral LdapResult, with the ancestor's URLs
	yes	no	no	JNDI	Adds the entry. Updates the ReferralManager
				protocol	Adds the entry. Updates the ReferralManager
			yes	JNDI	Adds the entry. Updates the ReferralManager
				protocol	Adds the entry. Updates the ReferralManager
		yes	no	JNDI	Returns a Referral LdapResult, with the ancestor's URLs
				protocol	Returns a Referral LdapResult, with the ancestor's URLs
			yes	JNDI	Returns a Referral LdapResult, with the ancestor's URLs
				protocol	Returns a Referral LdapResult, with the ancestor's URLs
yes	no	no	no	JNDI	Returns an entryAlreadyExists error
				protocol	Returns an entryAlreadyExists error
			yes	JNDI	Returns an entryAlreadyExists error
				protocol	Returns an entryAlreadyExists error
	yes	no	no	JNDI	Returns an entryAlreadyExists error
				protocol	Returns an entryAlreadyExists error
			yes	JNDI	Returns an entryAlreadyExists error
				protocol	Returns an entryAlreadyExists error

An entry cannot exist and have an ancestor.

Delete Operation handling

target exists	has an ancestor	ManageDsaIT present	JNDI/protocol handling	Description
no	no	no	JNDI	Returns a NoSuchObject result
			protocol	Returns a NoSuchObject result
		yes	JNDI	Returns a NoSuchObject result
			protocol	Returns a NoSuchObject result
	yes	no	JNDI	Returns a Referral LdapResult, with the ancestor's URLs
			protocol	Returns a Referral LdapResult, with the ancestor's URLs
		yes	JNDI	Returns a NoSuchObject result
			protocol	Returns a NoSuchObject result
yes	no	no	JNDI	Deletes the object
			protocol	Deletes the object
		yes	JNDI	Deletes the object
			protocol	Deletes the object

An entry cannot exist and have an ancestor.

Modify Operation handling

target exists	has an ancestor	ManageDsaIT present	JNDI/protocol handling	Description
no	no	no	JNDI	Returns a NoSuchObject result
			protocol	Returns a NoSuchObject result
		yes	JNDI	Returns a NoSuchObject result
			protocol	Returns a NoSuchObject result
	yes	no	JNDI	Returns a Referral LdapResult, with the ancestor's URLs
			protocol	Returns a Referral LdapResult, with the ancestor's URLs
		yes	JNDI	Returns a Referral LdapResult, with the ancestor's URLs
			protocol	Returns a Referral LdapResult, with the ancestor's URLs
yes	no	no	JNDI	Modify the entry
			protocol	Modify the entry
		yes	JNDI	Modify the entry
			protocol	Modify the entry

An entry cannot exist and have an ancestor.

ModifyDN Operation handling

target exists	has an ancestor	ManageDsaIT present	JNDI/protocol handling	Description
no	no	no	JNDI	Returns a NoSuchObject result
			protocol	Returns a NoSuchObject result
		yes	JNDI	Returns a NoSuchObject result
			protocol	Returns a NoSuchObject result
	yes	no	JNDI	Returns a Referral LdapResult, with the ancestor's URLs
			protocol	Returns a Referral LdapResult, with the ancestor's URLs
		yes	JNDI	Returns a NoSuchObject result
			protocol	Returns a NoSuchObject result
yes	no	no	JNDI	Deletes the object
			protocol	Deletes the object
		yes	JNDI	Deletes the object
			protocol	Deletes the object

An entry cannot exist and have an ancestor.

Search Operation handling

target exists	has an ancestor	ManageDsaIT present	JNDI/protocol handling	Description
no	no	no	JNDI	Returns a NoSuchObject result
			protocol	Returns a NoSuchObject result
		yes	JNDI	Returns a NoSuchObject result
			protocol	Returns a NoSuchObject result
	yes	no	JNDI	Returns a Referral LdapResult, with the ancestor's URLs
			protocol	Returns a Referral LdapResult, with the ancestor's URLs
		yes	JNDI	Returns a NoSuchObject result
			protocol	Returns a NoSuchObject result
yes	no	no	JNDI	Deletes the object
			protocol	Deletes the object
		yes	JNDI	Deletes the object
			protocol	Deletes the object

...

throw	Throw a LdapReferralException
6	yes	yes	no	JNDI	ignore	Remove the entry from the server
7	yes	yes	no	CoreAPI	no	Throw a LdapReferralException
8	yes	yes	no	CoreAPI	yes	Remove the entry from the server

Test 1

Trying to delete dn: cn=not present, c=MNN, c=WW should fail

Test 2 & 3

Trying to delete dn: cn=alex karasulu, ou=people, c=MNN, c=WW should throw a PartialResultException

Test 4

We should be able to delete dn: o=MNN, c=WW

Test 5

Trying to delete dn: ou=people, c=MNN, c=WW should throw a ReferralException

Test 6 & 8

We should be able to delete dn: ou=people, c=MNN, c=WW

Test 7

Trying to delete dn: ou=people, c=MNN, c=WW should throw a ReferralException

Compare Operation handling

Modify Operation handling

ModifyDN Operation handling

Search Operation handling

case #1: Target is not a referral, has no ancestor which is a referraThe presence of the ManageDsaIT control is irrelevent.
JNDI handlingAs the entry is not a referral, whatever value is set to the Context.REFERRAL property, the response will be the same : the server simply returns the entry if it existsMINA provider handling

...

Child pages

Versions Compared

Old Version 12

New Version 13

Key

Referral Handling Scenarios

Finding target in non-search operations

Referrals and LDAP operations

Add Operation handling

Test 6

Delete Operation handling

Delete Operation handling

Modify Operation handling

ModifyDN Operation handling

Search Operation handling

Test 1

Test 2 & 3

Test 4

Test 5

Test 6 & 8

Test 7

Compare Operation handling

Modify Operation handling

ModifyDN Operation handling

Search Operation handling

Child pages

Page History

Versions Compared

Old Version 12

New Version 13

Key

Referral Handling Scenarios

Finding target in non-search operations

Referrals and LDAP operations

Add Operation handling

Test 6

Delete Operation handling

Delete Operation handling

Modify Operation handling

ModifyDN Operation handling

Search Operation handling

Test 1

Test 2 & 3

Test 4

Test 5

Test 6 & 8

Test 7

Compare Operation handling

Modify Operation handling

ModifyDN Operation handling

Search Operation handling