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    
029    
030    
031    import org.opends.server.config.ConfigEntry;
032    import org.opends.server.config.ConfigException;
033    import org.opends.server.types.DirectoryException;
034    import org.opends.server.types.DN;
035    import org.opends.server.types.InitializationException;
036    
037    
038    /**
039     * This class defines the set of methods and structures that must be
040     * implemented by a Directory Server configuration handler.
041     */
042    @org.opends.server.types.PublicAPI(
043         stability=org.opends.server.types.StabilityLevel.VOLATILE,
044         mayInstantiate=false,
045         mayExtend=true,
046         mayInvoke=true)
047    public abstract class ConfigHandler
048           extends Backend
049    {
050      /**
051       * Bootstraps this configuration handler using the information in
052       * the provided configuration file.  Depending on this configuration
053       * handler implementation, the provided file may contain either the
054       * entire server configuration or information that is needed to
055       * access the configuration in some other location or repository.
056       *
057       * @param  configFile   The path to the file to use to initialize
058       *                      this configuration handler.
059       * @param  checkSchema  Indicates whether to perform schema checking
060       *                      on the configuration data.
061       *
062       * @throws  InitializationException  If a problem occurs while
063       *                                   attempting to initialize this
064       *                                   configuration handler.
065       */
066      public abstract void initializeConfigHandler(String configFile,
067                                                   boolean checkSchema)
068             throws InitializationException;
069    
070    
071    
072      /**
073       * Finalizes this configuration handler so that it will release any
074       * resources associated with it so that it will no longer be used.
075       * This will be called when the Directory Server is shutting down,
076       * as well as in the startup process once the schema has been read
077       * so that the configuration can be re-read using the updated
078       * schema.
079       */
080      public abstract void finalizeConfigHandler();
081    
082    
083    
084      /**
085       * Retrieves the entry that is at the root of the Directory Server
086       * configuration.
087       *
088       * @return  The entry that is at the root of the Directory Server
089       *          configuration.
090       *
091       * @throws  ConfigException  If a problem occurs while interacting
092       *                           with the configuration.
093       */
094      public abstract ConfigEntry getConfigRootEntry()
095             throws ConfigException;
096    
097    
098    
099      /**
100       * Retrieves the requested entry from the configuration.
101       *
102       * @param  entryDN  The distinguished name of the configuration
103       *                  entry to retrieve.
104       *
105       * @return  The requested configuration entry.
106       *
107       * @throws  ConfigException  If a problem occurs while interacting
108       *                           with the configuration.
109       */
110      public abstract ConfigEntry getConfigEntry(DN entryDN)
111             throws ConfigException;
112    
113    
114    
115      /**
116       * Retrieves the absolute path of the Directory Server instance
117       * root.
118       *
119       * @return  The absolute path of the Directory Server instance root.
120       */
121      public abstract String getServerRoot();
122    
123    
124    
125      /**
126       * Writes an updated version of the Directory Server configuration
127       * to the repository.  This should ensure that the stored
128       * configuration matches the pending configuration.
129       *
130       * @throws  DirectoryException  If a problem is encountered while
131       *                              writing the updated configuration.
132       */
133      public abstract void writeUpdatedConfig()
134             throws DirectoryException;
135    
136    
137    
138      /**
139       * Indicates that the Directory Server has started successfully and
140       * that the configuration handler should save a copy of the current
141       * configuration for use as a "last known good" reference.  Note
142       * that this may not be possible with some kinds of configuration
143       * repositories, so it should be a best effort attempt.
144       * <BR><BR>
145       * This method should only be called by the Directory Server itself
146       * when the server has started successfully.  It should not be
147       * invoked by any other component at any other time.
148       */
149      @org.opends.server.types.PublicAPI(
150           stability=org.opends.server.types.StabilityLevel.VOLATILE,
151           mayInstantiate=false,
152           mayExtend=true,
153           mayInvoke=false)
154      public abstract void writeSuccessfulStartupConfig();
155    }
156