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