001/*************************************************** 002 * Licensed under MIT No Attribution (SPDX: MIT-0) * 003 ***************************************************/ 004 005package org.reactivestreams.tck.flow.support; 006 007/** 008 * Internal TCK use only. 009 * Add / Remove tests for PublisherVerification here to make sure that they arre added/removed in the other places. 010 */ 011public interface PublisherVerificationRules { 012 /** 013 * Validates that the override of {@link org.reactivestreams.tck.PublisherVerification#maxElementsFromPublisher()} 014 * returns a non-negative value. 015 */ 016 void required_validate_maxElementsFromPublisher() throws Exception; 017 /** 018 * Validates that the override of {@link org.reactivestreams.tck.PublisherVerification#boundedDepthOfOnNextAndRequestRecursion()} 019 * returns a positive value. 020 */ 021 void required_validate_boundedDepthOfOnNextAndRequestRecursion() throws Exception; 022 /** 023 * Asks for a {@code Publisher} that should emit exactly one item and complete (both within a 024 * timeout specified by {@link org.reactivestreams.tck.TestEnvironment#defaultTimeoutMillis()}) 025 * in response to a request(1). 026 * <p> 027 * The test is not executed if {@link org.reactivestreams.tck.PublisherVerification#maxElementsFromPublisher()} returns zero. 028 * If this test fails, the following could be checked within the {@code Publisher} implementation: 029 * <ul> 030 * <li>the {@code Publisher.subscribe(Subscriber)} method has actual implementation,</li> 031 * <li>in the {@code Publisher.subscribe(Subscriber)} method, if there is an upstream {@code Publisher}, 032 * that {@code Publisher} is actually subscribed to,</li> 033 * <li>if the {@code Publisher} is part of a chain, all elements actually issue a {@code request()} call 034 * in response to the test subscriber or by default to their upstream,</li> 035 * <li>in the {@code Publisher.subscribe(Subscriber)} method, the {@code Subscriber.onSubscribe} is called 036 * as part of the preparation process (usually before subscribing to other {@code Publisher}s),</li> 037 * <li>if the {@code Publisher} implementation works for a consumer that calls {@code request(1)},</li> 038 * <li>if the {@code Publisher} implementation is able to emit an {@code onComplete} without requests,</li> 039 * <li>that the {@code Publisher} implementation does not emit more than the allowed elements (exactly one).</li> 040 * </ul> 041 */ 042 void required_createPublisher1MustProduceAStreamOfExactly1Element() throws Throwable; 043 /** 044 * Asks for a {@code Publisher} that should emit exactly three items and complete (all within a 045 * timeout specified by {@link org.reactivestreams.tck.TestEnvironment#defaultTimeoutMillis()}). 046 * <p> 047 * The test is not executed if {@link org.reactivestreams.tck.PublisherVerification#maxElementsFromPublisher()} is less than 3. 048 * <p> 049 * The tests requests one-by-one and verifies each single response item arrives in time. 050 * <p> 051 * If this test fails, the following could be checked within the {@code Publisher} implementation: 052 * <ul> 053 * <li>the {@code Publisher.subscribe(Subscriber)} method has actual implementation,</li> 054 * <li>in the {@code Publisher.subscribe(Subscriber)} method, if there is an upstream {@code Publisher}, 055 * that {@code Publisher} is actually subscribed to,</li> 056 * <li>if the {@code Publisher} is part of a chain, all elements actually issue a {@code request()} call 057 * in response to the test subscriber or by default to their upstream,</li> 058 * <li>in the {@code Publisher.subscribe(Subscriber)} method, the {@code Subscriber.onSubscribe} is called 059 * as part of the preparation process (usually before subscribing to other {@code Publisher}s),</li> 060 * <li>if the {@code Publisher} implementation works for a subscriber that calls {@code request(1)} after consuming an item,</li> 061 * <li>if the {@code Publisher} implementation is able to emit an {@code onComplete} without requests.</li> 062 * </ul> 063 */ 064 void required_createPublisher3MustProduceAStreamOfExactly3Elements() throws Throwable; 065 /** 066 * Asks for a {@code Publisher} that responds to a request pattern of 0 (not requesting upfront), 1, 1 and 2 067 * in a timely manner. 068 * <p> 069 * <b>Verifies rule:</b> <a href='https://github.com/reactive-streams/reactive-streams-jvm#1.1'>1.1</a> 070 * <p> 071 * The test is not executed if {@link org.reactivestreams.tck.PublisherVerification#maxElementsFromPublisher()} is less than 5. 072 * <p> 073 * This test ensures that the {@code Publisher} implementation correctly responds to {@code request()} calls that in 074 * total are less than the number of elements this {@code Publisher} could emit (thus the completion event won't be emitted). 075 * <p> 076 * If this test fails, the following could be checked within the {@code Publisher} implementation: 077 * <ul> 078 * <li>the {@code TestEnvironment} has large enough timeout specified in case the {@code Publisher} has some time-delay behavior,</li> 079 * <li>make sure the {@link #required_createPublisher1MustProduceAStreamOfExactly1Element()} and {@link #required_createPublisher3MustProduceAStreamOfExactly3Elements()} tests pass,</li> 080 * <li>if the {@code Publisher} implementation considers the cumulative request amount it receives,</li> 081 * <li>if the {@code Publisher} doesn't lose any {@code request()} signal and the state transition from idle -> emitting or emitting -> keep emitting works properly.</li> 082 * </ul> 083 */ 084 void required_spec101_subscriptionRequestMustResultInTheCorrectNumberOfProducedElements() throws Throwable; 085 /** 086 * Asks for a short {@code Publisher} and verifies that requesting once and with more than the length (but bounded) results in the 087 * correct number of items to be emitted (i.e., length 3 and request 10) followed by an {@code onComplete} signal. 088 * <p> 089 * <b>Verifies rule:</b> <a href='https://github.com/reactive-streams/reactive-streams-jvm#1.2'>1.2</a> 090 * <p> 091 * The test is not executed if {@link org.reactivestreams.tck.PublisherVerification#maxElementsFromPublisher()} is less than 3. 092 * <p> 093 * This test ensures that the {@code Publisher} implementation can deal with larger requests than the number of items it can produce. 094 * <p> 095 * If this test fails, the following could be checked within the {@code Publisher} implementation: 096 * <ul> 097 * <li>the {@code TestEnvironment} has large enough timeout specified in case the {@code Publisher} has some time-delay behavior,</li> 098 * <li>make sure the {@link #required_createPublisher1MustProduceAStreamOfExactly1Element()} and {@link #required_createPublisher3MustProduceAStreamOfExactly3Elements()} tests pass.</li> 099 * </ul> 100 */ 101 void required_spec102_maySignalLessThanRequestedAndTerminateSubscription() throws Throwable; 102 /** 103 * Asks for a short {@code Publisher} (i.e., length 10), repeatedly subscribes to this {@code Publisher}, requests items 104 * one by one and verifies the {@code Publisher} calls the {@code onXXX} methods non-overlappingly. 105 * <p> 106 * <b>Verifies rule:</b> <a href='https://github.com/reactive-streams/reactive-streams-jvm#1.3'>1.3</a> 107 * <p> 108 * The test is not executed if {@link org.reactivestreams.tck.PublisherVerification#maxElementsFromPublisher()} is less than 10. 109 * <p> 110 * Note that this test is probabilistic, that is, may not capture any concurrent invocation in a {code Publisher} implementation. 111 * Note also that this test is sensitive to cases when a {@code request()} call in {@code onSubscribe()} triggers an asynchronous 112 * call to the other {@code onXXX} methods. In contrast, the test allows synchronous call chain of 113 * {@code onSubscribe -> request -> onNext}. 114 * <p> 115 * If this test fails, the following could be checked within the {@code Publisher} implementation: 116 * <ul> 117 * <li>the {@code TestEnvironment} has large enough timeout specified in case the {@code Publisher} has some time-delay behavior,</li> 118 * <li>make sure the {@link #required_createPublisher1MustProduceAStreamOfExactly1Element()} and {@link #required_createPublisher3MustProduceAStreamOfExactly3Elements()} tests pass,</li> 119 * <li>if a {@code request()} call from {@code onSubscribe()} could trigger an asynchronous call to {@code onNext()} and if so, make sure 120 * such {@code request()} calls are deferred until the call to {@code onSubscribe()} returns normally.</li> 121 * </ul> 122 */ 123 void stochastic_spec103_mustSignalOnMethodsSequentially() throws Throwable; 124 /** 125 * Asks for an error {@code Publisher} that should call {@code onSubscribe} exactly once 126 * followed by a single call to {@code onError()} without receiving any requests and otherwise 127 * not throwing any exception. 128 * <p> 129 * <b>Verifies rule:</b> <a href='https://github.com/reactive-streams/reactive-streams-jvm#1.4'>1.4</a> 130 * <p> 131 * The test is not executed if {@code PublisherVerification.createErrorPublisher()} returns null. 132 * <p> 133 * If this test fails, the following could be checked within the error {@code Publisher} implementation: 134 * <ul> 135 * <li>the {@code Publisher.subscribe(Subscriber)} method has actual implementation,</li> 136 * <li>in the {@code Publisher.subscribe(Subscriber)} method, if there is an upstream {@code Publisher}, 137 * that {@code Publisher} is actually subscribed to,</li> 138 * <li>if the {@code Publisher} implementation does signal an {@code onSubscribe} before signalling {@code onError},</li> 139 * <li>if the {@code Publisher} implementation is able to emit an {@code onError} without requests,</li> 140 * <li>if the {@code Publisher} is non-empty as this test requires a {@code Publisher} to signal an 141 * {@code onError} eagerly.</li> 142 * </ul> 143 */ 144 void optional_spec104_mustSignalOnErrorWhenFails() throws Throwable; 145 /** 146 * Asks for a short {@code Publisher} (i.e., length 3) and verifies, after requesting one by one, the sequence 147 * completes normally. 148 * <p> 149 * <b>Verifies rule:</b> <a href='https://github.com/reactive-streams/reactive-streams-jvm#1.5'>1.5</a> 150 * <p> 151 * The test is not executed if {@link org.reactivestreams.tck.PublisherVerification#maxElementsFromPublisher()} is less than 3. 152 * <p> 153 * Note that the tests requests 1 after the items have been received and before expecting an {@code onComplete} signal. 154 * <p> 155 * If this test fails, the following could be checked within the {@code Publisher} implementation: 156 * <ul> 157 * <li>the {@code TestEnvironment} has large enough timeout specified in case the {@code Publisher} has some time-delay behavior,</li> 158 * <li>make sure the {@link #required_createPublisher1MustProduceAStreamOfExactly1Element()} and {@link #required_createPublisher3MustProduceAStreamOfExactly3Elements()} tests pass,</li> 159 * </ul> 160 */ 161 void required_spec105_mustSignalOnCompleteWhenFiniteStreamTerminates() throws Throwable; 162 /** 163 * Asks for an empty {@code Publisher} (i.e., length 0) and verifies it completes in a timely manner. 164 * <p> 165 * <b>Verifies rule:</b> <a href='https://github.com/reactive-streams/reactive-streams-jvm#1.5'>1.5</a> 166 * <p> 167 * Note that the tests requests 1 before expecting an {@code onComplete} signal. 168 * <p> 169 * If this test fails, the following could be checked within the {@code Publisher} implementation: 170 * <ul> 171 * <li>the {@code TestEnvironment} has large enough timeout specified in case the {@code Publisher} has some time-delay behavior,</li> 172 * <li>if the {@code Publisher} is non-empty as this test requires a {@code Publisher} without items.</li> 173 * </ul> 174 */ 175 void optional_spec105_emptyStreamMustTerminateBySignallingOnComplete() throws Throwable; 176 /** 177 * Currently, this test is skipped because it is unclear this rule can be effectively checked 178 * on a {@code Publisher} instance without looking into or hooking into the implementation of it. 179 * <p> 180 * <b>Verifies rule:</b> <a href='https://github.com/reactive-streams/reactive-streams-jvm#1.6'>1.6</a> 181 */ 182 void untested_spec106_mustConsiderSubscriptionCancelledAfterOnErrorOrOnCompleteHasBeenCalled() throws Throwable; 183 /** 184 * Asks for a single-element {@code Publisher} and checks if requesting after the terminal event doesn't 185 * lead to more items or terminal signals to be emitted. 186 * <p> 187 * <b>Verifies rule:</b> <a href='https://github.com/reactive-streams/reactive-streams-jvm#1.7'>1.7</a> 188 * <p> 189 * The test is not executed if {@link org.reactivestreams.tck.PublisherVerification#maxElementsFromPublisher()} is less than 1. 190 * <p> 191 * The tests requests more items than the expected {@code Publisher} length upfront and some more items after its completion. 192 * <p> 193 * If this test fails, the following could be checked within the {@code Publisher} implementation: 194 * <ul> 195 * <li>the {@code TestEnvironment} has large enough timeout specified in case the {@code Publisher} has some time-delay behavior,</li> 196 * <li>the indication for the terminal state is properly persisted and a request call can't trigger emission of more items or another 197 * terminal signal.</li> 198 * </ul> 199 */ 200 void required_spec107_mustNotEmitFurtherSignalsOnceOnCompleteHasBeenSignalled() throws Throwable; 201 /** 202 * Currently, this test is skipped, although it is possible to validate an error {@code Publisher} along 203 * the same lines as {@link #required_spec107_mustNotEmitFurtherSignalsOnceOnCompleteHasBeenSignalled()}. 204 * <p> 205 * <b>Verifies rule:</b> <a href='https://github.com/reactive-streams/reactive-streams-jvm#1.7'>1.7</a> 206 */ 207 void untested_spec107_mustNotEmitFurtherSignalsOnceOnErrorHasBeenSignalled() throws Throwable; 208 /** 209 * Currently, this test is skipped because there was no agreement on how to verify its "eventually" requirement. 210 * <p> 211 * <b>Verifies rule:</b> <a href='https://github.com/reactive-streams/reactive-streams-jvm#1.8'>1.8</a> 212 */ 213 void untested_spec108_possiblyCanceledSubscriptionShouldNotReceiveOnErrorOrOnCompleteSignals() throws Throwable; 214 /** 215 * Asks for an empty {@code Publisher} and verifies if {@code onSubscribe} signal was emitted before 216 * any other {@code onNext}, {@code onError} or {@code onComplete} signal. 217 * <p> 218 * <b>Verifies rule:</b> <a href='https://github.com/reactive-streams/reactive-streams-jvm#1.9'>1.9</a> 219 * <p> 220 * Note that this test doesn't request anything, however, an {@code onNext} is not considered as a failure. 221 * <p> 222 * If this test fails, the following could be checked within the {@code Publisher} implementation: 223 * <ul> 224 * <li>the {@code TestEnvironment} has large enough timeout specified in case the {@code Publisher} has some time-delay behavior,</li> 225 * <li>the {@code Publisher.subscribe(Subscriber)} method has actual implementation,</li> 226 * <li>in the {@code Publisher.subscribe(Subscriber)} method, if there is an upstream {@code Publisher}, 227 * that {@code Publisher} is actually subscribed to,</li> 228 * <li>in the {@code Publisher.subscribe(Subscriber)} method, the {@code Subscriber.onSubscribe} is called 229 * as part of the preparation process (usually before subscribing to other {@code Publisher}s).</li> 230 * </ul> 231 */ 232 void required_spec109_mustIssueOnSubscribeForNonNullSubscriber() throws Throwable; 233 /** 234 * Currently, this test is skipped because there is no common agreement on what is to be considered a fatal exception and 235 * besides, {@code Publisher.subscribe} is only allowed throw a {@code NullPointerException} and any other 236 * exception would require looking into or hooking into the implementation of the {@code Publisher}. 237 * <p> 238 * <b>Verifies rule:</b> <a href='https://github.com/reactive-streams/reactive-streams-jvm#1.9'>1.9</a> 239 */ 240 void untested_spec109_subscribeShouldNotThrowNonFatalThrowable() throws Throwable; 241 /** 242 * Asks for an empty {@code Publisher} and calls {@code subscribe} on it with {@code null} that should result in 243 * a {@code NullPointerException} to be thrown. 244 * <p> 245 * <b>Verifies rule:</b> <a href='https://github.com/reactive-streams/reactive-streams-jvm#1.9'>1.9</a> 246 * <p> 247 * If this test fails, check if the {@code subscribe()} implementation has an explicit null check (or a method dereference 248 * on the {@code Subscriber}), especially if the incoming {@code Subscriber} is wrapped or stored to be used later. 249 */ 250 void required_spec109_subscribeThrowNPEOnNullSubscriber() throws Throwable; 251 /** 252 * Asks for an error {@code Publisher} that should call {@code onSubscribe} exactly once 253 * followed by a single call to {@code onError()} without receiving any requests. 254 * <p> 255 * <b>Verifies rule:</b> <a href='https://github.com/reactive-streams/reactive-streams-jvm#1.9'>1.9</a> 256 * <p> 257 * The test is not executed if {@code PublisherVerification.createErrorPublisher()} returns null. 258 * <p> 259 * The difference between this test and {@link #optional_spec104_mustSignalOnErrorWhenFails()} is that there is 260 * no explicit verification if exceptions were thrown in addition to the regular {@code onSubscribe+onError} signal pair. 261 * <p> 262 * If this test fails, the following could be checked within the error {@code Publisher} implementation: 263 * <ul> 264 * <li>the {@code Publisher.subscribe(Subscriber)} method has actual implementation,</li> 265 * <li>in the {@code Publisher.subscribe(Subscriber)} method, if there is an upstream {@code Publisher}, 266 * that {@code Publisher} is actually subscribed to,</li> 267 * <li>if the {@code Publisher} implementation is able to emit an {@code onError} without requests,</li> 268 * <li>if the {@code Publisher} is non-empty as this test expects a {@code Publisher} without items.</li> 269 * </ul> 270 */ 271 void required_spec109_mayRejectCallsToSubscribeIfPublisherIsUnableOrUnwillingToServeThemRejectionMustTriggerOnErrorAfterOnSubscribe() throws Throwable; 272 /** 273 * Currently, this test is skipped because enforcing rule ยง1.10 requires unlimited retention and reference-equal checks on 274 * all incoming {@code Subscriber} which is generally infeasible, plus reusing the same {@code Subscriber} instance is 275 * better detected (or ignored) inside {@code Subscriber.onSubscribe} when the method is called multiple times. 276 * <p> 277 * <b>Verifies rule:</b> <a href='https://github.com/reactive-streams/reactive-streams-jvm#1.10'>1.10</a> 278 */ 279 void untested_spec110_rejectASubscriptionRequestIfTheSameSubscriberSubscribesTwice() throws Throwable; 280 /** 281 * Asks for a single-element {@code Publisher} and subscribes to it twice, without consuming with either 282 * {@code Subscriber} instance 283 * (i.e., no requests are issued). 284 * <p> 285 * <b>Verifies rule:</b> <a href='https://github.com/reactive-streams/reactive-streams-jvm#1.11'>1.11</a> 286 * <p> 287 * The test is not executed if {@link org.reactivestreams.tck.PublisherVerification#maxElementsFromPublisher()} is less than 1. 288 * <p> 289 * Note that this test ignores what signals the {@code Publisher} emits. Any exception thrown through non-regular 290 * means will indicate a skipped test. 291 */ 292 void optional_spec111_maySupportMultiSubscribe() throws Throwable; 293 /** 294 * Asks for a single-element {@code Publisher} and subscribes to it twice. 295 * Each {@code Subscriber} requests for 1 element and checks if onNext or onComplete signals was received. 296 * <p> 297 * <b>Verifies rule:</b> <a href='https://github.com/reactive-streams/reactive-streams-jvm#1.11'>1.11</a>, 298 * and depends on valid implementation of rule <a href='https://github.com/reactive-streams/reactive-streams-jvm#1.5'>1.5</a> 299 * in order to verify this. 300 * <p> 301 * The test is not executed if {@link org.reactivestreams.tck.PublisherVerification#maxElementsFromPublisher()} is less than 1. 302 * <p> 303 * Any exception thrown through non-regular means will indicate a skipped test. 304 */ 305 void optional_spec111_registeredSubscribersMustReceiveOnNextOrOnCompleteSignals() throws Throwable; 306 /** 307 * Asks for a short {@code Publisher} (length 5), subscribes 3 {@code Subscriber}s to it, requests with different 308 * patterns and checks if all 3 received the same events in the same order. 309 * <p> 310 * <b>Verifies rule:</b> <a href='https://github.com/reactive-streams/reactive-streams-jvm#1.11'>1.11</a> 311 * <p> 312 * The test is not executed if {@link org.reactivestreams.tck.PublisherVerification#maxElementsFromPublisher()} is less than 5. 313 * <p> 314 * The request pattern for the first {@code Subscriber} is (1, 1, 2, 1); for the second is (2, 3) and for the third is (3, 1, 1). 315 * <p> 316 * Note that this test requires a {@code Publisher} that always emits the same signals to any {@code Subscriber}, regardless of 317 * when they subscribe and how they request elements. I.e., a "live" {@code Publisher} emitting the current time would not pass this test. 318 * <p> 319 * Note that this test is optional and may appear skipped even if the behavior should be actually supported by the {@code Publisher}, 320 * see the skip message for an indication of this. 321 * <p> 322 * If this test fails, the following could be checked within the {@code Publisher} implementation: 323 * <ul> 324 * <li>the {@code TestEnvironment} has large enough timeout specified in case the {@code Publisher} has some time-delay behavior,</li> 325 * <li>make sure the {@link #required_createPublisher1MustProduceAStreamOfExactly1Element()} and {@link #required_createPublisher3MustProduceAStreamOfExactly3Elements()} tests pass,</li> 326 * <li>if the {@code Publisher} implementation considers the cumulative request amount it receives,</li> 327 * <li>if the {@code Publisher} doesn't lose any {@code request()} signal and the state transition from idle -> emitting or emitting -> keep emitting works properly.</li> 328 * </ul> 329 */ 330 void optional_spec111_multicast_mustProduceTheSameElementsInTheSameSequenceToAllOfItsSubscribersWhenRequestingOneByOne() throws Throwable; 331 /** 332 * Asks for a short {@code Publisher} (length 3), subscribes 3 {@code Subscriber}s to it, requests more than the length items 333 * upfront with each and verifies they all received the same items in the same order (but does not verify they all complete). 334 * <p> 335 * <b>Verifies rule:</b> <a href='https://github.com/reactive-streams/reactive-streams-jvm#1.11'>1.11</a> 336 * <p> 337 * The test is not executed if {@link org.reactivestreams.tck.PublisherVerification#maxElementsFromPublisher()} is less than 3. 338 * <p> 339 * Note that this test requires a {@code Publisher} that always emits the same signals to any {@code Subscriber}, regardless of 340 * when they subscribe and how they request elements. I.e., a "live" {@code Publisher} emitting the current time would not pass this test. 341 * <p> 342 * Note that this test is optional and may appear skipped even if the behavior should be actually supported by the {@code Publisher}, 343 * see the skip message for an indication of this. 344 * <p> 345 * If this test fails, the following could be checked within the {@code Publisher} implementation: 346 * <ul> 347 * <li>the {@code TestEnvironment} has large enough timeout specified in case the {@code Publisher} has some time-delay behavior,</li> 348 * <li>make sure the {@link #required_createPublisher1MustProduceAStreamOfExactly1Element()} and {@link #required_createPublisher3MustProduceAStreamOfExactly3Elements()} tests pass,</li> 349 * <li>if the {@code Publisher} implementation considers the cumulative request amount it receives,</li> 350 * <li>if the {@code Publisher} doesn't lose any {@code request()} signal and the state transition from idle -> emitting or emitting -> keep emitting works properly.</li> 351 * </ul> 352 */ 353 void optional_spec111_multicast_mustProduceTheSameElementsInTheSameSequenceToAllOfItsSubscribersWhenRequestingManyUpfront() throws Throwable; 354 /** 355 * Asks for a short {@code Publisher} (length 3), subscribes 3 {@code Subscriber}s to it, requests more than the length items 356 * upfront with each and verifies they all received the same items in the same order followed by an {@code onComplete} signal. 357 * <p> 358 * <b>Verifies rule:</b> <a href='https://github.com/reactive-streams/reactive-streams-jvm#1.11'>1.11</a> 359 * <p> 360 * The test is not executed if {@link org.reactivestreams.tck.PublisherVerification#maxElementsFromPublisher()} is less than 3. 361 * <p> 362 * Note that this test requires a {@code Publisher} that always emits the same signals to any {@code Subscriber}, regardless of 363 * when they subscribe and how they request elements. I.e., a "live" {@code Publisher} emitting the current time would not pass this test. 364 * <p> 365 * Note that this test is optional and may appear skipped even if the behavior should be actually supported by the {@code Publisher}, 366 * see the skip message for an indication of this. 367 * <p> 368 * If this test fails, the following could be checked within the {@code Publisher} implementation: 369 * <ul> 370 * <li>the {@code TestEnvironment} has large enough timeout specified in case the {@code Publisher} has some time-delay behavior,</li> 371 * <li>make sure the {@link #required_createPublisher1MustProduceAStreamOfExactly1Element()} and {@link #required_createPublisher3MustProduceAStreamOfExactly3Elements()} tests pass,</li> 372 * <li>if the {@code Publisher} implementation considers the cumulative request amount it receives,</li> 373 * <li>if the {@code Publisher} doesn't lose any {@code request()} signal and the state transition from idle -> emitting or emitting -> keep emitting works properly.</li> 374 * </ul> 375 */ 376 void optional_spec111_multicast_mustProduceTheSameElementsInTheSameSequenceToAllOfItsSubscribersWhenRequestingManyUpfrontAndCompleteAsExpected() throws Throwable; 377 /** 378 * Asks for a short {@code Publisher} (length 6), requests several times from within {@code onSubscribe} and then requests 379 * one-by-one from {@code onNext}. 380 * <p> 381 * <b>Verifies rule:</b> <a href='https://github.com/reactive-streams/reactive-streams-jvm#3.2'>3.2</a> 382 * <p> 383 * The test is not executed if {@link org.reactivestreams.tck.PublisherVerification#maxElementsFromPublisher()} is less than 6. 384 * <p> 385 * The request pattern is 3 x 1 from within {@code onSubscribe} and one from within each {@code onNext} invocation. 386 * <p> 387 * The test consumes the {@code Publisher} but otherwise doesn't verify the {@code Publisher} completes (however, it checks 388 * for errors). 389 * <p> 390 * If this test fails, the following could be checked within the {@code Publisher} implementation: 391 * <ul> 392 * <li>the {@code TestEnvironment} has large enough timeout specified in case the {@code Publisher} has some time-delay behavior,</li> 393 * <li>make sure the {@link #required_createPublisher1MustProduceAStreamOfExactly1Element()} and {@link #required_createPublisher3MustProduceAStreamOfExactly3Elements()} tests pass,</li> 394 * <li>if the {@code Publisher} implementation considers the cumulative request amount it receives,</li> 395 * <li>if the {@code Publisher} doesn't lose any {@code request()} signal and the state transition from idle -> emitting or emitting -> keep emitting works properly.</li> 396 * </ul> 397 */ 398 void required_spec302_mustAllowSynchronousRequestCallsFromOnNextAndOnSubscribe() throws Throwable; 399 /** 400 * Asks for a {@code Publisher} with length equal to the value returned by {@link #required_validate_boundedDepthOfOnNextAndRequestRecursion()} plus 1, 401 * calls {@code request(1)} externally and then from within {@code onNext} and checks if the stack depth did not increase beyond the 402 * amount permitted by {@link #required_validate_boundedDepthOfOnNextAndRequestRecursion()}. 403 * <p> 404 * <b>Verifies rule:</b> <a href='https://github.com/reactive-streams/reactive-streams-jvm#3.3'>3.3</a> 405 * <p> 406 * The test is not executed if {@link org.reactivestreams.tck.PublisherVerification#maxElementsFromPublisher()} is less than 407 * {@link #required_validate_boundedDepthOfOnNextAndRequestRecursion()} plus 1. 408 * <p> 409 * If this test fails, the following could be checked within the {@code Publisher} implementation: 410 * <ul> 411 * <li>the {@code TestEnvironment} has large enough timeout specified in case the {@code Publisher} has some time-delay behavior,</li> 412 * <li>make sure the {@link #required_createPublisher1MustProduceAStreamOfExactly1Element()} and {@link #required_createPublisher3MustProduceAStreamOfExactly3Elements()} tests pass,</li> 413 * <li>the implementation doesn't allow unbounded recursion when {@code request()} is called from within {@code onNext}, i.e., the lack of 414 * reentrant-safe state machine around the request amount (such as a for loop with a bound on the parameter {@code n} that calls {@code onNext}). 415 * </ul> 416 */ 417 void required_spec303_mustNotAllowUnboundedRecursion() throws Throwable; 418 /** 419 * Currently, this test is skipped because a {@code request} could enter into a synchronous computation via {@code onNext} 420 * legally and otherwise there is no common agreement how to detect such heavy computation reliably. 421 * <p> 422 * <b>Verifies rule:</b> <a href='https://github.com/reactive-streams/reactive-streams-jvm#3.4'>3.4</a> 423 */ 424 void untested_spec304_requestShouldNotPerformHeavyComputations() throws Exception; 425 /** 426 * Currently, this test is skipped because there is no reliable agreed upon way to detect a heavy computation. 427 * <p> 428 * <b>Verifies rule:</b> <a href='https://github.com/reactive-streams/reactive-streams-jvm#3.5'>3.5</a> 429 */ 430 void untested_spec305_cancelMustNotSynchronouslyPerformHeavyComputation() throws Exception; 431 /** 432 * Asks for a short {@code Publisher} (length 3) and verifies that cancelling without requesting anything, then requesting 433 * items should result in no signals to be emitted. 434 * <p> 435 * <b>Verifies rule:</b> <a href='https://github.com/reactive-streams/reactive-streams-jvm#3.6'>3.6</a> 436 * <p> 437 * The test is not executed if {@link org.reactivestreams.tck.PublisherVerification#maxElementsFromPublisher()} is less than 3. 438 * <p> 439 * The post-cancellation request pattern is (1, 1, 1). 440 * <p> 441 * If this test fails, the following could be checked within the {@code Publisher} implementation: 442 * <ul> 443 * <li>the {@code TestEnvironment} has large enough timeout specified in case the {@code Publisher} has some time-delay behavior,</li> 444 * <li>make sure the {@link #required_createPublisher1MustProduceAStreamOfExactly1Element()} and {@link #required_createPublisher3MustProduceAStreamOfExactly3Elements()} tests pass,</li> 445 * <li>the cancellation indicator flag is properly persisted (may require volatile) and checked as part of the signal emission process.</li> 446 * </ul> 447 */ 448 void required_spec306_afterSubscriptionIsCancelledRequestMustBeNops() throws Throwable; 449 /** 450 * Asks for a single-element {@code Publisher} and verifies that without requesting anything, cancelling the sequence 451 * multiple times should result in no signals to be emitted and should result in an thrown exception. 452 * <p> 453 * <b>Verifies rule:</b> <a href='https://github.com/reactive-streams/reactive-streams-jvm#3.7'>3.7</a> 454 * <p> 455 * The test is not executed if {@link org.reactivestreams.tck.PublisherVerification#maxElementsFromPublisher()} is less than 1. 456 * <p> 457 * If this test fails, the following could be checked within the {@code Publisher} implementation: 458 * <ul> 459 * <li>the {@code TestEnvironment} has large enough timeout specified in case the {@code Publisher} has some time-delay behavior,</li> 460 * <li>make sure the {@link #required_createPublisher1MustProduceAStreamOfExactly1Element()} and {@link #required_createPublisher3MustProduceAStreamOfExactly3Elements()} tests pass,</li> 461 * <li>the cancellation indicator flag is properly persisted (may require volatile) and checked as part of the signal emission process.</li> 462 * </ul> 463 */ 464 void required_spec307_afterSubscriptionIsCancelledAdditionalCancelationsMustBeNops() throws Throwable; 465 /** 466 * Asks for a short {@code Publisher} (length 10) and issues a {@code request(0)} which should trigger an {@code onError} call 467 * with an {@code IllegalArgumentException}. 468 * <p> 469 * <b>Verifies rule:</b> <a href='https://github.com/reactive-streams/reactive-streams-jvm#3.9'>3.9</a> 470 * <p> 471 * The test is not executed if {@link org.reactivestreams.tck.PublisherVerification#maxElementsFromPublisher()} is less than 10. 472 * <p> 473 * Note that this test expects the {@code IllegalArgumentException} being signalled through {@code onError}, not by 474 * throwing from {@code request()} (which is also forbidden) or signalling the error by any other means (i.e., through the 475 * {@code Thread.currentThread().getUncaughtExceptionHandler()} for example). 476 * <p> 477 * Note also that requesting and emission may happen concurrently and honoring this rule may require extra coordination within 478 * the {@code Publisher}. 479 * <p> 480 * If this test fails, the following could be checked within the {@code Publisher} implementation: 481 * <ul> 482 * <li>the {@code TestEnvironment} has large enough timeout specified in case the {@code Publisher} has some time-delay behavior,</li> 483 * <li>make sure the {@link #required_createPublisher1MustProduceAStreamOfExactly1Element()} and {@link #required_createPublisher3MustProduceAStreamOfExactly3Elements()} tests pass,</li> 484 * <li>the {@code Publisher} can emit an {@code onError} in this particular case, even if there was no prior and legal 485 * {@code request} call and even if the {@code Publisher} would like to emit items first before emitting an {@code onError} 486 * in general. 487 * </ul> 488 */ 489 void required_spec309_requestZeroMustSignalIllegalArgumentException() throws Throwable; 490 /** 491 * Asks for a short {@code Publisher} (length 10) and issues a random, negative {@code request()} call which should 492 * trigger an {@code onError} call with an {@code IllegalArgumentException}. 493 * <p> 494 * <b>Verifies rule:</b> <a href='https://github.com/reactive-streams/reactive-streams-jvm#3.9'>3.9</a> 495 * <p> 496 * The test is not executed if {@link org.reactivestreams.tck.PublisherVerification#maxElementsFromPublisher()} is less than 10. 497 * <p> 498 * Note that this test expects the {@code IllegalArgumentException} being signalled through {@code onError}, not by 499 * throwing from {@code request()} (which is also forbidden) or signalling the error by any other means (i.e., through the 500 * {@code Thread.currentThread().getUncaughtExceptionHandler()} for example). 501 * <p> 502 * Note also that requesting and emission may happen concurrently and honoring this rule may require extra coordination within 503 * the {@code Publisher}. 504 * <p> 505 * If this test fails, the following could be checked within the {@code Publisher} implementation: 506 * <ul> 507 * <li>the {@code TestEnvironment} has large enough timeout specified in case the {@code Publisher} has some time-delay behavior,</li> 508 * <li>make sure the {@link #required_createPublisher1MustProduceAStreamOfExactly1Element()} and {@link #required_createPublisher3MustProduceAStreamOfExactly3Elements()} tests pass,</li> 509 * <li>the {@code Publisher} can emit an {@code onError} in this particular case, even if there was no prior and legal 510 * {@code request} call and even if the {@code Publisher} would like to emit items first before emitting an {@code onError} 511 * in general. 512 * </ul> 513 */ 514 void required_spec309_requestNegativeNumberMustSignalIllegalArgumentException() throws Throwable; 515 /** 516 * Asks for a short {@code Publisher} (length 10) and issues a random, negative {@code request()} call which should 517 * trigger an {@code onError} call with an {@code IllegalArgumentException}. 518 * <p> 519 * <b>Verifies rule:</b> <a href='https://github.com/reactive-streams/reactive-streams-jvm#3.9'>3.9</a> 520 * <p> 521 * The test is not executed if {@link org.reactivestreams.tck.PublisherVerification#maxElementsFromPublisher()} is less than 10. 522 * <p> 523 * Note that this test expects the {@code IllegalArgumentException} being signalled through {@code onError}, not by 524 * throwing from {@code request()} (which is also forbidden) or signalling the error by any other means (i.e., through the 525 * {@code Thread.currentThread().getUncaughtExceptionHandler()} for example). 526 * <p> 527 * Note also that requesting and emission may happen concurrently and honoring this rule may require extra coordination within 528 * the {@code Publisher}. 529 * <p> 530 * If this test fails, the following could be checked within the {@code Publisher} implementation: 531 * <ul> 532 * <li>the {@code TestEnvironment} has large enough timeout specified in case the {@code Publisher} has some time-delay behavior,</li> 533 * <li>make sure the {@link #required_createPublisher1MustProduceAStreamOfExactly1Element()} and {@link #required_createPublisher3MustProduceAStreamOfExactly3Elements()} tests pass,</li> 534 * <li>the {@code Publisher} can emit an {@code onError} in this particular case, even if there was no prior and legal 535 * {@code request} call and even if the {@code Publisher} would like to emit items first before emitting an {@code onError} 536 * in general. 537 * </ul> 538 */ 539 void optional_spec309_requestNegativeNumberMaySignalIllegalArgumentExceptionWithSpecificMessage() throws Throwable; 540 /** 541 * Asks for a short {@code Publisher} (length 20), requests some items (less than the length), consumes one item then 542 * cancels the sequence and verifies the publisher emitted at most the requested amount and stopped emitting (or terminated). 543 * <p> 544 * <b>Verifies rule:</b> <a href='https://github.com/reactive-streams/reactive-streams-jvm#3.12'>3.12</a> 545 * <p> 546 * The test is not executed if {@link org.reactivestreams.tck.PublisherVerification#maxElementsFromPublisher()} is less than 20. 547 * <p> 548 * If this test fails, the following could be checked within the {@code Publisher} implementation: 549 * <ul> 550 * <li>the {@code TestEnvironment} has large enough timeout specified in case the {@code Publisher} has some time-delay behavior,</li> 551 * <li>make sure the {@link #required_createPublisher1MustProduceAStreamOfExactly1Element()} and {@link #required_createPublisher3MustProduceAStreamOfExactly3Elements()} tests pass,</li> 552 * <li>the cancellation indicator flag is properly persisted (may require volatile) and checked as part of the signal emission process.</li> 553 * </ul> 554 */ 555 void required_spec312_cancelMustMakeThePublisherToEventuallyStopSignaling() throws Throwable; 556 /** 557 * Asks for a short {@code Publisher} (length 3) requests and consumes one element from it, cancels the {@code Subscription} 558 * , calls {@code System.gc()} and then checks if all references to the test {@code Subscriber} has been dropped (by checking 559 * the {@code WeakReference} has been emptied). 560 * <p> 561 * <b>Verifies rule:</b> <a href='https://github.com/reactive-streams/reactive-streams-jvm#3.13'>3.13</a> 562 * <p> 563 * The test is not executed if {@link org.reactivestreams.tck.PublisherVerification#maxElementsFromPublisher()} is less than 3. 564 * <p> 565 * If this test fails, the following could be checked within the {@code Publisher} implementation: 566 * <ul> 567 * <li>the {@code TestEnvironment} has large enough timeout specified in case the {@code Publisher} has some time-delay behavior,</li> 568 * <li>make sure the {@link #required_createPublisher1MustProduceAStreamOfExactly1Element()} and {@link #required_createPublisher3MustProduceAStreamOfExactly3Elements()} tests pass,</li> 569 * <li>the cancellation indicator flag is properly persisted (may require volatile) and checked as part of the signal emission process.</li> 570 * <li>the {@code Publisher} stores the {@code Subscriber} reference somewhere which is then not cleaned up when the {@code Subscriber} is cancelled. 571 * Note that this may happen on many code paths in a {@code Publisher}, for example in an emission loop that terminates because of the 572 * {@code cancel} signal or because reaching a terminal state. Note also that eagerly nulling {@code Subscriber} references may not be necessary 573 * for this test to pass in case there is a self-contained chain of them (i.e., {@code Publisher.subscribe()} creates a chain of fresh 574 * {@code Subscriber} instances where each of them only references their downstream {@code Subscriber} thus the chain can get GC'd 575 * when the reference to the final {@code Subscriber} is dropped). 576 * </ul> 577 */ 578 void required_spec313_cancelMustMakeThePublisherEventuallyDropAllReferencesToTheSubscriber() throws Throwable; 579 /** 580 * Asks for a short {@code Publisher} (length 3) and requests {@code Long.MAX_VALUE} from it, verifying that the 581 * {@code Publisher} emits all of its items and completes normally 582 * and does not keep spinning attempting to fulfill the {@code Long.MAX_VALUE} demand by some means. 583 * <p> 584 * <b>Verifies rule:</b> <a href='https://github.com/reactive-streams/reactive-streams-jvm#3.17'>3.17</a> 585 * <p> 586 * The test is not executed if {@link org.reactivestreams.tck.PublisherVerification#maxElementsFromPublisher()} is less than 3. 587 * <p> 588 * If this test fails, the following could be checked within the {@code Publisher} implementation: 589 * <ul> 590 * <li>the {@code TestEnvironment} has large enough timeout specified in case the {@code Publisher} has some time-delay behavior,</li> 591 * <li>make sure the {@link #required_createPublisher1MustProduceAStreamOfExactly1Element()} and {@link #required_createPublisher3MustProduceAStreamOfExactly3Elements()} tests pass,</li> 592 * <li>if the {@code Publisher} implementation considers the cumulative request amount it receives,</li> 593 * <li>if the {@code Publisher} doesn't lose any {@code request()} signal and the state transition from idle -> emitting or emitting -> keep emitting works properly.</li> 594 * </ul> 595 */ 596 void required_spec317_mustSupportAPendingElementCountUpToLongMaxValue() throws Throwable; 597 /** 598 * Asks for a short {@code Publisher} (length 3) and requests {@code Long.MAX_VALUE} from it in total (split across 599 * two {@code Long.MAX_VALUE / 2} and one {@code request(1)}), verifying that the 600 * {@code Publisher} emits all of its items and completes normally. 601 * <p> 602 * <b>Verifies rule:</b> <a href='https://github.com/reactive-streams/reactive-streams-jvm#3.17'>3.17</a> 603 * <p> 604 * The test is not executed if {@link org.reactivestreams.tck.PublisherVerification#maxElementsFromPublisher()} is less than 3. 605 * <p> 606 * If this test fails, the following could be checked within the {@code Publisher} implementation: 607 * <ul> 608 * <li>the {@code TestEnvironment} has large enough timeout specified in case the {@code Publisher} has some time-delay behavior,</li> 609 * <li>make sure the {@link #required_createPublisher1MustProduceAStreamOfExactly1Element()} and {@link #required_createPublisher3MustProduceAStreamOfExactly3Elements()} tests pass,</li> 610 * <li>if the {@code Publisher} implementation considers the cumulative request amount it receives,</li> 611 * <li>if the {@code Publisher} implements adding individual request amounts together properly (not overflowing into zero or negative pending request amounts) 612 * or not properly deducing the number of emitted items from the pending amount,</li> 613 * <li>if the {@code Publisher} doesn't lose any {@code request()} signal and the state transition from idle -> emitting or emitting -> keep emitting works properly.</li> 614 * </ul> 615 */ 616 void required_spec317_mustSupportACumulativePendingElementCountUpToLongMaxValue() throws Throwable; 617 /** 618 * Asks for a very long {@code Publisher} (up to {@code Integer.MAX_VALUE}), requests {@code Long.MAX_VALUE - 1} after 619 * each received item and expects no failure due to a potential overflow in the pending emission count while consuming 620 * 10 items and cancelling the sequence. 621 * <p> 622 * <b>Verifies rule:</b> <a href='https://github.com/reactive-streams/reactive-streams-jvm#3.17'>3.17</a> 623 * <p> 624 * The test is not executed if {@link org.reactivestreams.tck.PublisherVerification#maxElementsFromPublisher()} is less than {@code Integer.MAX_VALUE}. 625 * <p> 626 * The request pattern is one {@code request(1)} upfront and ten {@code request(Long.MAX_VALUE - 1)} after. 627 * <p> 628 * If this test fails, the following could be checked within the {@code Publisher} implementation: 629 * <ul> 630 * <li>the {@code TestEnvironment} has large enough timeout specified in case the {@code Publisher} has some time-delay behavior,</li> 631 * <li>make sure the {@link #required_createPublisher1MustProduceAStreamOfExactly1Element()} and {@link #required_createPublisher3MustProduceAStreamOfExactly3Elements()} tests pass,</li> 632 * <li>if the {@code Publisher} implementation considers the cumulative request amount it receives,</li> 633 * <li>if the {@code Publisher} implements adding individual request amounts together properly (not overflowing into zero or negative pending request amounts) 634 * or not properly deducing the number of emitted items from the pending amount,</li> 635 * <li>if the {@code Publisher} doesn't lose any {@code request()} signal and the state transition from idle -> emitting or emitting -> keep emitting works properly.</li> 636 * </ul> 637 */ 638 void required_spec317_mustNotSignalOnErrorWhenPendingAboveLongMaxValue() throws Throwable; 639}