Eclipse
/
jetty.project
mirror of https://github.com/jetty/jetty.project.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Improvements to the Jetty documentation. 

Renamed section ids from "eg-" (embedded guide)
to "pg-" (programming guide).

Signed-off-by: Simone Bordet <simone.bordet@gmail.com>
This commit is contained in:
Simone Bordet 2020-09-03 10:50:49 +02:00
parent cd0bf1cf5a
commit af5f11710e
30 changed files with 202 additions and 180 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

20
jetty-documentation/src/main/asciidoc/programming-guide/arch-bean.adoc
View File

@ -16,7 +16,7 @@
// ========================================================================
//
[[eg-arch-bean]]
[[pg-arch-bean]]
=== Jetty Component Architecture
Applications that use the Jetty libraries (both client and server) create objects from Jetty classes and compose them together to obtain the desired functionalities.
@ -31,11 +31,11 @@ The end result is that an application based on the Jetty libraries is a _tree_ o
In server application the root of the component tree is a `Server` instance, while in client applications the root of the component tree is an `HttpClient` instance.
Having all the Jetty components in a tree is beneficial in a number of use cases.
It makes possible to register the components in the tree as xref:eg-arch-jmx[JMX MBeans] so that a JMX console can look at the internal state of the components.
It also makes possible to xref:eg-troubleshooting-component-dump[dump the component tree] (and therefore each component's internal state) to a log file or to the console for xref:eg-troubleshooting[troubleshooting purposes].
It makes possible to register the components in the tree as xref:pg-arch-jmx[JMX MBeans] so that a JMX console can look at the internal state of the components.
It also makes possible to xref:pg-troubleshooting-component-dump[dump the component tree] (and therefore each component's internal state) to a log file or to the console for xref:pg-troubleshooting[troubleshooting purposes].
// TODO: add a section on Dumpable?
[[eg-arch-bean-lifecycle]]
[[pg-arch-bean-lifecycle]]
==== Jetty Component Lifecycle
Jetty components typically have a life cycle: they can be started and stopped.
@ -110,11 +110,11 @@ The component tree should be used for long-lived or medium-lived components such
It is not recommended adding to, and removing from, the component tree short-lived objects such as HTTP requests or TCP connections, for performance reasons.
If you need component tree features such as automatic xref:eg-arch-jmx[export to JMX] or xref:eg-troubleshooting-component-dump[dump capabilities] for short-lived objects, consider having a long-lived container in the component tree instead.
If you need component tree features such as automatic xref:pg-arch-jmx[export to JMX] or xref:pg-troubleshooting-component-dump[dump capabilities] for short-lived objects, consider having a long-lived container in the component tree instead.
You can make the long-lived container efficient at adding/removing the short-lived components using a data structure that is not part of the component tree, and make the long-lived container handle the JMX and dump features for the short-lived components.
====
[[eg-arch-bean-listener]]
[[pg-arch-bean-listener]]
==== Jetty Component Listeners
A component that extends `AbstractLifeCycle` inherits the possibility to add/remove event _listeners_ for various events emitted by components.
@ -123,7 +123,7 @@ A component that implements `java.util.EventListener` that is added to a `Contai
The following sections describe in details the various listeners available in the Jetty component architecture.
[[eg-arch-bean-listener-lifecycle]]
[[pg-arch-bean-listener-lifecycle]]
===== LifeCycle.Listener
A `LifeCycle.Listener` emits events for life cycle events such as starting, stopping and failures:
@ -135,7 +135,7 @@ include::{doc_code}/embedded/ComponentDocs.java[tags=lifecycleListener]
For example, a life cycle listener attached to a `Server` instance could be used to create (for the _started_ event) and delete (for the _stopped_ event) a file containing the process ID of the JVM that runs the `Server`.
[[eg-arch-bean-listener-container]]
[[pg-arch-bean-listener-container]]
===== Container.Listener
A component that implements `Container` is a container for other components and `ContainerLifeCycle` is the typical implementation.
@ -154,13 +154,13 @@ A `Container.Listener` added as a bean will also be registered as a listener:
include::{doc_code}/embedded/ComponentDocs.java[tags=containerSiblings]
----
[[eg-arch-bean-listener-inherited]]
[[pg-arch-bean-listener-inherited]]
===== Container.InheritedListener
A `Container.InheritedListener` is a listener that will be added to all descendants that are also ``Container``s.
Listeners of this type may be added to the component tree root only, but will be notified of every descendant component that is added to or removed from the component tree (not only first level children).
The primary use of `Container.InheritedListener` within the Jetty Libraries is `MBeanContainer` from the xref:eg-arch-jmx[Jetty JMX support].
The primary use of `Container.InheritedListener` within the Jetty Libraries is `MBeanContainer` from the xref:pg-arch-jmx[Jetty JMX support].
`MBeanContainer` listens for every component added to the tree, converts it to an MBean and registers it to the MBeanServer; for every component removed from the tree, it unregisters the corresponding MBean from the MBeanServer.

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

@ -16,12 +16,12 @@
// ========================================================================
//
[[eg-arch-io]]
[[pg-arch-io]]
=== Jetty I/O Architecture
Jetty libraries (both client and server) use Java NIO to handle I/O, so that at its core Jetty I/O is completely non-blocking.
[[eg-arch-io-selector-manager]]
[[pg-arch-io-selector-manager]]
==== Jetty I/O: `SelectorManager`
The core class of Jetty I/O is link:{JDURL}/org/eclipse/jetty/io/SelectorManager.html[`SelectorManager`].
@ -50,7 +50,7 @@ This example shows how a server accepts a client connection:
include::{doc_code}/embedded/SelectorManagerDocs.java[tags=accept]
----
[[eg-arch-io-endpoint-connection]]
[[pg-arch-io-endpoint-connection]]
==== Jetty I/O: `EndPoint` and `Connection`
``SocketChannel``s that are passed to `SelectorManager` are wrapped into two related components: an link:{JDURL}/org/eclipse/jetty/io/EndPoint.html[`EndPoint`] and a link:{JDURL}/org/eclipse/jetty/io/Connection.html[`Connection`].
@ -80,11 +80,11 @@ NOTE: TODO: add a section on `UpgradeFrom` and `UpgradeTo`?
Creating `Connection` instances is performed on the server-side by link:{JDURL}/org/eclipse/jetty/server/ConnectionFactory.html[`ConnectionFactory`]s and on the client-side by link:{JDURL}/org/eclipse/jetty/io/ClientConnectionFactory.html[`ClientConnectionFactory`]s
On the server-side, the component that aggregates a `SelectorManager` with a set of ``ConnectionFactory``s is link:{JDURL}/org/eclipse/jetty/server/ServerConnector.html[`ServerConnector`]s, see xref:eg-server-io-arch[].
On the server-side, the component that aggregates a `SelectorManager` with a set of ``ConnectionFactory``s is link:{JDURL}/org/eclipse/jetty/server/ServerConnector.html[`ServerConnector`]s, see xref:pg-server-io-arch[].
On the client-side, the components that aggregates a `SelectorManager` with a set of ``ClientConnectionFactory``s are link:{JDURL}/org/eclipse/jetty/client/HttpClientTransport.html[`HttpClientTransport`] subclasses, see xref:eg-client-io-arch[].
On the client-side, the components that aggregates a `SelectorManager` with a set of ``ClientConnectionFactory``s are link:{JDURL}/org/eclipse/jetty/client/HttpClientTransport.html[`HttpClientTransport`] subclasses, see xref:pg-client-io-arch[].
[[eg-arch-io-endpoint]]
[[pg-arch-io-endpoint]]
==== Jetty I/O: `EndPoint`
The Jetty I/O library use Java NIO to handle I/O, so that I/O is non-blocking.
@ -99,9 +99,9 @@ In order to be notified when a `SocketChannel` uncongests and it is therefore wr
In the Jetty I/O library, you can call `EndPoint.write(Callback, ByteBuffer...)` to write the ``ByteBuffer``s and the `Callback` parameter is the object that is notified when the whole write is finished (i.e. _all_ ``ByteBuffer``s have been fully written, even if they are delayed by TCP congestion/uncongestion).
The `EndPoint` APIs abstract out the Java NIO details by providing non-blocking APIs based on `Callback` objects for I/O operations.
The `EndPoint` APIs are typically called by `Connection` implementations, see xref:eg-arch-io-connection[this section].
The `EndPoint` APIs are typically called by `Connection` implementations, see xref:pg-arch-io-connection[this section].
[[eg-arch-io-connection]]
[[pg-arch-io-connection]]
==== Jetty I/O: `Connection`
`Connection` is the abstraction that deserializes incoming bytes into objects, for example a HTTP request object or a WebSocket frame object, that can be used by more abstract layers.
@ -122,12 +122,12 @@ The example below shows a typical implementation that extends `AbstractConnectio
include::{doc_code}/embedded/SelectorManagerDocs.java[tags=connection]
----
[[eg-arch-io-connection-listener]]
[[pg-arch-io-connection-listener]]
===== Jetty I/O: `Connection.Listener`
// TODO: Introduce Connection.Listener
[[eg-arch-io-echo]]
[[pg-arch-io-echo]]
==== Jetty I/O: Network Echo
With the concepts above it is now possible to write a simple, fully non-blocking, `Connection` implementation that simply echoes the bytes that it reads back to the other peer.

20
jetty-documentation/src/main/asciidoc/programming-guide/arch-jmx.adoc
View File

@ -16,18 +16,18 @@
// ========================================================================
//
[[eg-arch-jmx]]
[[pg-arch-jmx]]
== Jetty JMX Support
The Java Management Extensions (JMX) APIs are standard API for managing and monitoring resources such as applications, devices, services, and the Java Virtual Machine itself.
The JMX API includes remote access, so a remote management console such as link:https://openjdk.java.net/projects/jmc/[Java Mission Control] can interact with a running application for these purposes.
Jetty architecture is based on xref:eg-arch-bean[components] organized in a tree. Every time a component is added to or removed from the component tree, an event is emitted, and xref:eg-arch-bean-listener-container[Container.Listener] implementations can listen to those events and perform additional actions.
Jetty architecture is based on xref:pg-arch-bean[components] organized in a tree. Every time a component is added to or removed from the component tree, an event is emitted, and xref:pg-arch-bean-listener-container[Container.Listener] implementations can listen to those events and perform additional actions.
`org.eclipse.jetty.jmx.MBeanContainer` listens to those events and registers/unregisters the Jetty components as MBeans into the platform MBeanServer.
The Jetty components are annotated with xref:eg-arch-jmx-annotation[Jetty JMX annotations] so that they can provide specific JMX metadata such as attributes and operations that should be exposed via JMX.
The Jetty components are annotated with xref:pg-arch-jmx-annotation[Jetty JMX annotations] so that they can provide specific JMX metadata such as attributes and operations that should be exposed via JMX.
Therefore, when a component is added to the component tree, `MBeanContainer` is notified, it creates the MBean from the component POJO and registers it to the `MBeanServer`.
Similarly, when a component is removed from the tree, `MBeanContainer` is notified, and unregisters the MBean from the `MBeanServer`.
@ -66,12 +66,12 @@ include::{doc_code}/embedded/JMXDocs.java[tags=client]
The MBeans exported to the platform MBeanServer can only be accessed locally (from the same machine), not from remote machines.
This means that this configuration is enough for development, where you have easy access (with graphical user interface) to the machine where Jetty runs, but it is typically not enough when the machine where Jetty runs is remote, or only accessible via SSH or otherwise without graphical user interface support.
In these cases, you have to enable xref:eg-arch-jmx-remote[JMX Remote Access].
In these cases, you have to enable xref:pg-arch-jmx-remote[JMX Remote Access].
====
// TODO: add a section about how to expose logging once #4830 is fixed.
[[eg-arch-jmx-remote]]
[[pg-arch-jmx-remote]]
=== Enabling JMX Remote Access
There are two ways of enabling remote connectivity so that JMC can connect to the remote JVM to visualize MBeans.
@ -106,7 +106,7 @@ rmi_registry_port = 1099
----
With the default configuration, only clients that are local to the server machine can connect to the RMI registry and RMI server - this is done for security reasons.
With this configuration it would still be possible to access the MBeans from remote using a xref:eg-arch-jmx-remote-ssh-tunnel[SSH tunnel].
With this configuration it would still be possible to access the MBeans from remote using a xref:pg-arch-jmx-remote-ssh-tunnel[SSH tunnel].
By specifying an appropriate `JMXServiceURL`, you can fine tune the network interfaces the RMI registry and the RMI server bind to, and the ports that the RMI registry and the RMI server listen to.
The RMI server and RMI registry hosts and ports can be the same (as in the default configuration) because RMI is able to multiplex traffic arriving to a port to multiple RMI objects.
@ -142,7 +142,7 @@ When `ConnectorServer` is started, its RMI stub is exported to the RMI registry.
The RMI stub contains the IP address and port to connect to the RMI object, but the IP address is typically the machine host name, not the host specified in the `JMXServiceURL`.
To control the IP address stored in the RMI stub you need to set the system property `java.rmi.server.hostname` with the desired value.
This is especially important when binding the RMI server host to the loopback address for security reasons. See also xref:eg-arch-jmx-remote-ssh-tunnel[JMX Remote Access via SSH Tunnel.]
This is especially important when binding the RMI server host to the loopback address for security reasons. See also xref:pg-arch-jmx-remote-ssh-tunnel[JMX Remote Access via SSH Tunnel.]
====
To allow JMX remote access, create and configure a `ConnectorServer`:
@ -152,7 +152,7 @@ To allow JMX remote access, create and configure a `ConnectorServer`:
include::{doc_code}/embedded/JMXDocs.java[tags=remote]
----
[[eg-arch-jmx-remote-authorization]]
[[pg-arch-jmx-remote-authorization]]
==== JMX Remote Access Authorization
The standard `JMXConnectorServer` provides several options to authorize access, for example via JAAS or via configuration files.
@ -226,7 +226,7 @@ $ jmc -vmargs -Djavax.net.ssl.trustStore=/path/to/trustStore -Djavax.net.ssl.tru
IMPORTANT: These system properties are required when launching the `ConnectorServer` too, on the server, because it acts as an RMI client with respect to the RMI registry.
[[eg-arch-jmx-remote-ssh-tunnel]]
[[pg-arch-jmx-remote-ssh-tunnel]]
===== JMX Remote Access with Port Forwarding via SSH Tunnel
You can access JMX MBeans on a remote machine when the RMI ports are not open, for example because of firewall policies, but you have SSH access to the machine using local port forwarding via an SSH tunnel.
@ -246,7 +246,7 @@ The traffic will be forwarded to `machine_host` and when there, SSH will forward
When you configure `ConnectorServer` in this way, you must set the system property `-Djava.rmi.server.hostname=localhost`, on the server.
This is required because when the RMI server is exported, its address and port are stored in the RMI stub. You want the address in the RMI stub to be `localhost` so that when the RMI stub is downloaded to the remote client, the RMI communication will go through the SSH tunnel.
[[eg-arch-jmx-annotation]]
[[pg-arch-jmx-annotation]]
=== Jetty JMX Annotations
The Jetty JMX support, and in particular `MBeanContainer`, is notified every time a bean is added to the component tree.

10
jetty-documentation/src/main/asciidoc/programming-guide/arch-listener.adoc
View File

@ -16,10 +16,10 @@
// ========================================================================
//
[[eg-arch-listener]]
[[pg-arch-listener]]
=== Jetty Listeners
The Jetty architecture is based on xref:eg-arch-bean[components], typically organized in a component tree.
The Jetty architecture is based on xref:pg-arch-bean[components], typically organized in a component tree.
These components have an internal state that varies with the component life cycle (that is, whether the component is started or stopped), as well as with the component use at runtime.
The typical example is a thread pool, whose internal state -- such as the number of pooled threads or the job queue size -- changes as the thread pool is used by the running client or server.
@ -28,6 +28,6 @@ Applications can register listeners to these components to be notified of the ev
This section lists the listeners available in the Jetty components, but the events and listener APIs are discussed in the component specific sections.
* xref:eg-arch-bean-listener[]
* xref:eg-arch-io-connection-listener[]
* xref:eg-server-http-channel-events[]
* xref:pg-arch-bean-listener[]
* xref:pg-arch-io-connection-listener[]
* xref:pg-server-http-channel-events[]

2
jetty-documentation/src/main/asciidoc/programming-guide/arch.adoc
View File

@ -17,7 +17,7 @@
//
[appendix]
[[eg-arch]]
[[pg-arch]]
== Jetty Architecture
include::arch-bean.adoc[]

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

@ -16,19 +16,19 @@
// ========================================================================
//
[[eg-client-io-arch]]
[[pg-client-io-arch]]
=== Client Libraries I/O Architecture
The Jetty client libraries provide the basic components and APIs to implement a network client.
They build on the common xref:eg-arch-io[Jetty I/O Architecture] and provide client specific concepts (such as establishing a connection to a server).
They build on the common xref:pg-arch-io[Jetty I/O Architecture] and provide client specific concepts (such as establishing a connection to a server).
There are conceptually two layers that compose the Jetty client libraries:
. xref:eg-client-io-arch-network[The network layer], that handles the low level I/O and deals with buffers, threads, etc.
. xref:eg-client-io-arch-protocol[The protocol layer], that handles the parsing of bytes read from the network and the generation of bytes to write to the network.
. xref:pg-client-io-arch-network[The network layer], that handles the low level I/O and deals with buffers, threads, etc.
. xref:pg-client-io-arch-protocol[The protocol layer], that handles the parsing of bytes read from the network and the generation of bytes to write to the network.
[[eg-client-io-arch-network]]
[[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].
@ -83,7 +83,7 @@ This time includes the DNS lookup time _and_ the TCP connect time.
Please refer to the `ClientConnector` link:{JDURL}/org/eclipse/jetty/io/ClientConnector.html[javadocs] for the complete list of configurable parameters.
[[eg-client-io-arch-protocol]]
[[pg-client-io-arch-protocol]]
==== Client Libraries Protocol Layer
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.

10
jetty-documentation/src/main/asciidoc/programming-guide/client/client.adoc
View File

@ -16,7 +16,7 @@
// ========================================================================
//
[[eg-client]]
[[pg-client]]
== Client Libraries
The Eclipse Jetty Project provides client-side libraries that allow you to embed a client in your applications.
@ -28,11 +28,11 @@ The client libraries are designed to be non-blocking and offer both synchronous
These are the available client libraries:
* xref:eg-client-http[The HTTP Client Library]
* xref:eg-client-http2[The HTTP/2 Client Library]
* xref:eg-client-websocket[The WebSocket client library]
* xref:pg-client-http[The HTTP Client Library]
* xref:pg-client-http2[The HTTP/2 Client Library]
* xref:pg-client-websocket[The WebSocket client library]
If you are interested in the low-level details of how the Eclipse Jetty client libraries work, or are interested in writing a custom protocol, look at the xref:eg-client-io-arch[Client I/O Architecture].
If you are interested in the low-level details of how the Eclipse Jetty client libraries work, or are interested in writing a custom protocol, look at the xref:pg-client-io-arch[Client I/O Architecture].
include::http/client-http.adoc[]
include::http2/client-http2.adoc[]

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

@ -16,12 +16,12 @@
// ========================================================================
//
[[eg-client-http-api]]
[[pg-client-http-api]]
=== HttpClient API Usage
`HttpClient` provides two types of APIs: a blocking API and a non-blocking API.
[[eg-client-http-blocking]]
[[pg-client-http-blocking]]
==== HttpClient Blocking APIs
The simpler way to perform a HTTP request is the following:
@ -81,7 +81,7 @@ include::../../{doc_code}/embedded/client/http/HTTPClientDocs.java[tags=totalTim
In the example above, when the 5 seconds expire, the request is aborted and a `java.util.concurrent.TimeoutException` is thrown.
[[eg-client-http-non-blocking]]
[[pg-client-http-non-blocking]]
==== HttpClient Non-Blocking APIs
So far we have shown how to use Jetty HTTP client in a blocking style - that is, the thread that issues the request blocks until the request/response conversation is complete.
@ -139,10 +139,10 @@ This makes Jetty HTTP client suitable for HTTP load testing because, for example
Have a look at the link:{JDURL}/org/eclipse/jetty/client/api/Request.Listener.html[`Request.Listener`] class to know about request events, and to the link:{JDURL}/org/eclipse/jetty/client/api/Response.Listener.html[`Response.Listener`] class to know about response events.
[[eg-client-http-content]]
[[pg-client-http-content]]
==== HttpClient Content Handling
[[eg-client-http-content-request]]
[[pg-client-http-content-request]]
===== Request Content Handling
Jetty's `HttpClient` provides a number of utility classes off the shelf to handle request content.
@ -189,7 +189,7 @@ Another way to provide request content is by using an `OutputStreamRequestConten
include::../../{doc_code}/embedded/client/http/HTTPClientDocs.java[tags=outputStreamRequestContent]
----
[[eg-client-http-content-response]]
[[pg-client-http-content-response]]
===== Response Content Handling
Jetty's `HttpClient` allows applications to handle response content in different ways.

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

@ -16,7 +16,7 @@
// ========================================================================
//
[[eg-client-http-authentication]]
[[pg-client-http-authentication]]
=== HttpClient Authentication Support
Jetty's `HttpClient` supports the `BASIC` and `DIGEST` authentication mechanisms defined by link:https://tools.ietf.org/html/rfc7235[RFC 7235], as well as the SPNEGO authentication mechanism defined in link:https://tools.ietf.org/html/rfc4559[RFC 4559].
@ -78,4 +78,4 @@ It is also possible to preempt the authentication for a single request only, in
include::../../{doc_code}/embedded/client/http/HTTPClientDocs.java[tag=requestPreemptedResult]
----
See also the xref:eg-client-http-proxy-authentication[proxy authentication section] for further information about how authentication works with HTTP proxies.
See also the xref:pg-client-http-proxy-authentication[proxy authentication section] for further information about how authentication works with HTTP proxies.

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

@ -16,7 +16,7 @@
// ========================================================================
//
[[eg-client-http-configuration]]
[[pg-client-http-configuration]]
=== HttpClient Configuration
`HttpClient` has a quite large number of configuration parameters.
@ -24,13 +24,13 @@ Please refer to the `HttpClient` link:{JDURL}/org/eclipse/jetty/client/HttpClien
The most common parameters are:
* `HttpClient.idleTimeout`: same as `ClientConnector.idleTimeout` described in xref:eg-client-io-arch-network[this section].
* `HttpClient.connectBlocking`: same as `ClientConnector.connectBlocking` described in xref:eg-client-io-arch-network[this section].
* `HttpClient.connectTimeout`: same as `ClientConnector.connectTimeout` described in xref:eg-client-io-arch-network[this section].
* `HttpClient.idleTimeout`: same as `ClientConnector.idleTimeout` described in xref:pg-client-io-arch-network[this section].
* `HttpClient.connectBlocking`: same as `ClientConnector.connectBlocking` described in xref:pg-client-io-arch-network[this section].
* `HttpClient.connectTimeout`: same as `ClientConnector.connectTimeout` described in xref:pg-client-io-arch-network[this section].
* `HttpClient.maxConnectionsPerDestination`: the max number of TCP connections that are opened for a particular destination (defaults to 64).
* `HttpClient.maxRequestsQueuedPerDestination`: the max number of requests queued (defaults to 1024).
[[eg-client-http-configuration-tls]]
[[pg-client-http-configuration-tls]]
==== HttpClient TLS Configuration
`HttpClient` supports HTTPS requests out-of-the-box like a browser does.

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

@ -16,7 +16,7 @@
// ========================================================================
//
[[eg-client-http-cookie]]
[[pg-client-http-cookie]]
=== HttpClient Cookie Support
Jetty's `HttpClient` supports cookies out of the box.

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

@ -16,7 +16,7 @@
// ========================================================================
//
[[eg-client-http-intro]]
[[pg-client-http-intro]]
=== HttpClient Introduction
The Jetty HTTP client module provides easy-to-use APIs and utility classes to perform HTTP (or HTTPS) requests.
@ -40,7 +40,7 @@ Out of the box features that you get with the Jetty HTTP client include:
* Authentication support - HTTP "Basic" and "Digest" authentications are supported, others are pluggable.
* Forward proxy support - HTTP proxying and SOCKS4 proxying.
[[eg-client-http-start]]
[[pg-client-http-start]]
==== Starting HttpClient
The Jetty artifact that provides the main HTTP client implementation is `jetty-client`.
@ -75,9 +75,9 @@ There are several reasons for having multiple `HttpClient` instances including,
* You want to use link:#eg-client-http-transport[different transports].
Like browsers, HTTPS requests are supported out-of-the-box, 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:eg-client-http-configuration-tls[this section].
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].
[[eg-client-http-stop]]
[[pg-client-http-stop]]
==== Stopping HttpClient
It is recommended that when your application stops, you also stop the `HttpClient` instance (or instances) that you are using.
@ -89,17 +89,17 @@ include::../../{doc_code}/embedded/client/http/HTTPClientDocs.java[tags=stop]
Stopping `HttpClient` makes sure that the memory it holds (for example, authentication credentials, cookies, etc.) is released, and that the thread pool and scheduler are properly stopped allowing all threads used by `HttpClient` to exit.
[[eg-client-http-arch]]
[[pg-client-http-arch]]
==== HttpClient Architecture
A `HttpClient` instance can be thought as a browser instance, and it manages the following components:
* a `CookieStore` (see xref:eg-client-http-cookie[this section]).
* a `AuthenticationStore` (see xref:eg-client-http-authentication[this section]).
* a `ProxyConfiguration` (see xref:eg-client-http-proxy[this section]).
* a `CookieStore` (see xref:pg-client-http-cookie[this section]).
* a `AuthenticationStore` (see xref:pg-client-http-authentication[this section]).
* 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:eg-client-http-connection-pool[pool of connections] to that origin.
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.
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.
@ -118,7 +118,7 @@ Two origins with the same `(scheme, host, port)` but different `protocol` create
Therefore an origin is identified by the tuple `(scheme, host, port, tag, protocol)`.
[[eg-client-http-connection-pool]]
[[pg-client-http-connection-pool]]
==== HttpClient Connection Pooling
A destination manages a `org.eclipse.jetty.client.ConnectionPool`, where connections to a particular origin are pooled for performance reasons:
@ -146,7 +146,7 @@ The `ConnectionPool` implementation can be customized for each destination in by
include::../../{doc_code}/embedded/client/http/HTTPClientDocs.java[tags=setConnectionPool]
----
[[eg-client-http-request-processing]]
[[pg-client-http-request-processing]]
==== HttpClient Request Processing
[plantuml]
@ -184,7 +184,7 @@ Once the destination has obtained the connection, it dequeues the request and se
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.
The configuration parameter `HttpClient.maxConnectionsPerDestination` (see also the xref:eg-client-http-configuration[configuration section]) controls the max number of connections that can be opened for a destination.
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.
@ -194,4 +194,4 @@ For HTTP/2 this number is determined by the server `max_concurrent_stream` setti
When a destination has maxed out its number of connections, and all connections have maxed out their number of outstanding requests, more requests sent to that destination will be queued.
When the request queue is full, the request will be failed.
The configuration parameter `HttpClient.maxRequestsQueuedPerDestination` (see also the xref:eg-client-http-configuration[configuration section]) controls the max number of requests that can be queued for a destination.
The configuration parameter `HttpClient.maxRequestsQueuedPerDestination` (see also the xref:pg-client-http-configuration[configuration section]) controls the max number of requests that can be queued for a destination.

8
jetty-documentation/src/main/asciidoc/programming-guide/client/http/client-http-proxy.adoc
View File

@ -16,7 +16,7 @@
// ========================================================================
//
[[eg-client-http-proxy]]
[[pg-client-http-proxy]]
=== HttpClient Proxy Support
Jetty's `HttpClient` can be configured to use proxies to connect to destinations.
@ -37,10 +37,10 @@ Configured in this way, `HttpClient` makes requests to the HTTP proxy (for plain
Proxying is supported for both HTTP/1.1 and HTTP/2.
[[eg-client-http-proxy-authentication]]
[[pg-client-http-proxy-authentication]]
==== Proxy Authentication Support
Jetty's `HttpClient` supports proxy authentication in the same way it supports xref:eg-client-http-authentication[server authentication].
Jetty's `HttpClient` supports proxy authentication in the same way it supports xref:pg-client-http-authentication[server authentication].
In the example below, the proxy requires `BASIC` authentication, but the server requires `DIGEST` authentication, and therefore:
@ -77,4 +77,4 @@ HttpClient -> Application : 200 OK
The application does not receive events related to the responses with code 407 and 401 since they are handled internally by `HttpClient`.
Similarly to the xref:eg-client-http-authentication[authentication section], the proxy authentication result and the server authentication result can be preempted to avoid, respectively, the 407 and 401 roundtrips.
Similarly to the xref:pg-client-http-authentication[authentication section], the proxy authentication result and the server authentication result can be preempted to avoid, respectively, the 407 and 401 roundtrips.

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

@ -16,7 +16,7 @@
// ========================================================================
//
[[eg-client-http-transport]]
[[pg-client-http-transport]]
=== HttpClient Pluggable Transports
Jetty's `HttpClient` can be configured to use different transports to carry the semantic of HTTP requests and responses.
@ -54,14 +54,14 @@ Similarly, HTTP/2 is a binary protocol that transports the same information in a
A protocol may be _negotiated_ between client and server.
A request for a resource may be sent using one protocol (for example, HTTP/1.1), but the response may arrive in a different protocol (for example, HTTP/2).
`HttpClient` supports 3 static transports, each speaking only one protocol: xref:eg-client-http-transport-http11[HTTP/1.1], xref:eg-client-http-transport-http2[HTTP/2] and xref:eg-client-http-transport-fcgi[FastCGI], all of them with 2 variants: clear-text and TLS encrypted.
`HttpClient` supports 3 static transports, each speaking only one protocol: xref:pg-client-http-transport-http11[HTTP/1.1], xref:pg-client-http-transport-http2[HTTP/2] and xref:pg-client-http-transport-fcgi[FastCGI], all of them with 2 variants: clear-text and TLS encrypted.
`HttpClient` also supports one xref:eg-client-http-transport-dynamic[dynamic transport], that can speak different protocols and can select the right protocol by negotiating it with the server or by explicit indication from applications.
`HttpClient` also supports one xref:pg-client-http-transport-dynamic[dynamic transport], that can speak different protocols and can select the right protocol by negotiating it with the server or by explicit indication from applications.
Applications are typically not aware of the actual protocol being used.
This allows them to write their logic against a high-level API that hides the details of the specific protocol being used over the network.
[[eg-client-http-transport-http11]]
[[pg-client-http-transport-http11]]
==== HTTP/1.1 Transport
HTTP/1.1 is the default transport.
@ -78,7 +78,7 @@ If you want to customize the HTTP/1.1 transport, you can explicitly configure it
include::../../{doc_code}/embedded/client/http/HTTPClientDocs.java[tag=http11Transport]
----
[[eg-client-http-transport-http2]]
[[pg-client-http-transport-http2]]
==== HTTP/2 Transport
The HTTP/2 transport can be configured in this way:
@ -88,11 +88,11 @@ The HTTP/2 transport can be configured in this way:
include::../../{doc_code}/embedded/client/http/HTTPClientDocs.java[tag=http2Transport]
----
`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. See xref:eg-client-http2[the HTTP/2 client section] for more information.
`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. See xref:pg-client-http2[the HTTP/2 client section] for more information.
`HttpClientTransportOverHTTP2` uses `HTTP2Client` to format high-level semantic HTTP requests (like "GET resource /index.html") into the HTTP/2 specific format.
[[eg-client-http-transport-fcgi]]
[[pg-client-http-transport-fcgi]]
==== FastCGI Transport
The FastCGI transport can be configured in this way:
@ -106,7 +106,7 @@ In order to make requests using the FastCGI transport, you need to have a FastCG
The FastCGI transport is primarily used by Jetty's link:#fastcgi[FastCGI support] to serve PHP pages (WordPress for example).
[[eg-client-http-transport-dynamic]]
[[pg-client-http-transport-dynamic]]
==== Dynamic Transport
The static transports work well if you know in advance the protocol you want to speak with the server, or if the server only supports one protocol (such as FastCGI).

2
jetty-documentation/src/main/asciidoc/programming-guide/client/http/client-http.adoc
View File

@ -16,7 +16,7 @@
// ========================================================================
//
[[eg-client-http]]
[[pg-client-http]]
=== HTTP Client
include::client-http-intro.adoc[]

28
jetty-documentation/src/main/asciidoc/programming-guide/client/http2/client-http2.adoc
View File

@ -16,18 +16,18 @@
// ========================================================================
//
[[eg-client-http2]]
[[pg-client-http2]]
=== HTTP/2 Client Library
In the vast majority of cases, client applications should use the generic, high-level, xref:eg-client-http[HTTP client library] that also provides HTTP/2 support via the pluggable xref:eg-client-http-transport-http2[HTTP/2 transport] or the xref:eg-client-http-transport-dynamic[dynamic transport].
In the vast majority of cases, client applications should use the generic, high-level, xref:pg-client-http[HTTP client library] that also provides HTTP/2 support via the pluggable xref:pg-client-http-transport-http2[HTTP/2 transport] or the xref:pg-client-http-transport-dynamic[dynamic transport].
The high-level HTTP library supports cookies, authentication, redirection, connection pooling and a number of other features that are absent in the low-level HTTP/2 library.
The HTTP/2 client library has been designed for those applications that need low-level access to HTTP/2 features such as _sessions_, _streams_ and _frames_, and this is quite a rare use case.
See also the correspondent xref:eg-server-http2[HTTP/2 server library].
See also the correspondent xref:pg-server-http2[HTTP/2 server library].
[[eg-client-http2-intro]]
[[pg-client-http2-intro]]
==== Introducing HTTP2Client
The Maven artifact coordinates for the HTTP/2 client library are the following:
@ -61,14 +61,14 @@ A _session_ typically has a long life - once the TCP connection is established,
include::../../http2.adoc[tag=multiplex]
[[eg-client-http2-flow-control]]
[[pg-client-http2-flow-control]]
===== HTTP/2 Flow Control
include::../../http2.adoc[tag=flowControl]
How a client application should handle HTTP/2 flow control is discussed in details in xref:eg-client-http2-response[this section].
How a client application should handle HTTP/2 flow control is discussed in details in xref:pg-client-http2-response[this section].
[[eg-client-http2-connect]]
[[pg-client-http2-connect]]
==== Connecting to the Server
The first thing an application should do is to connect to the server and obtain a `Session`.
@ -88,7 +88,7 @@ include::../../{doc_code}/embedded/client/http2/HTTP2ClientDocs.java[tags=encryp
IMPORTANT: Applications must know in advance whether they want to connect to a clear-text or encrypted port, and pass the `SslContextFactory` parameter accordingly to the `connect(...)` method.
[[eg-client-http2-configure]]
[[pg-client-http2-configure]]
===== Configuring the Session
The `connect(...)` method takes a `Session.Listener` parameter.
@ -105,7 +105,7 @@ Please refer to the `Session.Listener` link:{JDURL}/org/eclipse/jetty/http2/api/
Once a `Session` has been established, the communication with the server happens by exchanging _frames_, as specified in the link:https://tools.ietf.org/html/rfc7540#section-4[HTTP/2 specification].
[[eg-client-http2-request]]
[[pg-client-http2-request]]
==== Sending a Request
Sending an HTTP request to the server, and receiving a response, creates a _stream_ that encapsulates the exchange of HTTP/2 frames that compose the request and the response.
@ -120,7 +120,7 @@ include::../../{doc_code}/embedded/client/http2/HTTP2ClientDocs.java[tags=newStr
----
Note how `Session.newStream(...)` takes a `Stream.Listener` parameter.
This listener is notified of stream events originated by the server such as receiving `HEADERS` or `DATA` frames that are part of the response, discussed in more details in the xref:eg-client-http2-response[section below].
This listener is notified of stream events originated by the server such as receiving `HEADERS` or `DATA` frames that are part of the response, discussed in more details in the xref:pg-client-http2-response[section below].
Please refer to the `Stream.Listener` link:{JDURL}/org/eclipse/jetty/http2/api/Stream.Listener.html[javadocs] for the complete list of events.
HTTP requests may have content, which is sent using the `Stream` APIs:
@ -133,7 +133,7 @@ include::../../{doc_code}/embedded/client/http2/HTTP2ClientDocs.java[tags=newStr
IMPORTANT: When sending two `DATA` frames consecutively, the second call to `Stream.data(...)` must be done only when the first is completed, or a `WritePendingException` will be thrown.
Use the `Callback` APIs or `CompletableFuture` APIs to ensure that the second `Stream.data(...)` call is performed when the first completed successfully.
[[eg-client-http2-response]]
[[pg-client-http2-response]]
==== Receiving a Response
Response events are delivered to the `Stream.Listener` passed to `Session.newStream(...)`.
@ -151,7 +151,7 @@ include::../../{doc_code}/embedded/client/http2/HTTP2ClientDocs.java[tags=respon
include::../../http2.adoc[tag=apiFlowControl]
[[eg-client-http2-reset]]
[[pg-client-http2-reset]]
==== Resetting a Request or Response
In HTTP/2, clients and servers have the ability to tell to the other peer that they are not interested anymore in either the request or the response, using a `RST_STREAM` frame.
@ -163,13 +163,13 @@ The `HTTP2Client` APIs allow client applications to send and receive this "reset
include::../../{doc_code}/embedded/client/http2/HTTP2ClientDocs.java[tags=reset]
----
[[eg-client-http2-push]]
[[pg-client-http2-push]]
==== Receiving HTTP/2 Pushes
HTTP/2 servers have the ability to push resources related to a primary resource.
When an HTTP/2 server pushes a resource, it sends to the client a `PUSH_PROMISE` frame that contains the request URI and headers that a client would use to request explicitly that resource.
Client applications can be configured to tell the server to never push resources, see xref:eg-client-http2-configure[this section].
Client applications can be configured to tell the server to never push resources, see xref:pg-client-http2-configure[this section].
Client applications can listen to the push events, and act accordingly:

22
jetty-documentation/src/main/asciidoc/programming-guide/client/websocket/client-websocket.adoc Normal file
View File

@ -0,0 +1,22 @@
//
// ========================================================================
// Copyright (c) 1995-2020 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under
// the terms of the Eclipse Public License 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0
//
// This Source Code may also be made available under the following
// Secondary Licenses when the conditions for such availability set
// forth in the Eclipse Public License, v. 2.0 are satisfied:
// the Apache License v2.0 which is available at
// https://www.apache.org/licenses/LICENSE-2.0
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[pg-client-websocket]]
=== WebSocket Client Libraries
TODO

4
jetty-documentation/src/main/asciidoc/programming-guide/introduction.adoc
View File

@ -22,8 +22,8 @@ The Eclipse Jetty Programming Guide targets developers that want to use the Ecli
The Eclipse Jetty libraries provide the client-side and server-side APIs to work with various web protocols such as HTTP/1.1, HTTP/2, WebSocket and FastCGI.
You may use the xref:eg-client[Eclipse Jetty client-side library] in your application to make calls to third party REST services, or to other REST microservices in your system.
You may use the xref:pg-client[Eclipse Jetty client-side library] in your application to make calls to third party REST services, or to other REST microservices in your system.
Likewise, you may use the xref:eg-server[Eclipse Jetty server-side library] to quickly create an HTTP or REST service without having to create a web application archive file (a `*.war` file) and deploy it to server that you have to download and install.
Likewise, you may use the xref:pg-server[Eclipse Jetty server-side library] to quickly create an HTTP or REST service without having to create a web application archive file (a `*.war` file) and deploy it to server that you have to download and install.
This guide will walk you through the design of the Eclipse Jetty and how to use its classes to write your applications.

6
jetty-documentation/src/main/asciidoc/programming-guide/server/http/server-http-application.adoc
View File

@ -16,19 +16,19 @@
// ========================================================================
//
[[eg-server-http-application]]
[[pg-server-http-application]]
=== Writing HTTP Server Applications
Writing HTTP applications is typically simple, especially when using blocking APIs.
However, there are subtle cases where it is worth clarifying what a server application should do to obtain the desired results when run by Jetty.
[[eg-server-http-application-1xx]]
[[pg-server-http-application-1xx]]
==== Sending 1xx Responses
The link:https://tools.ietf.org/html/rfc7231#section-5.1.1[HTTP/1.1 RFC] allows for `1xx` informational responses to be sent before a real content response.
Unfortunately the servlet specification does not provide a way for these to be sent, so Jetty has had to provide non-standard handling of these headers.
[[eg-server-http-application-100]]
[[pg-server-http-application-100]]
===== 100 Continue
The `100 Continue` response should be sent by the server when a client sends a request with an `Expect: 100-continue` header, as the client will not send the body of the request until the `100 Continue` response has been sent.

18
jetty-documentation/src/main/asciidoc/programming-guide/server/http/server-http-connector.adoc
View File

@ -16,7 +16,7 @@
// ========================================================================
//
[[eg-server-http-connector]]
[[pg-server-http-connector]]
=== Server Connectors
A `Connector` is the component that handles incoming requests from clients, and works in conjunction with `ConnectionFactory` instances.
@ -32,13 +32,13 @@ include::../../{doc_code}/embedded/server/http/HTTPServerDocs.java[tags=configur
----
The _acceptors_ are threads (typically only one) that compete to accept TCP connections on the listening port.
When a connection is accepted, `ServerConnector` wraps the accepted `SocketChannel` and passes it to the xref:eg-arch-io-selector-manager[`SelectorManager`].
When a connection is accepted, `ServerConnector` wraps the accepted `SocketChannel` and passes it to the xref:pg-arch-io-selector-manager[`SelectorManager`].
Therefore, there is a little moment where the acceptor thread is not accepting new connections because it is busy wrapping the just accepted connection to pass it to the `SelectorManager`.
Connections that are ready to be accepted but are not accepted yet are queued in a bounded queue (at the OS level) whose capacity can be configured with the `ServerConnector.acceptQueueSize` parameter.
If your application must withstand a very high rate of connections opened, configuring more than one acceptor thread may be beneficial: when one acceptor thread accepts one connection, another acceptor thread can take over accepting connections.
The _selectors_ are components that manage a set of connected sockets, implemented by xref:eg-arch-io-selector-manager[`ManagedSelector`].
The _selectors_ are components that manage a set of connected sockets, implemented by xref:pg-arch-io-selector-manager[`ManagedSelector`].
Each selector requires one thread and uses the Java NIO mechanism to efficiently handle a set of connected sockets.
As a rule of thumb, a single selector can easily manage up to 1000-5000 sockets, although the number may vary greatly depending on the application.
@ -54,15 +54,15 @@ It is possible to configure more than one `ServerConnector`, each listening on a
include::../../{doc_code}/embedded/server/http/HTTPServerDocs.java[tags=configureConnectors]
----
[[eg-server-http-connector-protocol]]
[[pg-server-http-connector-protocol]]
==== Configuring Protocols
For each accepted TCP connection, `ServerConnector` asks a `ConnectionFactory` to create a `Connection` object that handles the network traffic on that TCP connection, parsing and generating bytes for a specific protocol (see xref:eg-arch-io[this section] for more details about `Connection` objects).
For each accepted TCP connection, `ServerConnector` asks a `ConnectionFactory` to create a `Connection` object that handles the network traffic on that TCP connection, parsing and generating bytes for a specific protocol (see xref:pg-arch-io[this section] for more details about `Connection` objects).
A `ServerConnector` can be configured with one or more ``ConnectionFactory``s.
If no `ConnectionFactory` is specified then `HttpConnectionFactory` is implicitly configured.
[[eg-server-http-connector-protocol-http11]]
[[pg-server-http-connector-protocol-http11]]
===== Configuring HTTP/1.1
`HttpConnectionFactory` creates `HttpConnection` objects that parse bytes and generate bytes for the HTTP/1.1 protocol.
@ -81,7 +81,7 @@ Supporting encrypted HTTP/1.1 (that is, requests with the HTTPS scheme)is suppor
include::../../{doc_code}/embedded/server/http/HTTPServerDocs.java[tags=tlsHttp11]
----
[[eg-server-http-connector-protocol-proxy-http11]]
[[pg-server-http-connector-protocol-proxy-http11]]
===== Configuring Jetty behind a Load Balancer
It is often the case that Jetty receives connections from a load balancer configured to distribute the load among many Jetty backend servers.
@ -103,7 +103,7 @@ Note also how the PROXY `ConnectionFactory` needs to know its _next_ protocol (i
Each `ConnectionFactory` is asked to create a `Connection` object for each accepted TCP connection; the `Connection` objects will be chained together to handle the bytes, each for its own protocol.
Therefore the `ProxyConnection` will handle the PROXY protocol bytes and `HttpConnection` will handle the HTTP/1.1 bytes producing a request object and response object that will be processed by ``Handler``s.
[[eg-server-http-connector-protocol-http2]]
[[pg-server-http-connector-protocol-http2]]
===== Configuring HTTP/2
It is well known that the HTTP ports are `80` (for clear-text HTTP) and `443` for encrypted HTTP.
@ -124,7 +124,7 @@ Note how the ``ConnectionFactory``s passed to `ServerConnector` are in order: fi
This is necessary to support both protocols on the same port: Jetty will start parsing the incoming bytes as HTTP/1.1, but then realize that they are HTTP/2 bytes and will therefore _upgrade_ from HTTP/1.1 to HTTP/2.
This configuration is also typical when Jetty is installed in backend servers behind a load balancer that also takes care of offloading TLS.
When Jetty is behind a load balancer, you can always prepend the PROXY protocol as described in xref:eg-server-http-connector-protocol-proxy-http11[this section].
When Jetty is behind a load balancer, you can always prepend the PROXY protocol as described in xref:pg-server-http-connector-protocol-proxy-http11[this section].
When using encrypted HTTP/2, the unencrypted protocol is negotiated by client and server using an extension to the TLS protocol called ALPN.

6
jetty-documentation/src/main/asciidoc/programming-guide/server/http/server-http-handler-implement.adoc
View File

@ -16,7 +16,7 @@
// ========================================================================
//
[[eg-server-http-handler-implement]]
[[pg-server-http-handler-implement]]
==== Implementing Handler
The `Handler` API consist fundamentally of just one method:
@ -33,7 +33,7 @@ However, a request could be forwarded to either a named resource, in which case
Applications may wrap the request or response (or both) and forward the wrapped request or response to a different URI (which may be possibly handled by a different `Handler`).
This is the reason why there are two request parameters in the `Handler` APIs: the first is the unwrapped, original, request while the second is the application-wrapped request.
[[eg-server-http-handler-impl-hello]]
[[pg-server-http-handler-impl-hello]]
===== Hello World Handler
A simple "Hello World" `Handler` is the following:
@ -45,7 +45,7 @@ include::../../{doc_code}/embedded/server/http/HTTPServerDocs.java[tags=handlerH
Such a simple `Handler` extends from `AbstractHandler` and can access the request and response main features, such as reading request headers and content, or writing response headers and content.
[[eg-server-http-handler-impl-filter]]
[[pg-server-http-handler-impl-filter]]
===== Filtering Handler
A filtering `Handler` is a handler that perform some modification to the request or response, and then either forwards the request to another `Handler` or produces an error response:

46
jetty-documentation/src/main/asciidoc/programming-guide/server/http/server-http-handler-use.adoc
View File

@ -16,7 +16,7 @@
// ========================================================================
//
[[eg-server-http-handler-use]]
[[pg-server-http-handler-use]]
==== Using Provided Handlers
Web applications are the unit of deployment in an HTTP server or Servlet container such as Jetty.
@ -42,15 +42,15 @@ Many __context__s can be deployed together to enrich the web application offerin
Web applications can be written using exclusively the Servlet APIs, since developers know well the Servlet API and because they guarantee better portability across Servlet container implementations.
Embedded web applications based on the Servlet APIs are described in xref:eg-server-http-handler-use-servlet[this section].
Embedded web applications based on the Servlet APIs are described in xref:pg-server-http-handler-use-servlet[this section].
Embedded web applications may also require additional features such as access to Jetty specific APIs, or utility features such as redirection from HTTP to HTTPS, support for `gzip` content compression, etc.
The Jetty Server Libraries provides a number of out-of-the-box __Handler__s that implement the most common functionalities and are described in xref:eg-server-http-handler-use-util[this section].
The Jetty Server Libraries provides a number of out-of-the-box __Handler__s that implement the most common functionalities and are described in xref:pg-server-http-handler-use-util[this section].
[[eg-server-http-handler-use-util]]
[[pg-server-http-handler-use-util]]
==== Custom and Utility Handlers
[[eg-server-http-handler-use-util-context]]
[[pg-server-http-handler-use-util-context]]
===== ContextHandler
`ContextHandler` is a `Handler` that represents a _context_ for a web application.
@ -73,18 +73,18 @@ Server
└── ShopHandler
----
[[eg-server-http-handler-use-util-context-collection]]
[[pg-server-http-handler-use-util-context-collection]]
===== ContextHandlerCollection
Server applications may need to deploy to Jetty more than one web application.
Recall from the xref:eg-server-http-handler[introduction] that Jetty offers `HandlerCollection` and `HandlerList` that may contain a sequence of children ``Handler``s.
Recall from the xref:pg-server-http-handler[introduction] that Jetty offers `HandlerCollection` and `HandlerList` that may contain a sequence of children ``Handler``s.
However, both of these have no knowledge of the concept of _context_ and just iterate through the sequence of ``Handler``s.
A better choice for multiple web application is `ContextHandlerCollection`, that matches a _context_ from either its _context path_ or _virtual host_, without iterating through the ``Handler``s.
If `ContextHandlerCollection` does not find a match, it just returns.
What happens next depends on the `Handler` tree structure: other ``Handler``s may be invoked after `ContextHandlerCollection`, for example `DefaultHandler` (see xref:eg-server-http-handler-use-util-default-handler[this section]).
What happens next depends on the `Handler` tree structure: other ``Handler``s may be invoked after `ContextHandlerCollection`, for example `DefaultHandler` (see xref:pg-server-http-handler-use-util-default-handler[this section]).
Eventually, if `Request.setHandled(true)` is not called, Jetty returns an HTTP `404` response to the client.
[source,java,indent=0]
@ -104,7 +104,7 @@ Server
└── RESTHandler
----
[[eg-server-http-handler-use-util-resource-handler]]
[[pg-server-http-handler-use-util-resource-handler]]
===== ResourceHandler -- Static Content
Static content such as images or files (HTML, JavaScript, CSS) can be sent by Jetty very efficiently because Jetty can write the content asynchronously, using direct ``ByteBuffer``s to minimize data copy, and using a memory cache for faster access to the data to send.
@ -124,7 +124,7 @@ Therefore, the traditional architecture where Nginx/Apache was the front-end ser
This leads to simpler systems (less components to configure and manage) and more performance (no need to proxy dynamic requests from front-end servers to back-end servers).
NOTE: It is common to use Nginx/Apache as load balancers, or as rewrite/redirect servers.
We typically recommend link:https://haproxy.org[HAProxy] as load balancer, and Jetty has xref:eg-server-http-handler-use-util-rewrite-handler[rewrite/redirect features] as well.
We typically recommend link:https://haproxy.org[HAProxy] as load balancer, and Jetty has xref:pg-server-http-handler-use-util-rewrite-handler[rewrite/redirect features] as well.
This is how you configure a `ResourceHandler` to create a simple file server:
@ -141,9 +141,9 @@ include::../../{doc_code}/embedded/server/http/HTTPServerDocs.java[tags=multiple
----
If the resource is not found, `ResourceHandler` will not call `Request.setHandled(true)` so what happens next depends on the `Handler` tree structure.
See also xref:eg-server-http-handler-use-util-default-handler[how to use] `DefaultHandler`.
See also xref:pg-server-http-handler-use-util-default-handler[how to use] `DefaultHandler`.
[[eg-server-http-handler-use-util-gzip-handler]]
[[pg-server-http-handler-use-util-gzip-handler]]
===== GzipHandler
`GzipHandler` provides supports for automatic decompression of compressed request content and automatic compression of response content.
@ -193,7 +193,7 @@ Server
// TODO: does ServletContextHandler really need a special configuration?
[[eg-server-http-handler-use-util-rewrite-handler]]
[[pg-server-http-handler-use-util-rewrite-handler]]
===== RewriteHandler
`RewriteHandler` provides support for URL rewriting, very similarly to link:https://httpd.apache.org/docs/current/mod/mod_rewrite.html[Apache's mod_rewrite] or link:https://nginx.org/en/docs/http/ngx_http_rewrite_module.html[Nginx rewrite module].
@ -234,7 +234,7 @@ Server
└── ContextHandler N
----
[[eg-server-http-handler-use-util-stats-handler]]
[[pg-server-http-handler-use-util-stats-handler]]
===== StatisticsHandler
`StatisticsHandler` gathers and exposes a number of statistic values related to request processing such as:
@ -245,7 +245,7 @@ Server
* Number of responses grouped by HTTP code (i.e. how many `2xx` responses, how many `3xx` responses, etc.)
* Total response content bytes
Server applications can read these values and use them internally, or expose them via some service, or xref:eg-arch-jmx[export them to JMX].
Server applications can read these values and use them internally, or expose them via some service, or xref:pg-arch-jmx[export them to JMX].
`StatisticsHandler` can be configured at the server level or at the context level.
@ -266,7 +266,7 @@ Server
└── ContextHandler N
----
[[eg-server-http-handler-use-util-secure-handler]]
[[pg-server-http-handler-use-util-secure-handler]]
===== SecuredRedirectHandler -- Redirect from HTTP to HTTPS
`SecuredRedirectHandler` allows to redirect requests made with the `http` scheme (and therefore to the clear-text port) to the `https` scheme (and therefore to the encrypted port).
@ -282,7 +282,7 @@ Server applications must configure a `HttpConfiguration` object with the secure
include::../../{doc_code}/embedded/server/http/HTTPServerDocs.java[tags=securedHandler]
----
[[eg-server-http-handler-use-util-default-handler]]
[[pg-server-http-handler-use-util-default-handler]]
===== DefaultHandler
`DefaultHandler` is a terminal `Handler` that always calls `Request.setHandled(true)` and performs the following:
@ -316,10 +316,10 @@ In the example above, `ContextHandlerCollection` will try to match a request to
NOTE: `DefaultHandler` just sends a nicer HTTP `404` response in case of wrong requests from clients.
Jetty will send an HTTP `404` response anyway if `DefaultHandler` is not used.
[[eg-server-http-handler-use-servlet]]
[[pg-server-http-handler-use-servlet]]
==== Servlet API Handlers
[[eg-server-http-handler-use-servlet-context]]
[[pg-server-http-handler-use-servlet-context]]
===== ServletContextHandler
``Handler``s are easy to write, but often web applications have already been written using the Servlet APIs, using ``Servlet``s and ``Filter``s.
@ -364,7 +364,7 @@ Server applications must be careful when creating the `Handler` tree to put ``Se
// TODO: revise what above, as ServletContextHandler is not a terminal handler.
// TODO: introduce the fact that ServletContextHandler can have a class loader that may be used to "isolate" web application classes.
[[eg-server-http-handler-use-webapp-context]]
[[pg-server-http-handler-use-webapp-context]]
===== WebAppContext
`WebAppContext` is a `ServletContextHandler` that auto configures itself by reading a `web.xml` Servlet configuration file.
@ -378,7 +378,7 @@ Where server applications using `ServletContextHandler` must manually invoke met
include::../../{doc_code}/embedded/server/http/HTTPServerDocs.java[tags=webAppContextHandler]
----
[[eg-server-http-handler-use-webapp-context-class-loading]]
[[pg-server-http-handler-use-webapp-context-class-loading]]
====== WebAppContext Class Loading
The Servlet specification requires that a web application class loader must load the web application classes from `WEB-INF/classes` and `WEB_INF/lib`.
@ -408,10 +408,10 @@ However, Jetty picks good defaults and allows server applications to customize _
// TODO: add a section on Configuration (system/server classes)
// TODO: add a section about how to setup JSP support
[[eg-server-http-handler-use-default-servlet]]
[[pg-server-http-handler-use-default-servlet]]
===== DefaultServlet -- Static Content for Servlets
If you have a xref:eg-server-http-handler-use-servlet-context[Servlet web application], you may want to use a `DefaultServlet` instead of `ResourceHandler`.
If you have a xref:pg-server-http-handler-use-servlet-context[Servlet web application], you may want to use a `DefaultServlet` instead of `ResourceHandler`.
The features are similar, but `DefaultServlet` is more commonly used to serve static files for Servlet web applications.
[source,java,indent=0]

6
jetty-documentation/src/main/asciidoc/programming-guide/server/http/server-http-handler.adoc
View File

@ -16,7 +16,7 @@
// ========================================================================
//
[[eg-server-http-handler]]
[[pg-server-http-handler]]
=== Server Handlers
An `org.eclipse.jetty.server.Handler` is the component that processes incoming HTTP requests and eventually produces HTTP responses.
@ -55,11 +55,11 @@ HandlerCollection
----
Server applications should rarely write custom ``Handler``s, preferring instead to use existing ``Handler``s provided by the Jetty Server Libraries for managing web application contexts, security, HTTP sessions and Servlet support.
Refer to xref:eg-server-http-handler-use[this section] for more information about how to use the ``Handler``s provided by the Jetty Server Libraries.
Refer to xref:pg-server-http-handler-use[this section] for more information about how to use the ``Handler``s provided by the Jetty Server Libraries.
However, in some cases the additional features are not required, or additional constraints on memory footprint, or performance, or just simplicity must be met.
In these cases, implementing your own `Handler` may be a better solution.
Refer to xref:eg-server-http-handler-implement[this section] for more information about how to write your own ``Handler``s.
Refer to xref:pg-server-http-handler-implement[this section] for more information about how to write your own ``Handler``s.
// TODO: document ScopedHandler? Is this really necessary or just an implementation detail that application will never worry about?

2
jetty-documentation/src/main/asciidoc/programming-guide/server/http/server-http-security.adoc
View File

@ -16,7 +16,7 @@
// ========================================================================
//
[[eg-server-http-security]]
[[pg-server-http-security]]
==== Securing HTTP Server Applications
// TODO: ConstraintSecurityHandler and Authenticators and LoginServices

12
jetty-documentation/src/main/asciidoc/programming-guide/server/http/server-http.adoc
View File

@ -16,7 +16,7 @@
// ========================================================================
//
[[eg-server-http]]
[[pg-server-http]]
=== HTTP Server Libraries
The Eclipse Jetty Project has historically provided libraries to embed an HTTP server and a Servlet Container.
@ -67,11 +67,11 @@ The example above shows the simplest HTTP/1.1 server; it has no support for HTTP
All these features are provided by the Jetty Server Libraries, and server applications only need to put the required components together to provide all the required features.
The ``Handler``s provided by the Jetty Server Libraries allow writing server applications that have functionalities similar to Apache HTTPD or Nginx (for example: URL redirection, URL rewriting, serving static content, reverse proxying, etc.), as well as generating content dynamically by processing incoming requests.
Read xref:eg-server-http-handler[this section] for further details.
Read xref:pg-server-http-handler[this section] for further details.
If you are interested in writing your server application based on the Servlet APIs, jump to xref:eg-server-http-handler-use-servlet[this section].
If you are interested in writing your server application based on the Servlet APIs, jump to xref:pg-server-http-handler-use-servlet[this section].
[[eg-server-http-request-processing]]
[[pg-server-http-request-processing]]
==== Server Request Processing
The Jetty HTTP request processing is outlined below in the diagram below.
@ -114,7 +114,7 @@ that in turn are converted into method calls to `HttpChannel`.
When enough of the HTTP request is arrived, the `Connection` calls `HttpChannel.handle()` that calls the `Handler` chain, that eventually calls the server application code.
[[eg-server-http-channel-events]]
[[pg-server-http-channel-events]]
===== HttpChannel Events
The central component processing HTTP requests is `HttpChannel`.
@ -146,7 +146,7 @@ Currently, the following events are available:
Please refer to the `HttpChannel.Listener` link:{JDURL}/org/eclipse/jetty/server/HttpChannel.Listener.html[javadocs] for the complete list of events.
Server applications can register `HttpChannel.Listener` by adding them as xref:eg-arch-bean[beans] to the `Connector`:
Server applications can register `HttpChannel.Listener` by adding them as xref:pg-arch-bean[beans] to the `Connector`:
[source,java,indent=0]
----

24
jetty-documentation/src/main/asciidoc/programming-guide/server/http2/server-http2.adoc
View File

@ -16,16 +16,16 @@
// ========================================================================
//
[[eg-server-http2]]
[[pg-server-http2]]
=== HTTP/2 Server Library
In the vast majority of cases, server applications should use the generic, high-level, xref:eg-server-http[HTTP server library] that also provides HTTP/2 support via the HTTP/2 ``ConnectionFactory``s as described in details xref:eg-server-http-connector-protocol-http2[here].
In the vast majority of cases, server applications should use the generic, high-level, xref:pg-server-http[HTTP server library] that also provides HTTP/2 support via the HTTP/2 ``ConnectionFactory``s as described in details xref:pg-server-http-connector-protocol-http2[here].
The low-level HTTP/2 server library has been designed for those applications that need low-level access to HTTP/2 features such as _sessions_, _streams_ and _frames_, and this is quite a rare use case.
See also the correspondent xref:eg-client-http2[HTTP/2 client library].
See also the correspondent xref:pg-client-http2[HTTP/2 client library].
[[eg-server-http2-intro]]
[[pg-server-http2-intro]]
==== Introduction
The Maven artifact coordinates for the HTTP/2 client library are the following:
@ -41,14 +41,14 @@ The Maven artifact coordinates for the HTTP/2 client library are the following:
include::../../http2.adoc[tag=multiplex]
[[eg-server-http2-flow-control]]
[[pg-server-http2-flow-control]]
===== HTTP/2 Flow Control
include::../../http2.adoc[tag=flowControl]
How a server application should handle HTTP/2 flow control is discussed in details in xref:eg-server-http2-request[this section].
How a server application should handle HTTP/2 flow control is discussed in details in xref:pg-server-http2-request[this section].
[[eg-server-http2-setup]]
[[pg-server-http2-setup]]
==== Server Setup
The low-level HTTP/2 support is provided by `org.eclipse.jetty.http2.server.RawHTTP2ServerConnectionFactory` and `org.eclipse.jetty.http2.api.server.ServerSessionListener`:
@ -58,7 +58,7 @@ The low-level HTTP/2 support is provided by `org.eclipse.jetty.http2.server.RawH
include::../../{doc_code}/embedded/server/http2/HTTP2ServerDocs.java[tags=setup]
----
Where server applications using the xref:eg-server-http[high-level server library] deal with HTTP requests and responses in ``Handler``s, server applications using the low-level HTTP/2 server library deal directly with HTTP/2 __session__s, __stream__s and __frame__s in a `ServerSessionListener` implementation.
Where server applications using the xref:pg-server-http[high-level server library] deal with HTTP requests and responses in ``Handler``s, server applications using the low-level HTTP/2 server library deal directly with HTTP/2 __session__s, __stream__s and __frame__s in a `ServerSessionListener` implementation.
The `ServerSessionListener` interface defines a number of methods that are invoked by the implementation upon the occurrence of HTTP/2 events, and that server applications can override to react to those events.
@ -80,7 +80,7 @@ This is where server applications can customize the connection settings by retur
include::../../{doc_code}/embedded/server/http2/HTTP2ServerDocs.java[tags=preface]
----
[[eg-server-http2-request]]
[[pg-server-http2-request]]
==== Receiving a Request
Receiving an HTTP request from the client, and sending a response, creates a _stream_ that encapsulates the exchange of HTTP/2 frames that compose the request and the response.
@ -105,7 +105,7 @@ include::../../{doc_code}/embedded/server/http2/HTTP2ServerDocs.java[tags=reques
include::../../http2.adoc[tag=apiFlowControl]
[[eg-server-http2-response]]
[[pg-server-http2-response]]
==== Sending a Response
After receiving an HTTP request, a server application must send an HTTP response.
@ -121,7 +121,7 @@ A server application can send a response in this way:
include::../../{doc_code}/embedded/server/http2/HTTP2ServerDocs.java[tags=response;!exclude]
----
[[eg-server-http2-reset]]
[[pg-server-http2-reset]]
==== Resetting a Request
A server application may decide that it does not want to accept the request.
@ -134,7 +134,7 @@ A request can be reset in this way:
include::../../{doc_code}/embedded/server/http2/HTTP2ServerDocs.java[tags=reset;!exclude]
----
[[eg-server-http2-push]]
[[pg-server-http2-push]]
==== HTTP/2 Push of Resources
A server application may _push_ secondary resources related to a primary resource.

4
jetty-documentation/src/main/asciidoc/programming-guide/server/server-io-arch.adoc
View File

@ -16,12 +16,12 @@
// ========================================================================
//
[[eg-server-io-arch]]
[[pg-server-io-arch]]
=== Server Libraries I/O Architecture
The Jetty server libraries provide the basic components and APIs to implement a network server.
They build on the common xref:eg-arch-io[Jetty I/O Architecture] and provide server specific concepts.
They build on the common xref:pg-arch-io[Jetty I/O Architecture] and provide server specific concepts.
The main I/O server-side class is `org.eclipse.jetty.server.ServerConnector`.

12
jetty-documentation/src/main/asciidoc/programming-guide/server/server.adoc
View File

@ -16,22 +16,22 @@
// ========================================================================
//
[[eg-server]]
[[pg-server]]
== Server Libraries
The Eclipse Jetty Project provides server-side libraries that allow you to embed an HTTP or WebSocket server in your applications.
A typical example is a HTTP server that needs to expose a REST endpoint.
Another example is a proxy application that receives HTTP requests and forwards them to third party services possibly using also the Jetty xref:eg-client[client libraries].
Another example is a proxy application that receives HTTP requests and forwards them to third party services possibly using also the Jetty xref:pg-client[client libraries].
While historically Jetty is an HTTP server, it is possible to use the Jetty server-side libraries to write a generic network server that interprets any network protocol (not only HTTP).
If you are interested in the low-level details of how the Eclipse Jetty server libraries work, or are interested in writing a custom protocol, look at the xref:eg-server-io-arch[Server I/O Architecture].
If you are interested in the low-level details of how the Eclipse Jetty server libraries work, or are interested in writing a custom protocol, look at the xref:pg-server-io-arch[Server I/O Architecture].
The Jetty server-side libraries provide:
* HTTP support for HTTP/1.0, HTTP/1.1, HTTP/2, clear-text or encrypted, for applications that want to embed Jetty as a generic HTTP server or proxy, via the xref:eg-server-http[HTTP libraries]
* HTTP/2 low-level support, for applications that want to explicitly handle low-level HTTP/2 _sessions_, _streams_ and _frames_, via the xref:eg-server-http2[HTTP/2 libraries]
* WebSocket support, for applications that want to embed a WebSocket server, via the xref:eg-server-websocket[WebSocket libraries]
* HTTP support for HTTP/1.0, HTTP/1.1, HTTP/2, clear-text or encrypted, for applications that want to embed Jetty as a generic HTTP server or proxy, via the xref:pg-server-http[HTTP libraries]
* HTTP/2 low-level support, for applications that want to explicitly handle low-level HTTP/2 _sessions_, _streams_ and _frames_, via the xref:pg-server-http2[HTTP/2 libraries]
* WebSocket support, for applications that want to embed a WebSocket server, via the xref:pg-server-websocket[WebSocket libraries]
include::http/server-http.adoc[]
include::http2/server-http2.adoc[]

2
jetty-documentation/src/main/asciidoc/programming-guide/server/websocket/server-websocket.adoc
View File

@ -16,7 +16,7 @@
// ========================================================================
//
[[eg-server-websocket]]
[[pg-server-websocket]]
=== WebSocket Server Libraries
TODO

16
jetty-documentation/src/main/asciidoc/programming-guide/troubleshooting.adoc
View File

@ -17,7 +17,7 @@
//
[appendix]
[[eg-troubleshooting]]
[[pg-troubleshooting]]
== Troubleshooting Jetty
TODO: introduction
@ -27,7 +27,7 @@ TODO: introduction
// TODO: #3 take jvm/component dumps
// TODO: #4 enable debug logging if you can
[[eg-troubleshooting-logging]]
[[pg-troubleshooting-logging]]
=== Logging
The Jetty libraries (both client and server) use link:http://slf4j.org/[SLF4J] as logging APIs.
@ -73,28 +73,28 @@ If you want to enable DEBUG logging but only for the HTTP/2 classes:
java -Dorg.eclipse.jetty.http2.LEVEL=DEBUG --class-path ...
----
[[eg-troubleshooting-thread-dump]]
[[pg-troubleshooting-thread-dump]]
=== JVM Thread Dump
TODO
[[eg-troubleshooting-component-dump]]
[[pg-troubleshooting-component-dump]]
=== Jetty Component Tree Dump
Jetty components are organized in a xref:eg-arch-bean[component tree].
Jetty components are organized in a xref:pg-arch-bean[component tree].
At the root of the component tree there is typically a `ContainerLifeCycle` instance -- typically a `Server` instance on the server and an `HttpClient` instance on the client.
`ContainerLifeCycle` has built-in _dump_ APIs that can be invoked either directly or xref:eg-arch-jmx[via JMX].
`ContainerLifeCycle` has built-in _dump_ APIs that can be invoked either directly or xref:pg-arch-jmx[via JMX].
// TODO: images from JMC?
// TODO: Command line JMX will be in JMX section.
TIP: You can get more details from a Jetty's `QueuedThreadPool` dump by enabling detailed dumps via `queuedThreadPool.setDetailedDump(true)`.
[[eg-troubleshooting-debugging]]
[[pg-troubleshooting-debugging]]
=== Debugging
Sometimes, in order to figure out a problem, enabling xref:eg-troubleshooting-logging[DEBUG logging] is not enough and you really need to debug the code with a debugger.
Sometimes, in order to figure out a problem, enabling xref:pg-troubleshooting-logging[DEBUG logging] is not enough and you really need to debug the code with a debugger.
Debugging an embedded Jetty application is most easily done from your preferred IDE, so refer to your IDE instruction for how to debug Java applications.