Review feedback

[yeekangc]

• "What is reactive programming?": I find this section rather dense. Can we revise/improve? May be useful to have @Charlotte-Holt or team to take a look sooner rather than later. I will appreciate more support/elaboration for the advantages of reactive (and why) too.

• "You will learn how the default reactive JAX-RS client accesses remote RESTful services using asynchronous method calls.": The default reactive JAX-RS client of what? Call it out.

• "You will then learn how to update the client so that it uses custom objects form third-party libraries such as CXF or in this case Jersey.": Why these custom objects? What are they for? Why Jersey too?

• " You will also use this library to invoke your new client using Jersey’s custom invoker RxObservableInvoker. You will then update your resources to accommodate the new client. Instead of using elementary, single-use asynchronous solutions, you will use asynchronous data streams to transport data. Doing so, you will learn the benefits of using the Observable class over the more traditional CompletionStage interface, like more scalable implementation. You will also gain exposure to the rich set of operators that the former includes.": Can we use simpler words? I don't think the sections that follow explain all the benefits either? Should improve those or revise this section accordingly?

• "Additional Prerequisites": Use sentence-style capitalization to be consistent?

• "An implementation of the default reactive JAX-RS client is already provided for you.": I think we meant the application or service that we use/show, which is provided, has an implementation that uses the default JAX-RS client in reactive manner?

• "The classes changed are JobClient and GatewayJobResource which now implement the default JAX-RS reactive client.": If they are provided, they won't have changed?

• "Similarly to the synchronous approach, if we successfully get the completed jobs from the job microservice, then the resource will respond with an HTTP status of 200 and the body will contain a list of jobs.": We have not discussed "the synchronous approach" thus far so it's odd that it suddenly appears?

• "Using the default reactive JAX-RS client": For this section, I think we should explain what is this default client and where it comes from. We can dive into the details of the implementation i.e. how the client is used in the application. You may want to organize the explanation by classes or at least, logically group and discuss them.

• "Updating the client to use third-party objects": What are third-party objects? Why third-party objects? We are trying to plug in and use a third-party reactive library, right? Consider renaming the section.

• "JAX-RS supports the usage of third-party libraries like Jersey, and can allow for client configurations that are different from the default one.

By using Jersey, the client can be updated to support RxJava objects instead of only the CompletionStage interface. These custom objects are useful for covering use cases that the CompletionStage interface cannot.

The ReactiveX API and the required Jersey libraries are included as dependencies to your gateway/pom.xml file. Look for the dependencies with artifactIDs of rxjava, jersey-client, jersey-rx-client-rxjava and jersey-rx-client-rxjava2.": Why Jersey? Why not RxJava directly? What's ReactiveX? What's the relationship between Jersey, RxJava and ReactiveX? We should explain the relationship appropriately. And, we need to explain why a developer may want to use third-party library too. What's the benefits?

• "Observable is a class that is part of ReactiveX and, as will be seen later, is a more flexible data type than the CompletionStage interface.": Can we explain what is an Observable in more concrete terms? Perhaps with an example?

• "If you wanted to return a Flowable object instead, you would need to pass RxFlowableInvoker.class.": Flowable seems to appear out of the blue? Why Flowable here?

• "Sometimes there are scenarios where a producer will generate more data than the consumers and handle. In cases like these, JAX-RS can deal with this issue using backpressure and Flowables. You can learn more with this post about JAX-RS reactive extensions with RxJava Backpressure": What do we mean by "JAX-RS can deal with this ..."? JAX-RS is an API to do REST services in Java only? Missing a full stop for this paragraph too.

• "Updating the client to use third-party objects": Can we organize things more logically in this section? What if we start by talking about registering the Provider first?

• "Updating the JAX resources": What are "JAX resources"? Please rename.

• Consider updating "What you'll learn" to outline what the guide will cover in taking a user from a client using CompletionStage to plugging in a third-party library to work in a (native) reactive manner and the order where the different parts will be updated. It may be useful to call out and describe the observable pattern up front too.

• "The gateway, job, system, and inventory microservices will be built in a Docker container.": A Docker container only? And, built inside a Docker container?

• "Switching to an asynchronous programming model has freed up the thread handling your request to /api/jobs. While the client request is being handled, the thread can handle other work.": Are we asynchronous or reactive now?

• "mvn -pl models ...": Will it be useful to explain why we are doing this?

• Do we need to explain that JAX-RS allows you to plug in third-party library in this guide? Is this the basic premise for the guide?

• "You have just modified an application to make HTTP requests using reactive JAX-RS client with Open Liberty and Jersey.": This may need to be updated accordingly per changes to handle the above feedback.

• Front matter (metadata) should be reviewed and updated before publishing too.

@gkwan-ibm

[yeekangc]

Have these been fully addressed, @TiagoF99? It's unclear to me that they have been from my look at what I believe is the latest version.

[TiagoF99]

I referred to this when rewriting the guide and I believe alot of them should be addressed

[yeekangc]

Thanks. Let us close the issue when ready.