Improvements to the Jetty client documentation.

Fixed wrong xrefs after section ID renaming.
Added TODOs for sections that needs to be expanded.

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

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

@@ -31,7 +31,7 @@ There are conceptually two layers that compose the Jetty client libraries:
 [[pg-client-io-arch-network]]
 ==== Client Libraries Network Layer
 
-The Jetty client libraries use the common I/O design described in link:#eg-arch-io[this section].
+The Jetty client libraries use the common I/O design described in xref:pg-arch-io[this section].
 The main client-side component is the link:{JDURL}/org/eclipse/jetty/io/ClientConnector.html[`ClientConnector`].
 
 The `ClientConnector` primarily wraps the link:{JDURL}/org/eclipse/jetty/io/SelectorManager.html[`SelectorManager`] and aggregates other four components:
@@ -88,7 +88,7 @@ Please refer to the `ClientConnector` link:{JDURL}/org/eclipse/jetty/io/ClientCo
 
 The protocol layer builds on top of the network layer to generate the bytes to be written to the network and to parse the bytes read from the network.
 
-Recall from link:#eg-arch-io-connection[this section] that Jetty uses the `Connection` abstraction to produce and interpret the network bytes.
+Recall from xref:pg-arch-io-connection[this section] that Jetty uses the `Connection` abstraction to produce and interpret the network bytes.
 
 On the client side, a `ClientConnectionFactory` implementation is the component that creates `Connection` instances based on the protocol that the client wants to "speak" with the server.
 

jetty-documentation/src/main/asciidoc/programming-guide/client/http/client-http-api.adoc

@@ -34,7 +34,7 @@ include::../../{doc_code}/embedded/client/http/HTTPClientDocs.java[tags=simpleBl
 The method `HttpClient.GET(...)` performs a HTTP `GET` request to the given URI and returns a `ContentResponse` when the request/response conversation completes successfully.
 
 The `ContentResponse` object contains the HTTP response information: status code, headers and possibly content.
-The content length is limited by default to 2 MiB; for larger content see xref:client-http-content-response[].
+The content length is limited by default to 2 MiB; for larger content see xref:pg-client-http-content-response[the section on response content handling].
 
 If you want to customize the request, for example by issuing a `HEAD` request instead of a `GET`, and simulating a browser user agent, you can do it in this way:
 
@@ -62,7 +62,7 @@ include::../../{doc_code}/embedded/client/http/HTTPClientDocs.java[tags=postFlue
 
 The `POST` parameter values added via the `param()` method are automatically URL-encoded.
 
-Jetty's `HttpClient` automatically follows redirects, so it handles the typical web pattern http://en.wikipedia.org/wiki/Post/Redirect/Get[POST/Redirect/GET], and the response object contains the content of the response of the `GET` request.
+Jetty's `HttpClient` automatically follows redirects, so it handles the typical web pattern link:http://en.wikipedia.org/wiki/Post/Redirect/Get[POST/Redirect/GET], and the response object contains the content of the response of the `GET` request.
 Following redirects is a feature that you can enable/disable on a per-request basis or globally.
 
 File uploads also require one line, and make use of `java.nio.file` classes:
@@ -79,7 +79,7 @@ It is possible to impose a total timeout for the request/response conversation u
 include::../../{doc_code}/embedded/client/http/HTTPClientDocs.java[tags=totalTimeout]
 ----
 
-In the example above, when the 5 seconds expire, the request is aborted and a `java.util.concurrent.TimeoutException` is thrown.
+In the example above, when the 5 seconds expire, the request/response cycle is aborted and a `java.util.concurrent.TimeoutException` is thrown.
 
 [[pg-client-http-non-blocking]]
 ==== HttpClient Non-Blocking APIs
@@ -97,18 +97,19 @@ If you need to execute application code that takes long time inside a listener,
 
 Request and response processing are executed by two different threads and therefore may happen concurrently.
 A typical example of this concurrent processing is an echo server, where a large upload may be concurrent with the large download echoed back.
-As a side note, remember that responses may be processed and completed _before_ requests; a typical example is a large upload that triggers a quick response - for example an error - by the server: the response may arrive and be completed while the request content is still being uploaded.
 
-The application thread that calls `Request.send(Response.CompleteListener)` performs the processing of the request until either the request is fully processed or until it would block on I/O, then it returns (and therefore never blocks).
+NOTE: Remember that responses may be processed and completed _before_ requests; a typical example is a large upload that triggers a quick response - for example an error - by the server: the response may arrive and be completed while the request content is still being uploaded.
+
+The application thread that calls `Request.send(Response.CompleteListener)` performs the xref:pg-client-http-request-processing[processing of the request] until either the request is fully sent over the network or until it would block on I/O, then it returns (and therefore never blocks).
 If it would block on I/O, the thread asks the I/O system to emit an event when the I/O will be ready to continue, then returns.
 When such an event is fired, a thread taken from the `HttpClient` thread pool will resume the processing of the request.
 
-Response are processed from the I/O thread that fires the event that bytes are ready to be read.
+Response are processed from the I/O thread taken from the `HttpClient` thread pool that processes the event that bytes are ready to be read.
 Response processing continues until either the response is fully processed or until it would block for I/O.
 If it would block for I/O, the thread asks the I/O system to emit an event when the I/O will be ready to continue, then returns.
-When such an event is fired, a thread taken from the `HttpClient` thread pool will resume the processing of the response.
+When such an event is fired, a (possibly different) thread taken from the `HttpClient` thread pool will resume the processing of the response.
 
-When the request and the response are both fully processed, the thread that finished the last processing (usually the thread that processes the response, but may also be the thread that processes the request - if the request takes more time than the response to be processed) is used to dequeue the next request for the same destination and processes it.
+When the request and the response are both fully processed, the thread that finished the last processing (usually the thread that processes the response, but may also be the thread that processes the request - if the request takes more time than the response to be processed) is used to dequeue the next request for the same destination and to process it.
 
 A simple non-blocking `GET` request that discards the response content can be written in this way:
 
@@ -194,7 +195,7 @@ include::../../{doc_code}/embedded/client/http/HTTPClientDocs.java[tags=outputSt
 
 Jetty's `HttpClient` allows applications to handle response content in different ways.
 
-You can buffer the response content in memory; this is done when using the xref:client-http-blocking[blocking APIs] and the content is buffered within a `ContentResponse` up to 2 MiB.
+You can buffer the response content in memory; this is done when using the xref:pg-client-http-blocking[blocking APIs] and the content is buffered within a `ContentResponse` up to 2 MiB.
 
 If you want to control the length of the response content (for example limiting to values smaller than the default of 2 MiB), then you can use a `org.eclipse.jetty.client.util.FutureResponseListener` in this way:
 
@@ -205,7 +206,7 @@ include::../../{doc_code}/embedded/client/http/HTTPClientDocs.java[tags=futureRe
 
 If the response content length is exceeded, the response will be aborted, and an exception will be thrown by method `get(...)`.
 
-You can buffer the response content in memory also using the xref:client-http-non-blocking[non-blocking APIs], via the `BufferingResponseListener` utility class:
+You can buffer the response content in memory also using the xref:pg-client-http-non-blocking[non-blocking APIs], via the `BufferingResponseListener` utility class:
 
 [source,java,indent=0]
 ----

jetty-documentation/src/main/asciidoc/programming-guide/client/http/client-http-authentication.adoc

@@ -79,3 +79,7 @@ include::../../{doc_code}/embedded/client/http/HTTPClientDocs.java[tag=requestPr
 ----
 
 See also the xref:pg-client-http-proxy-authentication[proxy authentication section] for further information about how authentication works with HTTP proxies.
+
+[[pg-client-http-authentication-spnego]]
+=== HttpClient SPNEGO Authentication Support
+TODO

jetty-documentation/src/main/asciidoc/programming-guide/client/http/client-http-configuration.adoc

@@ -67,3 +67,11 @@ include::../../{doc_code}/embedded/client/http/HTTPClientDocs.java[tags=tlsAppVa
 ----
 
 Please refer to the `SslContextFactory.Client` link:{JDURL}/org/eclipse/jetty/util/ssl/SslContextFactory.Client.html[javadocs] for the complete list of configurable parameters.
+
+[[pg-client-http-configuration-tls-truststore]]
+==== HttpClient TLS TrustStore Configuration
+TODO
+
+[[pg-client-http-configuration-tls-client-certs]]
+==== HttpClient TLS Client Certificates Configuration
+TODO

jetty-documentation/src/main/asciidoc/programming-guide/client/http/client-http-cookie.adoc

@@ -20,6 +20,7 @@
 === HttpClient Cookie Support
 
 Jetty's `HttpClient` supports cookies out of the box.
+
 The `HttpClient` instance receives cookies from HTTP responses and stores them in a `java.net.CookieStore`, a class that is part of the JDK.
 When new requests are made, the cookie store is consulted and if there are matching cookies (that is, cookies that are not expired and that match domain and path of the request) then they are added to the requests.
 
@@ -73,7 +74,7 @@ The example above will retain only cookies that come from the `google.com` domai
 
 Jetty is compliant with link:https://tools.ietf.org/html/rfc6265[RFC6265], and as such care must be taken when setting a cookie value that includes special characters such as `;`.
 
-Previously, Version=1 cookies defined in link:https://tools.ietf.org/html/rfc2109[RFC2109] (and continued in link:https://tools.ietf.org/html/rfc2965[RFC2965]) allowed for special/reserved characters to be enclosed within double quotes when declared in a `Set-Cookie` response header:
+Previously, `Version=1` cookies defined in link:https://tools.ietf.org/html/rfc2109[RFC2109] (and continued in link:https://tools.ietf.org/html/rfc2965[RFC2965]) allowed for special/reserved characters to be enclosed within double quotes when declared in a `Set-Cookie` response header:
 
 [source,screen]
 ----
@@ -87,7 +88,7 @@ This was added to the HTTP Response as follows:
 protected void service(HttpServletRequest request, HttpServletResponse response)
 {
     javax.servlet.http.Cookie cookie = new Cookie("foo", "bar;baz");
-    cookie.setPath("/secur");
+    cookie.setPath("/secure");
     response.addCookie(cookie);
 }
 ----

jetty-documentation/src/main/asciidoc/programming-guide/client/http/client-http-intro.adoc

@@ -26,18 +26,18 @@ It offers an asynchronous API that never blocks for I/O, making it very efficien
 
 However, when all you need to do is to perform a `GET` request to a resource, Jetty's HTTP client offers also a synchronous API; a programming interface where the thread that issued the request blocks until the request/response conversation is complete.
 
-Jetty's HTTP client supports xref:#eg-client-http-transport[different transports]: HTTP/1.1, FastCGI and HTTP/2. This means that the semantic of a HTTP request (that is, " `GET` me the resource `/index.html` ") can be carried over the network in different formats.
+Jetty's HTTP client supports xref:pg-client-http-transport[different transports]: HTTP/1.1, FastCGI and HTTP/2. This means that the semantic of an HTTP request: " ``GET`` the resource ``/index.html`` " can be carried over the network in different formats.
 The most common and default format is HTTP/1.1. That said, Jetty's HTTP client can carry the same request using the FastCGI format or the HTTP/2 format.
 
-The FastCGI transport is heavily used in Jetty's link:#fastcgi[FastCGI support] that allows Jetty to work as a reverse proxy to PHP (exactly like Apache or Nginx do) and therefore be able to serve - for example - WordPress websites.
+The xref:pg-client-http-transport-fcgi[FastCGI transport] is heavily used in Jetty's xref:fastcgi[FastCGI support] that allows Jetty to work as a reverse proxy to PHP (exactly like Apache or Nginx do) and therefore be able to serve - for example - WordPress websites.
 
-The HTTP/2 transport allows Jetty's HTTP client to perform requests using HTTP/2 to HTTP/2 enabled web sites, see also Jetty's link:#http2[HTTP/2 support].
+The HTTP/2 transport allows Jetty's HTTP client to perform requests using HTTP/2 to HTTP/2 enabled web sites, see also Jetty's xref:pg-client-http2[HTTP/2 support].
 
 Out of the box features that you get with the Jetty HTTP client include:
 
 * Redirect support - redirect codes such as 302 or 303 are automatically followed.
 * Cookies support - cookies sent by servers are stored and sent back to servers in matching requests.
-* Authentication support - HTTP "Basic" and "Digest" authentications are supported, others are pluggable.
+* Authentication support - HTTP "Basic", "Digest" and "SPNEGO" authentications are supported, others are pluggable.
 * Forward proxy support - HTTP proxying and SOCKS4 proxying.
 
 [[pg-client-http-start]]
@@ -72,9 +72,9 @@ There are several reasons for having multiple `HttpClient` instances including,
 
 * You want to specify different configuration parameters (for example, one instance is configured with a forward proxy while another is not).
 * You want the two instances to behave like two different browsers and hence have different cookies, different authentication credentials, etc.
-* You want to use link:#eg-client-http-transport[different transports].
+* You want to use xref:pg-client-http-transport[different transports].
 
-Like browsers, HTTPS requests are supported out-of-the-box, as long as the server provides a valid certificate.
+Like browsers, HTTPS requests are supported out-of-the-box (see xref:pg-client-http-configuration-tls[this section] for the TLS configuration), as long as the server provides a valid certificate.
 In case the server does not provide a valid certificate (or in case it is self-signed) you want to customize ``HttpClient``'s TLS configuration as described in xref:pg-client-http-configuration-tls[this section].
 
 [[pg-client-http-stop]]
@@ -99,7 +99,7 @@ A `HttpClient` instance can be thought as a browser instance, and it manages the
 * a `ProxyConfiguration` (see xref:pg-client-http-proxy[this section]).
 * a set of _destinations_.
 
-A _destination_ is the client-side component that represent an _origin_ on a server, and manages a queue of requests for that origin, and a xref:pg-client-http-connection-pool[pool of connections] to that origin.
+A _destination_ is the client-side component that represents an _origin_ server, and manages a queue of requests for that origin, and a xref:pg-client-http-connection-pool[pool of TCP connections] to that origin.
 
 An _origin_ may be simply thought as the tuple `(scheme, host, port)` and it is where the client connects to in order to communicate with the server.
 However, this is not enough.
@@ -111,7 +111,7 @@ Instead, you want to use different connections for different clients and this ca
 Two origins with the same `(scheme, host, port)` but different `tag` create two different destinations and therefore two different connection pools.
 However, also this is not enough.
 
-It is possible that a server speaks different protocols on the same `port`.
+It is possible for a server to speak different protocols on the same `port`.
 A connection may start by speaking one protocol, for example HTTP/1.1, but then be upgraded to speak a different protocol, for example HTTP/2. After a connection has been upgraded to a second protocol, it cannot speak the first protocol anymore, so it can only be used to communicate using the second protocol.
 
 Two origins with the same `(scheme, host, port)` but different `protocol` create two different destinations and therefore two different connection pools.
@@ -182,11 +182,11 @@ If a connection is available, it is returned, otherwise a new connection is crea
 Once the destination has obtained the connection, it dequeues the request and sends it over the connection.
 
 The first request to a destination triggers the opening of the first connection.
-A second request with the same origin sent _after_ the first request/response cycle is completed will reuse the same connection.
-A second request with the same origin sent _concurrently_ with the first request will cause the opening of a second connection.
+A second request with the same origin sent _after_ the first request/response cycle is completed may reuse the same connection, depending on the connection pool implementation.
+A second request with the same origin sent _concurrently_ with the first request will likely cause the opening of a second connection, depending on the connection pool implementation.
 The configuration parameter `HttpClient.maxConnectionsPerDestination` (see also the xref:pg-client-http-configuration[configuration section]) controls the max number of connections that can be opened for a destination.
 
-NOTE: If opening connections to a given origin takes a long time, then requests for that origin will queue up in the corresponding destination.
+NOTE: If opening connections to a given origin takes a long time, then requests for that origin will queue up in the corresponding destination until the connections are established.
 
 Each connection can handle a limited number of concurrent requests.
 For HTTP/1.1, this number is always `1`: there can only be one outstanding request for each connection.

jetty-documentation/src/main/asciidoc/programming-guide/client/http/client-http-transport.adoc

@@ -23,7 +23,7 @@ Jetty's `HttpClient` can be configured to use different transports to carry the
 
 This means that the intention of a client to request resource `/index.html` using the `GET` method can be carried over the network in different formats.
 
-A `HttpClient` transport is the component that is in charge of converting a high-level, semantic, HTTP requests such as "`GET` resource ``/index.html``" into the specific format understood by the server (for example, HTTP/2), and to convert the server response from the specific format (HTTP/2) into high-level, semantic objects that can be used by applications.
+A `HttpClient` transport is the component that is in charge of converting a high-level, semantic, HTTP requests such as "``GET`` resource ``/index.html``" into the specific format understood by the server (for example, HTTP/2), and to convert the server response from the specific format (HTTP/2) into high-level, semantic objects that can be used by applications.
 
 The most common protocol format is HTTP/1.1, a textual protocol with lines separated by `\r\n`:
 
@@ -104,7 +104,7 @@ include::../../{doc_code}/embedded/client/http/HTTPClientDocs.java[tag=fcgiTrans
 
 In order to make requests using the FastCGI transport, you need to have a FastCGI server such as https://en.wikipedia.org/wiki/PHP#PHPFPM[PHP-FPM] (see also http://php.net/manual/en/install.fpm.php).
 
-The FastCGI transport is primarily used by Jetty's link:#fastcgi[FastCGI support] to serve PHP pages (WordPress for example).
+The FastCGI transport is primarily used by Jetty's xref:fastcgi[FastCGI support] to serve PHP pages (WordPress for example).
 
 [[pg-client-http-transport-dynamic]]
 ==== Dynamic Transport
@@ -116,7 +116,7 @@ With the advent of HTTP/2, however, servers are now able to support multiple pro
 The HTTP/2 protocol is typically negotiated between client and server.
 This negotiation can happen via ALPN, a TLS extension that allows the client to tell the server the list of protocol that the client supports, so that the server can pick one of the client supported protocols that also the server supports; or via HTTP/1.1 upgrade by means of the `Upgrade` header.
 
-Applications can configure the dynamic transport with one or more _application_ protocols such as HTTP/1.1 or HTTP/2. The implementation will take care of using TLS for HTTPS URIs, using ALPN, negotiating protocols, upgrading from one protocol to another, etc.
+Applications can configure the dynamic transport with one or more _application_ protocols such as HTTP/1.1 or HTTP/2. The implementation will take care of using TLS for HTTPS URIs, using ALPN if necessary, negotiating protocols, upgrading from one protocol to another, etc.
 
 By default, the dynamic transport only speaks HTTP/1.1: