001/*
002 * The contents of this file are subject to the terms of the Common Development and
003 * Distribution License (the License). You may not use this file except in compliance with the
004 * License.
005 *
006 * You can obtain a copy of the License at legal/CDDLv1.0.txt. See the License for the
007 * specific language governing permission and limitations under the License.
008 *
009 * When distributing Covered Software, include this CDDL Header Notice in each file and include
010 * the License file at legal/CDDLv1.0.txt. If applicable, add the following below the CDDL
011 * Header, with the fields enclosed by brackets [] replaced by your own identifying
012 * information: "Portions Copyright [year] [name of copyright owner]".
013 *
014 * Copyright 2008-2009 Sun Microsystems, Inc.
015 * Portions Copyright 2013-2016 ForgeRock AS.
016 */
017package org.forgerock.opendj.server.core;
018
019import java.util.Set;
020
021import org.forgerock.opendj.ldap.DN;
022import org.forgerock.opendj.ldap.Entry;
023import org.forgerock.opendj.ldap.LdapException;
024import org.forgerock.opendj.ldap.RequestHandler;
025
026/**
027 * An entry container which provides the content of one or more sub-trees.
028 * <p>
029 * A data provider can be:
030 * <ul>
031 * <li>a simple data source such as a local back-end, a remote LDAP server or a
032 * local LDIF file.
033 * <li>used to route operations. This is the case for load balancing and
034 * distribution.
035 * <li>combine and transform data from underlying data providers. For example,
036 * DN mapping, attribute renaming, attribute value transformations, etc.
037 * </ul>
038 * Data providers operate in two states:
039 * <ul>
040 * <li>initialized
041 * <li>accepting requests
042 * </ul>
043 * Data providers are created in the <i>initialized</i> state. In this state a
044 * data provider has validated its configuration and registered support for
045 * off-line services such as export, import, backup, and restore if available.
046 * <p>
047 * A data provider transitions to the <i>accepting requests</i> state when the
048 * {@link #startDataProvider()} method is invoked. In this state a data provider
049 * has acquired any remaining resources that it needs in order to be fully
050 * operational. This may include connections to underlying data providers. See
051 * the documentation for {@link #startDataProvider()} for more information.
052 * <p>
053 * A data provider transitions back to the <i>initialized</i> state using the
054 * {@link #stopDataProvider()} method. This occurs when the data provider is no
055 * longer needed in order process client requests, but may still be needed in
056 * order to perform off-line services such as import, export, backup, and
057 * restore.
058 * <p>
059 * If data provider is disabled or deleted from the server configuration or if
060 * the server is shutdown, then the {@link #finalizeDataProvider()} method is
061 * invoked. This method should ensure that the data provider is stopped and no
062 * longer available for off-line services such as import, export, backup, and
063 * restore.
064 */
065public interface DataProvider extends RequestHandler<Operation> {
066
067    /**
068     * Indicates whether this data provider contains the specified entry.
069     *
070     * @param dn
071     *            The DN of the entry.
072     * @return {@code true} if this data provider contains the specified entry,
073     *         or {@code false} if it does not.
074     * @throws LdapException
075     *             If a problem occurs while trying to make the determination,
076     *             or if {@code dn} is not a DN equal to or subordinate to one
077     *             of the base DNs managed by this data provider.
078     */
079    boolean containsEntry(DN dn) throws LdapException;
080
081    /**
082     * Deregisters an event listener from this data provider.
083     *
084     * @param listener
085     *            The event listener.
086     */
087    void deregisterEventListener(DataProviderEventListener listener);
088
089    /**
090     * Performs any necessary work to finalize this data provider. This may
091     * include closing any connections to underlying data providers, databases,
092     * and deregistering any listeners, etc.
093     * <p>
094     * This method may be called during the Directory Server shutdown process or
095     * if a data provider is disabled with the server online. It must not return
096     * until this data provider is finalized.
097     * <p>
098     * Implementations should assume that this data provider has already been
099     * stopped using {@link #stopDataProvider()}.
100     * <p>
101     * Implementations must deregister any listeners such as those required for
102     * performing import, export, backup, and restore.
103     * <p>
104     * Implementations must not throw any exceptions. If any problems are
105     * encountered, then they may be logged but the closure should progress as
106     * completely as possible.
107     */
108    void finalizeDataProvider();
109
110    /**
111     * Returns an unmodifiable set containing the base DNs of the sub-trees
112     * which this data provider contains.
113     *
114     * @return An unmodifiable set containing the base DNs of the sub-trees
115     *         which this data provider contains.
116     */
117    Set<DN> getBaseDNs();
118
119    /**
120     * Retrieves the specified entry from this data provider.
121     *
122     * @param dn
123     *            The DN of the entry.
124     * @return The requested entry, or {@code null} if this data provider does
125     *         not contain the specified entry.
126     * @throws LdapException
127     *             If a problem occurs while trying to retrieve the entry, or if
128     *             {@code dn} is not a DN equal to or subordinate to one of the
129     *             base DNs managed by this data provider.
130     */
131    Entry getEntry(DN dn) throws LdapException;
132
133    /**
134     * Returns the current status of the provided base DN in this data provider.
135     *
136     * @param baseDN
137     *            The base DN in this data provider.
138     * @return The current status of the provided base DN in this data provider.
139     * @throws LdapException
140     *             If {@code baseDN} is not one of the base DNs managed by this
141     *             data provider.
142     */
143    DataProviderStatus getStatus(DN baseDN) throws LdapException;
144
145    /**
146     * Returns an unmodifiable set containing the OIDs of the controls that may
147     * be supported by the provided base DN in this data provider.
148     *
149     * @param baseDN
150     *            The base DN in this data provider.
151     * @return An unmodifiable set containing the OIDs of the controls that may
152     *         be supported by the provided base DN in this data provider.
153     * @throws LdapException
154     *             If {@code baseDN} is not one of the base DNs managed by this
155     *             data provider.
156     */
157    Set<String> getSupportedControls(DN baseDN) throws LdapException;
158
159    /**
160     * Returns an unmodifiable set containing the OIDs of the features that may
161     * be supported by the provided base DN in this data provider.
162     *
163     * @param baseDN
164     *            The base DN in this data provider.
165     * @return An unmodifiable set containing the OIDs of the features that may
166     *         be supported by the provided base DN in this data provider.
167     * @throws LdapException
168     *             If {@code baseDN} is not one of the base DNs managed by this
169     *             data provider.
170     */
171    Set<String> getSupportedFeatures(DN baseDN) throws LdapException;
172
173    /**
174     * Registers an event listener with this data provider.
175     *
176     * @param listener
177     *            The event listener.
178     */
179    void registerEventListener(DataProviderEventListener listener);
180
181    /**
182     * Starts this data provider so that it is ready to process client requests.
183     * This method is called immediately before the first data provider
184     * connection is opened.
185     * <p>
186     * Implementations must acquire any remaining resources in order to make
187     * this data provider fully operational. This may include any of the
188     * following:
189     * <ul>
190     * <li>connections to other data providers
191     * <li>connections to remote databases
192     * <li>connections to remote servers
193     * <li>opening local databases and files
194     * <li>pre-loading databases.
195     * </ul>
196     * Implementations must perform all required work synchronously such that,
197     * on return, this data provider is fully operational.
198     */
199    void startDataProvider();
200
201    /**
202     * Performs any necessary work to stop this data provider. This includes
203     * closing any connections to underlying data providers, databases, etc.
204     * <p>
205     * This method is called immediately after the last data provider connection
206     * is closed. It must not return until this data provider is stopped.
207     * <p>
208     * Implementations must release all resources acquired when this data
209     * provider was started. This includes:
210     * <ul>
211     * <li>connections to other data providers
212     * <li>connections to remote databases
213     * <li>connections to remote servers
214     * <li>closing local databases and files.
215     * </ul>
216     * Implementations must not deregister this data provider or any associated
217     * listeners such as those required for performing import, export, backup,
218     * and restore.
219     * <p>
220     * Implementations must not throw any exceptions. If any problems are
221     * encountered, then they may be logged but the shutdown should progress as
222     * completely as possible.
223     */
224    void stopDataProvider();
225
226    /**
227     * Indicates whether the provided base DN in this data provider
228     * supports change notification.
229     *
230     * @param baseDN
231     *            The base DN in this data provider.
232     * @return {@code true} if the provided base DN in this data provider
233     *         supports change notification.
234     * @throws LdapException
235     *             If {@code baseDN} is not one of the base DNs managed by this
236     *             data provider.
237     */
238    boolean supportsChangeNotification(DN baseDN) throws LdapException;
239
240}