I’m happy to announce that I was selected to replace Marek as JAX-RS co-spec lead. Meaning that I’ll have something to blog about during next moths, most likely until JavaOne 2017.
If you are following discussions within various specifications, you might have noticed that JAX-RS was very quiet during last year. That is going to change. Or already did actually. The Expert Group (EG) is now working with updated schedule, which is mainly about following three items:
- Reactive Client API
- Server Sent Events
- Non-blocking I/O
First two items were already proposed in some way, but were never blessed from the EG, so we need to update them (if necessary), get them reviewed and incorporate review comments. That is what happened to Reactive Client API and this post will try to summarise that change.
JAX-RS Reactive Client API
Firstly, the goal of this feature is include support for reactive style programming on the client side. Not anything else. Also, we don’t want to create another client. Existing one already has support for synchronous and asynchronous request execution and we want to extend this with reactive style.
Let’s see the simples example:
CompletionStage<Response> csResponse = ClientBuilder.newClient() .target("http://oracle.com") .request() .rx() .get();
You can notice couple new things, namely the returned type is not the javax.ws.rs.Response or Future<Response> (which would be the case when rx() is replaced with async()) and there is new method in Client fluent API invocation chain – rx().
CompletionStage is a new interface, introduced in Java 8, which is also the only reactive standard which made it into the platform. (More about that later).
rx() method has been added to be able to switch from sync/async invoker to something new – RxInvoker in this case. It defines the same methods as the others, but it doesn’t have the return type specified in the same way – you can create subclass and redefine it, for example to the CompletionStage, as it is done in CompletionStageRxInvoker, which is also part of the proposed API.
There are several variants of the rx() method. One is related to providing an ExecutorService, the other one is about providing RxInvoker class. The former is simple to explain – reactive invocations are async by nature and we want to be able to specify the thread pool / executor service, which will be used to invoke that (which might be revisited later, for example removed by allowing client-wide async executor service configuration), the latter is about extensibility. That deserves another section, so..:
If you are implementing reactive application on Java, you most likely know other datatypes, provided by various frameworks. Namely Guava, RxJava and others. They do provide similar functionalities to CompletionStage, but with different APIs. Those can be beneficial to use, especially if you have an application already written using other, non-standard, frameworks and JAX-RS wants to make itself usable as easily as possible. Let’s start with code example:
Client client = ClientBuilder.newClient(); client.register(FlowableProvider.class); Flowable<Response> csResponse = client.target("http://oracle.com") .request() .rx(FlowableInvoker.class) .get();
Here, we do see how RxJava2 Flowable could be used when getting a JAX-RS Response.
Both FlowableProvider and FlowableInvoker are provided by the 3rd party – for example, if RxJava2 developer community things JAX-RS in important enough, they might release extension module, which will contain these classes. Also, as always, any JAX-RS implementation can choose the features and might provide similar provider as part of their implementation.
I don’t want to get into more detail, since this might be changed, but for now it seems like we have reached a conclusion, that this is the best possible way how the extensibility can be provided. If you are interested in knowing the decision process, feel free to read JAX-RS spec EG mailing list.
I hope you like newly proposed API. If you have any comments, please share them at the users mailing list on JAX-RS project!
Links, mailing lists, etc.
- JAX-RS JCP page: https://jcp.org/en/jsr/detail?id=370
- JAX-RS EG mailing list archive: https://java.net/projects/jax-rs-spec/lists/jsr370-experts/archive
- JAX-RS users mailing list: email@example.com
- JAX-RS source repository (Github mirror): https://github.com/jax-rs/api