--- a/src/main/java/openjdk/http/tutorial/exercise1/Retrievals.java	Tue Jan 16 20:40:42 2018 +0000
+++ b/src/main/java/openjdk/http/tutorial/exercise1/Retrievals.java	Tue Jan 16 21:08:16 2018 +0000
@@ -70,10 +70,10 @@
      * Exercise 1.
      *
      * Retrieve the response status code from a request to the given
-     * URI. The returned response code will be a int.
+     * URI. Return the response code, which is an integer.
      *
-     * Hint: use the discard BodyHandler since the response body is not
-     * interesting.
+     * Hint: use the {@link BodyHandler#discard(Object)BodyHandler} since
+     * the response body is not interesting.
      *
      * Hint: static imports reduce boilerplate when using BodyHandlers
      * and BodyProcessors, e.g. import static
@@ -90,13 +90,13 @@
     }
 
     /**
-     * Exercise 1.
+     * Exercise 2.
      *
      * Retrieve the response body from a given URI. Return the response
      * body as a String.
      *
-     * Hint: use the asString BodyHandler to convert the HTTP response
-     * body to a String.
+     * Hint: use the {@link BodyHandler#asString()} BodyHandler to convert
+     * the HTTP response body to a String.
      *
      * Hint: static imports reduce boilerplate when using BodyHandlers
      * and BodyProcessors, e.g. import static
@@ -113,13 +113,18 @@
     }
 
     /**
-     * Exercise 2.
+     * Exercise 3.
      *
-     * Retrieve the response body from a given URI, streaming teh body
+     * Retrieve the response body from a given URI, streaming the body
      * out to a file. Return the file's Path.
      *
      * Hint: use {@linkplain BodyHandler#asFile} to stream the HTTP
      * response body to a file.
+     *
+     * Hint: if a file already exists from a previous test run, either
+     * remove it or use the {@link java.nio.file.StandardOpenOption#CREATE}
+     * along with the {@link java.nio.file.StandardOpenOption#TRUNCATE_EXISTING}
+     * to create or truncate as needed.
      */
     public static Path retrieveResourceAsFile(URI uri)
         throws IOException, InterruptedException
@@ -131,17 +136,19 @@
                 .GET()
                 .build();
         HttpResponse<Path> response = client.send(request,
-                asFile(Paths.get("retrieveResourceAsFile.txt"), StandardOpenOption.TRUNCATE_EXISTING, StandardOpenOption.WRITE));
-
-        System.out.println("CHEGAR:   sc=" + response.statusCode());
-        System.out.println("CHEGAR:   by=" + Files.readAllLines(response.body()).stream().collect(joining()));
-
+                asFile(Paths.get("retrieveResourceAsFile.txt"),
+                       StandardOpenOption.CREATE,
+                       StandardOpenOption.TRUNCATE_EXISTING,
+                       StandardOpenOption.WRITE));
         return response.body();
     }
 
 
     /**
-     * Asserts that the response code is 200 ( OK ).
+     * A helper method, NOT an exercise.
+     *
+     * Asserts that the response code is 200 ( OK ). Throws IOException if
+     * the response code is not 200.
      *
      * Can be used in CompletableFuture pipelines when checking the
      * response of an {@linkplain HttpClient#sendAsync} call. For
@@ -161,27 +168,32 @@
     }
 
     /**
-     *  Exercise 3.
+     * Exercise 4.
      *
-     * Retrieve the response body from a given URI, using the
-     * asynchronous send API, sendAsync. Return a CompletableFuture that
-     * completes with the response body as a String.
+     * Retrieve the response body from a given URI, using thea synchronous
+     * send API, {@link HttpClient#sendAsync(HttpRequest, BodyHandler)}.
+     * Return a CompletableFuture that completes with the response body
+     * as a String.
      *
      * Hint: The {@linkplain CompletableFuture#thenApply(Function)}
      * method can be used to map the HttpResponse to a String.
      */
     public static CompletableFuture<String> retrieveResourceAsStringUsingAsyncAPI(URI uri) {
+        // TODO: why version needed?
+
         return HttpClient.newHttpClient()
-                .sendAsync(HttpRequest.newBuilder(uri).version(HTTP_1_1).build(), asString())  // TODO: why version needed?
+                .sendAsync(HttpRequest.newBuilder(uri).version(HTTP_1_1).build(), asString())
                 .thenApply(Retrievals::require200StatusCode)
                 .thenApply(HttpResponse::body);
     }
 
 
     /**
+     * A helper method, NOT an exercise.
+     *
      * Wrapper around Jackson's ObjectMapper that provides an unchecked
      * {@code readValue}, what can be used to help solve the next
-     * exercise, 4.
+     * exercise, 5.
      */
     public static class UncheckedObjectMapper extends ObjectMapper {
 
@@ -196,19 +208,19 @@
     }
 
     /**
-     * Exercise 4.
+     * Exercise 5.
      *
      * Retrieve the response body from a given URI. The response body
      * will be in the JSON format. The Jackson based UncheckedObjectMapper
      * ( above ) can be used to parse the String response body into a
-     * Map.
+     * Map. Return the response body as a Map.
      *
      * Hint: The asynchronous send API will allow construction of a
      * pipeline of CompletableFutures.
      *
      * Hint: The {@linkplain CompletableFuture#thenApply(Function)}
      * method can be used to map the HttpResponse to a String, and then
-     * again from a Sting to a Map ( via the object mapper ).
+     * again from a String ( of JSON ) to a Map ( via the object mapper ).
      */
     public CompletableFuture<Map<String,String>> JSONBodyAsMap(URI uri) {
         UncheckedObjectMapper objectMapper = new UncheckedObjectMapper();
@@ -221,6 +233,8 @@
 
 
     /**
+     * Exercise 6.
+     *
      * Post the given {@code data}, and receive the same data in
      * response. Return the response body data as a String.
      */
@@ -238,6 +252,4 @@
         return response.body();
     }
 
-
-     // JSON processor
 }

--- a/src/test/java/openjdk/http/tutorial/Exercise1Test.java	Tue Jan 16 20:40:42 2018 +0000
+++ b/src/test/java/openjdk/http/tutorial/Exercise1Test.java	Tue Jan 16 21:08:16 2018 +0000
@@ -321,7 +321,7 @@
                 .build();
         Path p = Paths.get("Exercise1Test_bodyAsFile.txt");
         HttpResponse<Path> response = client.send(request,
-                asFile(p, TRUNCATE_EXISTING, WRITE));
+                asFile(p, CREATE, TRUNCATE_EXISTING, WRITE));
 
         Assert.assertEquals(200, response.statusCode());