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}