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 2006-2009 Sun Microsystems, Inc. 015 * Portions Copyright 2013-2016 ForgeRock AS. 016 */ 017package org.opends.server.api; 018 019import java.util.Collections; 020import java.util.List; 021import java.util.Set; 022 023import org.forgerock.i18n.LocalizableMessage; 024import org.forgerock.opendj.server.config.server.ExtendedOperationHandlerCfg; 025import org.forgerock.opendj.config.server.ConfigException; 026import org.opends.server.core.DirectoryServer; 027import org.opends.server.core.ExtendedOperation; 028import org.opends.server.types.InitializationException; 029 030/** 031 * This class defines the set of methods and structures that must be 032 * implemented by a Directory Server module that implements the 033 * functionality required for one or more types of extended 034 * operations. 035 * 036 * @param <T> The configuration class that will be provided to 037 * initialize the handler. 038 */ 039@org.opends.server.types.PublicAPI( 040 stability=org.opends.server.types.StabilityLevel.VOLATILE, 041 mayInstantiate=false, 042 mayExtend=true, 043 mayInvoke=false) 044public abstract class 045 ExtendedOperationHandler<T extends ExtendedOperationHandlerCfg> 046{ 047 048 /** The default set of supported control OIDs for this extended op. */ 049 private final Set<String> supportedControlOIDs; 050 051 /** The default set of supported feature OIDs for this extended op. */ 052 private final Set<String> supportedFeatureOIDs = Collections.emptySet(); 053 054 /** 055 * Builds an extended operation. 056 */ 057 public ExtendedOperationHandler() 058 { 059 this.supportedControlOIDs = Collections.<String> emptySet(); 060 } 061 062 /** 063 * Builds an extended operation. 064 * 065 * @param supportedControlOIDs 066 * the default set of supported control OIDs for this extended op 067 */ 068 public ExtendedOperationHandler(Set<String> supportedControlOIDs) 069 { 070 this.supportedControlOIDs = supportedControlOIDs != null ? 071 Collections.unmodifiableSet(supportedControlOIDs) 072 : Collections.<String> emptySet(); 073 } 074 075 /** 076 * Initializes this extended operation handler based on the 077 * information in the provided configuration entry. It should also 078 * register itself with the Directory Server for the particular 079 * kinds of extended operations that it will process. 080 * 081 * @param config The extended operation handler configuration that 082 * contains the information to use to initialize 083 * this extended operation handler. 084 * 085 * @throws ConfigException If an unrecoverable problem arises in 086 * the process of performing the 087 * initialization. 088 * 089 * @throws InitializationException If a problem occurs 090 * during initialization that is 091 * not related to the server 092 * configuration. 093 */ 094 public void initializeExtendedOperationHandler(T config) 095 throws ConfigException, InitializationException 096 { 097 DirectoryServer.registerSupportedExtension(getExtendedOperationOID(), this); 098 registerControlsAndFeatures(); 099 } 100 101 102 103 /** 104 * Indicates whether the provided configuration is acceptable for 105 * this extended operation handler. It should be possible to call 106 * this method on an uninitialized extended operation handler 107 * instance in order to determine whether the extended operation 108 * handler would be able to use the provided configuration. 109 * <BR><BR> 110 * Note that implementations which use a subclass of the provided 111 * configuration class will likely need to cast the configuration 112 * to the appropriate subclass type. 113 * 114 * @param configuration The extended operation handler 115 * configuration for which to make the 116 * determination. 117 * @param unacceptableReasons A list that may be used to hold the 118 * reasons that the provided 119 * configuration is not acceptable. 120 * 121 * @return {@code true} if the provided configuration is acceptable 122 * for this extended operation handler, or {@code false} if 123 * not. 124 */ 125 public boolean isConfigurationAcceptable( 126 ExtendedOperationHandlerCfg configuration, 127 List<LocalizableMessage> unacceptableReasons) 128 { 129 // This default implementation does not perform any special 130 // validation. It should be overridden by extended operation 131 // handler implementations that wish to perform more detailed 132 // validation. 133 return true; 134 } 135 136 137 138 /** 139 * Performs any finalization that may be necessary for this extended 140 * operation handler. By default, no finalization is performed. 141 */ 142 public void finalizeExtendedOperationHandler() 143 { 144 DirectoryServer.deregisterSupportedExtension(getExtendedOperationOID()); 145 deregisterControlsAndFeatures(); 146 } 147 148 149 150 /** 151 * Processes the provided extended operation. 152 * 153 * @param operation The extended operation to be processed. 154 */ 155 public abstract void processExtendedOperation(ExtendedOperation 156 operation); 157 158 159 160 /** 161 * Retrieves the OIDs of the controls that may be supported by this 162 * extended operation handler. It should be overridden by any 163 * extended operation handler which provides special support for one 164 * or more controls. 165 * 166 * @return The OIDs of the controls that may be supported by this 167 * extended operation handler. 168 */ 169 public Set<String> getSupportedControls() 170 { 171 return supportedControlOIDs; 172 } 173 174 175 176 /** 177 * Indicates whether this extended operation handler supports the 178 * specified control. 179 * 180 * @param controlOID The OID of the control for which to make the 181 * determination. 182 * 183 * @return {@code true} if this extended operation handler does 184 * support the requested control, or {@code false} if not. 185 */ 186 public final boolean supportsControl(String controlOID) 187 { 188 return getSupportedControls().contains(controlOID); 189 } 190 191 192 193 /** 194 * Retrieves the OIDs of the features that may be supported by this 195 * extended operation handler. 196 * 197 * @return The OIDs of the features that may be supported by this 198 * extended operation handler. 199 */ 200 public Set<String> getSupportedFeatures() 201 { 202 return supportedFeatureOIDs; 203 } 204 205 206 207 /** 208 * Indicates whether this extended operation handler supports the 209 * specified feature. 210 * 211 * @param featureOID The OID of the feature for which to make the 212 * determination. 213 * 214 * @return {@code true} if this extended operation handler does 215 * support the requested feature, or {@code false} if not. 216 */ 217 public final boolean supportsFeature(String featureOID) 218 { 219 return getSupportedFeatures().contains(featureOID); 220 } 221 222 223 224 /** 225 * If the extended operation handler defines any supported controls 226 * and/or features, then register them with the server. 227 */ 228 private void registerControlsAndFeatures() 229 { 230 Set<String> controlOIDs = getSupportedControls(); 231 if (controlOIDs != null) 232 { 233 for (String oid : controlOIDs) 234 { 235 DirectoryServer.registerSupportedControl(oid); 236 } 237 } 238 239 Set<String> featureOIDs = getSupportedFeatures(); 240 if (featureOIDs != null) 241 { 242 for (String oid : featureOIDs) 243 { 244 DirectoryServer.registerSupportedFeature(oid); 245 } 246 } 247 } 248 249 250 251 /** 252 * If the extended operation handler defines any supported controls 253 * and/or features, then deregister them with the server. 254 */ 255 private void deregisterControlsAndFeatures() 256 { 257 Set<String> controlOIDs = getSupportedControls(); 258 if (controlOIDs != null) 259 { 260 for (String oid : controlOIDs) 261 { 262 DirectoryServer.deregisterSupportedControl(oid); 263 } 264 } 265 266 Set<String> featureOIDs = getSupportedFeatures(); 267 if (featureOIDs != null) 268 { 269 for (String oid : featureOIDs) 270 { 271 DirectoryServer.deregisterSupportedFeature(oid); 272 } 273 } 274 } 275 276 /** 277 * Retrieves the name associated with this extended operation. 278 * 279 * @return The name associated with this extended operation, 280 * if any, or <CODE>null</CODE> if there is none. 281 */ 282 public String getExtendedOperationName() 283 { 284 return null; 285 } 286 287 /** 288 * Retrieves the object OID associated with this extended operation. 289 * 290 * @return the oid associated with this extended operation, if any, or 291 * <CODE>null</CODE> if there is none. 292 */ 293 public String getExtendedOperationOID() 294 { 295 return null; 296 } 297} 298