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