From 22c78d79f03bb9bde85e7e85cb861b9514df421c Mon Sep 17 00:00:00 2001 From: Simone Bordet Date: Wed, 13 Jul 2016 12:35:03 +0200 Subject: [PATCH] Fixes #718 - Document HttpClient transports. --- .../development/clients/http/chapter.adoc | 1 + .../http/http-client-authentication.adoc | 2 +- .../clients/http/http-client-cookie.adoc | 2 +- .../clients/http/http-client-intro.adoc | 3 +- .../clients/http/http-client-proxy.adoc | 2 +- .../clients/http/http-client-transport.adoc | 127 ++++++++++++++++++ 6 files changed, 133 insertions(+), 4 deletions(-) create mode 100644 jetty-documentation/src/main/asciidoc/development/clients/http/http-client-transport.adoc diff --git a/jetty-documentation/src/main/asciidoc/development/clients/http/chapter.adoc b/jetty-documentation/src/main/asciidoc/development/clients/http/chapter.adoc index 8e6ba77cd70..a18da753b76 100644 --- a/jetty-documentation/src/main/asciidoc/development/clients/http/chapter.adoc +++ b/jetty-documentation/src/main/asciidoc/development/clients/http/chapter.adoc @@ -22,3 +22,4 @@ include::http-client-api.adoc[] include::http-client-cookie.adoc[] include::http-client-authentication.adoc[] include::http-client-proxy.adoc[] +include::http-client-transport.adoc[] diff --git a/jetty-documentation/src/main/asciidoc/development/clients/http/http-client-authentication.adoc b/jetty-documentation/src/main/asciidoc/development/clients/http/http-client-authentication.adoc index c49b7a75220..68ee54e717d 100644 --- a/jetty-documentation/src/main/asciidoc/development/clients/http/http-client-authentication.adoc +++ b/jetty-documentation/src/main/asciidoc/development/clients/http/http-client-authentication.adoc @@ -15,7 +15,7 @@ // ======================================================================== [[http-client-authentication]] -==== Authentication Support +=== Authentication Support Jetty's HTTP client supports the "Basic" and "Digest" authentication mechanisms defined by https://tools.ietf.org/html/rfc7235[RFC 7235]. diff --git a/jetty-documentation/src/main/asciidoc/development/clients/http/http-client-cookie.adoc b/jetty-documentation/src/main/asciidoc/development/clients/http/http-client-cookie.adoc index 5b30b731364..a041c90b434 100644 --- a/jetty-documentation/src/main/asciidoc/development/clients/http/http-client-cookie.adoc +++ b/jetty-documentation/src/main/asciidoc/development/clients/http/http-client-cookie.adoc @@ -15,7 +15,7 @@ // ======================================================================== [[http-client-cookie]] -==== Cookies Support +=== Cookies Support Jetty HTTP client supports cookies out of the box. The `HttpClient` instance receives cookies from HTTP responses and stores them diff --git a/jetty-documentation/src/main/asciidoc/development/clients/http/http-client-intro.adoc b/jetty-documentation/src/main/asciidoc/development/clients/http/http-client-intro.adoc index 2a315bb9498..dbe9dec9b26 100644 --- a/jetty-documentation/src/main/asciidoc/development/clients/http/http-client-intro.adoc +++ b/jetty-documentation/src/main/asciidoc/development/clients/http/http-client-intro.adoc @@ -30,7 +30,8 @@ Jetty's HTTP client offers also a synchronous API, that is a programming interfa where the thread that issued the request blocks until the request/response conversation is complete. -Jetty's HTTP client supports different transports: HTTP/1.1, FastCGI and HTTP/2. +Jetty's HTTP client supports different <>: +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. The most common and default format is HTTP/1.1. diff --git a/jetty-documentation/src/main/asciidoc/development/clients/http/http-client-proxy.adoc b/jetty-documentation/src/main/asciidoc/development/clients/http/http-client-proxy.adoc index f396cf9244a..ce176a3027a 100644 --- a/jetty-documentation/src/main/asciidoc/development/clients/http/http-client-proxy.adoc +++ b/jetty-documentation/src/main/asciidoc/development/clients/http/http-client-proxy.adoc @@ -15,7 +15,7 @@ // ======================================================================== [[http-client-proxy]] -==== Proxy Support +=== Proxy Support Jetty's HTTP client can be configured to use proxies to connect to destinations. diff --git a/jetty-documentation/src/main/asciidoc/development/clients/http/http-client-transport.adoc b/jetty-documentation/src/main/asciidoc/development/clients/http/http-client-transport.adoc new file mode 100644 index 00000000000..e8ec2bbcfe7 --- /dev/null +++ b/jetty-documentation/src/main/asciidoc/development/clients/http/http-client-transport.adoc @@ -0,0 +1,127 @@ +// ======================================================================== +// Copyright (c) 1995-2016 Mort Bay Consulting Pty. Ltd. +// ======================================================================== +// All rights reserved. This program and the accompanying materials +// are made available under the terms of the Eclipse Public License v1.0 +// and Apache License v2.0 which accompanies this distribution. +// +// The Eclipse Public License is available at +// http://www.eclipse.org/legal/epl-v10.html +// +// The Apache License v2.0 is available at +// http://www.opensource.org/licenses/apache2.0.php +// +// You may elect to redistribute this code under either of these licenses. +// ======================================================================== + +[[http-client-transport]] +=== Pluggable Transports + +Jetty's HTTP client can be configured to use different transports to carry +the semantic of HTTP requests and responses. + +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 HTTP client 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. + +In this way, applications are not aware of the actual protocol being used. +They can write their logic against a high-level API that hides the details +of the specific protocol being used over the network. + +The most common protocol format is HTTP/1.1, a text-based protocol with +lines separated by `\r\n`: + +---- +GET /index.html HTTP/1.1\r\n +Host: domain.com\r\n +... +\r\n +---- + +However, the same request can be made using FastCGI, a binary protocol: + +---- +x01 x01 x00 x01 x00 x08 x00 x00 +x00 x01 x01 x00 x00 x00 x00 x00 +x01 x04 x00 x01 xLL xLL x00 x00 +x0C x0B D O C U M E + N T _ U R I / i + n d e x . h t m + l +... +---- + +Similarly, HTTP/2 is a binary protocol that transports the same information +in a yet different format. + +==== HTTP/1.1 Transport + +HTTP/1.1 is the default transport. + +[source, java, subs="{sub-order}"] +---- +// No transport specified, using default. +HttpClient client = new HttpClient(); +client.start(); +---- + +If you want to customize the HTTP/1.1 transport, you can explicitly configure +`HttpClient` in this way: + +[source, java, subs="{sub-order}"] +---- +int selectors = 1; +HttpClientTransportOverHTTP transport = new HttpClientTransportOverHTTP(selectors); + +HttpClient client = new HttpClient(transport, null); +client.start(); +---- + +The example above allows you to customize the number of NIO selectors that +`HttpClient` will be using. + +==== HTTP/2 Transport + +The HTTP/2 transport can be configured in this way: + +[source, java, subs="{sub-order}"] +---- +HTTP2Client h2Client = new HTTP2Client(); +h2Client.setSelectors(1); +HttpClientTransportOverHTTP2 transport = new HttpClientTransportOverHTTP2(h2Client); + +HttpClient client = new HttpClient(transport, null); +client.start(); +---- + +`HTTP2Client` is the lower-level client that provides an API based on HTTP/2 +concepts such as _sessions_, _streams_ and _frames_ that are specific to HTTP/2. + +`HttpClientTransportOverHTTP2` uses `HTTP2Client` to format high-level semantic +HTTP requests ("GET resource /index.html") into the HTTP/2 specific format. + +==== FastCGI Transport + +The FastCGI transport can be configured in this way: + +[source, java, subs="{sub-order}"] +---- +int selectors = 1; +String scriptRoot = "/var/www/wordpress"; +HttpClientTransportOverFCGI transport = new HttpClientTransportOverFCGI(selectors, false, scriptRoot); + +HttpClient client = new HttpClient(transport, null); +client.start(); +---- + +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 <> +to serve PHP pages (for example WordPress).