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 * A connection to a data provider. When a connection is no longer needed it
028 * must be closed.
029 */
030public interface DataProviderConnection extends RequestHandler<Operation> {
031
032    /**
033     * Closes this data provider connection. When this method returns the
034     * connection can no longer be used.
035     */
036    void close();
037
038    /**
039     * Indicates whether the underlying data provider contains the specified
040     * entry.
041     *
042     * @param dn
043     *            The DN of the entry.
044     * @return {@code true} if the underlying data provider contains the
045     *         specified entry, or {@code false} if it does not.
046     * @throws LdapException
047     *             If a problem occurs while trying to make the determination,
048     *             or if {@code dn} is not a DN equal to or subordinate to one
049     *             of the base DNs managed by the underlying data provider.
050     */
051    boolean containsEntry(DN dn) throws LdapException;
052
053    /**
054     * Deregisters an event listener from the underlying data provider.
055     *
056     * @param listener
057     *            The event listener.
058     */
059    void deregisterEventListener(DataProviderEventListener listener);
060
061    /**
062     * Returns an unmodifiable set containing the base DNs of the sub-trees
063     * which the underlying data provider contains.
064     *
065     * @return An unmodifiable set containing the base DNs of the sub-trees
066     *         which the underlying data provider contains.
067     */
068    Set<DN> getBaseDNs();
069
070    /**
071     * Retrieves the specified entry from the underlying data provider.
072     *
073     * @param dn
074     *            The DN of the entry.
075     * @return The requested entry, or {@code null} if the underlying data
076     *         provider does not contain the specified entry.
077     * @throws LdapException
078     *             If a problem occurs while trying to retrieve the entry, or if
079     *             {@code dn} is not a DN equal to or subordinate to one of the
080     *             base DNs managed by the underlying data provider.
081     */
082    Entry getEntry(DN dn) throws LdapException;
083
084    /**
085     * Returns the current status of the provided base DN in the underlying data
086     * provider.
087     *
088     * @param baseDN
089     *            The base DN in the underlying data provider.
090     * @return The current status of the provided base DN in the underlying data
091     *         provider.
092     * @throws LdapException
093     *             If {@code baseDN} is not one of the base DNs managed by the
094     *             underlying data provider.
095     */
096    DataProviderStatus getStatus(DN baseDN) throws LdapException;
097
098    /**
099     * Returns an unmodifiable set containing the OIDs of the controls that may
100     * be supported by the provided base DN in the underlying data provider.
101     *
102     * @param baseDN
103     *            The base DN in the underlying data provider.
104     * @return An unmodifiable set containing the OIDs of the controls that may
105     *         be supported by the provided base DN in the underlying data
106     *         provider.
107     * @throws LdapException
108     *             If {@code baseDN} is not one of the base DNs managed by the
109     *             underlying data provider.
110     */
111    Set<String> getSupportedControls(DN baseDN) throws LdapException;
112
113    /**
114     * Returns an unmodifiable set containing the OIDs of the features that may
115     * be supported by the provided base DN in the underlying data provider.
116     *
117     * @param baseDN
118     *            The base DN in the underlying data provider.
119     * @return An unmodifiable set containing the OIDs of the features that may
120     *         be supported by the provided base DN in the underlying data
121     *         provider.
122     * @throws LdapException
123     *             If {@code baseDN} is not one of the base DNs managed by the
124     *             underlying data provider.
125     */
126    Set<String> getSupportedFeatures(DN baseDN) throws LdapException;
127
128    /**
129     * Registers an event listener with the underlying data provider.
130     *
131     * @param listener
132     *            The event listener.
133     */
134    void registerEventListener(DataProviderEventListener listener);
135
136    /**
137     * Indicates whether the provided base DN in the underlying data
138     * provider supports change notification.
139     *
140     * @param baseDN
141     *            The base DN in the underlying data provider.
142     * @return {@code true} if the provided base DN in the underlying data
143     *         provider supports change notification.
144     * @throws LdapException
145     *             If {@code baseDN} is not one of the base DNs managed by the
146     *             underlying data provider.
147     */
148    boolean supportsChangeNotification(DN baseDN) throws LdapException;
149}