Apache Hop
Download
Development Documentation 2.20.0

User manual

Edit this page

Hop Plugin Development Guide

Apache Hop is architected around an extensible plugin ecosystem. Nearly every functional capability in Hop is a plugin: the transforms that process rows, the actions in workflows, the databases Hop connects to, the metadata objects edited in the GUI, the GUI perspectives, the CLI sub-commands, and the storage systems accessed via VFS.

This guide provides practical, step-by-step instructions for implementing Hop plugins across 15 primary plugin types, with direct references to real-world implementations in the Apache Hop repository.

How Hop Discovers Plugins

Hop uses annotation-driven discovery powered by Jandex annotation indexes (META-INF/jandex.idx):

  1. Native Classpath Plugins: Discovered from jars on the application classpath containing a Jandex index. Core plugins in hop-core, hop-engine, and hop-ui are loaded this way.

  2. Plugin Folder Plugins: Discovered from jars inside the plugins/ directory (or custom folders configured via HOP_PLUGIN_BASE_FOLDERS). Each plugin folder receives its own isolated URLClassLoader covering the plugin jar and its private lib/ directory.

No Jandex index = No plugin. Every plugin jar must contain META-INF/jandex.idx. The root Hop POM binds the jandex-maven-plugin automatically for all modules in the repository. If you develop a plugin outside the Hop repository, you must configure the Jandex plugin in your pom.xml.

Classloading and classLoaderGroup

To avoid classpath conflicts, external plugins run in isolated classloaders. However, related plugins often need to share classes (for example, a database dialect and its corresponding bulk-loader transform, or a VFS plugin and its metadata connection).

Set classLoaderGroup on the plugin annotation to group plugins into a shared classloader:

java
@VfsPlugin(
    type = "azure",
    typeDescription = "Azure VFS",
    classLoaderGroup = "vfs-azure"
)

Project Structure & Packaging

In the Hop codebase, plugins are organized under plugins/ by category:

  • plugins/transforms: Pipeline transforms

  • plugins/actions: Workflow actions

  • plugins/databases: Database dialects

  • plugins/tech: Technology bundles (AWS, Azure, Google, Neo4j, and the VFS providers)

  • plugins/valuetypes: Custom row data types

  • plugins/resolvers: Variable resolvers

  • plugins/misc: Miscellaneous plugins

Adding a plugin requires: 1. Creating a Maven module inheriting from the category POM (e.g. hop-plugins-transforms). 2. Adding src/assembly/assembly.xml referring to assemblies/shared/hop-plugin-libs.xml. 3. Adding src/main/resources/version.xml with ${project.version}. 4. Adding a <dependency> with <type>zip</type> in assemblies/plugins/pom.xml.

Plugin Types Catalogue

Explore the dedicated development guides below for each plugin type:

Plugin Type Annotation Guide & Overview

Transform

@Transform

Transform Plugins — Units of work in pipelines streaming rows.

Action

@Action

Action Plugins — Sequential and conditional tasks in workflows.

Metadata Element

@HopMetadata

Metadata Element Plugins — Shared configurations persisted as JSON.

Database Dialect

@DatabaseMetaPlugin

Database Plugins — Relational database dialects and SQL syntax.

GUI Contribution

@GuiPlugin

GUI Plugins — Toolbars, menus, settings tabs, and composite widgets.

File Type

@HopFileTypePlugin

Hop File Types — File formats recognised and opened by Hop GUI.

Variable Resolver

@VariableResolverPlugin

Variable Resolvers — Retrieving secrets from external vaults.

Extension Point

@ExtensionPoint

Extension Points — Hooking into runtime and GUI lifecycles.

Hop Command

@HopCommand

Hop Commands — New CLI sub-commands (hop <subcommand>).

Configuration

@ConfigPlugin

Configuration Plugins — CLI option mixins and GUI options tabs.

Perspective

@HopPerspectivePlugin

Perspectives — Full-screen workbenches in Hop GUI.

VFS Provider

@VfsPlugin

VFS Plugins — Storage URL schemes for Apache Commons VFS.

Value Metadata

@ValueMetaPlugin

Value Types — Custom data types in the pipeline row stream.

Hop Server Servlet

@HopServerServlet

Server Servlets — Custom HTTP endpoints on Hop Server.

Execution Info Location

@ExecutionInfoLocationPlugin

Execution Information Locations — Storing runtime metrics and logs.

See also