• Loaders
  • PartLoader
  • StaticPartLoader
  • BuilderLoader
  • FutureLoader
  • CommandLoader
  • ResultConsumerLoader
  • ScrapConsumerLoader
• Get Loaders by Conveyor name
• Lazy Loader suppliers

Loaders is a collection of immutable classes that help to create and load different types of Carts. Immutability of loaders guarantees the absence of side effects. Loaders also allow hiding the conveyor instance from the client, providing just enough functionality for main conveyor tasks, which are sending building parts wrapped into messages.

Loaders Code

Although Loaders have public constructors, in most cases you will not use them directly. Instead, Conveyor provides a family of convenient accessors.

public interface Conveyor<K, L, OUT> {
    public <X> PartLoader<K, L, X, OUT, Boolean> part();
    public <X> StaticPartLoader<L, X, OUT, Boolean> staticPart();
    public BuilderLoader<K, OUT, Boolean> build();
    public FutureLoader<K, OUT> future();
    public CommandLoader<K, OUT> command();
    public ResultConsumerLoader<K, OUT> resultConsumer();
    public ResultConsumerLoader<K, OUT> resultConsumer(ResultConsumer<K,OUT> consumer);
    public ScrapConsumerLoader<K> scrapConsumer();
    public ScrapConsumerLoader<K> scrapConsumer(ScrapConsumer<K,?> scrapConsumer);
}

PartLoader is the main vehicle that sends data to conveyors. It's API includes methods:

• id(K id) - Sets ID for the build. Call of the id method cancels any predicates set by foreach methods
• foreach() - Tells conveyor to apply values to all active builds. Call of the foreach method removes value of key set by the id call
• foreach(Predicate<K> f) - Tells conveyor to apply values to all active builds, with keys matching provided filter. Call of the foreach method removes value of key set by the id call
• label(L l) - Sets label.
• value(X v) - Sets value of the part.
• expirationTime - Sets expiration time. Expiration time can be a long epoch timestamp in milliseconds, or Instant object
• ttl - Sets TTL. TTL can be passed as a TimeUnit or as a Duration
• priority(long priority) - Sets priority. This parameter only affects conveyors created with Priority Queues and ignored by others.
• place() - data will not be sent, until this method is called. Unlike previous methods it returns a Future of the building part.

Example

conveyor.part().id(123).label("FirstName").value("John").ttl(1,TimeUnit.SECONDS).place();

StaticPartLoader - loads data, that will be stored on the conveyor level, and applied to all newly created builds in undefined order. Note that static parts have no expiration time. If you would like to delete static value, you should call the delete() method explicitly. The API includes methods:

• label(L l) - Sets label.
• value(X v) - Sets value of the part.
• priority(long priority) - Sets priority. This parameter only affects conveyors created with Priority Queues and ignored by others.
• delete() - Tells the conveyor to delete static value with specified label
• place() - data will not be sent, until this method is called. Unlike previous methods it returns a Future of the building part.

BuilderLoader - It's API includes methods:

• id(K id) - Sets ID for the build.
• supplier(BuilderSupplier<OUT> v) - Supplier that will be used to create an instance of the Builder. If missing, default supplier will be used.
• expirationTime - Sets expiration time. Expiration time can be a long epoch timestamp in milliseconds, or Instant object
• ttl - Sets TTL. TTL can be passed as a TimeUnit or as a Duration
• priority(long priority) - Sets priority. This parameter only affects conveyors created with Priority Queues and ignored by others.
• create() - sends the message to create the build. Returns Future of the message.
• createFuture() - sends the message to create the build. Returns Future of the Product.

FutureLoader - It's API includes methods:

• id(K id) - Sets ID for the buildю
• expirationTime - Sets expiration time. Expiration time can be a long epoch timestamp in milliseconds, or Instant object
• ttl - Sets TTL. TTL can be passed as a TimeUnit or as a Duration
• priority(long priority) - Sets priority. This parameter only affects conveyors created with Priority Queues and ignored by others.
• get() - Returns Future of the Product. If conveyor has a default Builder Supplier, and build with provided ID does not exist, then the new build is created. If default Builder Supplier is absent, then future will be immediately completed with exception.

CommandLoader - CommandLoader and MultiKeyCommandLoader send messaged to the command queue, which has higher priority and bypasses the main input queue for Building parts. It's API includes methods:

CommandLoader (and its counterpart MultiKeyCommandLoader) provide a way to send special high-priority commands to a Conveyor’s command queue. These commands bypass the main input queue for building parts, allowing you to perform lifecycle and state management operations more directly and immediately.

When you use CommandLoader to send commands, they go directly to the command queue, which has higher priority than the normal input queue. This means your commands—like canceling, checking, or timing out a build—take effect right away, even if parts are still pending in the main queue.

You can target a single build by setting an ID with id(K), or apply commands to multiple builds by using foreach() or foreach(Predicate<K>). Note that certain commands, such as create and check, are only valid when a specific ID is set and cannot be used with foreach methods.

• id(K id)
  Sets the ID of the build you want to control. This is required for commands that specifically target a single build (like create, check, complete, etc.).

• foreach()
  Causes the subsequent command to apply to all active builds at once. Using foreach will override any previously set ID. Global operations such as canceling all builds can be done this way.
  Note: foreach cannot be used with create or check.

• foreach(Predicate f)
  Similar to foreach() but applies the command only to builds whose keys match the given predicate.
  Note: foreach cannot be used with create or check.

• expirationTime(...)
  Sets a new expiration time for the selected build(s). You can pass either a long epoch timestamp in milliseconds or an Instant.

• creationTime(...)
  Adjusts the internal creation time of the build, either as a long epoch timestamp or an Instant.

• ttl(...)
  Sets a Time-To-Live (TTL) for the build. You can specify TTL using a (long, TimeUnit) pair or a Duration. The expiration time is then calculated as creationTime + ttl.

• create() / create(BuilderSupplier builder)
  Sends a command to create a new build using the provided builder or a default one. Requires id(K) to be set first. Returns a CompletableFuture<Boolean>.

• cancel()
  Cancels the build. The build is treated as failed once canceled. Returns a CompletableFuture<Boolean>.

• timeout()
  Similar to cancel(), but invokes an onTimeout handler before completion. Depending on the handler’s result, the build can complete successfully or fail. Returns a CompletableFuture<Boolean>.

• reschedule()
  Adjusts the build’s expiration time based on parameters passed with the command. Returns a CompletableFuture<Boolean>.

• check()
  Returns a CompletableFuture<Boolean>. The future completes with true if the build is currently running, or false otherwise. Requires id(K).

• complete(OUT result)
  Immediately completes the build successfully with the provided result. Returns a CompletableFuture<Boolean>.

• completeExceptionally(Throwable error)
  Immediately completes the build as failed with the given exception. Returns a CompletableFuture<Boolean>.

• suspend()
  Temporarily suspends execution of the input balancing queue. New parts can be added though. Returns a CompletableFuture<Boolean>.

• addProperty(String property, Object value)
  Adds a single named property to the build. Properties can be used to influence building logic or subsequent operations. Returns a CompletableFuture<Boolean>.

• addProperties(Map<String, Object> properties)
  Adds multiple properties at once to the build. Returns a CompletableFuture<Boolean>.

• peek()
  Returns a CompletableFuture<ProductBin<K, OUT>> that, once completed, provides the current product state of the build. This allows you to inspect the in-progress result without completing the build.

• peek(Consumer<ProductBin<K,OUT>> consumer)
  Similar to peek(), but instead of returning the product, it accepts a consumer that will be called with the product state. Returns a CompletableFuture<Boolean>.

• peekId(Consumer consumer)
  Provides the build’s key to the specified consumer. Returns a CompletableFuture<Boolean>.

• memento()
  Returns a CompletableFuture<Memento> representing a snapshot of the build’s current state (including collected parts, properties, and partial results).

• memento(Consumer consumer)
  Calls the given consumer with the build’s Memento. Returns a CompletableFuture<Boolean>.

• restore(Memento memento)
  Restores a build to a previously captured state using a Memento. If no id was set, the ID will be inferred from the Memento. Returns a CompletableFuture<Boolean>.

When you call foreach() or foreach(Predicate<K>) on a CommandLoader, you get a MultiKeyCommandLoader. This loader applies commands to multiple builds at once, enabling batch operations such as global cancellation or property updates. Remember that create and check are not applicable in this mode since they require a specific build ID.

ResultConsumerLoader - Sets Result Consumer for conveyor, individual builds or family of builds. It's API includes methods:

• id(K id) - Sets ID for the build.
• foreach() - Tells conveyor to apply ResultConsumer to all active builds. Call of the foreach method removes value of key set by the id call
• foreach(Predicate<K> f) - Tells conveyor to apply ResultConsumer to all active builds, with keys matching provided filter. Call of the foreach method removes value of key set by the id call
• expirationTime - Sets expiration time. Expiration time can be a long epoch timestamp in milliseconds, or Instant object
• ttl - Sets TTL. TTL can be passed as a TimeUnit or as a Duration
• priority(long priority) - Sets priority. This parameter only affects conveyors created with Priority Queues and ignored by others.
• first(ResultConsumer <K,OUT> consumer) - When created with the resultConsumer() method, ResultConsumerLoader is seeded with current value of the ResultConsumer. This method replaces the head in the consumers chain.
• andThen(ResultConsumer <K,OUT> consumer) - links new ResultConsumer to the chain of consumers.
• set() - If neither id, nor foreach methods were called, sets new default ResultConsumer for the conveyor. If id method were called, sets new ResultConsumer for the Build. If foreach methods were called, sets ResultConsumer for all Builds with ids matching the filter.

ScrapConsumerLoader - Sets scrap consumer for the conveyor. It's API includes methods:

• first(ScrapConsumer <K,?> consumer) - When created with the scrapConsumer() method, ScrapConsumerLoader is seeded with current value of the ScrapConsumer. This method replaces the head in the consumers chain.
• andThen(ScrapConsumer <K,?> consumer) - links new ScrapConsumer to the chain of consumers.
• set() - Sets new default ScrapConsumer for the conveyor.

Detailed information about Consumers can be found in this article.

If the only thing you need in some module - is a Loader, you can retrieve it directly by conveyor's name. Loaders have simple interfaces and you cannot break conveyor configuration by using it.

PartLoader.byConveyorName("name");
StaticPartLoader.byConveyorName("name");
BuilderLoader.byConveyorName("name");
CommandLoader.byConveyorName("name");
FutureLoader.byConveyorName("name");
ResultConsumerLoader.byConveyorName("name");
ScrapConsumerLoader.byConveyorName("name");

Lazy supplier will keep a reference to the Conveyor for you. You can retrieve lazy Supplier before conveyor is created.

PartLoader.lazySupplier("name");
PartLoader.lazySupplier("name").get();

StaticPartLoader.lazySupplier("name");
StaticPartLoader.lazySupplier("name").get();

BuilderLoader.lazySupplier("name");
BuilderLoader.lazySupplier("name").get();

CommandLoader.lazySupplier("name");
CommandLoader.lazySupplier("name").get();

FutureLoader.lazySupplier("name");
FutureLoader.lazySupplier("name").get();

ResultConsumerLoader.lazySupplier("name");
ResultConsumerLoader.lazySupplier("name").get();

ScrapConsumerLoader.lazySupplier("name");
ScrapConsumerLoader.lazySupplier("name").get();