<chapter id="Reactive">
<title>Reactive programming support</title>
 
    <para>
       With version 2.1, the JAX-RS specification 
       (<ulink url="https://jcp.org/en/jsr/detail?id=370">https://jcp.org/en/jsr/detail?id=370</ulink>)
       takes its first steps into the world of <emphasis role="bold">Reactive Programming</emphasis>. There are many discussions
       of reactive programming on the internet, and a general introduction is beyond the scope of this document,
       but there are a few things worth discussing. Some primary aspects of reactive programming are the following: 
    </para>
    
    <itemizedlist>
        <listitem>
           Reactive programming supports the declarative creation of rich computational structures. The 
           representations of these structures can be passed around as first class objects such as method parameters
           and return values.
        </listitem>
        <listitem>
           Reactive programming supports both synchronous and asynchronous computation, but it is particularly helpful
           in facilitating, at a relatively high level of expression, asynchronous computation. Conceptually,
           asynchronous computation in reactive program typically involves pushing data from one entity to another, rather
           than polling for data.
        </listitem>
    </itemizedlist>
<sect1>
<title>CompletionStage</title>
    <para>
       In java 1.8 and JAX-RS 2.1, the support for reactive programming is fairly limited. Java 1.8 introduces the interface
       <classname>java.util.concurrent.CompletionStage</classname>, and JAX-RS 2.1 mandates support for the
       <classname>javax.ws.rs.client.CompletionStageRxInvoker</classname>, which allows a client to obtain a 
       response in the form of a <classname>CompletionStage</classname>. 
    </para>
    
    <para>
       One implementation of <classname>CompletionStage</classname> is the <classname>java.util.concurrent.CompleteableFuture</classname>.
       For example:
    </para>
    
<programlisting>
@Test
public void testCompletionStage() throws Exception {
   CompletionStage&lt;String&gt; stage = getCompletionStage();
   log.info("result: " + stage.toCompletableFuture().get());
}

private CompletionStage&lt;String&gt; getCompletionStage() {
   CompletableFuture&lt;String&gt; future = new CompletableFuture&lt;String&gt;();
   future.complete("foo");
   return future;
}
</programlisting>

    <para>
       Here, a <classname>CompleteableFuture</classname> is created with the value "foo", and its value is 
       extracted by the method <methodname>CompletableFuture.get()</methodname>. That's fine, but consider the
       altered version:
    </para>
    
<programlisting>
@Test
public void testCompletionStageAsync() throws Exception {
   log.info("start");
   CompletionStage&lt;String&gt; stage = getCompletionStageAsync();
   String result = stage.toCompletableFuture().get();
   log.info("do some work");
   log.info("result: " + result);
}

private CompletionStage&lt;String&gt; getCompletionStageAsync() {
   CompletableFuture&lt;String&gt; future = new CompletableFuture&lt;String&gt;();
   Executors.newCachedThreadPool().submit(() -&gt; {sleep(2000); future.complete("foo");});
   return future;
}

private void sleep(long l) {
   try {
      Thread.sleep(l);
   } catch (InterruptedException e) {
      e.printStackTrace();
   }
}
</programlisting>

   <para>
      with output something like:
   </para>
   
<programlisting>
3:10:51 PM INFO: start
3:10:53 PM INFO: do some work
3:10:53 PM INFO: result: foo
</programlisting>

    <para>
       It also works, but it illustrates the fact that <methodname>CompletableFuture.get()</methodname> is a blocking
       call. The <classname>CompletionStage</classname> is constructed and returned immediately,
       but the value isn't returned for two seconds. A version that is more in the spirit of the reactive style is:
    </para>
    
<programlisting>
@Test
public void testCompletionStageAsyncAccept() throws Exception {
   log.info("start");
   CompletionStage&lt;String&gt; stage = getCompletionStageAsync();
   stage.thenAccept((String s) -&gt; log.info("s: " + s));
   log.info("do some work");
   ...
}
</programlisting>

    <para>
       In this case, the lambda (String s) -&gt; log.info("s: " + s) is registered with the 
       <classname>CompletionStage</classname> as a "subscriber", and, when the <classname>CompletionStage</classname>
       eventually has a value, that value is passed to the lambda. Note that the output is something like
    </para>
    
<programlisting>
3:23:05 INFO: start
3:23:05 INFO: do some work
3:23:07 INFO: s: foo
</programlisting>
    
    <para>
       Executing <classname>CompletionStage</classname>s asynchronously is so common that there are 
       several supporting convenience methods. For example:
    </para>
    
<programlisting>
@Test
public void testCompletionStageSupplyAsync() throws Exception {
   CompletionStage&lt;String&gt; stage = getCompletionStageSupplyAsync();;
   stage.thenAccept((String s) -&gt; log.info("s: " + s));
}

private CompletionStage&lt;String&gt; getCompletionStageSupplyAsync() {
   return CompletableFuture.supplyAsync(() -&gt; "foo");
}
</programlisting>
    
    <para>
       The static method <classname>ComputableFuture.supplyAsync()</classname> creates a
       <classname>ComputableFuture</classname>, the value of which is supplied asynchronously
       by the lambda () -> "foo", running, by default, in the default pool of
       <methodname>java.util.concurrent.ForkJoinPool</methodname>.
    </para>
    
    <para>
       One final example illustrates a more complex computational structure:
    </para>
    
<programlisting>
@Test
public void testCompletionStageComplex() throws Exception {
   ExecutorService executor = Executors.newCachedThreadPool();
   CompletionStage&lt;String&gt; stage1 = getCompletionStageSupplyAsync1("foo", executor);
   CompletionStage&lt;String&gt; stage2 = getCompletionStageSupplyAsync1("bar", executor);
   CompletionStage&lt;String&gt; stage3 = stage1.thenCombineAsync(stage2, (String s, String t) -> s + t, executor);
   stage3.thenAccept((String s) -> log.info("s: " + s));
}

private CompletionStage&lt;String&gt; getCompletionStageSupplyAsync1(String s, ExecutorService executor) {
   return CompletableFuture.supplyAsync(() -> s, executor);
}
</programlisting>

    <para>
       <classname>stage1</classname> returns "foo", <classname>stage2</classname> returns "bar", and
       <classname>stage3</classname>, which runs when both <classname>stage1</classname> and <classname>stage2</classname>
       have completed, returns the concatenation of "foo" and "bar". Note that, in this example, an explict
       <classname>ExecutorService</classname> is provided for asynchronous processing.
    </para>
</sect1>

<sect1>
<title>CompletionStage in JAX-RS</title>

    <para>
       On the client side, the JAX-RS 2.1 specification mandates an implementation of the interface
       <classname>javax.ws.rs.client.CompletionStageRxInvoker</classname>:
    </para>
    
<programlisting>
public interface CompletionStageRxInvoker extends RxInvoker&lt;CompletionStage&gt; {

    @Override
    public CompletionStage&lt;Response&gt; get();

    @Override
    public &lt;T&gt; CompletionStage&lt;T&gt; get(Class&lt;T&gt; responseType);

    @Override
    public &lt;T&gt; CompletionStage&lt;T&gt; get(GenericType&lt;T&gt; responseType);
    ...
</programlisting>

    <para>
       That is, there are invocation methods for the standard HTTP verbs, just as in the standard 
       <classname>javax.ws.rs.client.SyncInvoker</classname>. A <classname>CompletionStageRxInvoker</classname>
       is obtained by calling <methodname>rx()</methodname> on a
       <classname>javax.ws.rs.client.Invocation.Builder</classname>, which extends <classname>SyncInvoker</classname>.
       For example,
    </para>
    
<programlisting>
Invocation.Builder builder = client.target(generateURL("/get/string")).request();
CompletionStageRxInvoker invoker = builder.rx(CompletionStageRxInvoker.class);
CompletionStage&lt;Response&gt; stage = invoker.get();
Response response = stage.toCompletableFuture().get();
log.info("result: " + response.readEntity(String.class));
</programlisting>

    <para>
       or
    </para>
    
<programlisting>
CompletionStageRxInvoker invoker = client.target(generateURL("/get/string")).request().rx(CompletionStageRxInvoker.class);
CompletionStage&lt;String&gt; stage = invoker.get(String.class);
String s = stage.toCompletableFuture().get();
log.info("result: " + s);
</programlisting>

    <para>
       On the server side, the JAX-RS 2.1 specification requires support for resource methods with return type
       <classname>CompletionStage&lt;T&gt;</classname>. For example,
    </para>
    
<programlisting>
@GET
@Path("get/async")
public CompletionStage&lt;String&gt; longRunningOpAsync() {
   CompletableFuture&lt;String&gt; cs = new CompletableFuture&lt;&gt;();
   executor.submit(
      new Runnable() {
         public void run() {
            executeLongRunningOp();
            cs.complete("Hello async world!");
         }
      });
   return cs;
}
</programlisting>

    <para>
       The way to think about <methodname>longRunningOpAsync()</methodname> is that it is asynchronously
       creating and returning a <classname>String</classname>. After <classname>cs.complete()</classname> is called,
       the server will return the <classname>String</classname> "Hello async world!" to the client.
    </para>
    
    <para>
       An important thing to understand is that the decision to produce a result asynchronously on the server and the
       decision to retrieve the result asynchronously on the client are independent. Suppose that there is also a
       resource method
    </para>
    
<programlisting>
@GET
@Path("get/sync")
public String longRunningOpSync() {
   return "Hello async world!";
}
</programlisting>

    <para>
       Then all three of the following invocations are valid:
    </para>
    
<programlisting>
public void testGetStringAsyncAsync() throws Exception {
   CompletionStageRxInvoker invoker = client.target(generateURL("/get/async")).request().rx();
   CompletionStage&lt;String&gt; stage = invoker.get(String.class);
   log.info("s: " + stage.toCompletableFuture().get());
}
</programlisting>

<programlisting>
public void testGetStringSyncAsync() throws Exception {
   Builder request = client.target(generateURL("/get/async")).request();
   String s = request.get(String.class);
   log.info("s: " + s);
}
</programlisting>

    <para>
       and
    </para>
    
<programlisting>
public void testGetStringAsyncSync() throws Exception {
   CompletionStageRxInvoker invoker = client.target(generateURL("/get/sync")).request().rx();
   CompletionStage&lt;String&gt; stage = invoker.get(String.class);
   log.info("s: " + stage.toCompletableFuture().get());
}
</programlisting>

   <note>
       <para>
          <classname>CompletionStage</classname> in JAX-RS is also discussed in the chapter
          <link linkend="Asynchronous_HTTP_Request_Processing">Asynchronous HTTP Request Processing</link>.
       </para>
   </note>
   
   <note id="asyncContextNote">
       <para>
          Since running code asynchronously is so common in this context, it is worth pointing out
          that objects obtained by way of the annotation <code>@Context</code> or by way of calling
          <code>ResteasyProviderFactory.getContextData()</code> are sensitive to the
          executing thread. For example, given resource method
       </para>
   
<programlisting>
@GET
@Path("test")
@Produces("text/plain")
public CompletionStage&lt;String&gt; text(@Context HttpRequest request) {
   System.out.println("request (inline): " + request);
   System.out.println("application (inline): " + ResteasyProviderFactory.getContextData(Application.class));
   CompletableFuture&lt;String&gt; cs = new CompletableFuture&lt;&gt;();
   ExecutorService executor = Executors.newSingleThreadExecutor();
   executor.submit(
         new Runnable() {
            public void run() {
               try {
                  System.out.println("request (async): " + request); 
                  System.out.println("application (async): " + ResteasyProviderFactory.getContextData(Application.class));
                  cs.complete("hello");
               } catch (Exception e) {
                  e.printStackTrace();
               }
            }
         });
   return cs;
}
</programlisting>

       <para>
          the output will look something like
       </para>
       
<programlisting>
application (inline): org.jboss.resteasy.experiment.Test1798CompletionStage$TestApp@23c57474
request (inline): org.jboss.resteasy.plugins.server.servlet.Servlet3AsyncHttpRequest@2ce23138
application (async): null
org.jboss.resteasy.spi.LoggableFailure: RESTEASY003880: Unable to find contextual data of type: org.jboss.resteasy.spi.HttpRequest
</programlisting>

       <para>
          The point is that it is the developer's responsibility to extract information from these context objects
          in advance. For example:
       </para>
       
<programlisting>
@GET
@Path("test")
@Produces("text/plain")
public CompletionStage&lt;String&gt; text(@Context HttpRequest req) {
   System.out.println("request (inline): " + request);
   System.out.println("application (inline): " + ResteasyProviderFactory.getContextData(Application.class));
   CompletableFuture&lt;String&gt; cs = new CompletableFuture&lt;&gt;();
   ExecutorService executor = Executors.newSingleThreadExecutor();
   final String httpMethodFinal = request.getHttpMethod();
   final Map&lt;String, Object&gt; mapFinal = ResteasyProviderFactory.getContextData(Application.class).getProperties();
   executor.submit(
         new Runnable() {
            public void run() {
               System.out.println("httpMethod (async): " + httpMethodFinal); 
               System.out.println("map (async): " + mapFinal); 
               cs.complete("hello");
            }
         });
   return cs;
}
</programlisting>
   </note>
</sect1>

<sect1>
<title>Beyond CompletionStage</title>

    <para>
       The picture becomes more complex and interesting when sequences are added. A <classname>CompletionStage</classname>
       holds no more than one potential value, but other reactive objects can hold multiple, even unlimited, values.
       Currently, most Java implementations of reactive programming are based on the project Reactive Streams
       (<ulink url="http://www.reactive-streams.org/">http://www.reactive-streams.org/</ulink>), which defines a set of
       four interfaces and a specification, in the form of a set of rules, describing how they interact:
    </para>
    
<programlisting>
public interface Publisher&lt;T&gt; {
    public void subscribe(Subscriber&lt;? super T&gt; s);
}

public interface Subscriber&lt;T&gt; {
    public void onSubscribe(Subscription s);
    public void onNext(T t);
    public void onError(Throwable t);
    public void onComplete();
}

public interface Subscription {
    public void request(long n);
    public void cancel();
}

public interface Processor&lt;T, R&gt; extends Subscriber&lt;T&gt;, Publisher&lt;R&gt; {
}
</programlisting>

    <para>
       A <classname>Producer</classname> pushes objects to a <classname>Subscriber</classname>, a
       <classname>Subscription</classname> mediates the relationship between the two, and a
       <classname>Processor</classname> which is derived from both, helps to construct pipelines
       through which objects pass.
    </para>
    
    <para>
       One important aspect of the specification is flow control, the ability of a <classname>Suscriber</classname>
       to control the load it receives from a <classname>Producer</classname> by calling
       <methodname>Suscription.request()</methodname>. The general term in this context for flow control is
       <emphasis role="bold">backpressure</emphasis>.
    </para>
    
    <para>
       There are a number of implementations of Reactive Streams, including 
    </para>
    
    <orderedlist>
       <listitem><emphasis role="bold">RxJava</emphasis>: 
          <ulink url="https://github.com/ReactiveX/RxJava">https://github.com/ReactiveX/RxJava</ulink> (end of life, superceded by RxJava 2)
       </listitem>
       <listitem><emphasis role="bold">RxJava 2</emphasis>: 
          <ulink url="https://github.com/ReactiveX/RxJava">https://github.com/ReactiveX/RxJava</ulink>
       </listitem>
       <listitem><emphasis role="bold">Reactor</emphasis>: 
          <ulink url="http://projectreactor.io/">http://projectreactor.io/</ulink>
       </listitem>
       <listitem><emphasis role="bold">Flow</emphasis>: 
          <ulink url="https://community.oracle.com/docs/DOC-1006738">https://community.oracle.com/docs/DOC-1006738/</ulink>:
          (Java JDK 9+)
          </listitem>
    </orderedlist>
    
    <para>
       RESTEasy currently supports RxJava (deprecated) and RxJava2.
    </para>
    
</sect1>

<sect1>
<title>Pluggable reactive types: RxJava 2 in RESTEasy</title>

    <para>
       JAX-RS 2.1 doesn't require support for any Reactive Streams implementations, but it does allow
       for extensibility to support various reactive libraries.
       RESTEasy's optional modules <code>resteasy-rxjava1</code> and <code>resteasy-rxjava2</code> 
       add support for <ulink url="https://github.com/ReactiveX/RxJava">RxJava 1 and 2</ulink>.
       [Only <code>resteasy-rxjava2</code> will be discussed here, since <code>resteasy-rxjava1</code> is
       deprecated, but the treatment of the two is quite similar.]
    </para>
    
    <para>
       In particular, <code>resteasy-rxjava2</code>
       contributes support for reactive types <classname>io.reactivex.Single</classname>,
       <classname>io.reactivex.Flowable</classname>, and <classname>io.reactivex.Observable</classname>.
       Of these, <classname>Single</classname> is similar to <classname>CompletionStage</classname> in that
       it holds at most one potential value. <classname>Flowable</classname> implements 
       <classname>io.reactivex.Publisher</classname>, and <classname>Observable</classname> is very
       similar to <classname>Flowable</classname> except that it doesn't support backpressure.
       So, if you import <code>resteasy-rxjava2</code>, you can just start returning these reactive types from your
       resource methods on the server side and receiving them on the client side.
    </para>
    
<sect1>
<title>Server side</title>
    <para>
       Given the class <classname>Thing</classname>, which can be represented in JSON:
    </para>
    
<programlisting>
public class Thing {

   private String name;

   public Thing() {
   }

   public Thing(String name) {
      this.name = name;
   }
   ...
}
</programlisting>

    <para>the method <methodname>postThingList()</methodname> in the following is a valid resource method:
    </para>
...
<programlisting>
@POST
@Path("post/thing/list")
@Produces(MediaType.APPLICATION_JSON)
@Stream
public Flowable&lt;List&lt;Thing&gt;&gt; postThingList(String s) {
   return buildFlowableThingList(s, 2, 3);
}

static Flowable&lt;List&lt;Thing&gt;&gt; buildFlowableThingList(String s, int listSize, int elementSize) {
   return Flowable.create(
      new FlowableOnSubscribe&lt;List&lt;Thing&gt;&gt;() {

         @Override
         public void subscribe(FlowableEmitter&lt;List&lt;Thing&gt;&gt; emitter) throws Exception {
            for (int i = 0; i &lt; listSize; i++) {
               List&lt;Thing&gt; list = new ArrayList&lt;Thing&gt;();
               for (int j = 0; j &lt; elementSize; j++) {
                  list.add(new Thing(s));
               }
               emitter.onNext(list);
            }
            emitter.onComplete();
         }
      },
      BackpressureStrategy.BUFFER);
}
</programlisting>

    <para>
       The somewhat imposing method <methodname>buildFlowableThingList()</methodname> probably deserves
       some explanation. First,
    </para>
    
<programlisting>
Flowable&lt;List&lt;Thing&gt;&gt; Flowable.create(FlowableOnSubscribe&lt;List&lt;Thing&gt;&gt; source, BackpressureStrategy mode);
</programlisting>
    
    <para>
    creates a <classname>Flowable&lt;List&lt;Thing&gt;&gt;</classname> by describing what should happen when
    the <classname>Flowable&lt;List&lt;Thing&gt;&gt;</classname> is subscribed to. 
    <classname>FlowableEmitter&lt;List&lt;Thing&gt;&gt;</classname>
    extends <classname> io.reactivex.Emitter&lt;List&lt;Thing&gt;&gt;</classname>:
    </para>
    
<programlisting>
/**
 * Base interface for emitting signals in a push-fashion in various generator-like source
 * operators (create, generate).
 *
 * @param &lt;T&gt; the value type emitted
 */
public interface Emitter&lt;T&gt; {

    /**
     * Signal a normal value.
     * @param value the value to signal, not null
     */
    void onNext(@NonNull T value);

    /**
     * Signal a Throwable exception.
     * @param error the Throwable to signal, not null
     */
    void onError(@NonNull Throwable error);

    /**
     * Signal a completion.
     */
    void onComplete();
}
</programlisting>

    <para>
       and <classname>FlowableOnSubscribe</classname> uses a <classname>FlowableEmitter</classname>
       to send out values from the <classname>Flowable&lt;List&lt;Thing&gt;&gt;</classname>:
    </para>
    
<programlisting>
/**
 * A functional interface that has a {@code subscribe()} method that receives
 * an instance of a {@link FlowableEmitter} instance that allows pushing
 * events in a backpressure-safe and cancellation-safe manner.
 *
 * @param &lt;T&gt; the value type pushed
 */
public interface FlowableOnSubscribe&lt;T&gt; {

    /**
     * Called for each Subscriber that subscribes.
     * @param e the safe emitter instance, never null
     * @throws Exception on error
     */
    void subscribe(@NonNull FlowableEmitter&lt;T&gt; e) throws Exception;
}
</programlisting>
    
    <para>
       So, what will happen
       when a subscription to the <classname>Flowable&lt;List&lt;Thing&gt;&gt;</classname> is created is,
       the <methodname>FlowableEmitter.onNext()</methodname> will be called, once for each
       <classname>&lt;List&lt;Thing&gt;&gt;</classname> created, followed by a call to
       <methodname>FlowableEmitter.onComplete()</methodname> to indicate that the sequence has ended. Under the covers,
       RESTEasy subscribes to the <classname>Flowable&lt;List&lt;Thing&gt;&gt;</classname> and handles each element passed in
       by way of <methodname>onNext()</methodname>.
    </para>
</sect1>
    
<sect1>
<title>Client side</title>
   
    <para>
       On the client side, JAX-RS 2.1 supports extensions for reactive classes by adding the method
    </para>
    
<programlisting>
/**
 * Access a reactive invoker based on a {@link RxInvoker} subclass provider. Note
 * that corresponding {@link RxInvokerProvider} must be registered in the client runtime.
 * 
 * This method is an extension point for JAX-RS implementations to support other types
 * representing asynchronous computations.
 *
 * @param clazz {@link RxInvoker} subclass.
 * @return reactive invoker instance.
 * @throws IllegalStateException when provider for given class is not registered.
 * @see javax.ws.rs.client.Client#register(Class)
 * @since 2.1
 */
public &lt;T extends RxInvoker&gt; T rx(Class&lt;T&gt; clazz);
</programlisting>

    <para>
       to interface <classname> javax.ws.rs.client.Invocation.Builder</classname>. Resteasy
       module <code>resteasy-rxjava2</code> adds support for classes:
    </para>
    
   <orderedlist>
      <listitem><classname>org.jboss.resteasy.rxjava2.SingleRxInvoker</classname>,</listitem>
      <listitem><classname>org.jboss.resteasy.rxjava2.FlowableRxInvoker</classname></listitem>, and
      <listitem><classname>org.jbosss.resteasy.rxjava2.ObservableRxInvoker</classname></listitem>.
   </orderedlist>
   
   <para>
      which allow accessing <classname>Single</classname>s, <classname>Observable</classname>s, and
      <classname>Flowable</classname>s on the client side.
   </para>
   
   <para>
      For example, given the resource method <methodname>postThingList()</methodname> above, a
      <classname>Flowable&lt;List&lt;Thing&gt;&gt;</classname> can be retrieved from the server
      by calling
   </para>
   
<programlisting>
@SuppressWarnings("unchecked")
@Test
public void testPostThingList() throws Exception {
   CountDownLatch latch = new CountdownLatch(1);
   FlowableRxInvoker invoker = client.target(generateURL("/post/thing/list")).request().rx(FlowableRxInvoker.class);
   Flowable&lt;List&lt;Thing&gt;&gt; flowable = (Flowable&lt;List&lt;Thing&gt;&gt;) invoker.post(Entity.entity("a", MediaType.TEXT_PLAIN_TYPE), new GenericType&lt;List&lt;Thing&gt;&gt;() {});
   flowable.subscribe(
         (List&lt;?&gt; l) -&gt; thingListList.add(l),
         (Throwable t) -&gt; latch.countDown(),
         () -&gt; latch.countDown());
   latch.await();
   Assert.assertEquals(aThingListList, thingListList);
}
</programlisting>
 
   <para>
      where <code>aThingListList</code> is
   </para>  
   
<programlisting>
[[Thing[a], Thing[a], Thing[a]], [Thing[a], Thing[a], Thing[a]]]
</programlisting>

   <para>
      Note the call to <methodname>Flowable.suscribe()</methodname>. On the server side, RESTEasy subscribes to a 
      returning <classname>Flowable</classname> in order to receive its elements and send them over the wire. On the client side,
      the user subscribes to the <classname>Flowable</classname> in order to receive its elements and do whatever it wants to
      with them. In this case, three lambdas determine what should happen 1) for each element, 2) if a <classname>Throwable</classname>
      is thrown, and 3) when the <classname>Flowable</classname> is done passing elements.
   </para>
   
</sect1>

<sect1>
<title>Representation on the wire</title>

    <para>
       Neither Reactive Streams nor JAX-RS have anything to say about representing reactive types on the network.
       RESTEasy offers a number of representations, each suitable for different circumstances. The wire protocol
       is determined by 1) the presence or absence of the <code>@Stream</code> annotation on the resource method, 
       and 2) the value of the <code>value</code> field in the <code>@Stream</code> annotation:
    </para>
    
<programlisting>
@Target({ElementType.TYPE, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface Stream
{
   public enum MODE {RAW, GENERAL};
   public String INCLUDE_STREAMING_PARAMETER = "streaming";
   public MODE value() default MODE.GENERAL;
   public boolean includeStreaming() default false;
}
</programlisting>

    <para>
       Note that <code>MODE.GENERAL</code> is the default value, so <code>@Stream</code> is equivalent
       to <code>@Stream(Stream.MODE.GENERAL)</code>.
    </para>
    
    <variablelist>
        <varlistentry>
            <term>No <code>@Stream</code> annotation on the resource method</term>
            <listitem>
                Resteasy will collect every value until the stream is complete, then wrap them into a
                <code>java.util.List</code> entity  and send to the client.
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><code>@Stream(Stream.MODE.GENERAL)</code></term>
            <listitem>
                This case uses a variant of the SSE format, modified to eliminate some restrictions inherent in SSE.
                (See the specification at
                <ulink url="https://html.spec.whatwg.org/multipage/server-sent-events.html">
                https://html.spec.whatwg.org/multipage/server-sent-events.html</ulink> for details.)
                In particular, 1) SSE events are meant to hold text data, represented in character set UTF-8. In the general streaming mode,
                certain delimiting characters in the data ('\r', '\n', and '\') are escaped so that arbitrary binary data can be
                transmitted. Also, 2) the SSE specification requires the client to reconnect if it gets disconnected. If the stream
                is finite, reconnecting will induce a repeat of the stream, so SSE is really meant for unlimited streams.
                In general streaming mode, the client will close, rather than automatically reconnect, at the end of the stream. It follows
                that this mode is suitable for finite streams.
                
                <para>
                   <emphasis role="bold">Note. </emphasis> The Content-Type header in general streaming mode is set to
                </para>
                
                <programlisting>
          applicaton/x-stream-general;"element-type=&lt;element-type&gt;"
                </programlisting>
                <para>
                   where &lt;element-type&gt;
                   is the media type of the data elements in the stream. The element media type is derived
                   from the @Produces annotation. For example, 
                </para>
      
                <programlisting>
      @GET
      @Path("flowable/thing")
      @Stream
      @Produces("application/json")
      public Flowable&lt;Thing&gt; getFlowable() { ... }
                </programlisting>
                
                <para>
                   induces the media type
                </para>
                
                <programlisting>
          application/x-stream-general;"element-type=application/json"
                </programlisting>
                
                <para>
                   which describes a stream of JSON elements.
                </para>
            </listitem>
        </varlistentry>
         <varlistentry>
            <term><code>@Stream(Stream.MODE.RAW)</code></term>
            <listitem>
                In this case each value is written directly to the wire, without any formatting, as it becomes available. 
                This is most useful for values that can be cut in pieces, such as strings, bytes, buffers, etc., and then
                re-concatenated on the client side. Note that without delimiters as in
                general mode, it isn't possible to reconstruct something like <classname>List&lt;List&lt;String&gt;&gt;</classname>.

                <para>
                   <emphasis role="bold">Note. </emphasis> The Content-Type header in raw streaming mode is derived from
                   the <code>@Produces</code> annotation. The <code>@Stream</code> annotation offers the possibility of an
                   optional <classname>MediaType</classname> parameter called "streaming". The point is to be able to suggest
                   that the stream of data emanating from the server is unbounded, i.e., that the client shouldn't try to
                   read it all as a single byte array, for example. The parameter is set by explicitly setting the
                   <code>@Stream</code> parameter <code>includeStreaming()</code> to <code>true</code>. For example,
                </para>
                
<programlisting>
   @GET
   @Path("byte/default")
   @Produces("application/octet-stream;x=y")
   @Stream(Stream.MODE.RAW)
   public Flowable&lt;Byte&gt; aByteDefault() {
      return Flowable.fromArray((byte) 0, (byte) 1, (byte) 2);
   }
</programlisting>

    <para>
       induces the <classname>MediaType</classname> "application/octet-stream;x=y", and
    </para>
    
<programlisting>
   @GET
   @Path("byte/true")
   @Produces("application/octet-stream;x=y")
   @Stream(value=Stream.MODE.RAW, includeStreaming=true)
   public Flowable&lt;Byte&gt; aByteTrue() {
      return Flowable.fromArray((byte) 0, (byte) 1, (byte) 2);
   }
</programlisting>

    <para>
       induces the <classname>MediaType</classname> "application/octet-stream;x=y;streaming=true".
    </para>
    
    <para>
       Note that browsers such as Firefox and Chrome seem to be comfortable with reading unlimited streams
       without any additional hints.
    </para>
           </listitem>
        </varlistentry>
    </variablelist>
</sect1>

<sect1>
<title>Examples.</title>
    
    <para>
       <emphasis role="bold">Example 1.</emphasis>
    </para>
    
<programlisting>
@POST
@Path("post/thing/list")
@Produces(MediaType.APPLICATION_JSON)
@Stream(Stream.MODE.GENERAL)
public Flowable&lt;List&lt;Thing&gt;&gt; postThingList(String s) {
   return buildFlowableThingList(s, 2, 3);
}
...
@SuppressWarnings("unchecked")
@Test
public void testPostThingList() throws Exception {
   CountDownLatch latch = new CountdownLatch(1);
   FlowableRxInvoker invoker = client.target(generateURL("/post/thing/list")).request().rx(FlowableRxInvoker.class);
   Flowable&lt;List&lt;Thing&gt;&gt; flowable = (Flowable&lt;List&lt;Thing&gt;&gt;) invoker.post(Entity.entity("a", MediaType.TEXT_PLAIN_TYPE), new GenericType&lt;List&lt;Thing&gt;&gt;() {});
   flowable.subscribe(
         (List&lt;?&gt; l) -&gt; thingListList.add(l),
         (Throwable t) -&gt; latch.countDown(),
         () -&gt; latch.countDown());
   latch.await();
   Assert.assertEquals(aThingListList, thingListList);
}
</programlisting>

    <para>
       This is the example given previously, except that the mode in the <code>@Stream</code> annotation (which defaults
       to MODE.GENERAL) is given explicitly. In this scenario, the <classname>Flowable</classname> emits
       <classname>&lt;List&lt;Thing&gt;&gt;</classname> elements on the server, they are transmitted over the wire as
       SSE events:
    </para>
    
<programlisting>
data: [{"name":"a"},{"name":"a"},{"name":"a"}]
data: [{"name":"a"},{"name":"a"},{"name":"a"}]
</programlisting>
       
    <para>
       and the <classname>FlowableRxInvoker</classname> reconstitutes a <classname>Flowable</classname> on the
       client side.
    </para>
    
    <para><emphasis role="bold">Example 2.</emphasis></para>
    
<programlisting>
@POST
@Path("post/thing/list")
@Produces(MediaType.APPLICATION_JSON)
public Flowable&lt;List&lt;Thing&gt;&gt; postThingList(String s) {
   return buildFlowableThingList(s, 2, 3);
}
...
@Test
public void testPostThingList() throws Exception {
   Builder request = client.target(generateURL("/post/thing/list")).request();
   List&lt;List&lt;Thing&gt;&gt; list = request.post(Entity.entity("a", MediaType.TEXT_PLAIN_TYPE), new GenericType&lt;List&lt;List&lt;Thing&gt;&gt;&gt;() {});
   Assert.assertEquals(aThingListList, list);
}  
</programlisting>

    <para>
       In this scenario, in which the resource method has no <code>@Stream</code> annotation, the 
       <classname>Flowable</classname> emits stream elements which are accumulated by the server until
       the <classname>Flowable</classname> is done, at which point the entire JSON list is transmitted over the wire:
    </para>
    
<programlisting>
[[{"name":"a"},{"name":"a"},{"name":"a"}],[{"name":"a"},{"name":"a"},{"name":"a"}]]
</programlisting>

    <para>
       and the list is reconstituted on the client side by an ordinary invoker.
    </para>
    
    <para><emphasis role="bold">Example 3.</emphasis></para>
     
<programlisting>
@GET
@Path("get/bytes")
@Produces(MediaType.APPLICATION_OCTET_STREAM)
@Stream(Stream.MODE.RAW)
public Flowable&lt;byte[]&gt; getBytes() {
   return Flowable.create(
      new FlowableOnSubscribe&lt;byte[]&gt;() {

         @Override
         public void subscribe(FlowableEmitter&lt;byte[]&gt; emitter) throws Exception {
            for (int i = 0; i &lt; 3; i++) {
               byte[] b = new byte[10];
               for (int j = 0; j &lt; 10; j++) {
                  b[j] = (byte) (i + j);
               }
               emitter.onNext(b);
            }
            emitter.onComplete();
         }
      },
      BackpressureStrategy.BUFFER);
}
...
@Test
public void testGetBytes() throws Exception {
   Builder request = client.target(generateURL("/get/bytes")).request();
   InputStream is = request.get(InputStream.class);
   int n = is.read();
   while (n &gt; -1) {
      System.out.print(n);
      n = is.read();
   }
}
</programlisting>

    <para>
       Here, the byte arrays are written to the network as they are created by the <classname>Flowable</classname>.
       On the network, they are concatenated, so the client sees one stream of bytes.
    </para>
    
    <note>
        <para>
           Given that asynchronous code is common in this context, it is worth looking at the earlier 
           <link linkend="asyncContextNote">Note</link>.
       </para>
   </note>
</sect1>

<sect1>
<title>Rx and SSE</title>

    <para>
       Since general streaming mode and SSE share minor variants of the same wire protocol, they are, modulo the SSE
       restriction to character data, interchangeable. That is, an SSE client can connect to a resource method that returns
       a <classname>Flowable</classname> or an <classname>Observable</classname>, and a <classname>FlowableRxInvoker</classname>,
       for example, can connect to an SSE resource method.
    </para>
    
    <para>
        <emphasis role="bold">Note.</emphasis> SSE requires a <code>@Produces("text/event-stream")</code>
        annotation, so, unlike the cases of raw and general streaming, the element media type cannot
        be derived from the <code>@Produces</code> annotation. To solve this problem, Resteasy introduces the
    </para>
    
<programlisting>
@Target({ElementType.TYPE, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface SseElementType
{
   public String value();
}
</programlisting>

    <para>
        annotation, from which the element media type is derived.
    </para>
    
    <para><emphasis role="bold">Example 1.</emphasis></para>
    
<programlisting>
@GET
@Path("eventStream/thing")
@Produces("text/event-stream")
@SseElementType("application/json")
public void eventStreamThing(@Context SseEventSink eventSink, @Context Sse sse) {
   new ScheduledThreadPoolExecutor(5).execute(() -&gt; {
      try (SseEventSink sink = eventSink) {
         OutboundSseEvent.Builder  builder = sse.newEventBuilder();
         eventSink.send(builder.data(new Thing("e1")).build());
         eventSink.send(builder.data(new Thing("e2")).build());
         eventSink.send(builder.data(new Thing("e3")).build());
      }
   });
}
...
@SuppressWarnings("unchecked")
@Test
public void testFlowableToSse() throws Exception {
   CountDownLatch latch = new CountDownLatch(1);
   final AtomicInteger errors = new AtomicInteger(0);
   FlowableRxInvoker invoker = client.target(generateURL("/eventStream/thing")).request().rx(FlowableRxInvoker.class);
   Flowable&lt;Thing&gt; flowable = (Flowable&lt;Thing&gt;) invoker.get(Thing.class);
   flowable.subscribe(
      (Thing t) -&gt; thingList.add(t),
      (Throwable t) -&gt; errors.incrementAndGet(),
      () -&gt; latch.countDown());
   boolean waitResult = latch.await(30, TimeUnit.SECONDS);
   Assert.assertTrue("Waiting for event to be delivered has timed out.", waitResult);
   Assert.assertEquals(0, errors.get());
   Assert.assertEquals(eThingList, thingList);
}  
</programlisting>

    <para>
       Here, a <classname>FlowableRxInvoker</classname> is connecting to an SSE resource method. On the network,
       the data looks like
    </para>
    
<programlisting>
data: {"name":"e1"}
data: {"name":"e2"}
data: {"name":"e3"}
</programlisting>

    <para>
       Note that the character data is suitable for an SSE resource method.
    </para>

    <para>
       Also, note that the <methodname>eventStreamThing()</methodname> method in this example induces the media type
    </para>
    
<programlisting>
    text/event-stream;element-type="application/json"
</programlisting>
    
    <para><emphasis role="bold">Example 2.</emphasis></para>
    
<programlisting>
@GET
@Path("flowable/thing")
@Produces("text/event-stream")
@SseElementType("application/json")
public Flowable&lt;Thing&gt; flowableSSE() {
   return Flowable.create(
      new FlowableOnSubscribe&lt;Thing&gt;() {

         @Override
         public void subscribe(FlowableEmitter&lt;Thing&gt; emitter) throws Exception {
            emitter.onNext(new Thing("e1"));
            emitter.onNext(new Thing("e2"));
            emitter.onNext(new Thing("e3"));
            emitter.onComplete();
         }
      },
      BackpressureStrategy.BUFFER);
}
...
@Test
public void testSseToFlowable() throws Exception {
   final CountDownLatch latch = new CountDownLatch(3);
   final AtomicInteger errors = new AtomicInteger(0);
   WebTarget target = client.target(generateURL("/flowable/thing"));
   SseEventSource msgEventSource = SseEventSource.target(target).build();
   try (SseEventSource eventSource = msgEventSource)
   {
      eventSource.register(
         event -&gt; {thingList.add(event.readData(Thing.class, MediaType.APPLICATION_JSON_TYPE)); latch.countDown();},
         ex -&gt; errors.incrementAndGet());
      eventSource.open();

      boolean waitResult = latch.await(30, TimeUnit.SECONDS);
      Assert.assertTrue("Waiting for event to be delivered has timed out.", waitResult);
      Assert.assertEquals(0, errors.get());
      Assert.assertEquals(eThingList, thingList);
   }
}
</programlisting>

    <para>
       Here, an SSE client is connecting to a resource method that returns a <classname>Flowable</classname>.
       Again, the server is sending character data, which is suitable for the SSE client, and the data looks
       the same on the network.
    </para>
</sect1>

<sect1>
<title>To stream or not to stream</title>

    <para>
       Whether or not it is appropriate to stream a list of values is a judgment call. Certainly, if the
       list is unbounded, then it isn't practical, or even possible, perhaps, to collect the entire list
       and send it at once. In other cases, the decision is less obvious. 
    </para>
    
    <para>
       <emphasis role="bold">Case 1.</emphasis> Suppose that all of the elements are producible quickly.
       Then the overhead of sending them independently is probably not worth it.
    </para>
    
    <para>
       <emphasis role="bold">Case 2.</emphasis> Suppose that the list is bounded but the elements will
       be produced over an extended period of time. Then returning the initial elements when they become
       available might lead to a better user experience.
    </para>
    
    <para>
       <emphasis role="bold">Case 3.</emphasis> Suppose that the list is bounded and the elements can be
       produced in a relatively short span of time but only after some delay. Here is a situation that
       illustrates the fact that asynchronous reactive processing and streaming over the network are
       independent concepts. In this case it's worth considering having the resource method return
       something like <classname>CompletionStage&lt;List&lt;Thing&gt;&gt;</classname> rather than
       <classname>Flowable&lt;List&lt;Thing&gt;&gt;</classname>. This has the 
       benefit of creating the list asynchronously but, once it is available, sending it to the client
       in one piece.
    </para>
</sect1>
</sect1>

<sect1>
<title>Proxies</title>

    <para>
       Proxies, discussed in <link linkend="proxies">RESTEasy Proxy Framework</link>, are a RESTEasy extension
       that supports a natural programming style in which generic JAX-RS invoker calls are replaced by application
       specific interface calls. The proxy framework is extended to include both
       <classname>CompletionStage</classname> and the RxJava2 types <classname>Single</classname>,
       <classname>Observable</classname>, and <classname>Flowable</classname>.
    </para>
    
    <para><emphasis role="bold">Example 1.</emphasis></para>
    
<programlisting>
@Path("")
public interface RxCompletionStageResource {

   @GET
   @Path("get/string")
   @Produces(MediaType.TEXT_PLAIN)
   public CompletionStage&lt;String&gt; getString();
}

@Path("")
public class RxCompletionStageResourceImpl {

   @GET
   @Path("get/string")
   @Produces(MediaType.TEXT_PLAIN)
   public CompletionStage&lt;String&gt; getString() { .... }
}

public class RxCompletionStageProxyTest {

   private static ResteasyClient client;
   private static RxCompletionStageResource proxy;
   
   static {
      client = new ResteasyClientBuilder().build();
      proxy = client.target(generateURL("/")).proxy(RxCompletionStageResource.class);
   }
   
   @Test
   public void testGet() throws Exception {
      CompletionStage&lt;String&gt; completionStage = proxy.getString();
      Assert.assertEquals("x", completionStage.toCompletableFuture().get());
   }
}
</programlisting>

    <para>
       <emphasis role="bold">Example 2.</emphasis>
    </para>
    
<programlisting>
public interface Rx2FlowableResource {

   @GET
   @Path("get/string")
   @Produces(MediaType.TEXT_PLAIN)
   @Stream
   public Flowable&lt;String&gt; getFlowable();
}

@Path("")
public class Rx2FlowableResourceImpl {

   @GET
   @Path("get/string")
   @Produces(MediaType.TEXT_PLAIN)
   @Stream
   public Flowable&lt;String&gt; getFlowable() { ... }
}

public class Rx2FlowableProxyTest {

   private static ResteasyClient client;
   private static Rx2FlowableResource proxy;
   
   static {
      client = new ResteasyClientBuilder().build();
      proxy = client.target(generateURL("/")).proxy(Rx2FlowableResource.class);
   }
   
   @Test
   public void testGet() throws Exception {
      Flowable&lt;String&gt; flowable = proxy.getFlowable();
      flowable.subscribe(
         (String o) -&gt; stringList.add(o),
         (Throwable t) -&gt; errors.incrementAndGet(),
         () -&gt; latch.countDown());
      boolean waitResult = latch.await(30, TimeUnit.SECONDS);
      Assert.assertTrue("Waiting for event to be delivered has timed out.", waitResult);
      Assert.assertEquals(0, errors.get());
      Assert.assertEquals(xStringList, stringList);
   }
}
</programlisting>
</sect1>

<sect1>
<title>Adding extensions</title>

    <para>
       RESTEasy implements a framework that supports extensions for additional reactive classes. To understand
       the framework, it is necessary to understand the existing support for <classname>CompletionStage</classname>
       and other reactive classes.
    </para>
    
    <para>
       <emphasis role="bold">Server side.</emphasis> When a resource method returns a
       <classname>CompletionStage</classname>, RESTEasy subscribes to it using the class
       <classname>org.jboss.resteasy.core.AsyncResponseConsumer.CompletionStageResponseConsumer</classname>.
       When the <classname>CompletionStage</classname> completes, it calls 
       <methodname>CompletionStageResponseConsumer.accept()</methodname>, which sends the result back to
       the client.
    </para>
    
    <para>
       Support for <classname>CompletionStage</classname> is built in to RESTEasy, but it's not hard to extend
       that support to a class like <classname>Single</classname> by providing a mechanism for transforming a
       <classname>Single</classname> into a <classname>CompletionStage</classname>. In module resteasy-rxjava2,
       that mechanism is supplied by <classname>org.jboss.resteasy.rxjava2.SingleProvider</classname>, which
       implements interface <classname>org.jboss.resteasy.spi.AsyncResponseProvider&lt;Single&lt;?&gt;&gt;</classname>:
    </para>
    
<programlisting>
public interface AsyncResponseProvider&lt;T&gt; {
   public CompletionStage toCompletionStage(T asyncResponse);
}
</programlisting>

    <para>
       Given <classname>SingleProvider</classname>, RESTEasy can take a <classname>Single</classname>,
       transform it into a <classname>CompletionStage</classname>, and then use 
       <classname>CompletionStageResponseConsumer</classname> to handle the eventual value of
       the <classname>Single</classname>.
    </para>
    
    <para>
       Similarly, when a resource method returns a streaming reactive class like <classname>Flowable</classname>,
       RESTEasy subscribes to it, receives a stream of data elements, and sends them to the client.
       <classname>AsyncResponseConsumer</classname> has several supporting classes, each of which implements a 
       different mode of streaming. For example, <classname>AsyncResponseConsumer.AsyncGeneralStreamingSseResponseConsumer</classname>
       handles general streaming and SSE streaming. Subscribing is done by calling 
       <methodname>org.reactivestreams.Publisher.subscribe()</methodname>, so a mechanism is needed
       for turning, say, a <classname>Flowable</classname> into a <classname>Publisher</classname>.
       That is, an implementation of <classname>org.jboss.resteasy.spi.AsyncStreamProvider&lt;Flowable&gt;</classname>
       is called for, where <classname>AsyncStreamProvider</classname> is defined:
    </para>
       
<programlisting>
public interface AsyncStreamProvider&lt;T&gt; {
   public Publisher toAsyncStream(T asyncResponse);
}
</programlisting>
       
    <para>
       In module resteasy-rxjava2, <classname>org.jboss.resteasy.FlowableProvider</classname> provides
       that mechanism for <classname>Flowable</classname>. [Actually, that's not too hard since, in
       rxjava2, a <classname>Flowable</classname> <emphasis>is</emphasis> a <classname>Provider</classname>.]
    </para>
    
    <para>
        So, on the server side, adding support for other reactive types can be done by declaring a <code>@Provider</code> for the interface
        <code>AsyncStreamProvider</code> (for streams) or <code>AsyncResponseProvider</code> (for single values), which
        both have a single method to convert the new reactive type into (respectively) a <code>Publisher</code> (for streams)
        or a <code>CompletionStage</code> (for single values).
    </para>
    
    <para>
       <emphasis role="bold">Client side.</emphasis> The JAX-RS specification version 2.1 imposes two
       requirements for support of reactive classes on the client side:   
    </para> 
    
    <orderedlist>
       <listitem>support for <classname>CompletionStage</classname> in the form of
          an implementation of the interface <classname>javax.ws.rs.client.CompletionStageRxInvoker</classname>, and
       </listitem>
       <listitem>
          extensibility in the form of support for registering providers that implement
<programlisting>
public interface RxInvokerProvider&lt;T extends RxInvoker&gt; {
    public boolean isProviderFor(Class&lt;T&gt; clazz);
    public T getRxInvoker(SyncInvoker syncInvoker, ExecutorService executorService);
}
</programlisting>
          Once an <classname>RxInvokerProvider</classname> is registered, an <classname>RxInvoker</classname>
          can be requested by calling the <classname>javax.ws.rs.client.Invocation.Builder</classname> method
<programlisting>
public &lt;T extends RxInvoker&gt; T rx(Class&lt;T&gt; clazz);
</programlisting>
          That <classname>RxInvoker</classname> can then be used for making an invocation that returns
          the appropriate reactive class. For example,
<programlisting>
FlowableRxInvoker invoker = client.target(generateURL("/get/string")).request().rx(FlowableRxInvoker.class);
Flowable&lt;String&gt; flowable = (Flowable&lt;String&gt;) invoker.get();
</programlisting>
       </listitem>
    </orderedlist>
    
    <para>
       RESTEasy provides partial support for implementing <classname>RxInvoker</classname>s. For example,
       <classname>SingleProvider</classname>, mentioned above, also implements
       <classname>org.jboss.resteasy.spi.AsyncClientResponseProvider&lt;Single&lt;?&gt;&gt;</classname>,
       where <classname>AsyncClientResponseProvider</classname> is defined
    </para>
    
<programlisting>
public interface AsyncClientResponseProvider&lt;T&gt; {
   public T fromCompletionStage(CompletionStage&lt;?&gt; completionStage);
}
</programlisting>

    <para>
       <classname>SingleProvider</classname>'s ability to turn a <classname>CompletionStage</classname>
       into a <classname>Single</classname> is used in the implementation of 
       <classname>org.jboss.resteasy.rxjava2.SingleRxInvokerImpl</classname>.
    </para>
    
    <para>
       The same concept might be useful in implementing other <classname>RxInvoker</classname>s. Note, 
       though, that <classname>ObservableRxInvokerImpl</classname> and 
       <classname>FlowableRxInvokerImpl</classname> in module resteasy-rxjava2 are each derived
       directly from the SSE implementation.
    </para>

</sect1>

</chapter>