Eclipse Plugin Developer Guide

Plugins let you extend Eclipse platform behaviour at runtime without modifying platform source code. A plugin is a plain JAR uploaded through the Plugin API. The platform hot-loads it, wires CDI injection into it, and calls its handler methods when the relevant events occur.

There are three broad categories of plugin:

1. Core Annotations

@PluginDescriptor (required, class-level)

Every plugin JAR must contain exactly one class annotated with @PluginDescriptor. This is how the platform identifies and names the plugin.

@PluginDescriptor(
    name        = "my-plugin",          // unique plugin name (required)
    version     = "1.0",                // version string (optional, default "1.0")
    description = "Does something useful" // human-readable description (optional)
)
public class MyPluginInfo { }

The name field must be unique across all loaded plugins. Uploading a JAR with an existing name is treated as an upgrade.

@OnNamedInjectionPoint (method-level)

Marks a method as a handler for a named platform event.

@OnNamedInjectionPoint(
    injectionPoint = "wallet.postWalletTransfer",  // event name (required)
    priority       = 10                             // higher = runs first (optional, default 0)
)
public void afterTransfer(@Named("from") IWallet from, @Named("to") IWallet to) { ... }

The framework resolves method parameters by type or by name (see section 3). Multiple methods in the same plugin, or across multiple plugins, can handle the same injection point. They run in descending priority order.

2. Plugin Lifecycle and Management

Uploading a plugin

Plugins are managed via the Plugin REST API. To deploy a plugin:

POST /eclipse-conductor/rest/v1/plugins
Content-Type: multipart/form-data

jar=<jarBytes>   (required)
status=ON|OFF    (optional, defaults to OFF)
isGlobal=true    (optional, applies to all tenants)
tenantIds=1,2,3  (optional, specific tenants)

On first upload the platform scans the JAR, discovers all @OnNamedInjectionPoint methods, and auto-populates a config JSON:

{
  "injectionPoints": {
    "com.example.MyPlugin#afterTransfer": true,
    "com.example.MyPlugin#onWalletCreate": true
  }
}

Each key is ClassName#methodName. Set the value to false to disable a specific handler without disabling the whole plugin.

Plugin status

PUT /eclipse-conductor/rest/v1/plugins/{pluginId}/status
Body: "ON"

Updating a plugin

Re-upload a JAR with the same @PluginDescriptor name. The platform merges the existing config with the new JAR's injection points — handlers that no longer exist in the new JAR are automatically removed from the config; new handlers are added with enabled: true; existing handlers keep their current enabled state.

PUT /eclipse-conductor/rest/v1/plugins/{pluginId}
Body: { "jar": "<base64>" }

Tenant mapping

A plugin can be global (runs for all tenants) or restricted to specific tenant IDs:

PUT /eclipse-conductor/rest/v1/plugins/{pluginId}/mappings
Body: { "global": false, "mappings": { "tenantIds": [42, 99] } }

3. Injection-Point Plugins

Writing a handler

@PluginDescriptor(name = "transfer-audit", version = "1.0")
@Singleton
public class TransferAuditPlugin {

    @OnNamedInjectionPoint(injectionPoint = "wallet.postWalletTransfer", priority = 5)
    public void auditTransfer(
            @Named("from")    IWallet from,
            @Named("to")      IWallet to,
            @Named("history") List<WalletHistory> history) {

        // 'from' and 'to' are the same IWallet type, so @Named is required to distinguish them
        log.info("Transfer: {} → {} ({} entries)", from.getWalletId(), to.getWalletId(), history.size());
    }
}

CDI injection in plugins

Classes annotated with @Singleton, @ApplicationScoped, @RequestScoped, or @Dependent get CDI wiring. The platform injects the following services automatically:

Add them a method parameters to receive them:

@Singleton
public class MyPlugin {

    
    @OnNamedInjectionPoint(injectionPoint = "domainEvent")
    public void onEvent(DomainEvent event, RequestContext ctx, EntityManager em) {
        log.info("Tenant {} fired event {}", ctx.getTenantId(), event);
    }
}

Parameter resolution rules

The framework resolves each method parameter in this order:

1. If the parameter is annotated with @Named("x"), it looks for a NamedParam whose name matches "x" in the ctx varargs passed to fireInjectionPoint.
2. Otherwise it resolves by type — exact match first, then assignability, then the global CDI context.

When the same type appears more than once at an injection point all such arguments are wrapped in NamedParam by the platform. Your method must use @Named to tell the framework which one you want, otherwise it throws.

// Correct — two IWallet args must use @Named
public void handle(@Named("from") IWallet from, @Named("to") IWallet to) { ... }

// Wrong — ambiguous, will throw at runtime
public void handle(IWallet from, IWallet to) { ... }

Return values

If a handler returns a non-null value, it is collected by the caller. fireInjectionPoint returns a List<Object> of all non-null return values from all handlers, in priority order. The platform uses this for injection points like convertCurrency and sendTextSms where a plugin is expected to produce a result.

4. All Supported Injection Points

Wallet events

Exchange rate

If a plugin returns an ExchangeRate, the platform uses it. If no plugin handles the injection point, the built-in rate provider is used.

SMS

HTTP request / response interception

Use JaxRsUtils.replyImmediately(rq, response) inside a conductorRequest handler to short-circuit the request and return a custom response immediately.

Domain events

Exceptions and alerts

Payment events

Loan events

Remittance events

User and organisation events

Credential fields (password, secretOrKey, info) are always stripped before these events fire so that plugin code cannot read or log credentials.

Attachment events

Property events

Property is a global platform resource with no tenant concept. All property injection points fire with tenantId = null.

5. Implementation Plugins

Implementation plugins provide a complete custom implementation of a platform interface. The plugin class extends a Pluggable* base class and is registered by class name in configuration. When the platform needs an instance of that interface it calls UK.Runtime.getBean(className), which returns the plugin's CDI-managed instance.

5.1 Fraud Event Handler

Use case: Provide a custom fraud decision engine. The platform calls handle() for each fraud event and uses the returned result.

Base class: com.ukheshe.services.fraud.publish.pluggable.PluggableFraudEventPublishHandler

Interface method:

FraudEventPublishResponse handle(FraudEventPublishEvent fraudPublishEvent)

Plugin example:

@PluginDescriptor(name = "my-fraud-engine", version = "1.0")
@Singleton
public class MyFraudPlugin extends PluggableFraudEventPublishHandler {

    @Override
    public FraudEventPublishResponse handle(FraudEventPublishEvent event) {
        FraudEventPublishResponse response = new FraudEventPublishResponse();
        // Inspect event.getMessage(), event.getMessageType(), event.getTenantId() etc.
        response.setFraudResult(FraudEventPublishResult.NOT_FRAUD);
        return response;
    }
}

Configuration property:

fraud.event.handlers.<handlerType> = com.example.MyFraudPlugin

Where <handlerType> matches the handlerType field on the FraudEventPublishEvent sent by the transaction pipeline (e.g. MYENGINE).

Field mapping utilities:

FraudEventPublishHandler provides static helpers for reading tenant-specific field mappings from properties:

Map<String, String> requestFields  = FraudEventPublishHandler.getRequestConfig(event);
Map<String, String> responseFields = FraudEventPublishHandler.getResponseConfig(event);

Property key format:

fraud.event.handler.<handlerType>.field-mappings.request.<messageTypeRegex>           # global
fraud.event.handler.<handlerType>.field-mappings.request.<messageTypeRegex>.<tenantId> # tenant override

5.2 Wallet Type

Use case: Provide a custom wallet type with overridden balance calculation, custom charging logic, or bespoke limit behaviour. The platform instantiates one wallet object per wallet access.

Base class: com.ukheshe.services.wallet.pluggable.PluggableWallet

Key base class method:

protected void setSuperClass(BiDirectionalDelegatingWallet superclass)

Call setSuperClass in @PostConstruct, passing an injected BiDirectionalDelegatingLimitCheckingWallet. This wires the bidirectional delegation that makes super.* calls work correctly through managed CDI beans (see note below).

Plugin example:

@PluginDescriptor(name = "high-balance-wallet", version = "1.0")
@Dependent
public class HighBalanceWallet extends PluggableWallet {

    @PostConstruct
    public void init() {
        setSuperClass(UK.Runtime.getBean(BiDirectionalDelegatingLimitCheckingWallet.class));
    }

    @Override
    public BigDecimal getCurrentBalance() {
        // override — calls the real implementation via super
        return super.getCurrentBalance().add(BONUS);
    }
}

Configuration:

Set the implementationClass field on the wallet type DB record to the fully qualified class name of your plugin class (e.g. com.example.HighBalanceWallet). The WalletFactory uses this field to look up and instantiate the correct implementation for each wallet.

Why setSuperClass? Quarkus generates CDI proxy classes at build time. A plugin loaded at runtime cannot directly extend a managed bean; if it tried, calling super.method() would hit an unmanaged instance where all @Inject fields are null. PluggableWallet + BiDirectionalDelegatingLimitCheckingWallet solve this: the plugin extends the plain PluggableWallet POJO, which delegates to the managed bean via a bidirectional reference. When the managed bean calls this.method() internally, it is redirected to the plugin subclass so standard Java polymorphism works as expected.

5.3 Payment Gateway

Use case: Implement a custom payment gateway (e.g. a new card acquirer, mobile money provider, or voucher system).

Base class: com.ukheshe.services.payment.gateway.pluggable.PluggablePaymentGateway

Interface: com.ukheshe.services.payment.gateway.IPaymentGateway

Bidirectional delegate interface: com.ukheshe.services.payment.gateway.pluggable.BiDirectionalDelegatingPaymentGateway

Call setSuperClass(BiDirectionalDelegatingPaymentGateway) in @PostConstruct to wire bidirectional delegation. The concrete bean to inject is BasePaymentGateway, which implements this interface.

Key methods the plugin must implement:

Plugin example:

@PluginDescriptor(name = "my-payment-gateway", version = "1.0")
@ApplicationScoped
public class MyPaymentGateway extends PluggablePaymentGateway {

    @PostConstruct
    public void setup() {
        setSuperClass(UK.Runtime.getBean(BiDirectionalDelegatingPaymentGateway.class));
    }

    @Override
    public void initiatePayment(Object data) {
        // call external provider
    }

    @Override
    public boolean supportsReverse() { return false; }
    // ... implement remaining interface methods
}

Registration: The plugin class must be registered in the payment gateway factory. Contact the platform team to add a new gateway type string mapping to your class, or use an existing type string with a property override.

5.4 Withdrawal Gateway

Use case: Implement a custom withdrawal gateway (e.g. a new bank EFT rail, mobile wallet disbursement, or ATM network).

Base class: com.ukheshe.services.payment.gateway.pluggable.PluggableWithdrawalGateway

Interface: com.ukheshe.services.payment.gateway.IWithdrawalGateway

Bidirectional delegate interface: com.ukheshe.services.payment.gateway.pluggable.BiDirectionalDelegatingWithdrawalGateway

Call setSuperClass(BiDirectionalDelegatingWithdrawalGateway) in @PostConstruct. The concrete bean to inject is BaseWithdrawalGateway, which implements this interface.

Key methods:

Plugin example:

@PluginDescriptor(name = "my-withdrawal-gateway", version = "1.0")
@ApplicationScoped
public class MyWithdrawalGateway extends PluggableWithdrawalGateway {

    @PostConstruct
    public void setup() {
        setSuperClass(UK.Runtime.getBean(BiDirectionalDelegatingWithdrawalGateway.class));
    }

    @Override
    public void processWithdrawal() {
        DbWithdrawal wd = getDbWithdrawal();
        // call external provider
    }
    // ... implement remaining methods
}

Registration: Same as payment gateway — register the type string in the withdrawal gateway factory.

5.5 Loan Gateway

Use case: Implement a custom loan gateway to connect to an external lending provider (credit bureau, BNPL platform, or in-house loan engine).

Base class: com.ukheshe.services.loan.gateway.pluggable.PluggableLoanGateway

Interface: com.ukheshe.services.loan.gateway.ILoanGateway

Bidirectional delegate interface: com.ukheshe.services.loan.gateway.pluggable.BiDirectionalDelegatingLoanGateway

Concrete delegate bean: com.ukheshe.services.loan.gateway.pluggable.BiDirectionalDelegatingBaseLoanGateway (@Dependent )

Call setSuperClass(BiDirectionalDelegatingLoanGateway) in @PostConstruct, injecting the BiDirectionalDelegatingBaseLoanGateway bean.

Key methods:

Plugin example:

@PluginDescriptor(name = "my-loan-gateway", version = "1.0")
@ApplicationScoped
public class MyLoanGateway extends PluggableLoanGateway {

    @Inject BiDirectionalDelegatingBaseLoanGateway baseGateway;

    @PostConstruct
    public void setup() {
        setSuperClass(baseGateway);
    }

    @Override
    public void initiateLoan(Object data) {
        // call external lending provider
    }

    @Override
    public LoanOptIn loanOptIn(NewLoanOptIn newLoanOptIn) {
        // enrol customer
        return new LoanOptIn();
    }
    // ... implement remaining no-base-impl methods
}

Registration: Contact the platform team to register the gateway class for the relevant loan type.

5.6 Remittance Gateway

Use case: Implement a custom remittance gateway (cross-border money transfer, mobile money payout, or FX provider).

Base class: com.ukheshe.services.remittance.gateway.pluggable.PluggableRemittanceGateway

Interface: com.ukheshe.services.remittance.gateway.IRemittanceGateway

Bidirectional delegate interface: com.ukheshe.services.remittance.gateway.pluggable.BiDirectionalDelegatingRemittanceGateway

Concrete delegate bean: com.ukheshe.services.remittance.gateway.pluggable.BiDirectionalDelegatingBaseRemittanceGateway (`@Dependent)

Call setSuperClass(BiDirectionalDelegatingRemittanceGateway) in @PostConstruct, injecting the BiDirectionalDelegatingBaseRemittanceGateway bean.

Key methods:

Plugin example:

@PluginDescriptor(name = "my-remittance-gateway", version = "1.0")
@ApplicationScoped
public class MyRemittanceGateway extends PluggableRemittanceGateway {

    @Inject BiDirectionalDelegatingBaseRemittanceGateway baseGateway;

    @PostConstruct
    public void setup() {
        setSuperClass(baseGateway);
    }

    @Override
    public void initiateRemittance(Object data) {
        // call external remittance provider
    }

    @Override
    public void getRemittance(DbRemittance dbRemittance) {
        // fetch current state
    }
    // ... override other methods as needed
}

Registration: Contact the platform team to register the gateway class for the relevant remittance type.

5.7 Payment Processor

Use case: Customise how a payment is enriched before creation, how its result is interpreted, or how completion is attempted. Processors sit between the Conductor API layer and the payment service.

Base class: com.ukheshe.eclipse.conductor.service.payments.PluggablePaymentProcessor

Interface: com.ukheshe.eclipse.conductor.service.payments.IPaymentProcessor

Key methods:

Plugin example:

@PluginDescriptor(name = "my-payment-processor", version = "1.0")
@ApplicationScoped
public class MyPaymentProcessor extends PluggablePaymentProcessor {

    @PostConstruct
    public void setup() {
        setSuperClass(UK.Runtime.getBean(BiDirectionalDelegatingMyBaseProcessor.class));
    }

    @Override
    public void enrichForCreation(NewEclipsePayment eclipsePayment, NewPayment newPayment) {
        super.enrichForCreation(eclipsePayment, newPayment); // delegates to base
        // additional enrichment
    }
}

Registration: The processor factory selects a processor based on payment type. Contact the platform team to wire a new payment type to your plugin class.

5.8 Withdrawal Processor

Use case: Customise enrichment, fee calculation, or limit enforcement for a withdrawal flow.

Base class: com.ukheshe.eclipse.conductor.service.withdrawals.PluggableWithdrawalProcessor

Interface: com.ukheshe.eclipse.conductor.service.withdrawals.IWithdrawalProcessor

Key methods:

Plugin example:

@PluginDescriptor(name = "my-withdrawal-processor", version = "1.0")
@ApplicationScoped
public class MyWithdrawalProcessor extends PluggableWithdrawalProcessor {

    @PostConstruct
    public void setup() {
        setSuperClass(UK.Runtime.getBean(BiDirectionalDelegatingMyBaseWithdrawalProcessor.class));
    }

    @Override
    public Fee getWithdrawalFee(long tenantId, Wallet wallet, String type, BigDecimal amount) {
        // custom fee logic
        return new Fee(amount.multiply(BigDecimal.valueOf(0.01)));
    }
}

Registration: Contact the platform team to register your processor class for the relevant withdrawal type.

6. Listener Plugins

Listener plugins let you react to service lifecycle events across any microservice. Each service exposes a Pluggable*Listener class that you extend. Overriding a method gives you a pre-post hook around that lifecycle event, with access to full CDI injection.

Listener chain

Every service has a four-layer listener chain:

SilentXxxListener          (no-op base — defines the interface)
    └── PublishingXxxListener    (publishes domain events via UK.Events)
            └── PluggableXxxListener  (fires injection points via UK.Plugins)
                    └── EclipseXxxListener  (platform overrides; extend this one)

Your plugin should extend EclipseXxxListener (or a service-specific subclass of it provided by the platform). When you call super.method(...), the call propagates up through PluggableXxxListener (firing the injection point) and then PublishingXxxListener (publishing the domain event). Both always run unless you intentionally skip the super call.

Available Pluggable*Listener classes

Plugin example

@PluginDescriptor(name = "payment-audit", version = "1.0")
@ApplicationScoped
public class PaymentAuditListener extends EclipsePaymentListener {

    @Inject AuditService audit;

    @Override
    public void postCreatePayment(Payment payment) {
        audit.record(payment.getTenantId(), "payment.create", payment.getPaymentId());
        super.postCreatePayment(payment); // fires injection point + publishes domain event
    }

    @Override
    public void postPaymentComplete(Payment payment) {
        audit.record(payment.getTenantId(), "payment.complete", payment.getPaymentId());
        super.postPaymentComplete(payment);
    }
}

Registration: Contact the platform team to configure the listener class for the relevant service. The platform instantiates one listener per service via CDI and calls it for every lifecycle event.

7. Building a Plugin JAR

A plugin is a regular JAR with no main class. It must:

1. Declare one @PluginDescriptor-annotated class — used for identification and versioning.
2. Implement handler methods or extend a Pluggable* base class (or both).
3. Not bundle platform classes — classes from com.ukheshe.* are available at runtime via the parent class loader and must not be included in the plugin JAR.

The plugin-sdk.jar at the root of the repository contains the platform API classes needed for compilation. Reference it as a provided-scope dependency.

<dependency>
    <groupId>com.ukheshe</groupId>
    <artifactId>plugin-sdk</artifactId>
    <version>${project.version}</version>
    <scope>provided</scope>
</dependency>

Build a fat JAR that includes your own classes and any third-party libraries not already on the platform classpath.

8. Quick Reference

Minimal injection-point plugin

@PluginDescriptor(name = "my-plugin", version = "1.0", description = "Example plugin")
public class MyPluginDescriptor { }

@Singleton
public class MyHandlers {

    @OnNamedInjectionPoint(injectionPoint = "wallet.postWalletCreate", priority = 1)
    public void onWalletCreated(Wallet wallet) {
        // runs after every wallet is created
    }
}

Minimal fraud handler plugin

@PluginDescriptor(name = "my-fraud-plugin", version = "1.0")
public class MyFraudDescriptor { }

@Singleton
public class MyFraudHandler extends PluggableFraudEventPublishHandler {

    @Override
    public FraudEventPublishResponse handle(FraudEventPublishEvent event) {
        FraudEventPublishResponse res = new FraudEventPublishResponse();
        res.setFraudResult(FraudEventPublishResult.NOT_FRAUD);
        return res;
    }
}

Property: fraud.event.handlers.MYENGINE = com.example.MyFraudHandler

Minimal wallet type plugin

@PluginDescriptor(name = "my-wallet", version = "1.0")
public class MyWalletDescriptor { }

@Dependent
public class MyWallet extends PluggableWallet {

    @PostConstruct
    public void init() {
        setSuperClass(UK.Runtime.getBean(BiDirectionalDelegatingLimitCheckingWallet.class));
    }

    @Override
    public BigDecimal getCurrentBalance() {
        return super.getCurrentBalance(); // add custom logic here
    }
}

Wallet type DB record: implementationClass = com.example.MyWallet

Minimal loan gateway plugin

@PluginDescriptor(name = "my-loan-gateway", version = "1.0")
public class MyLoanDescriptor { }

@ApplicationScoped
public class MyLoanGateway extends PluggableLoanGateway {

    @Inject BiDirectionalDelegatingBaseLoanGateway baseGateway;

    @PostConstruct
    public void init() {
        setSuperClass(baseGateway);
    }

    @Override
    public void initiateLoan(Object data) { /* call provider */ }

    @Override
    public LoanOptIn loanOptIn(NewLoanOptIn req) { return new LoanOptIn(); }

    @Override
    public void updateLoan(Object data) { }

    @Override
    public LoanLimit loanLimit(String customerId, String productId) { return null; }

    @Override
    public Loan getLoan(DbLoan dbLoan) { return null; }

    @Override
    public List<Loan> getLoans(DbLoan filter, int offset, int limit) { return List.of(); }
}

Minimal listener plugin

@PluginDescriptor(name = "my-listener", version = "1.0")
public class MyListenerDescriptor { }

@ApplicationScoped
public class MyListener extends EclipseUserListener {

    @Override
    public void onUserCreated(User user) {
        // react to new user
        super.onUserCreated(user); // always call super to fire injection point + domain event
    }
}