swim-developer-extensions

Pluggable Kafka adapters for the SWIM framework. Each module is an independent Maven dependency that implements one of the framework's extension points (SPIs). Add only the modules your application needs.

There are two distinct sides. Consumer extensions implement the three extension points of the consumer pipeline. Provider extensions feed external events into the provider ingestion pipeline.

Consumer extensions

Consumer applications use three extension points in sequence:

EP	Module	SPI	What it does
EP1	swim-inbox-store-kafka	SwimInboxStore	Receives each AMQP message from the framework, wraps it as an InboxEnvelope, and writes it to a Kafka inbox topic. Ships as a @Default CDI bean — active by adding the dependency.
EP2	swim-inbox-reader-kafka	SwimInboxReader	Provides AbstractKafkaInboxReader. Extend it in your application module, add @Incoming with your Kafka channel, and implement the three template methods. Switching to a different transport (Artemis, etc.) means extending a different abstract class.
EP3	swim-outbox-kafka-dnotam / swim-outbox-kafka-ed254	SwimOutboxRouter	Receives validated domain events from OutboxDispatcher, classifies them by scenario, and routes each to the correct Kafka topic.

Consumer pipeline flow

AMQP Broker
  --> AbstractAmqpConsumerManager (framework)
      --> InboxBatchProcessor --> SwimInboxStore (EP1: swim-inbox-store-kafka)
                                       --> Kafka inbox topic
                                           --> @Incoming in concrete handler (EP2: swim-inbox-reader-kafka)
                                               --> AbstractStreamingInboxConsumer (framework)
                                                   --> EventProcessor --> OutboxDispatcher
                                                       --> SwimOutboxRouter (EP3: swim-outbox-kafka-dnotam/ed254)
                                                           --> Kafka domain topics

Provider extensions

Provider applications use a separate set of extensions to receive events from an external Kafka topic and feed them into the provider's ingestion pipeline:

Module	SPI	What it does
swim-inbox-kafka-dnotam	SwimIngressHandler	Consumes DNOTAM events from a Kafka topic and delegates to the provider pipeline via DnotamEventProcessor.
swim-inbox-kafka-ed254	SwimIngressHandler	Consumes ED-254 events from a Kafka topic and delegates to the provider pipeline.

Provider ingestion flow

External event source
  --> Kafka topic (dnotam-events-all-topic / ed254-events-all-topic)
      --> swim-inbox-kafka-dnotam / swim-inbox-kafka-ed254 (SwimIngressHandler)
          --> SWIM Provider ingestion pipeline
              --> AMQP Broker (broadcast to subscribers)

GET STARTED

Prerequisites

• Java 21
• Maven 3.9+
• swim-developer-framework installed locally (see swim-developer-framework)

Build

# Install the framework first if not already done
# git clone https://github.com/swim-developer/swim-developer-framework
# cd swim-developer-framework && ./mvnw clean install -DskipTests

./mvnw clean install -DskipTests

Adding consumer extensions to a consumer application

<!-- EP1: store AMQP messages to Kafka inbox (active automatically as @Default CDI bean) -->
<dependency>
    <groupId>com.github.swim-developer</groupId>
    <artifactId>swim-inbox-store-kafka</artifactId>
    <version>1.0.0-SNAPSHOT</version>
</dependency>

<!-- EP2: Kafka inbox reader base (extend AbstractKafkaInboxReader in your application) -->
<dependency>
    <groupId>com.github.swim-developer</groupId>
    <artifactId>swim-inbox-reader-kafka</artifactId>
    <version>1.0.0-SNAPSHOT</version>
</dependency>

<!-- EP3: route validated DNOTAM events to Kafka domain topics -->
<dependency>
    <groupId>com.github.swim-developer</groupId>
    <artifactId>swim-outbox-kafka-dnotam</artifactId>
    <version>1.0.0-SNAPSHOT</version>
</dependency>

Override the inbox topic name in application.properties:

# EP1: override the default swim-inbox topic name
mp.messaging.outgoing.swim-inbox.topic=${DNOTAM_INBOX_TOPIC:dnotam-inbox-topic}

For EP2, extend AbstractKafkaInboxReader in your application module and bind the @Incoming channel:

@ApplicationScoped
public class DnotamInboxMessageHandler extends AbstractKafkaInboxReader {
    @Incoming("in-dnotam-inbox")
    @Blocking
    public CompletionStage<Void> consume(KafkaRecordBatch<String, String> batch) {
        return processBatch(batch, orchestrator);
    }

    @Override
    public void processSingleMessage(InboxEnvelope envelope, String xmlPayload, int index) {
        // domain-specific logic
    }

    @Override
    public String getMetricPrefix() { return "dnotam"; }
}

Adding provider extensions to a provider application

<!-- Ingest DNOTAM events from Kafka into the provider pipeline -->
<dependency>
    <groupId>com.github.swim-developer</groupId>
    <artifactId>swim-inbox-kafka-dnotam</artifactId>
    <version>1.0.0-SNAPSHOT</version>
</dependency>

Configure the source Kafka topic in application.properties:

mp.messaging.incoming.swim-dnotam-events-in.connector=smallrye-kafka
mp.messaging.incoming.swim-dnotam-events-in.topic=dnotam-events-all-topic

Development tasks

Target	What it does
make deps	Shows which sibling repos must be installed first
make install	Builds all modules and installs them to the local Maven repository
make test	Runs unit tests
make sonar-up	Starts SonarQube at http://localhost:9000 and waits until ready
make sonar	Runs static analysis (requires sonar-up first)
make sonar-down	Stops SonarQube
make security-deps	OWASP Dependency-Check -- report at target/dependency-check-report.html

SonarQube runs with authentication disabled -- no token or account needed. Results are published to http://localhost:9000 under project swim-extensions.

OWASP Dependency-Check

Without an NVD API key, the tool downloads the entire National Vulnerability Database (347,000+ records) which takes over one hour.

Get a free key at https://nvd.nist.gov/developers/request-an-api-key (instant registration).

Create a .env.owasp file in the project root (already in .gitignore):

NVD_API_KEY=your-key-here

make security-deps loads this file automatically. The NVD database is cached in ~/.m2 and reused across all projects on the same machine.

License

Licensed under the Apache License 2.0.