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