UnboundID Server SDK

ExampleManageExtensionPlugin.java

/*
 * CDDL HEADER START
 *
 * The contents of this file are subject to the terms of the
 * Common Development and Distribution License, Version 1.0 only
 * (the "License").  You may not use this file except in compliance
 * with the License.
 *
 * You can obtain a copy of the license at
 * docs/licenses/cddl.txt
 * or http://www.opensource.org/licenses/cddl1.php.
 * See the License for the specific language governing permissions
 * and limitations under the License.
 *
 * When distributing Covered Code, include this CDDL HEADER in each
 * file and include the License file at
 * docs/licenses/cddl.txt.  If applicable,
 * add the following below this CDDL HEADER, with the fields enclosed
 * by brackets "[]" replaced with your own identifying information:
 *      Portions Copyright [yyyy] [name of copyright owner]
 *
 * CDDL HEADER END
 *
 *
 *      Portions Copyright 2011-2024 Ping Identity Corporation
 */
package com.unboundid.directory.sdk.examples;

import com.unboundid.directory.sdk.common.api.ManageExtensionPlugin;
import com.unboundid.directory.sdk.common.types.PostManageExtensionPluginResult;
import com.unboundid.directory.sdk.common.types.PreManageExtensionPluginResult;
import com.unboundid.directory.sdk.common.types.UpdateExtensionDetails;

import java.io.File;
import java.util.Collections;

/**
 * This class provides a simple example of manage extension plugin that will
 * abort an update if the installed version is known to be incompatible. It will
 * also display a warning message prompting the user to finish the update
 * manually by migrating custom configuration changes.
 */
public class ExampleManageExtensionPlugin
    extends ManageExtensionPlugin
{

  // Whether a config file is found that will need migration.
  private boolean configFileFound;

  /**
   * Retrieves a human-readable description for this extension.  Each element
   * of the array that is returned will be considered a separate paragraph in
   * generated documentation.
   *
   * @return  A human-readable description for this extension, or {@code null}
   *          or an empty array if no description should be available.
   */
  public String[] getExtensionDescription() {
    return new String[]
    {
        "This manage extension plugin serves an example that may be used to " +
        "demonstrate the process for creating a third-party manage " +
        "extension plugin. It will abort an update if the installed " +
        "version is known to be incompatible. It will also display a " +
        "warning message prompting the user to finish the update manually " +
        "by migrating custom configuration changes."
    };
  }

  /**
   * Retrieves a human-readable name for this extension.
   *
   * @return  A human-readable name for this extension.
   */
  public String getExtensionName() {
    return "Example Manage Extension Plugin";
  }

  /**
   * Invoked when an extension is updated after all files are update to the
   * server installation but before restarting the server.
   *
   * @param details The state of the update after all files are updated.
   * @return Whether the server should be restarted after the update if
   *                 previous started.
   */
  @Override
  public PostManageExtensionPluginResult postUpdate(
      final UpdateExtensionDetails details) {
    if(configFileFound)
    {
      // This demonstrates a "flag day" use case of an manage extension plugin
      // where manual action is needed by the end user after the update before
      // the server may be restarted.
      return new PostManageExtensionPluginResult(false,
          Collections.singletonList(
              "Version " + details.getExtensionBundle().getVersion() +
                  "introduced changes to the configuration that needs to " +
                  "be migrated manually before starting the server. Please " +
                  "refer to the documentation " +
                  details.getInstalledExtensionBundle().getDocumentationDir() +
                  " for more details"));
    }
    return PostManageExtensionPluginResult.SUCCESS;
  }

  /**
   * Invoked when an extension is updated before shutting down the server and
   * any files are updated to the server installation.
   *
   * @param details The state of the update before any files are updated.
   * @return Whether to continue the update process.
   */
  @Override
  public PreManageExtensionPluginResult preUpdate(
      final UpdateExtensionDetails details) {
    String installedVersion =
        details.getInstalledExtensionBundle().getVersion();
    if(installedVersion.equals("1.2"))
    {
      // This demonstrates a "flag day" use case of an manage extension plugin.
      return new PreManageExtensionPluginResult(false,
          Collections.singletonList("Version 1.2 may not be updated due to " +
              "known incompatibilities"));
    }
    else if(installedVersion.equals("1.3"))
    {
      File configFile = new File(
          details.getInstalledExtensionBundle().getConfigDir(),
          "resources.xml");
      configFileFound = configFile.exists();
    }

    return PreManageExtensionPluginResult.SUCCESS;
  }
}