Add description to JAX-RS:Async-Client sample

Add AsciiDoc based JavaDoc to the Test Class to describe
the sample;

* How it works
* How to use it
* etc

Author: aslakknutsen

jaxrs/async-client/pom.xml

@@ -10,6 +10,8 @@
 
     <groupId>org.javaee7.jaxrs</groupId>
     <artifactId>async-client</artifactId>
+    <name>Async Client</name>
+    <description>Invoke a JAX-RS service via an asynchronous client</description>
     <version>1.0-SNAPSHOT</version>
     <packaging>war</packaging>
 </project>

jaxrs/async-client/src/test/java/org/javaee7/jaxrs/asyncclient/MyResourceTest.java

@@ -30,11 +30,42 @@
 import org.junit.runner.RunWith;
 
 /**
- * @author Arun Gupta
+ * In this sample we're going to explore how to communicate with a +JAX-RS+
+ * service via an asynchronous invocation from the client.
+ * 
+ * First step; we need a service to invoke.
+ * 
+ * Let's create a simple +GET+ method.
+ * 
+ * include::MyResource#getList[]
+ * 
+ * For +JAX-RS+ to expose our service we need to provide an implementation of
+ * the +JAX-RS+ +Application+ class to define our root path.
+ * 
+ * include::MyApplication[]
  */
 @RunWith(Arquillian.class)
 public class MyResourceTest {
 
+    /**
+     * Since +JAX-RS+ webservices are, well, web related and require a
+     * web contex, they are required to be deployed within a +web archive+.
+     * By default, +JAX-RS+ will perform autodiscovery of our services.
+     * That means there is no need to add a +web.xml+ in this scenario.
+     * 
+     * Based on the definition of our +@Deployment+ method, we will be
+     * creating and deploying the following archive structure.
+     * [source,file]
+     * ----
+     * /WEB-INF/
+     * /WEB-INF/classes/
+     * /WEB-INF/classes/org/
+     * /WEB-INF/classes/org/javaee7/jaxrs/
+     * /WEB-INF/classes/org/javaee7/jaxrs/asyncclient/
+     * /WEB-INF/classes/org/javaee7/jaxrs/asyncclient/MyResource.class
+     * /WEB-INF/classes/org/javaee7/jaxrs/asyncclient/MyApplication.class
+     * ----
+     */
     @Deployment(testable = false)
     public static WebArchive createDeployment() {
        return ShrinkWrap.create(WebArchive.class)
@@ -53,39 +84,48 @@ public void setUpClass() throws MalformedURLException {
     }
 
     /**
-     * Test of getList method, of class MyResource.
+     * Before we can invoke our service we need to setup the client.
+     * 
+     * include::MyResourceTest#setUpClass[]
+     *
+     * Now we're free to invoke our deployed service by using the +JAX-RS+
+     * client library.
+     * 
+     * The asynchronous client library comes with multiple option on how
+     * to invoke the methods. First let's look at using the +Future+ option
+     * with access to the complete +Response+. 
      */
     @Test
     public void testPollingResponse() throws InterruptedException, ExecutionException {
-        Future<Response> r1 = target.request().async().get();
-        String response = r1.get().readEntity(String.class);
-        assertEquals("apple", response);
+        Future<Response> r1 = target.request().async().get(); // <1> Build an asynchronous request handler for the +Response+ object
+        String response = r1.get().readEntity(String.class);  // <2> Read the entity from the body of the +Response+
+        assertEquals("apple", response);                      // <3> Validate we go the expected value
     }
 
     /**
-     * Test of getList method, of class MyResource.
+     * Another possibility is to use the +Future+ option with access to only the +Response+ body. 
      */
     @Test
     public void testPollingString() throws InterruptedException, ExecutionException {
-        Future<String> r1 = target.request().async().get(String.class);
-        String response = r1.get();
-        assertEquals("apple", response);
+        Future<String> r1 = target.request().async().get(String.class); // <1> Build an asynchronous request handler for the body of the +Response+
+        String response = r1.get();                                     // <2> Read the entity directly from the +Future+
+        assertEquals("apple", response);                                // <3> Validate we go the expected value
     }
 
     /**
-     * Test of getList method, of class MyResource.
+     * You can also register a +InvocationCallback+ and get a callback when the +Request+ is done.
      */
     @Test
     public void testInvocationCallback() throws InterruptedException, ExecutionException {
-            target.request().async().get(new InvocationCallback<String>() {
+            target.request().async().get(new InvocationCallback<String>() { // <1> Build an asynchronous request callback for the body of the +Response+
 
                 @Override
-                public void completed(String r) {
+                public void completed(String r) {                           // <2> Called when the +Request+ is completed and our entiy parsed
                     assertEquals("apple", r);
                 }
 
                 @Override
-                public void failed(Throwable t) {
+                public void failed(Throwable t) {                           // <3> Called if the +Request+ failed to complete
                     fail(t.getMessage());
                 }