Apache Hop
Download
Development Documentation 2.20.0

User manual

Edit this page

Configuration Plugins

A @ConfigPlugin adds extra command-line options to an existing Hop tool (such as hop run, hop conf, or hop search) via picocli mixins. Additionally, when combined with @GuiPlugin annotations, the same configuration plugin automatically renders as a settings tab in the Hop GUI Options dialog.

Implementing a Configuration Plugin

Annotate the class with @ConfigPlugin and implement IConfigOptions:

java
import org.apache.hop.core.config.plugin.ConfigPlugin;
import org.apache.hop.core.config.plugin.IConfigOptions;
import org.apache.hop.core.gui.plugin.GuiPlugin;
import org.apache.hop.core.gui.plugin.GuiWidgetElement;
import org.apache.hop.core.gui.plugin.GuiElementType;
import org.apache.hop.core.exception.HopException;
import org.apache.hop.core.logging.ILogChannel;
import org.apache.hop.core.variables.IVariables;
import org.apache.hop.metadata.api.IHasHopMetadataProvider;
import picocli.CommandLine.Option;

@ConfigPlugin(
    id = "CustomRunOption",
    description = "Adds notification webhook flag to hop run",
    category = ConfigPlugin.CATEGORY_RUN // Tool targeting: CATEGORY_RUN, CATEGORY_CONFIG, etc.
)
@GuiPlugin(
    id = "CustomRunOptionGui",
    description = "Custom Run Preferences"
)
public class CustomRunConfigPlugin implements IConfigOptions {

  private static CustomRunConfigPlugin instance;

  @Option(
      names = {"-w", "--webhook"},
      description = "Webhook URL to notify upon execution finish"
  )
  @GuiWidgetElement(
      id = "webhook_url",
      order = "0100",
      type = GuiElementType.TEXT,
      label = "Default Webhook Notification URL",
      parentId = "CustomRunOptionGui"
  )
  private String webhookUrl;

  public static CustomRunConfigPlugin getInstance() {
    if (instance == null) {
      instance = new CustomRunConfigPlugin();
    }
    return instance;
  }

  @Override
  public boolean handleOption(
      ILogChannel log, IHasHopMetadataProvider metadataProvider, IVariables variables)
      throws HopException {
    if (webhookUrl != null) {
      log.logBasic("Configured execution notification webhook: " + webhookUrl);
      // Return true if handled completely, or false to proceed with standard tool execution
    }
    return false;
  }
}

Key Architectural Attributes

  • category: Determines which command mixes in the plugin:

  • CATEGORY_RUN: hop run

  • CATEGORY_CONFIG: hop conf

  • CATEGORY_SEARCH: hop search

  • CATEGORY_SERVER: hop server

  • CATEGORY_IMPORT: hop import

  • CATEGORY_EXPORT: hop export

  • Dual CLI and GUI Role: By adding @GuiPlugin and @GuiWidgetElement to the same class along with a static getInstance() method, Hop GUI automatically creates a tab in the Options dialog.

Concrete Codebase Examples

  • plugins/misc/projects/src/main/java/org/apache/hop/projects/project/ManageProjectsOptionPlugin.java: Command-line project create and edit options, including -p.

  • ui/src/main/java/org/apache/hop/ui/hopgui/search/config/SearchConfigPlugin.java: Adds search configuration options to the CLI and the GUI settings dialog.

See also