diff --git a/documentation/jetty-documentation/src/main/asciidoc/programming-guide/client/client-io-arch.adoc b/documentation/jetty-documentation/src/main/asciidoc/programming-guide/client/client-io-arch.adoc index ee2d930f3e1f..9b3405a84400 100644 --- a/documentation/jetty-documentation/src/main/asciidoc/programming-guide/client/client-io-arch.adoc +++ b/documentation/jetty-documentation/src/main/asciidoc/programming-guide/client/client-io-arch.adoc @@ -36,7 +36,7 @@ The same high-level protocol can be carried by different low-level transports. For example, the high-level HTTP/1.1 protocol can be transported over either TCP (the default), or QUIC, or Unix-Domain sockets, or memory, because all these low-level transport provide reliable and ordered communication between client and server. Similarly, the high-level HTTP/3 protocol can be transported over either QUIC (the default) or memory. -It would be possible to transport HTTP/3 also over Unix-Domain sockets, but the current version of Java only supports Unix-Domain sockets for `SocketChannel` and not for `DatagramChannel`. +It would be possible to transport HTTP/3 also over Unix-Domain sockets, but the current version of Java only supports Unix-Domain sockets for ``SocketChannel``s and not for ``DatagramChannel``s. The Jetty client libraries use the common I/O design described in xref:pg-arch-io[this section]. @@ -47,7 +47,7 @@ The client-side abstraction for the low-level transport is `org.eclipse.jetty.io `Transport` represents how high-level protocols can be transported; there is `Transport.TCP_IP` that represents communication over TCP, but also `Transport.TCPUnix` for Unix-Domain sockets, `QuicTransport` for QUIC and `MemoryTransport` for memory. -Applications can specify the `Transport` to use for each request as described in xref:pg-client-http-api-protocol[this section]. +Applications can specify the `Transport` to use for each request as described in xref:pg-client-http-api-transport[this section]. When the `Transport` implementation uses the network, it delegates to `org.eclipse.jetty.io.ClientConnector`. @@ -88,7 +88,7 @@ Since `ClientConnector` is the component that handles the low-level network tran The most common parameters are: -* `ClientConnector.selectors`: the number of ``java.nio.Selector``s components (defaults to `1`) that are present to handle the ``SocketChannel``s opened by the `ClientConnector`. +* `ClientConnector.selectors`: the number of ``java.nio.Selector``s components (defaults to `1`) that are present to handle the ``SocketChannel``s and ``DatagramChannel``s opened by the `ClientConnector`. You typically want to increase the number of selectors only for those use cases where each selector should handle more than few hundreds _concurrent_ socket events. For example, one selector typically runs well for `250` _concurrent_ socket events; as a rule of thumb, you can multiply that number by `10` to obtain the number of opened sockets a selector can handle (`2500`), based on the assumption that not all the `2500` sockets will be active _at the same time_. * `ClientConnector.idleTimeout`: the duration of time after which `ClientConnector` closes a socket due to inactivity (defaults to `30` seconds). @@ -105,11 +105,11 @@ Please refer to the `ClientConnector` link:{javadoc-url}/org/eclipse/jetty/io/Cl [[pg-client-io-arch-unix-domain]] ===== Unix-Domain Support -link:https://openjdk.java.net/jeps/380[JEP 380] introduced Unix-Domain sockets support in Java 16, on all operative systems, for `SocketChannel`. +link:https://openjdk.java.net/jeps/380[JEP 380] introduced Unix-Domain sockets support in Java 16, on all operative systems, but only for ``SocketChannel``s (not for ``DatagramChannel``s). `ClientConnector` handles Unix-Domain sockets exactly like it handles regular TCP sockets, so there is no additional configuration necessary -- Unix-Domain sockets are supported out-of-the-box. -Applications can specify the `Transport` to use for each request as described in xref:pg-client-http-api-protocol[this section]. +Applications can specify the `Transport` to use for each request as described in xref:pg-client-http-api-transport[this section]. [[pg-client-io-arch-memory]] ===== Memory Support @@ -119,7 +119,7 @@ This means that the client and server must be in the same JVM process. This functionality is provided by `org.eclipse.jetty.server.MemoryTransport`, which does not delegate to `ClientConnector`, but instead delegates to the server-side `MemoryConnector` and its related classes. -Applications can specify the `Transport` to use for each request as described in xref:pg-client-http-api-protocol[this section]. +Applications can specify the `Transport` to use for each request as described in xref:pg-client-http-api-transport[this section]. [[pg-client-io-arch-protocol]] ==== Protocol Layer diff --git a/documentation/jetty-documentation/src/main/asciidoc/programming-guide/client/http/client-http-api.adoc b/documentation/jetty-documentation/src/main/asciidoc/programming-guide/client/http/client-http-api.adoc index 56513dc3ec7e..6339e011cd2a 100644 --- a/documentation/jetty-documentation/src/main/asciidoc/programming-guide/client/http/client-http-api.adoc +++ b/documentation/jetty-documentation/src/main/asciidoc/programming-guide/client/http/client-http-api.adoc @@ -271,7 +271,7 @@ An application that implements a forwarder between two servers can be implemente include::../../{doc_code}/org/eclipse/jetty/docs/programming/client/http/HTTPClientDocs.java[tag=forwardContent] ---- -[[pg-client-http-api-protocol]] +[[pg-client-http-api-transport]] ===== Request `Transport` The communication between client and server happens over a xref:pg-client-io-arch-transport[low-level transport], and applications can specify the low-level transport to use for each request. diff --git a/documentation/jetty-documentation/src/main/asciidoc/programming-guide/client/http/client-http-transport.adoc b/documentation/jetty-documentation/src/main/asciidoc/programming-guide/client/http/client-http-transport.adoc index 7362000e8fdf..a06a69284d85 100644 --- a/documentation/jetty-documentation/src/main/asciidoc/programming-guide/client/http/client-http-transport.adoc +++ b/documentation/jetty-documentation/src/main/asciidoc/programming-guide/client/http/client-http-transport.adoc @@ -16,7 +16,7 @@ Jetty's `HttpClient` can be configured to use different HTTP formats to carry the semantic of HTTP requests and responses, by specifying different `HttpClientTransport` implementations. -This means that the intention of a client to request resource `/index.html` using the `GET` method can be carried over a xref:pg-client-http-api-protocol[low-level transport] in different formats. +This means that the intention of a client to request resource `/index.html` using the `GET` method can be carried over a xref:pg-client-http-api-transport[low-level transport] in different formats. An `HttpClientTransport` 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 or HTTP/3), and to convert the server response from the specific format (HTTP/2 or HTTP/3) into high-level, semantic objects that can be used by applications. @@ -58,7 +58,7 @@ A request for a resource may be sent using one protocol (for example, HTTP/1.1), `HttpClient` also supports `HttpClientTransportDynamic`, a xref:pg-client-http-transport-dynamic[dynamic transport] that can speak different HTTP formats and can select the right protocol by negotiating it with the server or by explicit indication from applications. -Furthermore, every HTTP format can be sent over different xref:pg-client-http-api-protocol[low-level transports] such as TCP, Unix-Domain, QUIC or memory. +Furthermore, every HTTP format can be sent over different xref:pg-client-http-api-transport[low-level transports] such as TCP, Unix-Domain, QUIC or memory. Supports for Unix-Domain sockets requires Java 16 or later, since Unix-Domain sockets support has been introduced in OpenJDK with link:https://openjdk.java.net/jeps/380[JEP 380]. Applications are typically not aware of the actual HTTP format or low-level transport being used.