Package org.reactivestreams.tck.flow.support

Interface PublisherVerificationRules

    • Method Detail

      • required_createPublisher1MustProduceAStreamOfExactly1Element

        void required_createPublisher1MustProduceAStreamOfExactly1Element()
                                                           throws java.lang.Throwable
        Asks for a Publisher that should emit exactly one item and complete (both within a timeout specified by TestEnvironment.defaultTimeoutMillis()) in response to a request(1).

        The test is not executed if PublisherVerification.maxElementsFromPublisher() returns zero. If this test fails, the following could be checked within the Publisher implementation:

        • the Publisher.subscribe(Subscriber) method has actual implementation,
        • in the Publisher.subscribe(Subscriber) method, if there is an upstream Publisher, that Publisher is actually subscribed to,
        • if the Publisher is part of a chain, all elements actually issue a request() call in response to the test subscriber or by default to their upstream,
        • in the Publisher.subscribe(Subscriber) method, the Subscriber.onSubscribe is called as part of the preparation process (usually before subscribing to other Publishers),
        • if the Publisher implementation works for a consumer that calls request(1),
        • if the Publisher implementation is able to emit an onComplete without requests,
        • that the Publisher implementation does not emit more than the allowed elements (exactly one).
        Throws:
        java.lang.Throwable

      • required_createPublisher3MustProduceAStreamOfExactly3Elements

        void required_createPublisher3MustProduceAStreamOfExactly3Elements()
                                                            throws java.lang.Throwable
        Asks for a Publisher that should emit exactly three items and complete (all within a timeout specified by TestEnvironment.defaultTimeoutMillis()).

        The test is not executed if PublisherVerification.maxElementsFromPublisher() is less than 3.

        The tests requests one-by-one and verifies each single response item arrives in time.

        If this test fails, the following could be checked within the Publisher implementation:

        • the Publisher.subscribe(Subscriber) method has actual implementation,
        • in the Publisher.subscribe(Subscriber) method, if there is an upstream Publisher, that Publisher is actually subscribed to,
        • if the Publisher is part of a chain, all elements actually issue a request() call in response to the test subscriber or by default to their upstream,
        • in the Publisher.subscribe(Subscriber) method, the Subscriber.onSubscribe is called as part of the preparation process (usually before subscribing to other Publishers),
        • if the Publisher implementation works for a subscriber that calls request(1) after consuming an item,
        • if the Publisher implementation is able to emit an onComplete without requests.
        Throws:
        java.lang.Throwable

      • stochastic_spec103_mustSignalOnMethodsSequentially

        void stochastic_spec103_mustSignalOnMethodsSequentially()
                                                 throws java.lang.Throwable
        Asks for a short Publisher (i.e., length 10), repeatedly subscribes to this Publisher, requests items one by one and verifies the Publisher calls the onXXX methods non-overlappingly.

        Verifies rule: 1.3

        The test is not executed if PublisherVerification.maxElementsFromPublisher() is less than 10.

        Note that this test is probabilistic, that is, may not capture any concurrent invocation in a {code Publisher} implementation. Note also that this test is sensitive to cases when a request() call in onSubscribe() triggers an asynchronous call to the other onXXX methods. In contrast, the test allows synchronous call chain of onSubscribe -> request -> onNext.

        If this test fails, the following could be checked within the Publisher implementation:

        Throws:
        java.lang.Throwable

      • optional_spec104_mustSignalOnErrorWhenFails

        void optional_spec104_mustSignalOnErrorWhenFails()
                                          throws java.lang.Throwable
        Asks for an error Publisher that should call onSubscribe exactly once followed by a single call to onError() without receiving any requests and otherwise not throwing any exception.

        Verifies rule: 1.4

        The test is not executed if PublisherVerification.createErrorPublisher() returns null.

        If this test fails, the following could be checked within the error Publisher implementation:

        • the Publisher.subscribe(Subscriber) method has actual implementation,
        • in the Publisher.subscribe(Subscriber) method, if there is an upstream Publisher, that Publisher is actually subscribed to,
        • if the Publisher implementation does signal an onSubscribe before signalling onError,
        • if the Publisher implementation is able to emit an onError without requests,
        • if the Publisher is non-empty as this test requires a Publisher to signal an onError eagerly.
        Throws:
        java.lang.Throwable

      • optional_spec105_emptyStreamMustTerminateBySignallingOnComplete

        void optional_spec105_emptyStreamMustTerminateBySignallingOnComplete()
                                                              throws java.lang.Throwable
        Asks for an empty Publisher (i.e., length 0) and verifies it completes in a timely manner.

        Verifies rule: 1.5

        Note that the tests requests 1 before expecting an onComplete signal.

        If this test fails, the following could be checked within the Publisher implementation:

        • the TestEnvironment has large enough timeout specified in case the Publisher has some time-delay behavior,
        • if the Publisher is non-empty as this test requires a Publisher without items.
        Throws:
        java.lang.Throwable

      • required_spec107_mustNotEmitFurtherSignalsOnceOnCompleteHasBeenSignalled

        void required_spec107_mustNotEmitFurtherSignalsOnceOnCompleteHasBeenSignalled()
                                                                       throws java.lang.Throwable
        Asks for a single-element Publisher and checks if requesting after the terminal event doesn't lead to more items or terminal signals to be emitted.

        Verifies rule: 1.7

        The test is not executed if PublisherVerification.maxElementsFromPublisher() is less than 1.

        The tests requests more items than the expected Publisher length upfront and some more items after its completion.

        If this test fails, the following could be checked within the Publisher implementation:

        • the TestEnvironment has large enough timeout specified in case the Publisher has some time-delay behavior,
        • the indication for the terminal state is properly persisted and a request call can't trigger emission of more items or another terminal signal.
        Throws:
        java.lang.Throwable

      • required_spec109_mustIssueOnSubscribeForNonNullSubscriber

        void required_spec109_mustIssueOnSubscribeForNonNullSubscriber()
                                                        throws java.lang.Throwable
        Asks for an empty Publisher and verifies if onSubscribe signal was emitted before any other onNext, onError or onComplete signal.

        Verifies rule: 1.9

        Note that this test doesn't request anything, however, an onNext is not considered as a failure.

        If this test fails, the following could be checked within the Publisher implementation:

        • the TestEnvironment has large enough timeout specified in case the Publisher has some time-delay behavior,
        • the Publisher.subscribe(Subscriber) method has actual implementation,
        • in the Publisher.subscribe(Subscriber) method, if there is an upstream Publisher, that Publisher is actually subscribed to,
        • in the Publisher.subscribe(Subscriber) method, the Subscriber.onSubscribe is called as part of the preparation process (usually before subscribing to other Publishers).
        Throws:
        java.lang.Throwable

      • untested_spec109_subscribeShouldNotThrowNonFatalThrowable

        void untested_spec109_subscribeShouldNotThrowNonFatalThrowable()
                                                        throws java.lang.Throwable
        Currently, this test is skipped because there is no common agreement on what is to be considered a fatal exception and besides, Publisher.subscribe is only allowed throw a NullPointerException and any other exception would require looking into or hooking into the implementation of the Publisher.

        Verifies rule: 1.9

        Throws:
        java.lang.Throwable

      • required_spec109_subscribeThrowNPEOnNullSubscriber

        void required_spec109_subscribeThrowNPEOnNullSubscriber()
                                                 throws java.lang.Throwable
        Asks for an empty Publisher and calls subscribe on it with null that should result in a NullPointerException to be thrown.

        Verifies rule: 1.9

        If this test fails, check if the subscribe() implementation has an explicit null check (or a method dereference on the Subscriber), especially if the incoming Subscriber is wrapped or stored to be used later.

        Throws:
        java.lang.Throwable

      • required_spec109_mayRejectCallsToSubscribeIfPublisherIsUnableOrUnwillingToServeThemRejectionMustTriggerOnErrorAfterOnSubscribe

        void required_spec109_mayRejectCallsToSubscribeIfPublisherIsUnableOrUnwillingToServeThemRejectionMustTriggerOnErrorAfterOnSubscribe()
                                                                                                                             throws java.lang.Throwable
        Asks for an error Publisher that should call onSubscribe exactly once followed by a single call to onError() without receiving any requests.

        Verifies rule: 1.9

        The test is not executed if PublisherVerification.createErrorPublisher() returns null.

        The difference between this test and optional_spec104_mustSignalOnErrorWhenFails() is that there is no explicit verification if exceptions were thrown in addition to the regular onSubscribe+onError signal pair.

        If this test fails, the following could be checked within the error Publisher implementation:

        • the Publisher.subscribe(Subscriber) method has actual implementation,
        • in the Publisher.subscribe(Subscriber) method, if there is an upstream Publisher, that Publisher is actually subscribed to,
        • if the Publisher implementation is able to emit an onError without requests,
        • if the Publisher is non-empty as this test expects a Publisher without items.
        Throws:
        java.lang.Throwable

      • untested_spec110_rejectASubscriptionRequestIfTheSameSubscriberSubscribesTwice

        void untested_spec110_rejectASubscriptionRequestIfTheSameSubscriberSubscribesTwice()
                                                                            throws java.lang.Throwable
        Currently, this test is skipped because enforcing rule §1.10 requires unlimited retention and reference-equal checks on all incoming Subscriber which is generally infeasible, plus reusing the same Subscriber instance is better detected (or ignored) inside Subscriber.onSubscribe when the method is called multiple times.

        Verifies rule: 1.10

        Throws:
        java.lang.Throwable

      • optional_spec111_maySupportMultiSubscribe

        void optional_spec111_maySupportMultiSubscribe()
                                        throws java.lang.Throwable
        Asks for a single-element Publisher and subscribes to it twice, without consuming with either Subscriber instance (i.e., no requests are issued).

        Verifies rule: 1.11

        The test is not executed if PublisherVerification.maxElementsFromPublisher() is less than 1.

        Note that this test ignores what signals the Publisher emits. Any exception thrown through non-regular means will indicate a skipped test.

        Throws:
        java.lang.Throwable

      • optional_spec111_multicast_mustProduceTheSameElementsInTheSameSequenceToAllOfItsSubscribersWhenRequestingOneByOne

        void optional_spec111_multicast_mustProduceTheSameElementsInTheSameSequenceToAllOfItsSubscribersWhenRequestingOneByOne()
                                                                                                                throws java.lang.Throwable
        Asks for a short Publisher (length 5), subscribes 3 Subscribers to it, requests with different patterns and checks if all 3 received the same events in the same order.

        Verifies rule: 1.11

        The test is not executed if PublisherVerification.maxElementsFromPublisher() is less than 5.

        The request pattern for the first Subscriber is (1, 1, 2, 1); for the second is (2, 3) and for the third is (3, 1, 1).

        Note that this test requires a Publisher that always emits the same signals to any Subscriber, regardless of when they subscribe and how they request elements. I.e., a "live" Publisher emitting the current time would not pass this test.

        Note that this test is optional and may appear skipped even if the behavior should be actually supported by the Publisher, see the skip message for an indication of this.

        If this test fails, the following could be checked within the Publisher implementation:

        Throws:
        java.lang.Throwable

      • optional_spec111_multicast_mustProduceTheSameElementsInTheSameSequenceToAllOfItsSubscribersWhenRequestingManyUpfront

        void optional_spec111_multicast_mustProduceTheSameElementsInTheSameSequenceToAllOfItsSubscribersWhenRequestingManyUpfront()
                                                                                                                   throws java.lang.Throwable
        Asks for a short Publisher (length 3), subscribes 3 Subscribers to it, requests more than the length items upfront with each and verifies they all received the same items in the same order (but does not verify they all complete).

        Verifies rule: 1.11

        The test is not executed if PublisherVerification.maxElementsFromPublisher() is less than 3.

        Note that this test requires a Publisher that always emits the same signals to any Subscriber, regardless of when they subscribe and how they request elements. I.e., a "live" Publisher emitting the current time would not pass this test.

        Note that this test is optional and may appear skipped even if the behavior should be actually supported by the Publisher, see the skip message for an indication of this.

        If this test fails, the following could be checked within the Publisher implementation:

        Throws:
        java.lang.Throwable

      • optional_spec111_multicast_mustProduceTheSameElementsInTheSameSequenceToAllOfItsSubscribersWhenRequestingManyUpfrontAndCompleteAsExpected

        void optional_spec111_multicast_mustProduceTheSameElementsInTheSameSequenceToAllOfItsSubscribersWhenRequestingManyUpfrontAndCompleteAsExpected()
                                                                                                                                        throws java.lang.Throwable
        Asks for a short Publisher (length 3), subscribes 3 Subscribers to it, requests more than the length items upfront with each and verifies they all received the same items in the same order followed by an onComplete signal.

        Verifies rule: 1.11

        The test is not executed if PublisherVerification.maxElementsFromPublisher() is less than 3.

        Note that this test requires a Publisher that always emits the same signals to any Subscriber, regardless of when they subscribe and how they request elements. I.e., a "live" Publisher emitting the current time would not pass this test.

        Note that this test is optional and may appear skipped even if the behavior should be actually supported by the Publisher, see the skip message for an indication of this.

        If this test fails, the following could be checked within the Publisher implementation:

        Throws:
        java.lang.Throwable

      • required_spec302_mustAllowSynchronousRequestCallsFromOnNextAndOnSubscribe

        void required_spec302_mustAllowSynchronousRequestCallsFromOnNextAndOnSubscribe()
                                                                        throws java.lang.Throwable
        Asks for a short Publisher (length 6), requests several times from within onSubscribe and then requests one-by-one from onNext.

        Verifies rule: 3.2

        The test is not executed if PublisherVerification.maxElementsFromPublisher() is less than 6.

        The request pattern is 3 x 1 from within onSubscribe and one from within each onNext invocation.

        The test consumes the Publisher but otherwise doesn't verify the Publisher completes (however, it checks for errors).

        If this test fails, the following could be checked within the Publisher implementation:

        Throws:
        java.lang.Throwable

      • untested_spec304_requestShouldNotPerformHeavyComputations

        void untested_spec304_requestShouldNotPerformHeavyComputations()
                                                        throws java.lang.Exception
        Currently, this test is skipped because a request could enter into a synchronous computation via onNext legally and otherwise there is no common agreement how to detect such heavy computation reliably.

        Verifies rule: 3.4

        Throws:
        java.lang.Exception

      • required_spec309_requestZeroMustSignalIllegalArgumentException

        void required_spec309_requestZeroMustSignalIllegalArgumentException()
                                                             throws java.lang.Throwable
        Asks for a short Publisher (length 10) and issues a request(0) which should trigger an onError call with an IllegalArgumentException.

        Verifies rule: 3.9

        The test is not executed if PublisherVerification.maxElementsFromPublisher() is less than 10.

        Note that this test expects the IllegalArgumentException being signalled through onError, not by throwing from request() (which is also forbidden) or signalling the error by any other means (i.e., through the Thread.currentThread().getUncaughtExceptionHandler() for example).

        Note also that requesting and emission may happen concurrently and honoring this rule may require extra coordination within the Publisher.

        If this test fails, the following could be checked within the Publisher implementation:

        Throws:
        java.lang.Throwable

      • required_spec309_requestNegativeNumberMustSignalIllegalArgumentException

        void required_spec309_requestNegativeNumberMustSignalIllegalArgumentException()
                                                                       throws java.lang.Throwable
        Asks for a short Publisher (length 10) and issues a random, negative request() call which should trigger an onError call with an IllegalArgumentException.

        Verifies rule: 3.9

        The test is not executed if PublisherVerification.maxElementsFromPublisher() is less than 10.

        Note that this test expects the IllegalArgumentException being signalled through onError, not by throwing from request() (which is also forbidden) or signalling the error by any other means (i.e., through the Thread.currentThread().getUncaughtExceptionHandler() for example).

        Note also that requesting and emission may happen concurrently and honoring this rule may require extra coordination within the Publisher.

        If this test fails, the following could be checked within the Publisher implementation:

        Throws:
        java.lang.Throwable

      • optional_spec309_requestNegativeNumberMaySignalIllegalArgumentExceptionWithSpecificMessage

        void optional_spec309_requestNegativeNumberMaySignalIllegalArgumentExceptionWithSpecificMessage()
                                                                                         throws java.lang.Throwable
        Asks for a short Publisher (length 10) and issues a random, negative request() call which should trigger an onError call with an IllegalArgumentException.

        Verifies rule: 3.9

        The test is not executed if PublisherVerification.maxElementsFromPublisher() is less than 10.

        Note that this test expects the IllegalArgumentException being signalled through onError, not by throwing from request() (which is also forbidden) or signalling the error by any other means (i.e., through the Thread.currentThread().getUncaughtExceptionHandler() for example).

        Note also that requesting and emission may happen concurrently and honoring this rule may require extra coordination within the Publisher.

        If this test fails, the following could be checked within the Publisher implementation:

        Throws:
        java.lang.Throwable

      • required_spec313_cancelMustMakeThePublisherEventuallyDropAllReferencesToTheSubscriber

        void required_spec313_cancelMustMakeThePublisherEventuallyDropAllReferencesToTheSubscriber()
                                                                                    throws java.lang.Throwable
        Asks for a short Publisher (length 3) requests and consumes one element from it, cancels the Subscription , calls System.gc() and then checks if all references to the test Subscriber has been dropped (by checking the WeakReference has been emptied).

        Verifies rule: 3.13

        The test is not executed if PublisherVerification.maxElementsFromPublisher() is less than 3.

        If this test fails, the following could be checked within the Publisher implementation:

        • the TestEnvironment has large enough timeout specified in case the Publisher has some time-delay behavior,
        • make sure the required_createPublisher1MustProduceAStreamOfExactly1Element() and required_createPublisher3MustProduceAStreamOfExactly3Elements() tests pass,
        • the cancellation indicator flag is properly persisted (may require volatile) and checked as part of the signal emission process.
        • the Publisher stores the Subscriber reference somewhere which is then not cleaned up when the Subscriber is cancelled. Note that this may happen on many code paths in a Publisher, for example in an emission loop that terminates because of the cancel signal or because reaching a terminal state. Note also that eagerly nulling Subscriber references may not be necessary for this test to pass in case there is a self-contained chain of them (i.e., Publisher.subscribe() creates a chain of fresh Subscriber instances where each of them only references their downstream Subscriber thus the chain can get GC'd when the reference to the final Subscriber is dropped).
        Throws:
        java.lang.Throwable

      • required_spec317_mustSupportACumulativePendingElementCountUpToLongMaxValue

        void required_spec317_mustSupportACumulativePendingElementCountUpToLongMaxValue()
                                                                         throws java.lang.Throwable
        Asks for a short Publisher (length 3) and requests Long.MAX_VALUE from it in total (split across two Long.MAX_VALUE / 2 and one request(1)), verifying that the Publisher emits all of its items and completes normally.

        Verifies rule: 3.17

        The test is not executed if PublisherVerification.maxElementsFromPublisher() is less than 3.

        If this test fails, the following could be checked within the Publisher implementation:

        • the TestEnvironment has large enough timeout specified in case the Publisher has some time-delay behavior,
        • make sure the required_createPublisher1MustProduceAStreamOfExactly1Element() and required_createPublisher3MustProduceAStreamOfExactly3Elements() tests pass,
        • if the Publisher implementation considers the cumulative request amount it receives,
        • if the Publisher implements adding individual request amounts together properly (not overflowing into zero or negative pending request amounts) or not properly deducing the number of emitted items from the pending amount,
        • if the Publisher doesn't lose any request() signal and the state transition from idle -> emitting or emitting -> keep emitting works properly.
        Throws:
        java.lang.Throwable

      • required_spec317_mustNotSignalOnErrorWhenPendingAboveLongMaxValue

        void required_spec317_mustNotSignalOnErrorWhenPendingAboveLongMaxValue()
                                                                throws java.lang.Throwable
        Asks for a very long Publisher (up to Integer.MAX_VALUE), requests Long.MAX_VALUE - 1 after each received item and expects no failure due to a potential overflow in the pending emission count while consuming 10 items and cancelling the sequence.

        Verifies rule: 3.17

        The test is not executed if PublisherVerification.maxElementsFromPublisher() is less than Integer.MAX_VALUE.

        The request pattern is one request(1) upfront and ten request(Long.MAX_VALUE - 1) after.

        If this test fails, the following could be checked within the Publisher implementation:

        • the TestEnvironment has large enough timeout specified in case the Publisher has some time-delay behavior,
        • make sure the required_createPublisher1MustProduceAStreamOfExactly1Element() and required_createPublisher3MustProduceAStreamOfExactly3Elements() tests pass,
        • if the Publisher implementation considers the cumulative request amount it receives,
        • if the Publisher implements adding individual request amounts together properly (not overflowing into zero or negative pending request amounts) or not properly deducing the number of emitted items from the pending amount,
        • if the Publisher doesn't lose any request() signal and the state transition from idle -> emitting or emitting -> keep emitting works properly.
        Throws:
        java.lang.Throwable