Skip to content

Jafly. Plugin API

Plugin API

Define plugins, extension points, extension registration, and lifecycle contracts without the host implementation.

Implement Plugin and the host extension interfaces; describe the plugin with the model/annotation contracts. Hosts use PluginManager to load, start, stop, and unload plugins and ExtensionRegistry to locate contributed extensions.

Maven artifact Packaging Source project
org.fireflyframework:plugin-api jar modules/plugins/plugin-api

Part of Team-wide architecture.

In the onboarding service

Define a host extension contract for an onboarding check and implement it in an application plugin. Stable plugin IDs identify lifecycle/dependency relationships; they are separate from applicant IDs.

Add the component

Installation and version availability explains source builds and published releases.

<dependency>
    <groupId>org.fireflyframework</groupId>
    <artifactId>plugin-api</artifactId>
    <version>26.10.20-SNAPSHOT</version>
</dependency>

Quick start

The Java examples in this section are API fragments for application code. Use the stated imports and supply the application-owned collaborators described alongside them.

Plugin authors implement org.fireflyframework.plugin.api.Plugin; the annotation with the same simple name lives in org.fireflyframework.plugin.annotation. Hosts operate the API through PluginManager:

PluginDescriptor descriptor = manager.loadPlugin(MyPlugin.class);
manager.startPlugin(descriptor.getId());
// Use the host's registered extension points while the plugin is started.
manager.stopPlugin(descriptor.getId());
manager.unloadPlugin(descriptor.getId());

MyPlugin is the application plugin implementation, not a framework class. The host extension interfaces and registration contract are described in the plugin platform guide. Keep plugin metadata IDs stable because the manager uses them for lifecycle and dependency resolution.

Configuration and wiring

This module declares no @ConfigurationProperties class of its own. Use the constructor/port contracts above and the configuration of the host or related core module.

Public API and extension points

Type Contract and responsibility
Plugin Defines a plugin lifecycle and its metadata; the annotation with the same simple name labels plugin classes.
PluginManager Main interface for managing plugins.
ExtensionRegistry Registry for managing extension points and their implementations.
PluginDescriptor Complete descriptor of a plugin including its metadata and current state.
PluginMetadata Metadata information about a plugin.
Related component Why it belongs nearby
Common Plugins Group the API and implementation of the framework plugin system.
Kernel Share a consistent exception vocabulary across application, domain, and infrastructure boundaries.

Build and test

Use Java 25. From the repository root, build this component with its required dependencies:

git clone https://github.com/fireflyframework/fireflyframework-jafly.git
cd fireflyframework-jafly
./mvnw -pl :plugin-api -am verify
./mvnw -pl :plugin-api -am install

verify runs the selected projects' tests. install makes the current build available in your local Maven repository.

Representative test sources:

Test fixture

The shouldProvideConvenienceMethodsForMetadata test demonstrates one concrete behavior. Excerpt from PluginDescriptorTest.java. The test class supplies its fixtures and imports.

@Test
void shouldProvideConvenienceMethodsForMetadata() {
    PluginMetadata metadata = PluginMetadata.builder()
        .id("test-plugin")
        .name("Test Plugin")
        .version("2.0.0")
        .build();

    PluginDescriptor descriptor = PluginDescriptor.builder()
        .metadata(metadata)
        .state(PluginState.STARTED)
        .build();

    assertEquals("test-plugin", descriptor.getId());
    assertEquals("Test Plugin", descriptor.getName());
    assertEquals("2.0.0", descriptor.getVersion());
}

Continue the application

Use the Plugin Core guide for the next part of this integration. The runnable submission/query service is in Getting started.

Source and further reading