Package io.smallrye.reactive.converters

Interface ReactiveTypeConverter<T>

  • Type Parameters:
    T - the converted type.
    public interface ReactiveTypeConverter<T>
    Converts a specific reactive types from and to CompletionStage and Publisher. In addition to conversion operations, this class provides characteristics on the converted type:
    • whether or not the converted type <T> may emit at most one item
    • whether or not the converted type <T> may emit multiple items
    • whether or not the converted type <T> may emit null values
    • ...

    Implementations must be tested against the TCK by extending the test case from the io.smallrye.reactive.converters.tck packages.

    • Method Detail

      • toCompletionStage

        <X> CompletionStage<X> toCompletionStage​(T instance)
        Transforms an instance of T to a CompletionStage completed with a potential value. Each converter instances can use specific rules, however the following set of rules are mandatory:
        • The returned CompletionStage must never be null.
        • The returned CompletionStage completes with the first emitted value. This value may be null for empty stream or instance of T emitting null as first value.
        • If the passed instance emits several values, only the first one is considered, others are discarded.
        • If the passed instance fails before emitting a value, the returned CompletionStage completes with this failure.
        • If the passed instance does not emit any value and does not fail or complete, the returned CompletionStage does not complete.
        • If the passed instance completes before
          emitting a value, the CompletionStage is completed with a null value.
        • If the passed instance emits null as first value (if supported), the CompletionStage is completed with null. As a consequence, there are no differences between an instance emitting null as first value or completing without emitting a value. If the instance does not support emitting null values, the returned CompletionStage must be completed with a failure.
        Type Parameters:
        X - the type used to complete the returned CompletionStage. It is generally the type of data emitted by the passed instance.
        Parameters:
        instance - the instance to convert to a CompletionStage. Must not be null.
        Returns:
        a non-null CompletionStage.

      • toRSPublisher

        <X> org.reactivestreams.Publisher<X> toRSPublisher​(T instance)
        Transforms an instance of T to a Publisher. Each converter instances can use specific rules, however the following set of rules are mandatory:
        • The returned Publisher must never be null.
        • All values emitted by the instance are emitted by the returned Publisher.
        • If the instance emits a failure, Publisher propagates the same failure and terminates.
        • If the instance completes, Publisher also completes.
        • If the passed instance does not emit any value and does not fail or complete, the returned Publisher does not send any signals or values.
        • If the passed instance completes before
          emitting a value, the Publisher also completes empty.
        • If the passed instance emits null, the Publisher must send a failure (NullPointerException.
        • If the instance support back-pressure, the resulting Publisher must enforce back-pressure. When the instance does not support back-pressure, the Publisher consumes the data without back-pressure using an unbounded-buffer. In other words, this operation is a pass-through for back-pressure and its behavior is determined by the back-pressure behavior of the passed instance.
        Type Parameters:
        X - the type emitted by the returned Publisher. It is generally the type of data emitted by the passed instance.
        Parameters:
        instance - the instance to convert to a Publisher. Must not be null.
        Returns:
        a non-null Publisher.

      • fromCompletionStage

        <X> T fromCompletionStage​(CompletionStage<X> cs)
        Transforms an instance of CompletionStage to an instance of T. The value emitted by T depends on the completion of the passed CompletionStage. Each converter instances can use specific rules, however the following set of rules are mandatory:
        • The returned T must never be null.
        • If the passed CompletionStage never completes, no values are emitted by the returned T.
        • If the passed CompletionStage redeems a null value, and if T support null values, null is emitted by the returned instance of T.
        • If the passed CompletionStage redeems a null value, and if T does not support null values, a failure is emitted by the returned instance of T.
        • If the passed CompletionStage redeems a non-null value, the value is emitted by the returned instance of T.
        • If the passed CompletionStage is completed with a failure, the same failure is emitted by the returned instance of T.
        • If the passed CompletionStage is cancelled before having completed, the CancellationException must be emitted by the returned instance.

        Implementations must not expect the CompletionStage to be instances of CompletableFuture.

        Implementations may decide to adapt the emitted result when receiving container object such as Optional.

        Type Parameters:
        X - the type of result provided by the CompletionStage
        Parameters:
        cs - the instance of CompletionStage, must not be null
        Returns:
        the instance of T, generally emitting instances of X.

      • fromPublisher

        <X> T fromPublisher​(org.reactivestreams.Publisher<X> publisher)
        Transforms an instance of T to a Publisher. Each converter instances can use specific rules, however the following set of rules are mandatory:
        • The returned Publisher must never be null.
        • If the instance of T emits a single value, the returned Publisher emits the same value and completes.
        • If the instance of T does not emits value, sends the completion signal, the returned Publisher completes.
        • If the instance of T emits a failure, the returned Publisher emits a failure.
        • If the instance of T emits a null value, the returned Publisher emits an NullPointerException as null is not a valid value.
        • If the instance of T does neither emits a value nor a signal, the returned Publisher does not emits values or signals.
        • This operation is a pass-through for back-pressure and its behavior is determined by the back-pressure behavior of the returned instance.
        Type Parameters:
        X - the type of data emitted by the passed Publisher.
        Parameters:
        publisher - the Publisher to convert. Must not be null.
        Returns:
        a non-null instance of T.

      • type

        Class<T> type()
        Returns:
        the conversion type. Must not be null. Notice that sub-classes of the returned class are also managed by the same converter.

      • emitItems

        boolean emitItems()
        Returns:
        true if the type T may emit items, false otherwise.

      • emitAtMostOneItem

        boolean emitAtMostOneItem()
        Returns:
        true if the type T may emit items at most one item, false otherwise. Returning false to this method means that the converted type only signals about completion or error. Returning true means that emitItems() must also return true.

      • supportNullValue

        boolean supportNullValue()
        Returns:
        true if the type T can emit or receive null as item.

      • requireAtLeastOneItem

        default boolean requireAtLeastOneItem()
        Returns:
        true if the type T require at least one item. Converting from a type not emitting a value item would fail.