--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/test/jdk/java/net/httpclient/reactivestreams-tck/org/reactivestreams/tck/flow/support/SubscriberBlackboxVerificationRules.java Tue Jul 02 13:25:51 2019 +0100
@@ -0,0 +1,395 @@
+/*
+ * Copyright (c) 2019, Oracle and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+
+package org.reactivestreams.tck.flow.support;
+
+import org.reactivestreams.tck.SubscriberBlackboxVerification;
+
+/**
+ * Internal TCK use only.
+ * Add / Remove tests for SubscriberBlackboxVerification here to make sure that they arre added/removed in the other places.
+ */
+public interface SubscriberBlackboxVerificationRules {
+ /**
+ * Asks for a {@code Subscriber} instance, expects it to call {@code request()} in
+ * a timely manner and signals as many {@code onNext} items as the very first request
+ * amount specified by the {@code Subscriber}.
+ * <p>
+ * <b>Verifies rule:</b> <a href='https://github.com/reactive-streams/reactive-streams-jvm#2.1'>2.1</a>
+ * <p>
+ * Notes:
+ * <ul>
+ * <li>This test emits the number of items requested thus the {@code Subscriber} implementation
+ * should not request too much.</li>
+ * <li>Only the very first {@code request} amount is considered.</li>
+ * <li>This test doesn't signal {@code onComplete} after the first set of {@code onNext} signals
+ * has been emitted and may cause resource leak in
+ * {@code Subscriber}s that expect a finite {@code Publisher}.</li>
+ * <li>The test ignores cancellation from the {@code Subscriber} and emits the requested amount regardless.</li>
+ * </ul>
+ * <p>
+ * If this test fails, the following could be checked within the {@code Subscriber} implementation:
+ * <ul>
+ * <li>if the {@code Subscriber} requires external stimulus to begin requesting; override the
+ * {@link SubscriberBlackboxVerification#triggerRequest(org.reactivestreams.Subscriber)} method
+ * in this case,</li>
+ * <li>the {@code TestEnvironment} has large enough timeout specified in case the {@code Subscriber} has some time-delay behavior,</li>
+ * <li>if the {@code Subscriber} requests zero or a negative value in some circumstances,</li>
+ * <li>if the {@code Subscriber} throws an unchecked exception from its {@code onSubscribe} or
+ * {@code onNext} methods.
+ * </ul>
+ */
+ void required_spec201_blackbox_mustSignalDemandViaSubscriptionRequest() throws Throwable;
+ /**
+ * Currently, this test is skipped because there is no agreed upon approach how
+ * to detect if the {@code Subscriber} really goes async or just responds in
+ * a timely manner.
+ * <p>
+ * <b>Verifies rule:</b> <a href='https://github.com/reactive-streams/reactive-streams-jvm#2.2'>2.2</a>
+ */
+ void untested_spec202_blackbox_shouldAsynchronouslyDispatch() throws Exception;
+ /**
+ * Asks for a {@code Subscriber}, signals an {@code onSubscribe} followed by an {@code onComplete} synchronously,
+ * and checks if neither {@code request} nor {@code cancel} was called from within the {@code Subscriber}'s
+ * {@code onComplete} implementation.
+ * <p>
+ * <b>Verifies rule:</b> <a href='https://github.com/reactive-streams/reactive-streams-jvm#2.3'>2.3</a>
+ * <p>
+ * Notes:
+ * <ul>
+ * <li>The test checks for the presensce of method named "onComplete" in the current stacktrace when handling
+ * the {@code request} or {@code cancel} calls in the test's own {@code Subscription}.
+ * </ul>
+ * <p>
+ * If this test fails, the following could be checked within the {@code Subscriber} implementation:
+ * <ul>
+ * <li>no calls happen to {@code request} or {@code cancel} in response to an {@code onComplete}
+ * directly or indirectly,</li>
+ * <li>if the {@code Subscriber} throws an unchecked exception from its {@code onSubscribe} or
+ * {@code onComplete} methods.
+ * </ul>
+ */
+ void required_spec203_blackbox_mustNotCallMethodsOnSubscriptionOrPublisherInOnComplete() throws Throwable;
+ /**
+ * Asks for a {@code Subscriber}, signals an {@code onSubscribe} followed by an {@code onError} synchronously,
+ * and checks if neither {@code request} nor {@code cancel} was called from within the {@code Subscriber}'s
+ * {@code onComplete} implementation.
+ * <p>
+ * <b>Verifies rule:</b> <a href='https://github.com/reactive-streams/reactive-streams-jvm#2.3'>2.3</a>
+ * <p>
+ * Notes:
+ * <ul>
+ * <li>The test checks for the presensce of method named "onError" in the current stacktrace when handling
+ * the {@code request} or {@code cancel} calls in the test's own {@code Subscription}.
+ * </ul>
+ * <p>
+ * If this test fails, the following could be checked within the {@code Subscriber} implementation:
+ * <ul>
+ * <li>no calls happen to {@code request} or {@code cancel} in response to an {@code onError}
+ * directly or indirectly,</li>
+ * <li>if the {@code Subscriber} throws an unchecked exception from its {@code onSubscribe} or
+ * {@code onError} methods.
+ * </ul>
+ */
+ void required_spec203_blackbox_mustNotCallMethodsOnSubscriptionOrPublisherInOnError() throws Throwable;
+ /**
+ * Currently, this test is skipped because there is no way to check what the {@code Subscriber} "considers"
+ * since rule §2.3 forbids interaction from within the {@code onError} and {@code onComplete} methods.
+ * <p>
+ * <b>Verifies rule:</b> <a href='https://github.com/reactive-streams/reactive-streams-jvm#2.4'>2.4</a>
+ * <p>
+ * Notes:
+ * <ul>
+ * <li>It would be possible to check if there was an async interaction with the test's {@code Subscription}
+ * within a grace period but such check is still not generally decisive.</li>
+ * </ul>
+ */
+ void untested_spec204_blackbox_mustConsiderTheSubscriptionAsCancelledInAfterRecievingOnCompleteOrOnError() throws Exception;
+ /**
+ * Asks for a {@code Subscriber}, signals {@code onSubscribe} twice synchronously and expects the second {@code Subscription} gets
+ * cancelled in a timely manner and without any calls to its {@code request} method.
+ * <p>
+ * <b>Verifies rule:</b> <a href='https://github.com/reactive-streams/reactive-streams-jvm#2.5'>2.5</a>
+ * <p>
+ * Notes:
+ * <ul>
+ * <li>The test doesn't signal any other events than {@code onSubscribe} and may cause resource leak in
+ * {@code Subscriber}s that expect a finite {@code Publisher}.
+ * </ul>
+ * <p>
+ * If this test fails, the following could be checked within the {@code Subscriber} implementation:
+ * <ul>
+ * <li>if the {@code Subscribe.onSubscribe} implementation actually tries to detect multiple calls to it,</li>
+ * <li>if the second {@code Subscription} is cancelled asynchronously and that takes longer time than
+ * the {@code TestEnvironment}'s timeout permits.</li>
+ * </ul>
+ */
+ void required_spec205_blackbox_mustCallSubscriptionCancelIfItAlreadyHasAnSubscriptionAndReceivesAnotherOnSubscribeSignal() throws Exception;
+
+ /**
+ * Currently, this test is skipped because it requires more control over the {@code Subscriber} implementation
+ * to make it cancel the {@code Subscription} for some external condition.
+ * <p>
+ * <b>Verifies rule:</b> <a href='https://github.com/reactive-streams/reactive-streams-jvm#2.6'>2.6</a>
+ */
+ void untested_spec206_blackbox_mustCallSubscriptionCancelIfItIsNoLongerValid() throws Exception;
+ /**
+ * Currently, this test is skipped because it requires more control over the {@code Subscriber} implementation
+ * to issue requests based on external stimulus.
+ * <p>
+ * <b>Verifies rule:</b> <a href='https://github.com/reactive-streams/reactive-streams-jvm#2.7'>2.7</a>
+ */
+ void untested_spec207_blackbox_mustEnsureAllCallsOnItsSubscriptionTakePlaceFromTheSameThreadOrTakeCareOfSynchronization() throws Exception;
+ /**
+ * Currently, this test is skipped because there is no way to make the {@code Subscriber} implementation
+ * cancel the test's {@code Subscription} and check the outcome of sending {@code onNext}s after such
+ * cancel.
+ * <p>
+ * <b>Verifies rule:</b> <a href='https://github.com/reactive-streams/reactive-streams-jvm#2.8'>2.8</a>
+ */
+ void untested_spec208_blackbox_mustBePreparedToReceiveOnNextSignalsAfterHavingCalledSubscriptionCancel() throws Throwable;
+ /**
+ * Asks for a {@code Subscriber}, expects it to request some amount and in turn be able to receive an {@code onComplete}
+ * synchronously from the {@code request} call without any {@code onNext} signals before that.
+ * <p>
+ * <b>Verifies rule:</b> <a href='https://github.com/reactive-streams/reactive-streams-jvm#2.9'>2.9</a>
+ * <p>
+ * Notes:
+ * <ul>
+ * <li>The test ignores cancellation from the {@code Subscriber}.</li>
+ * <li>Invalid request amounts are ignored by this test.</li>
+ * <li>Concurrent calls to the test's {@code Subscription.request()} must be externally synchronized, otherwise
+ * such case results probabilistically in multiple {@code onComplete} calls by the test.</li>
+ * </ul>
+ * <p>
+ * If this test fails, the following could be checked within the {@code Subscriber} implementation:
+ * <ul>
+ * <li>if the {@code Subscriber} throws an unchecked exception from its {@code onSubscribe} or
+ * {@code onComplete} methods.
+ * <li>if the {@code Subscriber} requires external stimulus to begin requesting; override the
+ * {@link SubscriberBlackboxVerification#triggerRequest(org.reactivestreams.Subscriber)} method
+ * in this case,</li>
+ * </ul>
+ */
+ void required_spec209_blackbox_mustBePreparedToReceiveAnOnCompleteSignalWithPrecedingRequestCall() throws Throwable;
+ /**
+ * Asks for a {@code Subscriber} and expects it to handle {@code onComplete} independent of whether the {@code Subscriber}
+ * requests items or not.
+ * <p>
+ * <b>Verifies rule:</b> <a href='https://github.com/reactive-streams/reactive-streams-jvm#2.9'>2.9</a>
+ * <p>
+ * Notes:
+ * <ul>
+ * <li>Currently, the test doesn't call {@code onSubscribe} on the {@code Subscriber} which violates §1.9.
+ * </ul>
+ * <p>
+ * If this test fails, the following could be checked within the {@code Subscriber} implementation:
+ * <ul>
+ * <li>if the {@code Subscriber} throws an unchecked exception from its {@code onSubscribe} or
+ * {@code onComplete} methods.
+ * </ul>
+ */
+ void required_spec209_blackbox_mustBePreparedToReceiveAnOnCompleteSignalWithoutPrecedingRequestCall() throws Throwable;
+ /**
+ * Asks for a {@code Subscriber}, signals {@code onSubscribe} followed by an {@code onError} synchronously.
+ * <p>
+ * <b>Verifies rule:</b> <a href='https://github.com/reactive-streams/reactive-streams-jvm#2.10'>2.10</a>
+ * <p>
+ * Notes:
+ * <ul>
+ * <li>Despite the method name, the test doesn't expect a request signal from {@code Subscriber} and emits the
+ * {@code onError} signal anyway.
+ * </ul>
+ * <p>
+ * If this test fails, the following could be checked within the {@code Subscriber} implementation:
+ * <ul>
+ * <li>if the {@code Subscriber} throws an unchecked exception from its {@code onSubscribe} or
+ * {@code onError} methods.
+ * </ul>
+ */
+ void required_spec210_blackbox_mustBePreparedToReceiveAnOnErrorSignalWithPrecedingRequestCall() throws Throwable;
+
+ /**
+ * Asks for a {@code Subscriber}, signals {@code onSubscribe} followed by an {@code onError} synchronously.
+ * <p>
+ * <b>Verifies rule:</b> <a href='https://github.com/reactive-streams/reactive-streams-jvm#2.10'>2.10</a>
+ * <p>
+ * If this test fails, the following could be checked within the {@code Subscriber} implementation:
+ * <ul>
+ * <li>if the {@code Subscriber} throws an unchecked exception from its {@code onSubscribe} or
+ * {@code onError} methods.
+ * </ul>
+ */
+ void required_spec210_blackbox_mustBePreparedToReceiveAnOnErrorSignalWithoutPrecedingRequestCall() throws Throwable;
+
+ /**
+ * Currently, this test is skipped because it would require analyzing what the {@code Subscriber} implementation
+ * does.
+ * <p>
+ * <b>Verifies rule:</b> <a href='https://github.com/reactive-streams/reactive-streams-jvm#2.11'>2.11</a>
+ */
+ void untested_spec211_blackbox_mustMakeSureThatAllCallsOnItsMethodsHappenBeforeTheProcessingOfTheRespectiveEvents() throws Exception;
+ /**
+ * Currently, this test is skipped because the test for
+ * {@link #required_spec205_blackbox_mustCallSubscriptionCancelIfItAlreadyHasAnSubscriptionAndReceivesAnotherOnSubscribeSignal §2.5}
+ * is in a better position to test for handling the reuse of the same {@code Subscriber}.
+ * <p>
+ * <b>Verifies rule:</b> <a href='https://github.com/reactive-streams/reactive-streams-jvm#2.12'>2.12</a>
+ * <p>
+ * Notes:
+ * <ul>
+ * <li>In addition to §2.5, this rule could be better verified when testing a {@code Publisher}'s subscription behavior.
+ * </ul>
+ */
+ void untested_spec212_blackbox_mustNotCallOnSubscribeMoreThanOnceBasedOnObjectEquality() throws Throwable;
+ /**
+ * Currently, this test is skipped because it would require more control over the {@code Subscriber} to
+ * fail internally in response to a set of legal event emissions, not throw any exception from the {@code Subscriber}
+ * methods and have it cancel the {@code Subscription}.
+ * <p>
+ * <b>Verifies rule:</b> <a href='https://github.com/reactive-streams/reactive-streams-jvm#2.13'>2.13</a>
+ */
+ void untested_spec213_blackbox_failingOnSignalInvocation() throws Exception;
+ /**
+ * Asks for a {@code Subscriber} and signals an {@code onSubscribe} event with {@code null} as a parameter and
+ * expects an immediate {@code NullPointerException} to be thrown by the {@code Subscriber.onSubscribe} method.
+ * <p>
+ * <b>Verifies rule:</b> <a href='https://github.com/reactive-streams/reactive-streams-jvm#2.13'>2.13</a>
+ * <p>
+ * If this test fails, the following could be checked within the {@code Subscriber} implementation:
+ * <ul>
+ * <li>if the {@code Subscriber} throws a {@code NullPointerException} from its {@code onSubscribe} method
+ * in response to a {@code null} parameter and not some other unchecked exception or no exception at all.
+ * </ul>
+ */
+ void required_spec213_blackbox_onSubscribe_mustThrowNullPointerExceptionWhenParametersAreNull() throws Throwable;
+ /**
+ * Asks for a {@code Subscriber}, signals an {@code onSubscribe} event followed by a
+ * {@code onNext} with {@code null} as a parameter and
+ * expects an immediate {@code NullPointerException} to be thrown by the {@code Subscriber.onNext} method.
+ * <p>
+ * <b>Verifies rule:</b> <a href='https://github.com/reactive-streams/reactive-streams-jvm#2.13'>2.13</a>
+ * <p>
+ * Notes:
+ * <ul>
+ * <li>The test ignores cancellation and requests from the {@code Subscriber} and emits the {@code onNext}
+ * signal with a {@code null} parameter anyway.</li>
+ * </ul>
+ * <p>
+ * If this test fails, the following could be checked within the {@code Subscriber} implementation:
+ * <ul>
+ * <li>if the {@code Subscriber} throws a {@code NullPointerException} from its {@code onNext} method
+ * in response to a {@code null} parameter and not some other unchecked exception or no exception at all.
+ * </ul>
+ */
+ void required_spec213_blackbox_onNext_mustThrowNullPointerExceptionWhenParametersAreNull() throws Throwable;
+ /**
+ * Asks for a {@code Subscriber}, signals an {@code onSubscribe} event followed by a
+ * {@code onError} with {@code null} as a parameter and
+ * expects an immediate {@code NullPointerException} to be thrown by the {@code Subscriber.onError} method.
+ * <p>
+ * <b>Verifies rule:</b> <a href='https://github.com/reactive-streams/reactive-streams-jvm#2.13'>2.13</a>
+ * <p>
+ * Notes:
+ * <ul>
+ * <li>The test ignores cancellation from the {@code Subscriber} and emits the {@code onError}
+ * signal with a {@code null} parameter anyway.</li>
+ * </ul>
+ * <p>
+ * If this test fails, the following could be checked within the {@code Subscriber} implementation:
+ * <ul>
+ * <li>if the {@code Subscriber} throws a {@code NullPointerException} from its {@code onNext} method
+ * in response to a {@code null} parameter and not some other unchecked exception or no exception at all.
+ * </ul>
+ */
+ void required_spec213_blackbox_onError_mustThrowNullPointerExceptionWhenParametersAreNull() throws Throwable;
+ /**
+ * Currently, this test is skipped because there is no agreed upon way for specifying, enforcing and testing
+ * a {@code Subscriber} with an arbitrary context.
+ * <p>
+ * <b>Verifies rule:</b> <a href='https://github.com/reactive-streams/reactive-streams-jvm#3.1'>3.1</a>
+ */
+ void untested_spec301_blackbox_mustNotBeCalledOutsideSubscriberContext() throws Exception;
+ /**
+ * Currently, this test is skipped because element production is the responsibility of the {@code Publisher} and
+ * a {@code Subscription} is not expected to be the active element in an established subscription.
+ * <p>
+ * <b>Verifies rule:</b> <a href='https://github.com/reactive-streams/reactive-streams-jvm#3.8'>3.8</a>
+ */
+ void untested_spec308_blackbox_requestMustRegisterGivenNumberElementsToBeProduced() throws Throwable;
+ /**
+ * Currently, this test is skipped because element production is the responsibility of the {@code Publisher} and
+ * a {@code Subscription} is not expected to be the active element in an established subscription.
+ * <p>
+ * <b>Verifies rule:</b> <a href='https://github.com/reactive-streams/reactive-streams-jvm#3.10'>3.10</a>
+ * <p>
+ * Notes:
+ * <ul>
+ * <li>This could be tested with a synchronous source currently not available within the TCK.</li>
+ * </ul>
+ */
+ void untested_spec310_blackbox_requestMaySynchronouslyCallOnNextOnSubscriber() throws Exception;
+ /**
+ * Currently, this test is skipped because signal production is the responsibility of the {@code Publisher} and
+ * a {@code Subscription} is not expected to be the active element in an established subscription.
+ * <p>
+ * <b>Verifies rule:</b> <a href='https://github.com/reactive-streams/reactive-streams-jvm#3.11'>3.11</a>
+ * <p>
+ * Notes:
+ * <ul>
+ * <li>Tests {@link #required_spec209_blackbox_mustBePreparedToReceiveAnOnCompleteSignalWithPrecedingRequestCall() §2.9}
+ * and {@link #required_spec210_blackbox_mustBePreparedToReceiveAnOnErrorSignalWithPrecedingRequestCall() §2.10} are
+ * supposed to cover this case from the {@code Subscriber's} perspective.</li>
+ * </ul>
+ */
+ void untested_spec311_blackbox_requestMaySynchronouslyCallOnCompleteOrOnError() throws Exception;
+ /**
+ * Currently, this test is skipped because it is the responsibility of the {@code Publisher} deal with the case
+ * that all subscribers have cancelled their subscription.
+ * <p>
+ * <b>Verifies rule:</b> <a href='https://github.com/reactive-streams/reactive-streams-jvm#3.14'>3.14</a>
+ * <p>
+ * Notes:
+ * <ul>
+ * <li>The specification lists this as an optional behavior because only some {@code Publisher} implementations
+ * (most likely {@code Processor}s) would coordinate with multiple {@code Subscriber}s.</li>
+ * </ul>
+ */
+ void untested_spec314_blackbox_cancelMayCauseThePublisherToShutdownIfNoOtherSubscriptionExists() throws Exception;
+ /**
+ * Currently, this test is skipped because it requires more control over the {@code Subscriber} implementation
+ * thus there is no way to detect that the {@code Subscriber} called its own {@code onError} method in response
+ * to an exception thrown from {@code Subscription.cancel}.
+ * <p>
+ * <b>Verifies rule:</b> <a href='https://github.com/reactive-streams/reactive-streams-jvm#3.15'>3.15</a>
+ */
+ void untested_spec315_blackbox_cancelMustNotThrowExceptionAndMustSignalOnError() throws Exception;
+ /**
+ * Currently, this test is skipped because it requires more control over the {@code Subscriber} implementation
+ * thus there is no way to detect that the {@code Subscriber} called its own {@code onError} method in response
+ * to an exception thrown from {@code Subscription.request}.
+ * <p>
+ * <b>Verifies rule:</b> <a href='https://github.com/reactive-streams/reactive-streams-jvm#3.16'>3.16</a>
+ */
+ void untested_spec316_blackbox_requestMustNotThrowExceptionAndMustOnErrorTheSubscriber() throws Exception;
+}