Quarkus Qlue: The step wiring framework

Maven

The Maven coordinates for this project are io.quarkus.qlue:qlue.

Usage

Quarkus Qlue is a framework which wires up independent steps into an overall ordered chain of tasks to run. The ordering uses a produces/consumes model based on items.

The chain is assembled using a chain builder which, as one might expect, follows a builder pattern to provide initial items, express final item requirements, and add steps which can produce and/or consume items.

Basic example

In this basic example, a step method executes which produces a simple item that can be accessed at the end of the chain's execution.

Basic example

public final class MessageItem extends SimpleItem {
    private final String message;

    public MessageItem(String message) {
        this.message = message;
    }

    public String getMessage() {
        return message;
    }
}

// later...

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        // Build a new chain
        final ChainBuilder builder = Chain.builder();
        builder.addStepObject(new Object() {
            @Step
            public MessageItem produceHelloWorld() {
                return new MessageItem("Hello World");
            }
        });
        // make sure the step is run
        builder.addFinal(MessageItem.class);
        // create the reusable chain
        Chain chain = builder.build();
        // now create a new execution of the chain
        ExecutionBuilder executionBuilder = chain.createExecutionBuilder();
        // run the chain using a trivial executor
        final Result result = executionBuilder.execute(Runnable::run);
        if (result.isSuccess()) {
            String message = result.asSuccess().consume(MessageItem.class).getMessage();
            System.out.println(message);
        } else {
            System.err.println("Oh no :(");
        }
    }

Chain builder

The chain builder is used to assemble the list of step objects, step classes, and raw steps. Additionally, it can be used to specify initial input items and final output items (as shown in the trivial example above).

Items

There are three essential kinds of item which can be used with Qlue:

• Simple items, which are final classes which extend the SimpleItem base class; such items can be produced by one step and consumed by many steps

• Multi items, which are final classes which extend the MultiItem base class; such items can be produced by many steps and consumed by many steps

• Empty items, which are used only for ordering and cannot be constructed; such items can only be used in ordering constraints (e.g. annotations such as @BeforeConsume or @AfterProduce)

Steps

Steps are scheduled such that any step which consumes an item executes after any step which produces the item.

Step methods

A step method is an accessible method which is annotated with the @Step annotation. The parameters of a step method must be one of the following types:

• A simple item, indicating that the item of that type is consumed by the step

• A List of a multi item, indicating that all items of the item's type are consumed by the step

• An Optional of a simple item, indicating that the item of the `Optional’s type is optionally consumed by the step

• A Consumer of a simple item or multi item, indicating that the item is produced by the step by passing the produced item into the Consumer

The return type of the method must be one of the following:

• void

• A simple item, indicating that the item is produced by the method

• A multi item, indicating that the item is produced by the method

In cases where an item is returned, returning a null will cause consumers of the item to receive a null value for that item.

An example of a step method which produces and consumes simple values

    @Step
    public MessageItem assembleMessage(NameItem name, GreetingItem) {
        return new MessageItem(greeting.getGreeting() + ", " + name.getName());
    }

Step objects

A step object is any Java object which contains zero or more accessible methods which are annotated with the @Step annotation.

Such objects can be passed in to the chain builder directly. The object will be used as-is, with the object’s step methods being invoked as needed during the build process.

Step classes

A step class is a Java class with a single accessible constructor which contains zero or more accessible methods which are annotated with the @Step annotation.

When a step class is added to the chain builder, an instance of the class will be instantiated using the accessible constructor. This instance will be used to receive invocations of the step methods as needed during the build process.

Raw steps

A raw step is a step which interacts directly with the StepContext to directly produce and consume items. Normally, this type of step is reserved for advanced use cases.