org.apache.directory.api.ldap.model.message

Interface Referral

All Known Implementing Classes:

ReferralImpl

public interface Referral

Represents a referral which is a set of alternative locations where an entry can be found. Here's what RFC 2251 has to say about it:

  4.1.11. Referral
 
   The referral error indicates that the contacted server does not hold
   the target entry of the request.  The referral field is present in an
   LDAPResult if the LDAPResult.resultCode field value is referral, and
   absent with all other result codes.  It contains a reference to
   another server (or set of servers) which may be accessed via LDAP or
   other protocols.  Referrals can be returned in response to any
   operation request (except unbind and abandon which do not have
   responses). At least one URL MUST be present in the Referral.
 
   The referral is not returned for a singleLevel or wholeSubtree search
   in which the search scope spans multiple naming contexts, and several
   different servers would need to be contacted to complete the
   operation. Instead, continuation references, described in section
   4.5.3, are returned.
 
        Referral ::= SEQUENCE OF LDAPURL  -- one or more
 
        LDAPURL ::= LDAPString -- limited to characters permitted in URLs
 
   If the client wishes to progress the operation, it MUST follow the
   referral by contacting any one of servers.  All the URLs MUST be
   equally capable of being used to progress the operation.  (The
   mechanisms for how this is achieved by multiple servers are outside
   the scope of this document.)
 
   URLs for servers implementing the LDAP protocol are written according
   to <a href="http://www.faqs.org/rfcs/rfc2255.html">[9]</a>.  If an alias
   was dereferenced, the <dn> part of the URL MUST be present, with the new
   target object name.  If the <dn> part is present, the client MUST use this
   name in its next request to progress the operation, and if it is not present
   the client will use the same name as in the original request.  Some servers
   (e.g. participating in distributed indexing) may provide a different filter
   in a referral for a search operation.  If the filter part of the URL
    is present in an LDAPURL, the client MUST use this filter in its next
   request to progress this search, and if it is not present the client
   MUST use the same filter as it used for that search.  Other aspects
   of the new request may be the same or different as the request which
   generated the referral.
 
   Note that UTF-8 characters appearing in a Dn or search filter may not
   be legal for URLs (e.g. spaces) and MUST be escaped using the %
   method in RFC 1738 <a href="http://www.faqs.org/rfcs/rfc1738.html">[7]</a>.
 
   Other kinds of URLs may be returned, so long as the operation could
   be performed using that protocol.
 

Author:

Apache Directory Project TODO This interface should be located in a url package under common to be constructed from a LDAPv3 URL parser. The interface will eventually look very different once url support is added: for one it will add and remove LdapUrl objects instead of strings or provide both string and LdapUrl add/remove methods.

Method Summary

Modifier and Type	Method and Description
void	addLdapUrl(String url) Adds an LDAPv3 URL to this Referral.
void	addLdapUrlBytes(byte[] urlBytes) Adds an encoded LDAPv3 URL to this Referral.
Collection<String>	getLdapUrls() Gets an unmodifiable set of alternative referral urls.
Collection<byte[]>	getLdapUrlsBytes() Gets an unmodifiable set of encoded referral urls.
int	getReferralLength()
void	removeLdapUrl(String url) Removes an LDAPv3 URL to this Referral.
void	setReferralLength(int referralLength) Set the length of the referral

Method Detail

getLdapUrls

Collection<String> getLdapUrls()

Gets an unmodifiable set of alternative referral urls.

Returns:

the alternative url objects.

getLdapUrlsBytes

Collection<byte[]> getLdapUrlsBytes()

Gets an unmodifiable set of encoded referral urls.

Returns:

the encoded url objects.

addLdapUrl

void addLdapUrl(String url)

Adds an LDAPv3 URL to this Referral.

Parameters:

url - the LDAPv3 URL to add

addLdapUrlBytes

void addLdapUrlBytes(byte[] urlBytes)

Adds an encoded LDAPv3 URL to this Referral.

Parameters:

urlBytes - the encoded LDAPv3 URL to add

removeLdapUrl

void removeLdapUrl(String url)

Removes an LDAPv3 URL to this Referral.

Parameters:

url - the LDAPv3 URL to remove

getReferralLength

int getReferralLength()

Returns:

The total length of the Referral

setReferralLength

void setReferralLength(int referralLength)

Set the length of the referral

Parameters:

referralLength - The total length of the Referral