Improvements to the Jetty documentation.
Restructured the programming guide. Added collapsible TOC. Signed-off-by: Simone Bordet <simone.bordet@gmail.com>
This commit is contained in:
parent
a495539f53
commit
d425c9722c
|
@ -12,7 +12,7 @@
|
|||
//
|
||||
|
||||
[[pg-arch-jmx]]
|
||||
== Jetty JMX Support
|
||||
=== 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.
|
||||
|
||||
|
@ -38,7 +38,7 @@ The Maven coordinates for the Jetty JMX support are:
|
|||
</dependency>
|
||||
----
|
||||
|
||||
=== Enabling JMX Support
|
||||
==== Enabling JMX Support
|
||||
|
||||
Enabling JMX support is always recommended because it provides valuable information about the system, both for monitoring purposes and for troubleshooting purposes in case of problems.
|
||||
|
||||
|
@ -67,7 +67,7 @@ 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.
|
||||
|
||||
[[pg-arch-jmx-remote]]
|
||||
=== Enabling JMX Remote Access
|
||||
==== Enabling JMX Remote Access
|
||||
|
||||
There are two ways of enabling remote connectivity so that JMC can connect to the remote JVM to visualize MBeans.
|
||||
|
||||
|
@ -148,7 +148,7 @@ include::{doc_code}/org/eclipse/jetty/docs/programming/JMXDocs.java[tags=remote]
|
|||
----
|
||||
|
||||
[[pg-arch-jmx-remote-authorization]]
|
||||
==== JMX Remote Access Authorization
|
||||
===== JMX Remote Access Authorization
|
||||
|
||||
The standard `JMXConnectorServer` provides several options to authorize access, for example via JAAS or via configuration files.
|
||||
For a complete guide to controlling authentication and authorization in JMX, see https://docs.oracle.com/en/java/javase/11/management/[the official JMX documentation].
|
||||
|
@ -242,7 +242,7 @@ When you configure `ConnectorServer` in this way, you must set the system proper
|
|||
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.
|
||||
|
||||
[[pg-arch-jmx-annotation]]
|
||||
=== Jetty JMX Annotations
|
||||
==== Jetty JMX Annotations
|
||||
|
||||
The Jetty JMX support, and in particular `MBeanContainer`, is notified every time a bean is added to the component tree.
|
||||
|
||||
|
@ -278,24 +278,24 @@ For each type -- class or interface, the corresponding `+*.jmx.*MBean+` is looke
|
|||
For each type, the scan looks for the class-level annotation `@ManagedObject`.
|
||||
If it is found, the scan looks for method-level `@ManagedAttribute` and `@ManagedOperation` annotations; otherwise it skips the current type and moves to the next type to scan.
|
||||
|
||||
==== @ManagedObject
|
||||
===== @ManagedObject
|
||||
|
||||
The `@ManagedObject` annotation is used on a class at the top level to indicate that it should be exposed as an MBean.
|
||||
It has only one attribute to it which is used as the description of the MBean.
|
||||
|
||||
==== @ManagedAttribute
|
||||
===== @ManagedAttribute
|
||||
|
||||
The `@ManagedAttribute` annotation is used to indicate that a given method is exposed as a JMX attribute.
|
||||
This annotation is placed always on the getter method of a given attribute.
|
||||
Unless the `readonly` attribute is set to `true` in the annotation, a corresponding setter is looked up following normal naming conventions.
|
||||
For example if this annotation is on a method called `String getFoo()` then a method called `void setFoo(String)` would be looked up, and if found wired as the setter for the JMX attribute.
|
||||
|
||||
==== @ManagedOperation
|
||||
===== @ManagedOperation
|
||||
|
||||
The `@ManagedOperation` annotation is used to indicate that a given method is exposed as a JMX operation.
|
||||
A JMX operation has an _impact_ that can be `INFO` if the operation returns a value without modifying the object, `ACTION` if the operation does not return a value but modifies the object, and "ACTION_INFO" if the operation both returns a value and modifies the object.
|
||||
If the _impact_ is not specified, it has the default value of `UNKNOWN`.
|
||||
|
||||
==== @Name
|
||||
===== @Name
|
||||
|
||||
The `@Name` annotation is used to assign a name and description to parameters in method signatures so that when rendered by JMX consoles it is clearer what the parameter meaning is.
|
||||
|
|
|
@ -16,6 +16,6 @@
|
|||
== Jetty Architecture
|
||||
|
||||
include::arch-bean.adoc[]
|
||||
include::arch-jmx.adoc[]
|
||||
include::arch-listener.adoc[]
|
||||
include::arch-io.adoc[]
|
||||
include::arch-listener.adoc[]
|
||||
include::arch-jmx.adoc[]
|
||||
|
|
|
@ -29,6 +29,7 @@ These are the available client libraries:
|
|||
|
||||
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::client-io-arch.adoc[]
|
||||
include::http/client-http.adoc[]
|
||||
include::http2/client-http2.adoc[]
|
||||
include::client-io-arch.adoc[]
|
||||
include::websocket/client-websocket.adoc[]
|
||||
|
|
|
@ -12,12 +12,12 @@
|
|||
//
|
||||
|
||||
[[pg-client-http-api]]
|
||||
=== HttpClient API Usage
|
||||
==== HttpClient API Usage
|
||||
|
||||
`HttpClient` provides two types of APIs: a blocking API and a non-blocking API.
|
||||
|
||||
[[pg-client-http-blocking]]
|
||||
==== HttpClient Blocking APIs
|
||||
===== HttpClient Blocking APIs
|
||||
|
||||
The simpler way to perform a HTTP request is the following:
|
||||
|
||||
|
@ -77,7 +77,7 @@ include::../../{doc_code}/org/eclipse/jetty/docs/programming/client/http/HTTPCli
|
|||
In the example above, when the 5 seconds expire, the request/response cycle is aborted and a `java.util.concurrent.TimeoutException` is thrown.
|
||||
|
||||
[[pg-client-http-non-blocking]]
|
||||
==== HttpClient Non-Blocking APIs
|
||||
===== 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.
|
||||
|
||||
|
@ -135,9 +135,6 @@ 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.
|
||||
|
||||
[[pg-client-http-content]]
|
||||
==== HttpClient Content Handling
|
||||
|
||||
[[pg-client-http-content-request]]
|
||||
===== Request Content Handling
|
||||
|
||||
|
|
|
@ -12,7 +12,7 @@
|
|||
//
|
||||
|
||||
[[pg-client-http-authentication]]
|
||||
=== HttpClient Authentication Support
|
||||
==== 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].
|
||||
|
||||
|
@ -76,5 +76,5 @@ include::../../{doc_code}/org/eclipse/jetty/docs/programming/client/http/HTTPCli
|
|||
See also the xref:pg-client-http-proxy-authentication[proxy authentication section] for further information about how authentication works with HTTP proxies.
|
||||
|
||||
[[pg-client-http-authentication-spnego]]
|
||||
=== HttpClient SPNEGO Authentication Support
|
||||
===== HttpClient SPNEGO Authentication Support
|
||||
TODO
|
||||
|
|
|
@ -12,7 +12,7 @@
|
|||
//
|
||||
|
||||
[[pg-client-http-configuration]]
|
||||
=== HttpClient Configuration
|
||||
==== HttpClient Configuration
|
||||
|
||||
`HttpClient` has a quite large number of configuration parameters.
|
||||
Please refer to the `HttpClient` link:{JDURL}/org/eclipse/jetty/client/HttpClient.html[javadocs] for the complete list of configurable parameters.
|
||||
|
@ -26,7 +26,7 @@ The most common parameters are:
|
|||
* `HttpClient.maxRequestsQueuedPerDestination`: the max number of requests queued (defaults to 1024).
|
||||
|
||||
[[pg-client-http-configuration-tls]]
|
||||
==== HttpClient TLS Configuration
|
||||
===== HttpClient TLS Configuration
|
||||
|
||||
`HttpClient` supports HTTPS requests out-of-the-box like a browser does.
|
||||
|
||||
|
@ -64,9 +64,9 @@ include::../../{doc_code}/org/eclipse/jetty/docs/programming/client/http/HTTPCli
|
|||
Please refer to the `SslContextFactory.Client` link:{JDURL}/org/eclipse/jetty/util/ssl/SslContextFactory.Client.html[javadocs] for the complete list of configurable parameters.
|
||||
|
||||
[[pg-client-http-configuration-tls-truststore]]
|
||||
==== HttpClient TLS TrustStore Configuration
|
||||
====== HttpClient TLS TrustStore Configuration
|
||||
TODO
|
||||
|
||||
[[pg-client-http-configuration-tls-client-certs]]
|
||||
==== HttpClient TLS Client Certificates Configuration
|
||||
====== HttpClient TLS Client Certificates Configuration
|
||||
TODO
|
||||
|
|
|
@ -12,7 +12,7 @@
|
|||
//
|
||||
|
||||
[[pg-client-http-cookie]]
|
||||
=== HttpClient Cookie Support
|
||||
==== HttpClient Cookie Support
|
||||
|
||||
Jetty's `HttpClient` supports cookies out of the box.
|
||||
|
||||
|
@ -65,7 +65,7 @@ include::../../{doc_code}/org/eclipse/jetty/docs/programming/client/http/HTTPCli
|
|||
The example above will retain only cookies that come from the `google.com` domain or sub-domains.
|
||||
|
||||
// TODO: move this section to server-side
|
||||
==== Special Characters in Cookies
|
||||
===== Special Characters in Cookies
|
||||
|
||||
Jetty is compliant with link:https://tools.ietf.org/html/rfc6265[RFC6265], and as such care must be taken when setting a cookie value that includes special characters such as `;`.
|
||||
|
||||
|
|
|
@ -12,7 +12,7 @@
|
|||
//
|
||||
|
||||
[[pg-client-http-intro]]
|
||||
=== HttpClient Introduction
|
||||
==== HttpClient Introduction
|
||||
|
||||
The Jetty HTTP client module provides easy-to-use APIs and utility classes to perform HTTP (or HTTPS) requests.
|
||||
|
||||
|
|
|
@ -12,7 +12,7 @@
|
|||
//
|
||||
|
||||
[[pg-client-http-proxy]]
|
||||
=== HttpClient Proxy Support
|
||||
==== HttpClient Proxy Support
|
||||
|
||||
Jetty's `HttpClient` can be configured to use proxies to connect to destinations.
|
||||
|
||||
|
@ -33,7 +33,7 @@ Configured in this way, `HttpClient` makes requests to the HTTP proxy (for plain
|
|||
Proxying is supported for both HTTP/1.1 and HTTP/2.
|
||||
|
||||
[[pg-client-http-proxy-authentication]]
|
||||
==== Proxy Authentication Support
|
||||
===== Proxy Authentication Support
|
||||
|
||||
Jetty's `HttpClient` supports proxy authentication in the same way it supports xref:pg-client-http-authentication[server authentication].
|
||||
|
||||
|
|
|
@ -12,7 +12,7 @@
|
|||
//
|
||||
|
||||
[[pg-client-http-transport]]
|
||||
=== HttpClient Pluggable Transports
|
||||
==== HttpClient Pluggable Transports
|
||||
|
||||
Jetty's `HttpClient` can be configured to use different transports to carry the semantic of HTTP requests and responses.
|
||||
|
||||
|
@ -57,7 +57,7 @@ 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.
|
||||
|
||||
[[pg-client-http-transport-http11]]
|
||||
==== HTTP/1.1 Transport
|
||||
===== HTTP/1.1 Transport
|
||||
|
||||
HTTP/1.1 is the default transport.
|
||||
|
||||
|
@ -74,7 +74,7 @@ include::../../{doc_code}/org/eclipse/jetty/docs/programming/client/http/HTTPCli
|
|||
----
|
||||
|
||||
[[pg-client-http-transport-http2]]
|
||||
==== HTTP/2 Transport
|
||||
===== HTTP/2 Transport
|
||||
|
||||
The HTTP/2 transport can be configured in this way:
|
||||
|
||||
|
@ -88,7 +88,7 @@ include::../../{doc_code}/org/eclipse/jetty/docs/programming/client/http/HTTPCli
|
|||
`HttpClientTransportOverHTTP2` uses `HTTP2Client` to format high-level semantic HTTP requests (like "GET resource /index.html") into the HTTP/2 specific format.
|
||||
|
||||
[[pg-client-http-transport-fcgi]]
|
||||
==== FastCGI Transport
|
||||
===== FastCGI Transport
|
||||
|
||||
The FastCGI transport can be configured in this way:
|
||||
|
||||
|
@ -102,7 +102,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 xref:fastcgi[FastCGI support] to serve PHP pages (WordPress for example).
|
||||
|
||||
[[pg-client-http-transport-dynamic]]
|
||||
==== Dynamic Transport
|
||||
===== 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).
|
||||
|
||||
|
|
|
@ -57,7 +57,7 @@ A _session_ typically has a long life -- once the TCP connection is established,
|
|||
include::../../http2.adoc[tag=multiplex]
|
||||
|
||||
[[pg-client-http2-flow-control]]
|
||||
===== HTTP/2 Flow Control
|
||||
==== HTTP/2 Flow Control
|
||||
|
||||
include::../../http2.adoc[tag=flowControl]
|
||||
|
||||
|
@ -84,7 +84,7 @@ include::../../{doc_code}/org/eclipse/jetty/docs/programming/client/http2/HTTP2C
|
|||
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.
|
||||
|
||||
[[pg-client-http2-configure]]
|
||||
===== Configuring the Session
|
||||
==== Configuring the Session
|
||||
|
||||
The `connect(...)` method takes a `Session.Listener` parameter.
|
||||
This listener's `onPreface(...)` method is invoked just before establishing the connection to the server to gather the client configuration to send to the server.
|
||||
|
|
|
@ -12,6 +12,6 @@
|
|||
//
|
||||
|
||||
[[pg-client-websocket]]
|
||||
=== WebSocket Client Libraries
|
||||
=== WebSocket Client
|
||||
|
||||
TODO
|
||||
|
|
|
@ -0,0 +1,3 @@
|
|||
<link rel="stylesheet" href="../styles.css">
|
||||
<link rel="stylesheet" href="../toc.css">
|
||||
<script src="../toc.js"></script>
|
|
@ -12,9 +12,10 @@
|
|||
//
|
||||
|
||||
:doctitle: Eclipse Jetty: Programming Guide
|
||||
:toc-title: Programming Guide
|
||||
:toc-title: Jetty Programming Guide
|
||||
:breadcrumb: Home:../index.html | Programming Guide:./index.html
|
||||
:idprefix: pg-
|
||||
:docinfo: private-head
|
||||
|
||||
include::../config.adoc[]
|
||||
include::.asciidoctorconfig[]
|
||||
|
|
|
@ -12,19 +12,19 @@
|
|||
//
|
||||
|
||||
[[pg-server-http-application]]
|
||||
=== Writing HTTP Server Applications
|
||||
===== 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.
|
||||
|
||||
[[pg-server-http-application-1xx]]
|
||||
==== Sending 1xx Responses
|
||||
====== 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.
|
||||
|
||||
[[pg-server-http-application-100]]
|
||||
===== 100 Continue
|
||||
====== 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.
|
||||
|
||||
|
@ -39,7 +39,7 @@ include::../../{doc_code}/org/eclipse/jetty/docs/programming/server/http/HTTPSer
|
|||
----
|
||||
|
||||
[[jetty-102-processing]]
|
||||
===== 102 Processing
|
||||
====== 102 Processing
|
||||
|
||||
link:https://tools.ietf.org/html/rfc2518[RFC 2518] defined the `102 Processing` status code that can be sent:
|
||||
|
||||
|
|
|
@ -12,7 +12,7 @@
|
|||
//
|
||||
|
||||
[[pg-server-http-connector]]
|
||||
=== Server Connectors
|
||||
==== Server Connectors
|
||||
|
||||
A `Connector` is the component that handles incoming requests from clients, and works in conjunction with `ConnectionFactory` instances.
|
||||
|
||||
|
@ -50,7 +50,7 @@ include::../../{doc_code}/org/eclipse/jetty/docs/programming/server/http/HTTPSer
|
|||
----
|
||||
|
||||
[[pg-server-http-connector-protocol]]
|
||||
==== Configuring Protocols
|
||||
===== 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:pg-arch-io[this section] for more details about `Connection` objects).
|
||||
|
||||
|
@ -58,7 +58,7 @@ A `ServerConnector` can be configured with one or more ``ConnectionFactory``s.
|
|||
If no `ConnectionFactory` is specified then `HttpConnectionFactory` is implicitly configured.
|
||||
|
||||
[[pg-server-http-connector-protocol-http11]]
|
||||
===== Configuring Clear-Text HTTP/1.1
|
||||
====== Clear-Text HTTP/1.1
|
||||
|
||||
`HttpConnectionFactory` creates `HttpConnection` objects that parse bytes and generate bytes for the HTTP/1.1 protocol.
|
||||
|
||||
|
@ -70,7 +70,7 @@ include::../../{doc_code}/org/eclipse/jetty/docs/programming/server/http/HTTPSer
|
|||
----
|
||||
|
||||
[[pg-server-http-connector-protocol-http11-tls]]
|
||||
===== Configuring Encrypted HTTP/1.1 (https)
|
||||
====== Encrypted HTTP/1.1 (https)
|
||||
|
||||
Supporting encrypted HTTP/1.1 (that is, requests with the `https` scheme) is supported by configuring an `SslContextFactory` that has access to the keyStore containing the private server key and public server certificate, in this way:
|
||||
|
||||
|
@ -79,30 +79,8 @@ Supporting encrypted HTTP/1.1 (that is, requests with the `https` scheme) is sup
|
|||
include::../../{doc_code}/org/eclipse/jetty/docs/programming/server/http/HTTPServerDocs.java[tags=tlsHttp11]
|
||||
----
|
||||
|
||||
[[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.
|
||||
|
||||
From the Jetty point of view, all the connections arrive from the load balancer, rather than the real clients, but is possible to configure the load balancer to forward the real client IP address and port to the backend Jetty server using the link:https://www.haproxy.org/download/2.1/doc/proxy-protocol.txt[PROXY protocol].
|
||||
|
||||
NOTE: The PROXY protocol is widely supported by load balancers such as link:http://cbonte.github.io/haproxy-dconv/2.2/configuration.html#5.2-send-proxy[HAProxy] (via its `send-proxy` directive), link:https://docs.nginx.com/nginx/admin-guide/load-balancer/using-proxy-protocol[Nginx](via its `proxy_protocol on` directive) and others.
|
||||
|
||||
To support this case, Jetty can be configured in this way:
|
||||
|
||||
[source,java,indent=0]
|
||||
----
|
||||
include::../../{doc_code}/org/eclipse/jetty/docs/programming/server/http/HTTPServerDocs.java[tags=proxyHTTP]
|
||||
----
|
||||
|
||||
Note how the ``ConnectionFactory``s passed to `ServerConnector` are in order: first PROXY, then HTTP/1.1.
|
||||
Note also how the PROXY `ConnectionFactory` needs to know its _next_ protocol (in this example, HTTP/1.1).
|
||||
|
||||
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.
|
||||
|
||||
[[pg-server-http-connector-protocol-http2]]
|
||||
===== Configuring Clear-Text HTTP/2
|
||||
====== Clear-Text HTTP/2
|
||||
|
||||
It is well known that the HTTP ports are `80` (for clear-text HTTP) and `443` for encrypted HTTP.
|
||||
By using those ports, a client had _prior knowledge_ that the server would speak, respectively, the HTTP/1.x protocol and the TLS protocol (and, after decryption, the HTTP/1.x protocol).
|
||||
|
@ -125,7 +103,7 @@ This configuration is also typical when Jetty is installed in backend servers be
|
|||
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].
|
||||
|
||||
[[pg-server-http-connector-protocol-http2-tls]]
|
||||
===== Configuring Encrypted HTTP/2
|
||||
====== Encrypted HTTP/2
|
||||
|
||||
When using encrypted HTTP/2, the unencrypted protocol is negotiated by client and server using an extension to the TLS protocol called ALPN.
|
||||
|
||||
|
@ -144,3 +122,25 @@ With the ALPN extension information, Jetty can negotiate a protocol and pick, am
|
|||
The fact that the HTTP/2 protocol comes before the HTTP/1.1 protocol indicates that HTTP/2 is the preferred protocol for the server.
|
||||
|
||||
Note also that the default protocol set in the ALPN ``ConnectionFactory``, which is used in case ALPN is not supported by the client, is HTTP/1.1 -- if the client does not support ALPN is probably an old client so HTTP/1.1 is the safest choice.
|
||||
|
||||
[[pg-server-http-connector-protocol-proxy-http11]]
|
||||
====== 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.
|
||||
|
||||
From the Jetty point of view, all the connections arrive from the load balancer, rather than the real clients, but is possible to configure the load balancer to forward the real client IP address and port to the backend Jetty server using the link:https://www.haproxy.org/download/2.1/doc/proxy-protocol.txt[PROXY protocol].
|
||||
|
||||
NOTE: The PROXY protocol is widely supported by load balancers such as link:http://cbonte.github.io/haproxy-dconv/2.2/configuration.html#5.2-send-proxy[HAProxy] (via its `send-proxy` directive), link:https://docs.nginx.com/nginx/admin-guide/load-balancer/using-proxy-protocol[Nginx](via its `proxy_protocol on` directive) and others.
|
||||
|
||||
To support this case, Jetty can be configured in this way:
|
||||
|
||||
[source,java,indent=0]
|
||||
----
|
||||
include::../../{doc_code}/org/eclipse/jetty/docs/programming/server/http/HTTPServerDocs.java[tags=proxyHTTP]
|
||||
----
|
||||
|
||||
Note how the ``ConnectionFactory``s passed to `ServerConnector` are in order: first PROXY, then HTTP/1.1.
|
||||
Note also how the PROXY `ConnectionFactory` needs to know its _next_ protocol (in this example, HTTP/1.1).
|
||||
|
||||
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.
|
||||
|
|
|
@ -12,7 +12,7 @@
|
|||
//
|
||||
|
||||
[[pg-server-http-handler-implement]]
|
||||
==== Implementing Handler
|
||||
===== Implementing Handler
|
||||
|
||||
The `Handler` API consist fundamentally of just one method:
|
||||
|
||||
|
@ -29,7 +29,7 @@ Applications may wrap the request or response (or both) and forward the wrapped
|
|||
This is the reason why there are two request parameters in the `Handler` APIs: the first is the unwrapped, original, request that also gives access to Jetty-specific APIs, while the second is the application-wrapped Servlet request.
|
||||
|
||||
[[pg-server-http-handler-impl-hello]]
|
||||
===== Hello World Handler
|
||||
====== Hello World Handler
|
||||
|
||||
A simple "Hello World" `Handler` is the following:
|
||||
|
||||
|
@ -41,7 +41,7 @@ include::../../{doc_code}/org/eclipse/jetty/docs/programming/server/http/HTTPSer
|
|||
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.
|
||||
|
||||
[[pg-server-http-handler-impl-filter]]
|
||||
===== Filtering Handler
|
||||
====== 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:
|
||||
|
||||
|
|
|
@ -12,7 +12,7 @@
|
|||
//
|
||||
|
||||
[[pg-server-http-handler-use]]
|
||||
==== Using Provided Handlers
|
||||
===== Jetty Handlers
|
||||
|
||||
Web applications are the unit of deployment in an HTTP server or Servlet container such as Jetty.
|
||||
|
||||
|
@ -40,13 +40,10 @@ Web applications can be written using exclusively the Servlet APIs, since develo
|
|||
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:pg-server-http-handler-use-util[this section].
|
||||
|
||||
[[pg-server-http-handler-use-util]]
|
||||
==== Custom and Utility Handlers
|
||||
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[this section].
|
||||
|
||||
[[pg-server-http-handler-use-util-context]]
|
||||
===== ContextHandler
|
||||
====== ContextHandler
|
||||
|
||||
`ContextHandler` is a `Handler` that represents a _context_ for a web application.
|
||||
It is a `HandlerWrapper` that performs some action before and after delegating to the nested `Handler`.
|
||||
|
@ -69,7 +66,7 @@ Server
|
|||
----
|
||||
|
||||
[[pg-server-http-handler-use-util-context-collection]]
|
||||
===== ContextHandlerCollection
|
||||
====== ContextHandlerCollection
|
||||
|
||||
Server applications may need to deploy to Jetty more than one web application.
|
||||
|
||||
|
@ -100,7 +97,7 @@ Server
|
|||
----
|
||||
|
||||
[[pg-server-http-handler-use-util-resource-handler]]
|
||||
===== ResourceHandler -- Static Content
|
||||
====== 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.
|
||||
|
||||
|
@ -139,7 +136,7 @@ If the resource is not found, `ResourceHandler` will not call `Request.setHandle
|
|||
See also xref:pg-server-http-handler-use-util-default-handler[how to use] `DefaultHandler`.
|
||||
|
||||
[[pg-server-http-handler-use-util-gzip-handler]]
|
||||
===== GzipHandler
|
||||
====== GzipHandler
|
||||
|
||||
`GzipHandler` provides supports for automatic decompression of compressed request content and automatic compression of response content.
|
||||
|
||||
|
@ -189,7 +186,7 @@ Server
|
|||
// TODO: does ServletContextHandler really need a special configuration?
|
||||
|
||||
[[pg-server-http-handler-use-util-rewrite-handler]]
|
||||
===== RewriteHandler
|
||||
====== 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].
|
||||
|
||||
|
@ -230,7 +227,7 @@ Server
|
|||
----
|
||||
|
||||
[[pg-server-http-handler-use-util-stats-handler]]
|
||||
===== StatisticsHandler
|
||||
====== StatisticsHandler
|
||||
|
||||
`StatisticsHandler` gathers and exposes a number of statistic values related to request processing such as:
|
||||
|
||||
|
@ -262,7 +259,7 @@ Server
|
|||
----
|
||||
|
||||
[[pg-server-http-handler-use-util-secure-handler]]
|
||||
===== SecuredRedirectHandler -- Redirect from HTTP to HTTPS
|
||||
====== 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).
|
||||
|
||||
|
@ -278,7 +275,7 @@ include::../../{doc_code}/org/eclipse/jetty/docs/programming/server/http/HTTPSer
|
|||
----
|
||||
|
||||
[[pg-server-http-handler-use-util-default-handler]]
|
||||
===== DefaultHandler
|
||||
====== DefaultHandler
|
||||
|
||||
`DefaultHandler` is a terminal `Handler` that always calls `Request.setHandled(true)` and performs the following:
|
||||
|
||||
|
@ -312,10 +309,10 @@ NOTE: `DefaultHandler` just sends a nicer HTTP `404` response in case of wrong r
|
|||
Jetty will send an HTTP `404` response anyway if `DefaultHandler` is not used.
|
||||
|
||||
[[pg-server-http-handler-use-servlet]]
|
||||
==== Servlet API Handlers
|
||||
===== Servlet API Handlers
|
||||
|
||||
[[pg-server-http-handler-use-servlet-context]]
|
||||
===== ServletContextHandler
|
||||
====== 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.
|
||||
|
||||
|
@ -360,7 +357,7 @@ Server applications must be careful when creating the `Handler` tree to put ``Se
|
|||
// TODO: introduce the fact that ServletContextHandler can have a class loader that may be used to "isolate" web application classes.
|
||||
|
||||
[[pg-server-http-handler-use-webapp-context]]
|
||||
===== WebAppContext
|
||||
====== WebAppContext
|
||||
|
||||
`WebAppContext` is a `ServletContextHandler` that auto configures itself by reading a `web.xml` Servlet configuration file.
|
||||
|
||||
|
@ -374,7 +371,7 @@ include::../../{doc_code}/org/eclipse/jetty/docs/programming/server/http/HTTPSer
|
|||
----
|
||||
|
||||
[[pg-server-http-handler-use-webapp-context-class-loading]]
|
||||
====== WebAppContext 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`.
|
||||
The web application class loader is special because it behaves differently from typical class loaders: where typical class loaders first delegate to their parent class loader and then try to find the class locally, the web application class loader first tries to find the class locally and then delegates to the parent class loader.
|
||||
|
@ -404,7 +401,7 @@ However, Jetty picks good defaults and allows server applications to customize _
|
|||
// TODO: add a section about how to setup JSP support
|
||||
|
||||
[[pg-server-http-handler-use-default-servlet]]
|
||||
===== DefaultServlet -- Static Content for Servlets
|
||||
====== DefaultServlet -- Static Content for Servlets
|
||||
|
||||
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.
|
||||
|
|
|
@ -12,7 +12,7 @@
|
|||
//
|
||||
|
||||
[[pg-server-http-handler]]
|
||||
=== Server Handlers
|
||||
==== Server Handlers
|
||||
|
||||
An `org.eclipse.jetty.server.Handler` is the component that processes incoming HTTP requests and eventually produces HTTP responses.
|
||||
|
||||
|
|
|
@ -12,7 +12,7 @@
|
|||
//
|
||||
|
||||
[[pg-server-http-security]]
|
||||
==== Securing HTTP Server Applications
|
||||
===== Securing HTTP Server Applications
|
||||
|
||||
// TODO: ConstraintSecurityHandler and Authenticators and LoginServices
|
||||
TODO
|
||||
|
|
|
@ -37,7 +37,7 @@ The Maven artifact coordinates for the HTTP/2 client library are the following:
|
|||
include::../../http2.adoc[tag=multiplex]
|
||||
|
||||
[[pg-server-http2-flow-control]]
|
||||
===== HTTP/2 Flow Control
|
||||
==== HTTP/2 Flow Control
|
||||
|
||||
include::../../http2.adoc[tag=flowControl]
|
||||
|
||||
|
|
|
@ -12,7 +12,6 @@
|
|||
//
|
||||
|
||||
[[pg-server-session-architecture]]
|
||||
|
||||
==== Session Architecture
|
||||
|
||||
Terminology::
|
||||
|
|
|
@ -79,6 +79,7 @@ Jetty provides two `SessionCache` implementations: the link:{JDURL}/org/eclipse/
|
|||
|
||||
[[pg-server-session-hash]]
|
||||
===== The DefaultSessionCache
|
||||
|
||||
The link:{JDURL}/org/eclipse/jetty/server/session/DefaultSessionCache.html[DefaultSessionCache] retains `Session` objects in memory in a `ConcurrentHashMap`.
|
||||
It is suitable for non-clustered and clustered deployments.
|
||||
For clustered deployments, a sticky load balancer is *strongly* recommended, otherwise you risk indeterminate session state as the session bounces around multiple nodes.
|
||||
|
@ -113,6 +114,7 @@ NOTE: If you don't configure any `SessionCache` or `SessionCacheFactory`, the `S
|
|||
|
||||
[[pg-server-session-null]]
|
||||
===== The NullSessionCache
|
||||
|
||||
The link:{JDURL}/org/eclipse/jetty/server/session/NullSessionCache.html[NullSessionCache] does not actually cache any objects: each request uses a fresh `Session` object.
|
||||
It is suitable for clustered deployments without a sticky load balancer and non-clustered deployments when purely minimal support for sessions is needed.
|
||||
|
||||
|
@ -133,7 +135,7 @@ include::../../{doc_code}/org/eclipse/jetty/docs/programming/server/session/Sess
|
|||
|
||||
As previously mentioned, we highly recommend that you extend the link:{JDURL}/org/eclipse/jetty/server/session/AbstractSessionCache.html[AbstractSessionCache].
|
||||
|
||||
===== Heterogenous Caching
|
||||
===== Heterogeneous Caching
|
||||
|
||||
Using one of the ``SessionCacheFactory``s will ensure that every time a `SessionHandler` starts it will create a new instance of the corresponding type of `SessionCache`.
|
||||
|
||||
|
|
|
@ -13,6 +13,7 @@
|
|||
|
||||
[[pg-server-session-datastore-mongo]]
|
||||
===== The MongoSessionDataStore
|
||||
|
||||
The `MongoSessionDataStore` supports persistence of `SessionData` in a nosql database.
|
||||
|
||||
The best description for the document model for session information is found in the javadoc for the link:{JDURL}/org/eclipse/jetty/nosql/mongodb/MongoSessionDataStore.html[MongoSessionDataStore].
|
||||
|
|
|
@ -18,7 +18,7 @@ Each context can have a single `SessionHandler`.
|
|||
The purpose of the `SessionHandler` is to interact with the `Request` and `Response` to create, maintain and propagate sessions.
|
||||
It also calls the context-level session listeners at appropriate points in the session lifecycle.
|
||||
|
||||
===== Configuration =====
|
||||
===== Configuration
|
||||
|
||||
The majority of configuration for the link:{JDURL}/org/eclipse/jetty/server/session/SessionHandler.html[SessionHandler] can be done via `web.xml` `<session-config>` declarations, or the `javax.servlet.SessionCookieConfig` api.
|
||||
There are also a few jetty-specific configuration options that we will cover here:
|
||||
|
@ -128,7 +128,7 @@ This can also be configured by:
|
|||
* using the `javax.servlet.SessionCookieConfig.setPath(String)` method
|
||||
* defining the `<session-config><cookie-config><path/></cookie-config></session-config>` element in `web.xml`
|
||||
|
||||
===== Statistics =====
|
||||
===== Statistics
|
||||
|
||||
Some statistics about the sessions for a context can be obtained from the `SessionHandler`, either by calling the methods directly or via `jmx`:
|
||||
|
||||
|
|
|
@ -49,7 +49,7 @@ Here is an example of explicitly setting up a `DefaultSessionIdManager` with a `
|
|||
include::../../{doc_code}/org/eclipse/jetty/docs/programming/server/session/SessionDocs.java[tags=default]
|
||||
----
|
||||
|
||||
===== Implementing a Custom SessionIdManager
|
||||
==== Implementing a Custom SessionIdManager
|
||||
|
||||
If the `DefaultSessionIdManager` does not meet your needs, you can extend it, or implement the `SessionIdManager` interface directly.
|
||||
|
||||
|
|
|
@ -12,7 +12,7 @@
|
|||
//
|
||||
|
||||
[[pg-server-session]]
|
||||
=== Session Management
|
||||
=== HTTP Session Management
|
||||
|
||||
Sessions are a concept within the Servlet API which allow requests to store and retrieve information across the time a user spends in an application.
|
||||
Jetty provides a number of pluggable options for managing sessions.
|
||||
|
|
Loading…
Reference in New Issue