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