or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.mdio-integration.mdmulti.mdsingle.mdsupporting-types.md
tile.json

tessl/maven-io-helidon-common--helidon-common-reactive

Helidon Common Reactive Library - A reactive programming library providing Multi and Single abstractions

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/io.helidon.common/helidon-common-reactive@4.2.x

To install, run

npx @tessl/cli install tessl/maven-io-helidon-common--helidon-common-reactive@4.2.0

index.mddocs/

Helidon Common Reactive

Helidon Common Reactive is a comprehensive reactive programming library that implements Multi (0-N items) and Single (0-1 item) reactive streams following the Java Flow API specification. The library offers a rich set of operators for stream transformation, filtering, combining, and error handling, enabling developers to build non-blocking, backpressure-aware applications.

Package Information

  • Package Name: io.helidon.common:helidon-common-reactive
  • Package Type: maven
  • Language: Java
  • Installation: Add to your Maven pom.xml:
<dependency>
    <groupId>io.helidon.common</groupId>
    <artifactId>helidon-common-reactive</artifactId>
    <version>4.2.2</version>
</dependency>

For Gradle:

implementation 'io.helidon.common:helidon-common-reactive:4.2.2'

Core Imports

import io.helidon.common.reactive.Multi;
import io.helidon.common.reactive.Single;
import io.helidon.common.reactive.IoMulti;

Import supporting types as needed:

import io.helidon.common.reactive.Subscribable;
import io.helidon.common.reactive.Awaitable;
import io.helidon.common.reactive.CompletionAwaitable;
import io.helidon.common.reactive.RetrySchema;

Basic Usage

import io.helidon.common.reactive.Multi;
import io.helidon.common.reactive.Single;
import java.util.concurrent.CompletableFuture;
import java.util.List;

// Create and transform a Multi
Multi<String> names = Multi.just("Alice", "Bob", "Charlie")
    .filter(name -> name.length() > 3)
    .map(String::toUpperCase);

// Collect to List
List<String> result = names.collectList().await();
// Result: ["ALICE", "CHARLIE"]

// Create a Single from CompletionStage
CompletableFuture<String> future = CompletableFuture.completedFuture("Hello");
Single<String> greeting = Single.create(future)
    .map(s -> s + " World!");

String message = greeting.await();
// Result: "Hello World!"

// Chain operations
Multi<Integer> numbers = Multi.range(1, 10)
    .filter(n -> n % 2 == 0)
    .map(n -> n * n)
    .limit(3);

numbers.forEach(System.out::println); // Prints: 4, 16, 36

Architecture

Helidon Common Reactive is built around several key components:

  • Multi<T>: Represents 0-N items reactive stream with full backpressure support
  • Single<T>: Represents 0-1 item reactive stream with CompletionStage compatibility
  • Flow API: Based on Java's standard java.util.concurrent.Flow specification
  • Lazy Evaluation: All operations are cold and executed per subscriber
  • Type Safety: Full generic type support with type-safe transformations
  • I/O Integration: Specialized classes for reactive I/O operations with ByteChannels, InputStreams, and OutputStreams

Capabilities

Multi Reactive Streams

Multi represents reactive streams that emit zero or more items. Provides comprehensive operators for transformation, filtering, error handling, and collection operations.

public interface Multi<T> extends Subscribable<T> {
    // Factory methods
    static <T> Multi<T> empty();
    static <T> Multi<T> just(T... items);
    static <T> Multi<T> create(Flow.Publisher<T> publisher);
    static <T> Multi<T> range(int start, int count);
    
    // Transformation operators
    <U> Multi<U> map(Function<? super T, ? extends U> mapper);
    <U> Multi<U> flatMap(Function<? super T, ? extends Flow.Publisher<? extends U>> mapper);
    Multi<T> filter(Predicate<? super T> predicate);
    Multi<T> limit(long maxSize);
    
    // Terminal operations
    Single<List<T>> collectList();
    void forEach(Consumer<? super T> consumer);
}

Multi Reactive Streams

Single Reactive Values

Single represents reactive streams that emit at most one item. Implements CompletionStage and provides blocking await operations for integration with existing code.

public interface Single<T> extends Subscribable<T>, CompletionStage<T>, Awaitable<T> {
    // Factory methods
    static <T> Single<T> empty();
    static <T> Single<T> just(T item);
    static <T> Single<T> create(CompletionStage<T> completionStage);
    static <T> Single<T> error(Throwable error);
    
    // Transformation operators
    <U> Single<U> map(Function<? super T, ? extends U> mapper);
    <U> Multi<U> flatMap(Function<? super T, ? extends Flow.Publisher<? extends U>> mapper);
    
    // Blocking operations
    T await();
    T await(Duration timeout);
}

Single Reactive Values

I/O Integration

Reactive I/O utilities for integrating with Java I/O streams, channels, and file operations. Enables reactive processing of I/O data with proper backpressure handling.

public final class IoMulti {
    // InputStream integration
    static Multi<ByteBuffer> multiFromStream(InputStream inputStream);
    static MultiFromInputStreamBuilder multiFromStreamBuilder(InputStream inputStream);
    
    // OutputStream integration  
    static OutputStreamMulti outputStreamMulti();
    static OutputStreamMultiBuilder outputStreamMultiBuilder();
    
    // ByteChannel integration
    static Multi<ByteBuffer> multiFromByteChannel(ReadableByteChannel channel);
    static Function<Multi<ByteBuffer>, CompletionStage<Void>> multiToByteChannel(WritableByteChannel channel);
}

I/O Integration

Supporting Types

Core interfaces and utility classes that support reactive operations including subscription management, awaitable operations, and retry strategies.

public interface Subscribable<T> extends Flow.Publisher<T> {
    void subscribe(Consumer<? super T> onNext);
    void subscribe(Consumer<? super T> onNext, Consumer<? super Throwable> onError);
    void subscribe(Consumer<? super T> onNext, Consumer<? super Throwable> onError, Runnable onComplete);
}

public interface Awaitable<T> {
    CompletableFuture<T> toCompletableFuture();
    T await();
    T await(Duration timeout);
}

public interface RetrySchema {
    long nextDelay(int retryCount, long lastDelay);
    static RetrySchema constant(long delay);
    static RetrySchema linear(long firstDelay, long increment, long maxDelay);
    static RetrySchema geometric(long firstDelay, double ratio, long maxDelay);
}

Supporting Types

Error Handling Patterns

The library provides comprehensive error handling through several patterns:

  1. Resume Operations: onErrorResume() and onErrorResumeWith() allow recovering from errors
  2. Retry Logic: retry() methods with count, predicate, or publisher-based control
  3. Timeout Handling: timeout() methods with optional fallback publishers
  4. Completion Handling: onCompleteResume() methods for appending after completion

Integration Patterns

Java Standard Library Integration

  • CompletionStage: Single implements CompletionStage for seamless async integration
  • Stream: Multi.create(Stream<T>) converts Java Streams
  • Iterable: Multi.create(Iterable<T>) and flatMapIterable() methods
  • Optional: flatMapOptional() and toOptionalSingle() methods
  • Collectors: collectStream(java.util.stream.Collector) uses Stream collectors

Reactive Streams Integration

  • Flow.Publisher: Both Multi and Single are Flow.Publisher implementations
  • Backpressure: Full reactive streams backpressure support
  • Subscription: Proper subscription lifecycle management

Threading and Execution Model

  • Cold Streams: All operations are lazy and executed per subscriber
  • Thread Safety: Publishers are designed to be thread-safe for subscription
  • Execution Control: observeOn() methods allow switching execution contexts
  • Async Operations: CompletionStage integration allows async composition