001    /*
002     *  Licensed to the Apache Software Foundation (ASF) under one
003     *  or more contributor license agreements.  See the NOTICE file
004     *  distributed with this work for additional information
005     *  regarding copyright ownership.  The ASF licenses this file
006     *  to you under the Apache License, Version 2.0 (the
007     *  "License"); you may not use this file except in compliance
008     *  with the License.  You may obtain a copy of the License at
009     *  
010     *    http://www.apache.org/licenses/LICENSE-2.0
011     *  
012     *  Unless required by applicable law or agreed to in writing,
013     *  software distributed under the License is distributed on an
014     *  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015     *  KIND, either express or implied.  See the License for the
016     *  specific language governing permissions and limitations
017     *  under the License. 
018     *  
019     */
020    package org.apache.directory.shared.ldap.message.internal;
021    
022    
023    import java.util.Collection;
024    
025    
026    /**
027     * Represents a referral which is a set of alternative locations where an entry
028     * can be found. Here's what <a href="http://www.faqs.org/rfcs/rfc2251.html">
029     * RFC 2251 </a> has to say about it:
030     * 
031     * <pre>
032     *  4.1.11. Referral
033     * 
034     *   The referral error indicates that the contacted server does not hold
035     *   the target entry of the request.  The referral field is present in an
036     *   LDAPResult if the LDAPResult.resultCode field value is referral, and
037     *   absent with all other result codes.  It contains a reference to
038     *   another server (or set of servers) which may be accessed via LDAP or
039     *   other protocols.  Referrals can be returned in response to any
040     *   operation request (except unbind and abandon which do not have
041     *   responses). At least one URL MUST be present in the Referral.
042     * 
043     *   The referral is not returned for a singleLevel or wholeSubtree search
044     *   in which the search scope spans multiple naming contexts, and several
045     *   different servers would need to be contacted to complete the
046     *   operation. Instead, continuation references, described in section
047     *   4.5.3, are returned.
048     * 
049     *        Referral ::= SEQUENCE OF LDAPURL  -- one or more
050     * 
051     *        LDAPURL ::= LDAPString -- limited to characters permitted in URLs
052     * 
053     *   If the client wishes to progress the operation, it MUST follow the
054     *   referral by contacting any one of servers.  All the URLs MUST be
055     *   equally capable of being used to progress the operation.  (The
056     *   mechanisms for how this is achieved by multiple servers are outside
057     *   the scope of this document.)
058     * 
059     *   URLs for servers implementing the LDAP protocol are written according
060     *   to &lt;a href=&quot;http://www.faqs.org/rfcs/rfc2255.html&quot;&gt;[9]&lt;/a&gt;.  If an alias
061     *   was dereferenced, the &lt;dn&gt; part of the URL MUST be present, with the new
062     *   target object name.  If the &lt;dn&gt; part is present, the client MUST use this
063     *   name in its next request to progress the operation, and if it is not present
064     *   the client will use the same name as in the original request.  Some servers
065     *   (e.g. participating in distributed indexing) may provide a different filter
066     *   in a referral for a search operation.  If the filter part of the URL
067     *    is present in an LDAPURL, the client MUST use this filter in its next
068     *   request to progress this search, and if it is not present the client
069     *   MUST use the same filter as it used for that search.  Other aspects
070     *   of the new request may be the same or different as the request which
071     *   generated the referral.
072     * 
073     *   Note that UTF-8 characters appearing in a DN or search filter may not
074     *   be legal for URLs (e.g. spaces) and MUST be escaped using the %
075     *   method in RFC 1738 &lt;a href=&quot;http://www.faqs.org/rfcs/rfc1738.html&quot;&gt;[7]&lt;/a&gt;.
076     * 
077     *   Other kinds of URLs may be returned, so long as the operation could
078     *   be performed using that protocol.
079     * </pre>
080     * 
081     * @author <a href="mailto:dev@directory.apache.org"> Apache Directory Project</a>
082     * @version $Rev: 905344 $
083     * TODO This interface should be located in a url package under common to be
084     *       constructed from a LDAPv3 URL parser. The interface will eventually
085     *       look very different once url support is added: for one it will add and
086     *       remove LdapUrl objects instead of strings or provide both string and
087     *       LdapUrl add/remove methods.
088     */
089    public interface InternalReferral
090    {
091        /**
092         * Gets an unmodifiable set of alternative referral urls.
093         * 
094         * @return the alternative url objects.
095         */
096        Collection<String> getLdapUrls();
097    
098    
099        /**
100         * Adds an LDAPv3 URL to this Referral.
101         * 
102         * @param a_url
103         *            the LDAPv3 URL to add
104         */
105        void addLdapUrl( String url );
106    
107    
108        /**
109         * Removes an LDAPv3 URL to this Referral.
110         * 
111         * @param a_url
112         *            the LDAPv3 URL to remove
113         */
114        void removeLdapUrl( String url );
115    }