Plugin SDK
The Conncentric Plugin SDK extends the platform with custom Java components: Connectors, Processors, Transformers, Conditions, and ErrorProcessors. A component ships as a standard Java JAR, registers itself through a manifest file, and renders its Portal configuration form from a JSON Schema embedded on the class. No frontend code is involved.
When to use the SDK
Reach for the SDK only when an official plugin does not already provide the behavior.
| Requirement | Component type |
|---|---|
| Connect to a protocol not provided by an official plugin (internal binary feed, proprietary broker, legacy REST API). | Connector |
| Apply business logic, validation, enrichment, or a per-message side effect. | Processor |
| Convert a payload between representations (one wire format to another). | Transformer |
| Decide whether a route should run for a given message (predicate or filter). | Condition |
| React to a pipeline failure (retry, dead-letter, alert, suppress). | ErrorProcessor |
Component types
Each type maps to one Java interface. The interface is the contract; the class that implements it is what the platform loads.
| Component | Interface | Responsibility | Signature |
|---|---|---|---|
| Connector | com.connamara.sdk.v1.adapter.components.Connector | Protocol I/O. Opens and maintains a session with an external system; hands inbound messages into the pipeline; accepts outbound messages from the pipeline. | Protocol-specific. |
| Processor | com.connamara.sdk.v1.adapter.components.Processor | Business logic and side effects. Enriches, validates, routes, or drops a message. | Message<?> process(Message<?> message, RouteContext routeContext) |
| Transformer | com.connamara.sdk.v1.adapter.components.Transformer | Format conversion. Produces a new message whose payload or structure differs from the input. | Message<?> transform(Message<?> message) |
| Condition | com.connamara.sdk.v1.adapter.components.Condition | Route selection. Decides whether a route should run for the message. Acts as a filter in front of the pipeline. | boolean matches(Message<?> message, RouteContext context) |
| ErrorProcessor | com.connamara.sdk.v1.adapter.components.ErrorProcessor | Failure handling. Decides whether a failed message is recovered (Ack) or rejected (Nack). | boolean handleError(Message<?> failedMessage, Throwable cause, RouteContext routeContext) |
The platform discovers a component through the plugin's entry point: one class per plugin annotated with @org.pf4j.Extension and implementing com.connamara.sdk.v1.adapter.AdapterPlugin, which maps each component's type id to its class in a SimpleComponentRegistry and instantiates it from a createComponent switch. See Getting Started for the full registration walkthrough, and Components for per-type contracts and examples.
Messages are immutable
Message<?> is immutable. A component never mutates a message it receives. To change headers or payload, produce a new message with DerivedMessage.derive(...) and return it.
return DerivedMessage.derive(message, newPayload, Map.of("x-added-header", value));
DerivedMessage.derive(Message<?> source, Object payload, Map<String, Object> additionalHeaders) returns a new Message<?> that carries the source's original headers plus the supplied additions, with the supplied payload. The derived wrapper references the source rather than copying it, which preserves the pipeline's zero-copy semantics.
| Return value | Pipeline behavior |
|---|---|
The same message reference passed in | Message continues unchanged to the next step. |
A DerivedMessage.derive(...) result | New message continues with the derived headers and payload. |
null (Processor only) | Message is dropped from the pipeline. |
@ManifestResource is required for UI rendering
Every component class carries the com.connamara.sdk.v1.common.component.ManifestResource annotation. Its value is a JSON Schema document. The Portal reads the schema at load time and renders the configuration form (fields, validation, defaults, conditional visibility) from it.
A component without @ManifestResource is invisible to the Portal. A component whose manifest is invalid does not render at all.
See Component Manifest Schema for the full specification, including the x- extension keys that control layout and widgets.
How a plugin reaches the Portal
A plugin is a standard JAR containing one or more component classes plus an @Extension AdapterPlugin entry point that registers them. Once the JAR is loaded on the platform, each component the entry point registers appears in the Pipeline Designer. The Portal reads the component's @ManifestResource manifest, renders the configuration form, and accepts operator input. When an operator adds the component to a route, the platform calls the entry point's createComponent(id, config) to build the instance, passing the operator's input as a Map<String, Object>.
Official plugins and custom plugins load through the same mechanism. A reader opening the Pipeline Designer cannot tell which components came from the official catalog and which came from an SDK-built plugin.
Technical requirements
- Java 25.
- Gradle 9.6.1 (provided by the SDK builder image).
- Access to the SDK builder image, which ships with the Conncentric distribution. Contact your Connamara representative if you do not already have the image.
Follow Getting Started to set up a plugin project, build a first Transformer end to end, and package a deployable bundle. Then visit Components for the per-type contracts.