Merge pull request reactive-streams#241 from ktoso/error-publisher-readme

!tck - clarifies error publisher, and method name change (?)

Author: viktorklang

examples/src/test/java/org/reactivestreams/example/unicast/IterablePublisherTest.java

@@ -30,7 +30,7 @@ public IterablePublisherTest() {
     return new NumberIterablePublisher(0, (int)elements, e);
   }
 
-  @Override public Publisher<Integer> createErrorStatePublisher() {
+  @Override public Publisher<Integer> createFailedPublisher() {
     return new AsyncIterablePublisher<Integer>(new Iterable<Integer>() {
       @Override public Iterator<Integer> iterator() {
         throw new RuntimeException("Error state signal!");

examples/src/test/java/org/reactivestreams/example/unicast/UnboundedIntegerIncrementPublisherTest.java

@@ -25,7 +25,7 @@ public UnboundedIntegerIncrementPublisherTest() {
     return new InfiniteIncrementNumberPublisher(e);
   }
 
-  @Override public Publisher<Integer> createErrorStatePublisher() {
+  @Override public Publisher<Integer> createFailedPublisher() {
     return new AsyncIterablePublisher<Integer>(new Iterable<Integer>() {
       @Override public Iterator<Integer> iterator() {
         throw new RuntimeException("Error state signal!");

tck/README.md

@@ -66,7 +66,7 @@ Explanations:
 @Test public void optional_spec104_mustSignalOnErrorWhenFails() throws Throwable
 ```
 
-... means that this test case is optional, it covers a *MAY* or *SHOULD* Rule of the Specification. This prefix is also used if more configuration is needed in order to run it, e.g. `@Additional(implement = "createErrorStatePublisher") @Test` signals the implementer that in order to include this test case in his test runs, (s)he must implement the `Publisher<T> createErrorStatePublisher()` method.
+... means that this test case is optional, it covers a *MAY* or *SHOULD* Rule of the Specification.
 
 ```java
 @Test public void stochastic_spec103_mustSignalOnMethodsSequentially() throws Throwable
@@ -116,6 +116,27 @@ In order to inform the TCK that your Publiher is not able to signal completion,
 }
 ```
 
+### Testing a "failed" Publisher
+The Reactive Streams spec mandates certain behaviours for Publishers which are "failed",
+e.g. it was unable to initialize a connection it needs to emit elements.
+It may be useful to specifically such known to be failed Publisher using the TCK.
+
+In order to run additional tests on your failed publisher you can implement the `createFailedPublisher` method.
+The expected behaviour from the returned implementation is to follow Rule 1.4 and Rule 1.9 - which are concerned
+with the order of emiting the Subscription and signaling the failure.
+
+```java
+@Override public Publisher<T> createFailedPublisher() {
+  final String invalidData = "this input string is known it to be failed";
+  return new MyPublisher(invalidData);
+}
+```
+
+In case you don't really have a known up-front error state you can put your Publisher into,
+you can easily ignore these tests by returning `null` from the `createFailedPublisher` method.
+It is important to remember that it is **illegal** to signal `onNext / onComplete / onError` before
+you signal the `Subscription`, for details on this rule refer to the Reactive Streams specification.
+
 ## Publisher Verification
 
 `PublisherVerification` tests verify Publisher as well as some Subscription Rules of the Specification.
@@ -142,7 +163,7 @@ public class RangePublisherTest extends PublisherVerification<Integer> {
   }
 
   @Override
-  public Publisher<Integer> createErrorStatePublisher() {
+  public Publisher<Integer> createFailedPublisher() {
     return new Publisher<Integer>() {
       @Override
       public void subscribe(Subscriber<Integer> s) {
@@ -427,8 +448,7 @@ public class MyIdentityProcessorVerificationTest extends IdentityProcessorVerifi
   // ENABLE ADDITIONAL TESTS
 
   @Override
-  public Publisher<Integer> createErrorStatePublisher() {
-    // return error state Publisher instead of null to run additional tests
+  public Publisher<Integer> createFailedPublisher() {
     return null;
   }
 
@@ -504,7 +524,7 @@ class IterablePublisherTest(env: TestEnvironment, publisherShutdownTimeout: Long
   def createPublisher(elements: Long): Publisher[Int] = ???
 
   // example error state publisher implementation
-  override def createErrorStatePublisher(): Publisher[Int] =
+  override def createFailedPublisher(): Publisher[Int] =
     new Publisher[Int] {
       override def subscribe(s: Subscriber[Int]): Unit = {
         s.onError(new Exception("Unable to serve subscribers right now!"))

tck/src/main/java/org/reactivestreams/tck/IdentityProcessorVerification.java

@@ -94,8 +94,8 @@ public Publisher<T> createPublisher(long elements) {
       }
 
       @Override
-      public Publisher<T> createErrorStatePublisher() {
-        return IdentityProcessorVerification.this.createErrorStatePublisher();
+      public Publisher<T> createFailedPublisher() {
+        return IdentityProcessorVerification.this.createFailedPublisher();
       }
 
       @Override
@@ -125,10 +125,14 @@ public boolean skipStochasticTests() {
   public abstract Processor<T, T> createIdentityProcessor(int bufferSize);
 
   /**
-   * Return a Publisher that immediately signals {@code onError} to incoming subscriptions,
-   * or {@code null} in order to skip them.
+   * By implementing this method, additional TCK tests concerning a "failed" publishers will be run.
+   *
+   * The expected behaviour of the {@link Publisher} returned by this method is hand out a subscription,
+   * followed by signalling {@code onError} on it, as specified by Rule 1.9.
+   *
+   * If you ignore these additional tests, return {@code null} from this method.
    */
-  public abstract Publisher<T> createErrorStatePublisher();
+  public abstract Publisher<T> createFailedPublisher();
 
   /**
    * Override and return lower value if your Publisher is only able to produce a known number of elements.

tck/src/main/java/org/reactivestreams/tck/PublisherVerification.java

@@ -86,10 +86,14 @@ public static long envPublisherReferenceGCTimeoutMillis() {
   public abstract Publisher<T> createPublisher(long elements);
 
   /**
-   * Return a Publisher in {@code error} state in order to run additional tests on it,
-   * or {@code null} in order to skip them.
+   * By implementing this method, additional TCK tests concerning a "failed" publishers will be run.
+   *
+   * The expected behaviour of the {@link Publisher} returned by this method is hand out a subscription,
+   * followed by signalling {@code onError} on it, as specified by Rule 1.9.
+   *
+   * If you ignore these additional tests, return {@code null} from this method.
    */
-  public abstract Publisher<T> createErrorStatePublisher();
+  public abstract Publisher<T> createFailedPublisher();
 
 
   /**
@@ -1121,15 +1125,15 @@ public void optionalActivePublisherTest(long elements, boolean completionSignalR
 
   public static final String SKIPPING_NO_ERROR_PUBLISHER_AVAILABLE =
     "Skipping because no error state Publisher provided, and the test requires it. " +
-          "Please implement PublisherVerification#createErrorStatePublisher to run this test.";
+          "Please implement PublisherVerification#createFailedPublisher to run this test.";
 
   public static final String SKIPPING_OPTIONAL_TEST_FAILED =
     "Skipping, because provided Publisher does not pass this *additional* verification.";
   /**
    * Additional test for Publisher in error state
    */
   public void whenHasErrorPublisherTest(PublisherTestRun<T> body) throws Throwable {
-    potentiallyPendingTest(createErrorStatePublisher(), body, SKIPPING_NO_ERROR_PUBLISHER_AVAILABLE);
+    potentiallyPendingTest(createFailedPublisher(), body, SKIPPING_NO_ERROR_PUBLISHER_AVAILABLE);
   }
 
   public void potentiallyPendingTest(Publisher<T> pub, PublisherTestRun<T> body) throws Throwable {

tck/src/test/java/org/reactivestreams/tck/EmptyLazyPublisherTest.java

@@ -31,7 +31,7 @@ public Publisher<Integer> createPublisher(long elements) {
   }
 
   @Override
-  public Publisher<Integer> createErrorStatePublisher() {
+  public Publisher<Integer> createFailedPublisher() {
     return null;
   }
 

tck/src/test/java/org/reactivestreams/tck/IdentityProcessorVerificationTest.java

@@ -41,7 +41,7 @@ public void required_spec104_mustCallOnErrorOnAllItsSubscribersIfItEncountersANo
             return SKIP;
           }
 
-          @Override public Publisher<Integer> createErrorStatePublisher() {
+          @Override public Publisher<Integer> createFailedPublisher() {
             return SKIP;
           }
 
@@ -107,7 +107,7 @@ public void required_spec104_mustCallOnErrorOnAllItsSubscribersIfItEncountersANo
             };
           }
 
-          @Override public Publisher<Integer> createErrorStatePublisher() {
+          @Override public Publisher<Integer> createFailedPublisher() {
             return SKIP;
           }
         }.required_spec104_mustCallOnErrorOnAllItsSubscribersIfItEncountersANonRecoverableError();

tck/src/test/java/org/reactivestreams/tck/PublisherVerificationTest.java

@@ -203,7 +203,7 @@ public void optional_spec105_emptyStreamMustTerminateBySignallingOnComplete_shou
             return 0; // it is an "empty" Publisher
           }
 
-          @Override public Publisher<Integer> createErrorStatePublisher() {
+          @Override public Publisher<Integer> createFailedPublisher() {
             return null;
           }
         };
@@ -618,7 +618,7 @@ final PublisherVerification<Integer> noopPublisherVerification() {
 
       }
 
-      @Override public Publisher<Integer> createErrorStatePublisher() {
+      @Override public Publisher<Integer> createFailedPublisher() {
         return SKIP;
       }
     };
@@ -643,7 +643,7 @@ final PublisherVerification<Integer> onErroringPublisherVerification() {
 
       }
 
-      @Override public Publisher<Integer> createErrorStatePublisher() {
+      @Override public Publisher<Integer> createFailedPublisher() {
         return SKIP;
       }
     };
@@ -665,7 +665,7 @@ final PublisherVerification<Integer> customPublisherVerification(final Publisher
         return pub;
       }
 
-      @Override public Publisher<Integer> createErrorStatePublisher() {
+      @Override public Publisher<Integer> createFailedPublisher() {
         return errorPub;
       }
     };
@@ -694,7 +694,7 @@ final PublisherVerification<Integer> demandIgnoringSynchronousPublisherVerificat
 
       }
 
-      @Override public Publisher<Integer> createErrorStatePublisher() {
+      @Override public Publisher<Integer> createFailedPublisher() {
         return SKIP;
       }
     };
@@ -782,7 +782,7 @@ final PublisherVerification<Integer> demandIgnoringAsynchronousPublisherVerifica
 
       }
 
-      @Override public Publisher<Integer> createErrorStatePublisher() {
+      @Override public Publisher<Integer> createFailedPublisher() {
         return SKIP;
       }
     };

tck/src/test/java/org/reactivestreams/tck/SingleElementPublisherTest.java

@@ -31,7 +31,7 @@ public Publisher<Integer> createPublisher(long elements) {
   }
 
   @Override
-  public Publisher<Integer> createErrorStatePublisher() {
+  public Publisher<Integer> createFailedPublisher() {
     return null;
   }