Improved Content.Source documentation.

Signed-off-by: Simone Bordet <simone.bordet@gmail.com>

documentation/jetty-documentation/src/main/asciidoc/programming-guide/arch-io.adoc

@@ -271,9 +271,9 @@ include::{doc_code}/org/eclipse/jetty/docs/programming/ContentDocs.java[tags=asy
 
 Note how the reads do not happen in a loop, and therefore backpressure is applied to the reads, because there is not a next read until the chunk from the previous read has been consumed (and this may take time).
 
-You can use `Content.Source` static methods to conveniently read (in a blocking way or non-blocking way), for example via `static Content.Source.asStringAsync(Content.Source, Charset)`, or via an `InputStream` using `static Content.Source.asInputStream(Content.Source source)`.
+Since the `Chunk` is consumed asynchronously, you may need to retain it to extend its lifecycle, as explained in xref:pg-arch-io-content-source-chunk[this section].
 
-For
+You can use `Content.Source` static methods to conveniently read (in a blocking way or non-blocking way), for example via `static Content.Source.asStringAsync(Content.Source, Charset)`, or via an `InputStream` using `static Content.Source.asInputStream(Content.Source source)`.
 
 Refer to the `Content.Source` link:{javadoc-url}/org/eclipse/jetty/io/Content.Source.html[`javadocs`] for further details.
 

documentation/jetty-documentation/src/main/java/org/eclipse/jetty/docs/programming/ContentDocs.java

@@ -57,7 +57,7 @@ public class ContentDocs
                 // If there is a failure reading, handle it.
                 if (Content.Chunk.isFailure(chunk))
                 {
-                    handleFailure(chunk);
+                    handleFailure(chunk.getFailure());
                     return;
                 }
 
@@ -96,7 +96,7 @@ public class ContentDocs
             // If there is a failure reading, handle it.
             if (Content.Chunk.isFailure(chunk))
             {
-                handleFailure(chunk);
+                handleFailure(chunk.getFailure());
                 return;
             }
 
@@ -104,15 +104,14 @@ public class ContentDocs
             // read more chunks until this has been consumed.
             CompletableFuture<Void> consumed = consumeAsync(chunk);
 
-            // Only when the chunk has been consumed
-            // release it and try to read more.
+            // Release the chunk.
+            chunk.release(); // <2>
+
+            // Only when the chunk has been consumed try to read more.
             consumed.whenComplete((result, failure) ->
             {
                 if (failure == null)
                 {
-                    // Release the chunk.
-                    chunk.release(); // <2>
-
                     // Continue reading if EOF was not reached.
                     if (!chunk.isLast())
                         source.demand(() -> read(source));
@@ -121,7 +120,7 @@ public class ContentDocs
                 {
                     // If there is a failure reading, handle it,
                     // and stop reading by not demanding.
-                    handleFailure(chunk);
+                    handleFailure(failure);
                 }
             });
         }
@@ -133,7 +132,7 @@ public class ContentDocs
         }
     }
 
-    private static void handleFailure(Content.Chunk chunk)
+    private static void handleFailure(Throwable failure)
     {
     }
 
@@ -190,7 +189,7 @@ public class ContentDocs
 
                 if (Content.Chunk.isFailure(chunk))
                 {
-                    handleFailure(chunk);
+                    handleFailure(chunk.getFailure());
                     return;
                 }