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.server.core;
021    
022    import org.apache.directory.shared.ldap.entry.ServerEntry;
023    import org.apache.directory.shared.ldap.name.DN;
024    
025    /**
026     * An interface for managing referrals in the server
027     *
028     * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
029     * @version $Rev$, $Date$
030     */
031    public interface ReferralManager
032    {
033        /**
034         * Get a read-lock on the referralManager. 
035         * No read operation can be done on the referralManager if this
036         * method is not called before.
037         */
038        void lockRead();
039        
040        
041        /**
042         * Get a write-lock on the referralManager. 
043         * No write operation can be done on the referralManager if this
044         * method is not called before.
045         */
046        void lockWrite();
047        
048        
049        /**
050         * Release the read-write lock on the referralManager. 
051         * This method must be called after having read or modified the
052         * ReferralManager
053         */
054        void unlock();
055        
056        
057        /**
058         * Tells if a DN is a referral (its associated entry contains the Referral ObjectClass).
059         * 
060         * It does not check that the associated entry inherits from a referral.
061         *
062         * @param dn The entry's DN we want to check
063         * @return <code>true</code> if the DN is associated with a referral
064         */
065        boolean isReferral( DN dn );
066        
067        
068        /**
069         * Tells if this DN has a parent which is a referral.
070         * <br>
071         * For instance, if cn=example, dc=acme, dc=org is the DN to check,
072         * and if dc=acme, dc=org is a referral, this this method will return true.
073         *
074         * @param dn The DN we want to check for a referral in its partents
075         * @return <code>true</code> if there is a parent referral
076         */
077        boolean hasParentReferral( DN dn );
078        
079        
080        /**
081         * Get the DN of the parent referral for a specific DN
082         *
083         * @param dn The DN from which we want to get the parent referral
084         * @return The parent referral of null if none is found
085         */
086        ServerEntry getParentReferral( DN dn );
087        
088        
089        /**
090         * Add a referral to the manager.
091         *
092         * @param dn The referral to add
093         */
094        void addReferral( ServerEntry entry );
095        
096        
097        /**
098         * Remove a referral from the manager.
099         * 
100         * @param dn The referral to remove
101         */
102        void removeReferral( ServerEntry entry );
103        
104        
105        /**
106         * Initialize the manager, reading all the referrals from the base.
107         * The manager will search for every entries having a Referral ObjectClass.
108         *
109         * @param directoryService The associated LDAP service
110         * @param suffixes The partition list
111         * @exception If the initialization failed
112         */
113        void init( DirectoryService directoryService, String... suffixes ) throws Exception;
114    
115        
116        /**
117         * Remove a partition from the manager, reading all the referrals from the base.
118         * The manager will search for every entries having a Referral ObjectClass, and
119         * will remove them from the referrals table.
120         *
121         * @param directoryService The associated LDAP service
122         * @param suffixes The partition DN to remove
123         * @exception If the removal failed
124         */
125        void remove( DirectoryService directoryService, DN suffix ) throws Exception;
126    }