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}