diff --git a/documentation/jetty-documentation/pom.xml b/documentation/jetty-documentation/pom.xml index 5e332016a991..68cdbc4bdbe7 100644 --- a/documentation/jetty-documentation/pom.xml +++ b/documentation/jetty-documentation/pom.xml @@ -46,13 +46,13 @@ ${project.basedir} ${settings.localRepository} + ../programming-guide/index.html http://www.eclipse.org/jetty/javadoc/${project.version} http://download.eclipse.org/jetty/stable-9/xref ${basedir}/.. https://github.com/eclipse/jetty.project/tree/master https://github.com/eclipse/jetty.project/tree/jetty-10.0.x-doc-refactor/jetty-documentation/src/main/asciidoc ../operations-guide/index.html - ../programming-guide/index.html ../gettingstarted-guide/index.html ../contribution-guide/index.html https://repo1.maven.org/maven2 diff --git a/documentation/jetty-documentation/src/main/asciidoc/config.adoc b/documentation/jetty-documentation/src/main/asciidoc/config.adoc index 5528584fd01c..430aa7f786da 100644 --- a/documentation/jetty-documentation/src/main/asciidoc/config.adoc +++ b/documentation/jetty-documentation/src/main/asciidoc/config.adoc @@ -23,6 +23,8 @@ :sectlinks: :sectanchors: +:source-highlighter: coderay + // Use fonts for admonitions. :icons: font diff --git a/documentation/jetty-documentation/src/main/asciidoc/old_docs/startup/chapter.adoc b/documentation/jetty-documentation/src/main/asciidoc/old_docs/startup/chapter.adoc index abb572a38943..16d6ec790744 100644 --- a/documentation/jetty-documentation/src/main/asciidoc/old_docs/startup/chapter.adoc +++ b/documentation/jetty-documentation/src/main/asciidoc/old_docs/startup/chapter.adoc @@ -14,6 +14,5 @@ [[startup]] == Starting Jetty -include::custom-modules.adoc[] include::startup-unix-service.adoc[] include::startup-windows-service.adoc[] diff --git a/documentation/jetty-documentation/src/main/asciidoc/old_docs/startup/custom-modules.adoc b/documentation/jetty-documentation/src/main/asciidoc/old_docs/startup/custom-modules.adoc deleted file mode 100644 index 4403e82d75cc..000000000000 --- a/documentation/jetty-documentation/src/main/asciidoc/old_docs/startup/custom-modules.adoc +++ /dev/null @@ -1,242 +0,0 @@ -// -// ======================================================================== -// Copyright (c) 1995-2021 Mort Bay Consulting Pty Ltd and others. -// -// This program and the accompanying materials are made available under the -// terms of the Eclipse Public License v. 2.0 which is available at -// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0 -// which is available at https://www.apache.org/licenses/LICENSE-2.0. -// -// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0 -// ======================================================================== -// - -[[custom-modules]] -=== Custom Modules - -In addition to the modules that come packaged with the Jetty distribution, users are able to create and define their own custom modules for use with their Jetty implementation. -Custom modules can be used for a number of reasons - they can extend features in Jetty, add new features, manage additional libraries available to the server...etc. - -At the heart of a Jetty module is the `{name}.mod` file itself. -A jetty `.mod` file defines the following: - -[NOTE] --- -It is important to note that when creating your own module, none of these sections are required - simply use those which are applicable to your implementation. --- - -Module Description - `[description]`:: -The description of the module. -This will be showing when viewing the `.mod` file itself or using the `--list-modules` command. -List of Dependent Modules - `[depend]`:: -All modules can declare that they depend on other modules with the `[depend]` section. -The list of dependencies is used to transitively resolve other modules that are deemed to be required based on the modules that you activate. -The order of modules defined in the graph of active modules is used to determine various execution order for configuration, such as Jetty IoC XML configurations, and to resolve conflicting property declarations. -Optional Modules - `[optional]`;; -Of note: there is a special section `[optional]` used to describe structurally dependent modules that are not technically required, but might be of use to your specific configuration. -List of Libraries - `[lib]`:: -Modules can optionally declare that they have libraries that they need to function properly. -The `[lib]` section declares a set of pathnames that follow the link:#base-vs-home-resolution[Jetty Base and Jetty Home path resolution rules]. -List of Jetty IoC XML Configurations - `[xml]`:: -A Module can optionally declare a list of Jetty IoC XML configurations used to wire up the functionality that this module defines. -The `[xml]` section declares a set of pathnames that follow the link:#base-vs-home-resolution[Jetty Base and Jetty Home path resolution rules]. -Ideally, all XML files are parameterized to accept properties to configure the various elements of the standard configuration. -Allowing for a simplified configuration of Jetty for the vast majority of deployments. -The execution order of the Jetty IoC XML configurations is determined by the graph of active module dependencies resolved via the `[depend]` sections. -If the default XML is not sufficient to satisfy your needs, you can override this XML by making your own in the `${jetty.base}/etc/` directory, with the same name. -The resolution steps for Jetty Base and Jetty Home will ensure that your copy from `${jetty.base}` will be picked up over the default one in `${jetty.home}`. -List of Module Tags - `[tags]`:: -For ease of sorting, modules can be assigned tags. -When using the `--list-modules` command, modules will be groups by the first tag that exists in this section. -Modules can also be listed specifically by these tags using `--list-modules=` on the command line. -Ini Variables - `[ini]`:: -The `[ini]` section is used to add or change server parameters at startup. -The `[ini]` section can also include a the path of a file or several files which should be made available to the _server_ only. -This is helpful when you want to control what jars are available to deployed webapps. -Jetty INI Template - `[ini-template]`:: -Each module can optionally declare a startup ini template that is used to insert/append/inject sample configuration elements into the `start.ini` or `start.d/*.ini` files when using the `--add-to-start=` command line argument in `start.jar`. -Commonly used to present some of the parameterized property options from the Jetty IoC XML configuration files also referenced in the same module. -Required Files and Directories - `[files]`:: -If the activation of a module requires some paths to exist, the `[files]` section defines them. -There are 2 modes of operation of the entries in this section. -Ensure Directory Exists;; -If you add a pathname that ends in `"/"` (slash), such as `"webapps/"`, then that directory will be created if it does not yet exist in `${jetty.base}/` (eg: `"webapps/"` will result in `${jetty.base}/webapps/` being created). -Download File;; -There is a special syntax to allow you to download a file into a specific location if it doesn't exist yet: `:`. -Currently, the `` must be a `http://` scheme URL. -The `` portion follows the link:#base-vs-home-resolution[Jetty Base and Jetty Home path resolution rules]. -Example: `http://repo.corp.com/maven/corp-security-policy-1.0.jar:lib/corp-security-policy.jar` -This will check for the existence of `lib/corp-security-policy.jar`, and if it doesn't exist, it will download the jar file from `http://repo.corp.com/maven/corp-security-policy-1.0.jar` -Licenses - `[license]`:: -If you are implementing a software/technology that has a license, it's text can be placed here. -When a user attempts to activate the module they will be asked if they accept the license agreement. -If a user does not accept the license agreement, the module will not be activated. -Additional Startup Commands - `[exec]`:: -The `[exec]` section is used to define additional parameters specific to the module. -These commands are added to the server startup. -JPMS Module-Path Definitions - `[jpms]`:: -The `[jpms]` section is used to add link:#startup-jpms[JPMS modules] to the module-path for startup when using the `--jpms` command. - -[[custom-module-properties]] -==== Module Properties - -Properties are used to parameterize: - -* XML files using the `` element -* Module files using the `${pname}` syntax - -Properties and System Properties may be set on the command line, in a ini file or in a `[ini]` section of a module using the following syntax. - -`name=value`;; -Set a property that can be expanded in XML files with the element. - -`name+=value`;; -Append value to an existing property value. - -`name+=,value`;; -Append value to an existing property value, using a comma separator if needed. - -`name?=value`;; -Set a property only if it is not already set. - -If any of the previous formats is preceded by `-D`, then a system property is set as well as a start property. - -[[custom-module-location]] -==== Location of Modules -Jetty comes with dozens of modules as part of the distribution package. -By default these are located in the `${JETTY_HOME}/modules` directory. -These modules should not be modified. -In the unlikely circumstance you need to make changes to a stock module, copy it to your `${JETTY_BASE}` in a `modules` directory. - -Custom modules should also be maintained separately as part of the `${JETTY_BASE}/modules` directory, though you can optionally place them in `${JETTY_HOME}/modules` for convenience if you have several `{$JETTY_BASE}` locations in your implementation. - -[[custom-module-examples]] -==== Creating Custom Modules -As shown above, there are several options that can be utilized when creating custom module files. -This may seem daunting, but the good news is that creating custom modules is actually quite easy. - -For example, here is a look at the `http.mod` file which defines parameters for enabling HTTP features for the server: - -[source, screen] ----- -include::{SRCDIR}/jetty-server/src/main/config/modules/http.mod[] ----- - -You'll notice that the `http.mod` file only includes a handful of the possible sections available - `[description]`, `[tags]`, `[depend]`, `[xml]`, and `[ini-template]`. -When configuring your own modules, you are free to pick and choose what you include. - -As an example, below is a module file that defines a custom XML and lib, and activates a number of additional modules. -A module like this could be used to enable a set of standard modules and resources for a new JETTY_BASE without having to define them all manually. - -[source, screen] ----- -[description] -Enables the standard set of modules and resources for ACME Corp servers. - -[tags] -core - -[depend] -server -client -http -http2 -jsp -console-capture -requestlog -stats -gzip -deploy -jmx - -[files] -basehome:modules/acme/acme.xml|etc/acme.xml - -[lib] -lib/acme/ACMECustom.jar ----- - -Activating this module will activate all the dependent modules, create any required directories and copy in any required files: - -[source,screen] ----- -[my-base]$ java -jar /path/to/jetty-home/start.jar --add-to-start=acme - -ALERT: There are enabled module(s) with licenses. -The following 1 module(s): - + contains software not provided by the Eclipse Foundation! - + contains software not covered by the Eclipse Public License! - + has not been audited for compliance with its license - - Module: alpn-impl/alpn-8 - + ALPN is a hosted at github under the GPL v2 with ClassPath Exception. - + ALPN replaces/modifies OpenJDK classes in the sun.security.ssl package. - + http://github.com/jetty-project/jetty-alpn - + http://openjdk.java.net/legal/gplv2+ce.html - -Proceed (y/N)? y -INFO : webapp transitively enabled, ini template available with --add-to-start=webapp -INFO : server transitively enabled, ini template available with --add-to-start=server -INFO : requestlog transitively enabled, ini template available with --add-to-start=requestlog -INFO : alpn transitively enabled, ini template available with --add-to-start=alpn -INFO : jsp transitively enabled -INFO : servlet transitively enabled -INFO : alpn-impl/alpn-8 dynamic dependency of alpn -INFO : annotations transitively enabled -INFO : gzip transitively enabled, ini template available with --add-to-start=gzip -INFO : ssl transitively enabled, ini template available with --add-to-start=ssl -INFO : plus transitively enabled -INFO : deploy transitively enabled, ini template available with --add-to-start=deploy -INFO : alpn-impl/alpn-1.8.0_92 dynamic dependency of alpn-impl/alpn-8 -INFO : security transitively enabled -INFO : jmx transitively enabled -INFO : apache-jsp transitively enabled -INFO : stats transitively enabled, ini template available with --add-to-start=stats -INFO : acme initialized in ${jetty.base}/start.d/acme.ini -INFO : jndi transitively enabled -INFO : console-capture transitively enabled, ini template available with --add-to-start=console-capture -INFO : client transitively enabled -INFO : http transitively enabled, ini template available with --add-to-start=http -INFO : http2 transitively enabled, ini template available with --add-to-start=http2 -MKDIR : ${jetty.base}/logs -MKDIR : ${jetty.base}/lib -MKDIR : ${jetty.base}/lib/alpn -MKDIR : ${jetty.base}/etc -COPY : ${jetty.home}/modules/ssl/keystore to ${jetty.base}/etc/keystore -MKDIR : ${jetty.base}/webapps -DOWNLD: https://repo1.maven.org/maven2/org/mortbay/jetty/alpn/alpn-boot/8.1.8.v20160420/alpn-boot-8.1.8.v20160420.jar to ${jetty.base}/lib/alpn/alpn-boot-8.1.8.v20160420.jar -COPY : ${jetty.home}/modules/acme/acme.xml to ${jetty.base}/etc/acme.xml -INFO : Base directory was modified ----- - -==== Dependencies -When dependent modules are enabled, they are done so *transitively* by default. -This means that any `ini` files for dependent modules are not created in the `${JETTY_BASE}/start.d` directory (or added to `${JETTY_BASE}/start.ini`) and are as such not configurable. - -For Jetty to create/add the `ini-template` parameters to `start.d` or `start.ini` the associated module must be enabled explicitly. - -For example, if I activate the `http` module, it will be enabled, and the `server` module will be enabled transitively: - -[source,screen] ----- -[my-base]$ java -jar /path/to/jetty-home/start.jar --add-to-start=http -INFO : server transitively enabled, ini template available with --add-to-start=server -INFO : http initialized in ${jetty.base}/start.d/http.ini -INFO : Base directory was modified ----- - -You'll notice that Jetty informs you of what modules were enabled, and where there associated ini files are located (when applicable). -It also tells the user what command they would need to run to enable any missing or desired ini files for the selected modules, in this case `--add-to-start=server`. - -[source,screen] ----- -[my-base]$ java -jar /path/to/jetty-home/start.jar --add-to-start=server -INFO : server initialized in ${jetty.base}/start.d/server.ini -INFO : Base directory was modified ----- - -____ -[NOTE] -It is important to keep in mind that when activating a dependency, Jetty does not just go one layer down. -If a dependent module also has dependencies they too will be enabled. -____ diff --git a/documentation/jetty-documentation/src/main/asciidoc/operations-guide/architecture/architecture.adoc b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/architecture/architecture.adoc index 9a5e2ada087e..422e736fba53 100644 --- a/documentation/jetty-documentation/src/main/asciidoc/operations-guide/architecture/architecture.adoc +++ b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/architecture/architecture.adoc @@ -14,6 +14,41 @@ [[og-arch]] === Architecture Overview +[[og-arch-concepts]] +==== Main Concepts + +Jetty is an HTTP server and Servlet Container, and supports deployments of web applications. + +The Jetty _server_ listens on one or more network ports using one or more __connector__s. + +Clients send HTTP requests for specific URIs, such as `+https://host/store/cart+`. + +The HTTP requests arrive to the connectors through the network; the Jetty server processes the requests and, based on their URIs, forwards them to the appropriate web application. + +[plantuml] +---- +skinparam backgroundColor transparent +skinparam monochrome true +skinparam shadowing false +skinparam roundCorner 10 + +scale 1.25 + +cloud Internet as internet +rectangle "Jetty Server" as server +rectangle "HTTP/1.1 Connector" as http +rectangle "HTTP/2 Connector" as http2 +rectangle "WebApp "Store"" as store +rectangle "WebApp "Catalog"" as catalog + +internet -- http +internet -- http2 +http -- server +http2 -- server +server -- store +server -- catalog +---- + There are three main concepts on which the Jetty standalone server is based: * The xref:og-arch-modules[Jetty _module_ system], where Jetty modules provides Jetty features. diff --git a/documentation/jetty-documentation/src/main/asciidoc/operations-guide/deploy/chapter.adoc b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/deploy/chapter.adoc index 65a0ae11699a..7d1ee7cb155e 100644 --- a/documentation/jetty-documentation/src/main/asciidoc/operations-guide/deploy/chapter.adoc +++ b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/deploy/chapter.adoc @@ -12,7 +12,7 @@ // [[og-deploy]] -=== Customizing Web Application Deployment +=== Web Application Deployment Most of the times you want to be able to customize the deployment of your web applications, for example by changing the `contextPath`, or by adding JNDI entries, or by configuring virtual hosts, etc. diff --git a/documentation/jetty-documentation/src/main/asciidoc/operations-guide/index.adoc b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/index.adoc index f7c00e3b62bc..b18d235724e1 100644 --- a/documentation/jetty-documentation/src/main/asciidoc/operations-guide/index.adoc +++ b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/index.adoc @@ -29,7 +29,6 @@ include::modules/chapter.adoc[] include::deploy/chapter.adoc[] include::protocols/chapter.adoc[] include::keystore/chapter.adoc[] -include::xml/chapter.adoc[] include::sessions/chapter.adoc[] include::quickstart/chapter.adoc[] include::annotations/chapter.adoc[] @@ -39,3 +38,4 @@ include::jaas/chapter.adoc[] include::jmx/chapter.adoc[] include::logging/chapter.adoc[] include::troubleshooting/chapter.adoc[] +include::xml/chapter.adoc[] diff --git a/documentation/jetty-documentation/src/main/asciidoc/operations-guide/keystore/chapter.adoc b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/keystore/chapter.adoc index 4d1b1a3657b5..ecbad068fd78 100644 --- a/documentation/jetty-documentation/src/main/asciidoc/operations-guide/keystore/chapter.adoc +++ b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/keystore/chapter.adoc @@ -12,7 +12,7 @@ // [[og-keystore]] -=== Configuring KeyStores +=== Configuring SSL/TLS KeyStores A KeyStore is a file on the file system that contains a private key and a public certificate, along with the certificate chain of the certificate authorities that issued the certificate. The private key, the public certificate and the certificate chain, but more generally the items present in a KeyStore, are typically referred to as "cryptographic material". diff --git a/documentation/jetty-documentation/src/main/asciidoc/operations-guide/modules/modules-custom.adoc b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/modules/modules-custom.adoc index 49b5325f0fce..d152d40426ae 100644 --- a/documentation/jetty-documentation/src/main/asciidoc/operations-guide/modules/modules-custom.adoc +++ b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/modules/modules-custom.adoc @@ -14,4 +14,223 @@ [[og-modules-custom]] ==== Custom Jetty Modules -TODO +In addition to the modules that come packaged with Jetty, you can create your own custom modules. + +NOTE: Make sure you have read the xref:og-modules[Jetty modules section] if you are not familiar with the concepts used in this section. + +Custom modules can be used for a number of reasons -- they can extend Jetty features, or add new features, or make additional libraries available to the server, etc. + +[[og-modules-custom-modify]] +===== Modifying an Existing Module + +The standard Jetty modules typically come with a number of configurable properties that can be easily customized without the need of writing a custom module. + +However, there may be cases where the customization is more complex than a simple property, and a custom module is necessary. + +For example, let's assume that you want to modify the order of the TLS cipher suites offered by the server when a client connects, using the link:https://www.openssl.org/docs/man1.1.0/man1/ciphers.html[OpenSSL cipher list format]. + +The Jetty class that handles the TLS configuration is `SslContextFactory`, and it already has a method `setCipherComparator(Comparator)`; however, you need to pass your custom implementation, which cannot be represented with a simple module property. + +The `SslContextFactory` component is already allocated by the standard Jetty module `ssl`, so what you need to do is the following: + +* Write the custom cipher `Comparator` and package it into a `+*.jar+` file (exercise left to reader). +* Write a custom Jetty XML file that calls the `SslContextFactory.setCipherComparator(Comparator)` method. +* Write a custom Jetty module file that depends on the standard `ssl` module. + +Start with the custom Jetty XML file, `$JETTY_BASE/etc/custom-ssl.xml`: + +.custom-ssl.xml +[source,xml] +---- + + + + + + + + + ECDH+AESGCM:ECDH+AES256:!aNULL:!MD5:!DSS:!ADH + + + + + + +---- +<1> Reference the existing `SslContextFactory` object created by the standard `ssl` module using its `id`. +<2> Call the `setCipherComparator()` method. +<3> Instantiate your custom cipher comparator. +<4> Pass to the constructor the ordering string in OpenSSL format, reading it from the module property `com.acme.ssl.cipherList`. + +CAUTION: The cipher list used above may not be secure -- it's just an example. + +Then write your custom module in the `$JETTY_BASE/modules/custom-ssl.mod` file: + +.custom-ssl.mod +[source,subs=verbatim] +---- +[description] +Customizes the standard ssl module. + +[tags] <1> +acme + +[depends] <2> +ssl + +[lib] <3> +lib/custom-cipher-comparator.jar + +[xml] <4> +etc/custom-ssl.xml + +[ini-template] <5> +## The cipher list in OpenSSL format. +# com.acme.ssl.cipherList=ECDH+AESGCM:ECDH+AES256:!aNULL:!MD5:!DSS:!ADH + +---- +<1> A tag that characterizes this custom module (see xref:og-modules-directive-tags[here]). +<2> This custom module depends on the standard `ssl` module. +<3> The custom cipher comparator class is compiled and packaged into this `+*.jar+` file. +<4> The custom Jetty XML file from above. +<5> The text that will be copied in the `custom-ssl.ini` file when this custom module will be enabled. + +Now you can xref:og-start-configure-enable[enable] the custom module with the following command issued from the `$JETTY_BASE` directory: + +---- +$ java -jar $JETTY_HOME/start.jar --add-modules=https,custom-ssl +---- + +The command above will produce the following `$JETTY_BASE` directory structure: + +[source,subs=normal] +---- +$JETTY_BASE +├── etc +│ └── custom-ssl.xml +├── modules +│ └── custom-ssl.mod +├── resources +│ └── jetty-logging.properties +└── start.d + ├── https.ini + └── ##custom-ssl.ini## +---- + +In the custom XML file you have used a custom module property to parametrize your custom cipher comparator. +This custom module property was then referenced in the `[ini-template]` section of the custom module file, so that when the custom module is enabled, a correspondent `custom-ssl.ini` file is created. + +In this way, updating the cipher list won't require you to update the XML file, but just the `custom-ssl.ini` file. + +[[og-modules-custom-create]] +===== Creating a New Module + +In the cases where you need to enhance Jetty with a custom functionality, you can write a new Jetty module that provides it. + +For example, let's assume that you need to add a custom auditing component that integrates with the auditing tools used by your company. +This custom auditing component should measure the HTTP request processing times and record them (how they are recorded is irrelevant here -- could be in a local log file or sent via network to an external service). + +The Jetty libraries already provide a way to measure HTTP request processing times via xref:{prog_guide}#pg-server-http-channel-events[`HttpChannel` events]: you write a custom component that implements the `HttpChannel.Listener` interface and add it as a bean to the `ServerConnector` that receives the HTTP requests. + +The steps to create a Jetty module are similar to those necessary to xref:og-modules-custom-modify[modify an existing module]: + +* Write the auditing component and package it into a `+*.jar+` file. +* Write a custom Jetty XML file that wires the auditing component to the `ServerConnector`. +* Write a custom Jetty module file that puts everything together. + +Let's start with the auditing component, sketched below: + +[source,java] +---- +package com.acme.audit; + +public class AuditingHttpChannelListener implements HttpChannel.Listener { + // Auditing is implemented here. +} +---- + +Let's assume that this class is compiled and packaged into `acme-audit.jar`, and that it has a dependency on `acme-util.jar`. +Both `+*.jar+` files will be put in the `$JETTY_BASE/lib/` directory. + +Next, let's write the Jetty XML file that wires the auditing component to the `ServerConnector`, `$JETTY_BASE/etc/acme-audit.xml`: + +.acme-audit.xml +[source,xml,subs=verbatim,options=nowrap] +---- + + + + + + + + + + + + + + + + +---- +<1> Reference the existing clear-text HTTP `ServerConnector` object created by the standard `http` module. +<2> Call `addBean()` on the `ServerConnector` to wire the auditing component. +<3> Instantiate the auditing component. +<4> Configure the auditing component with a property. + +The last step is to create the custom Jetty module file for the auditing component, `$JETTY_BASE/modules/acme-audit.mod`: + +.acme-audit.mod +---- +[description] +Adds auditing to the clear-text HTTP connector + +[tags] <1> +acme +audit + +[depends] <2> +http + +[libs] <3> +lib/acme-audit.jar +lib/acme-util.jar + +[xml] <4> +etc/acme-audit.xml + +[ini-template] <5> +## An auditing property. +# com.acme.audit.some.property=42 +---- +<1> The tags that characterize this custom module (see xref:og-modules-directive-tags[here]). +<2> This custom module depends on the standard `http` module. +<3> The `+*.jar+` files that contains the custom auditing component, and its dependencies. +<4> The custom Jetty XML file from above. +<5> The text that will be copied in the `acme-audit.ini` file when this custom module will be enabled. + +Now you can xref:og-start-configure-enable[enable] the custom auditing module with the following command issued from the `$JETTY_BASE` directory: + +---- +$ java -jar $JETTY_HOME/start.jar --add-modules=http,acme-audit +---- + +The command above will produce the following `$JETTY_BASE` directory structure: + +[source,subs=normal] +---- +$JETTY_BASE +├── etc +│ └── acme-audit.xml +├── modules +│ └── acme-audit.mod +├── resources +│ └── jetty-logging.properties +└── start.d + ├── http.ini + └── ##acme-audit.ini## +---- + +Enabling the custom auditing component will create the `$JETTY_BASE/start.d/acme-audit.ini` module configuration file that you can edit to configure auditing properties. diff --git a/documentation/jetty-documentation/src/main/asciidoc/operations-guide/modules/modules.adoc b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/modules/modules.adoc index cc5034e0d6ff..64f515622bf8 100644 --- a/documentation/jetty-documentation/src/main/asciidoc/operations-guide/modules/modules.adoc +++ b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/modules/modules.adoc @@ -131,6 +131,7 @@ This is useful to append a value to properties that accept a comma separated lis jetty.webapp.addServerClasses+=,com.acme ---- + +// TODO: check what happens if the property is empty and +=,value is done: is the comma stripped? If so add a sentence about this. ?=:: Sets the property value only if it is not already set. This is useful to define default values, for example for "version" properties, where the "version" property can be explicitly configured to a newer version, but if it is not explicitly configured it will have a default version (see also xref:og-start-configure-custom-module[here]). diff --git a/documentation/jetty-documentation/src/main/asciidoc/operations-guide/protocols/chapter.adoc b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/protocols/chapter.adoc index 887808fb647c..3a99f3153f83 100644 --- a/documentation/jetty-documentation/src/main/asciidoc/operations-guide/protocols/chapter.adoc +++ b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/protocols/chapter.adoc @@ -12,7 +12,7 @@ // [[og-protocols]] -=== Configuring Eclipse Jetty Connectors and Protocols +=== Jetty Connectors and Protocols Connectors are the network components through which Jetty accepts incoming network connections. diff --git a/documentation/jetty-documentation/src/main/asciidoc/operations-guide/protocols/protocols-http.adoc b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/protocols/protocols-http.adoc index 1c713e9d7709..7113bfc84c17 100644 --- a/documentation/jetty-documentation/src/main/asciidoc/operations-guide/protocols/protocols-http.adoc +++ b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/protocols/protocols-http.adoc @@ -12,7 +12,7 @@ // [[og-protocols-http]] -==== Configuring Clear-Text HTTP/1.1 +==== Clear-Text HTTP/1.1 Clear text HTTP/1.1 is enabled with the `http` Jetty module with the following command (issued from within the `$JETTY_BASE` directory): diff --git a/documentation/jetty-documentation/src/main/asciidoc/operations-guide/protocols/protocols-http2c.adoc b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/protocols/protocols-http2c.adoc index 9f30ee051c3b..72ee3404a869 100644 --- a/documentation/jetty-documentation/src/main/asciidoc/operations-guide/protocols/protocols-http2c.adoc +++ b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/protocols/protocols-http2c.adoc @@ -12,7 +12,7 @@ // [[og-protocols-http2c]] -==== Configuring Clear-Text HTTP/2 +==== Clear-Text HTTP/2 When you enable clear-text HTTP/2 you typically want to enable also clear-text HTTP/1.1, for backwards compatibility reasons and to allow clients to link:https://tools.ietf.org/html/rfc7540#section-3.2[upgrade] from HTTP/1.1 to HTTP/2. diff --git a/documentation/jetty-documentation/src/main/asciidoc/operations-guide/protocols/protocols-http2s.adoc b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/protocols/protocols-http2s.adoc index e3e728f838a1..e4fbc50ddab7 100644 --- a/documentation/jetty-documentation/src/main/asciidoc/operations-guide/protocols/protocols-http2s.adoc +++ b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/protocols/protocols-http2s.adoc @@ -12,7 +12,7 @@ // [[og-protocols-http2s]] -==== Configuring Secure HTTP/2 +==== Secure HTTP/2 When you enable secure HTTP/2 you typically want to enable also secure HTTP/1.1, for backwards compatibility reasons: in this way, old browsers or other clients that do not support HTTP/2 will be able to connect to your server. diff --git a/documentation/jetty-documentation/src/main/asciidoc/operations-guide/protocols/protocols-https.adoc b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/protocols/protocols-https.adoc index e4a08992be25..8f40efe695e6 100644 --- a/documentation/jetty-documentation/src/main/asciidoc/operations-guide/protocols/protocols-https.adoc +++ b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/protocols/protocols-https.adoc @@ -12,7 +12,7 @@ // [[og-protocols-https]] -==== Configuring Secure HTTP/1.1 +==== Secure HTTP/1.1 Secure HTTP/1.1 is enabled with both the `ssl` and `https` Jetty modules with the following command (issued from within the `$JETTY_BASE` directory): diff --git a/documentation/jetty-documentation/src/main/asciidoc/operations-guide/protocols/protocols-proxy.adoc b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/protocols/protocols-proxy.adoc index b8a34166fc97..9208d3ec4551 100644 --- a/documentation/jetty-documentation/src/main/asciidoc/operations-guide/protocols/protocols-proxy.adoc +++ b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/protocols/protocols-proxy.adoc @@ -12,7 +12,7 @@ // [[og-protocols-proxy]] -==== Configuring Eclipse Jetty Behind a Load Balancer or Reverse Proxy +==== Jetty Behind a Load Balancer or Reverse Proxy You may need to configure one or more Jetty instances behind an _intermediary_, typically a load balancer such as link:https://haproxy.org[HAProxy], or a reverse proxy such as link:https://httpd.apache.org[Apache HTTP Server] or link:https://nginx.org[Nginx]. @@ -58,7 +58,7 @@ In both methods, web applications that call `HttpServletRequest.getRemoteAddr()` Likewise, `HttpServletRequest.getRemotePort()` will return the remote client IP port as specified by the client information sent by the intermediary, and `HttpServletRequest.isSecure()` will return whether the client made a secure request using the `https` scheme as specified by the client information sent by the intermediary. [[og-protocols-proxy-forwarded]] -===== Configuring Jetty for the Forwarded Header +===== Configuring the Forwarded Header The `Forwarded` HTTP header is added by the intermediary with information about the client and the client request, for example: @@ -92,7 +92,7 @@ With the `http-forwarded` Jetty module enabled, Jetty interprets the `Forwarded` For further information about configuring the `http-forwarded` Jetty module, see xref:og-module-http-forwarded[this section]. [[og-protocols-proxy-protocol]] -===== Configuring Jetty for the Proxy Protocol +===== Configuring the Proxy Protocol The link:https://www.haproxy.org/download/2.2/doc/proxy-protocol.txt[Proxy Protocol] is the _de facto_ standard, introduced by link:https://haproxy.org[HAProxy], to communicate client information to backend servers via the TCP connection, rather than via HTTP headers. @@ -174,7 +174,7 @@ include::jetty[setupArgs="--add-modules=https,test-keystore,proxy-protocol-ssl", Note how in the example above the list of protocols for the secure connector is first `proxy`, then `ssl` and then `http/1.1`. [[og-protocols-proxy-haproxy]] -===== Configuring HAProxy and Jetty for HTTP/1.1 and HTTP/2 +===== HAProxy and Jetty with HTTP/1.1 and HTTP/2 link:https://haproxy.org[HAProxy] is an open source solution that offers load balancing and proxying for TCP and HTTP based application, and can be used as a replacement for Apache or Nginx when these are used as reverse proxies. diff --git a/documentation/jetty-documentation/src/main/asciidoc/operations-guide/protocols/protocols-ssl.adoc b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/protocols/protocols-ssl.adoc index 62a02bc1ea19..5410bf40d045 100644 --- a/documentation/jetty-documentation/src/main/asciidoc/operations-guide/protocols/protocols-ssl.adoc +++ b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/protocols/protocols-ssl.adoc @@ -30,7 +30,7 @@ If you enable _both_ the `https` and the `http2` module, you will have a single TIP: Recall from the xref:og-modules[section about modules], that only modules that are explicitly enabled get their module configuration file (`+*.ini+`) saved in `$JETTY_BASE/start.d/`, and you want `$JETTY_BASE/start.d/ssl.ini` to be present so that you can configure the connector properties, the KeyStore properties and the TLS properties. [[og-protocols-ssl-customize]] -===== Customizing KeyStore and TLS Configuration +===== Customizing KeyStore and SSL/TLS Configuration Secure protocols have a slightly more complicated configuration since they require to configure a _KeyStore_. Refer to the xref:og-keystore[KeyStore section] for more information about how to create and manage a KeyStore. @@ -74,7 +74,7 @@ Refer to the link:{JDURL}/org/eclipse/jetty/util/ssl/SslContextFactory.html[SslC CAUTION: Use module properties whenever possible, and only resort to use a Jetty XML file for advanced configuration that you cannot do using module properties. [[og-protocols-ssl-customize-versions]] -====== Customizing TLS Protocol Versions +====== Customizing SSL/TLS Protocol Versions By default, the SSL protocols (SSL, SSLv2, SSLv3, etc.) are already excluded because they are vulnerable. To explicitly add the exclusion of TLSv1.0 and TLSv1.1 (that are also vulnerable -- which leaves only TLSv1.2 and TLSv1.3 available), you want to use this XML: @@ -100,7 +100,7 @@ To explicitly add the exclusion of TLSv1.0 and TLSv1.1 (that are also vulnerable ---- [[og-protocols-ssl-customize-ciphers]] -====== Customizing TLS Ciphers +====== Customizing SSL/TLS Ciphers You can precisely set the list of excluded ciphers, completely overriding Jetty's default, with this XML: @@ -160,7 +160,7 @@ $ java -jar $JETTY_HOME/start.jar --add-module=ssl-reload For more information about the configuration of the `ssl-reload` Jetty module, see xref:og-module-ssl-reload[this section]. [[og-protocols-ssl-conscrypt]] -===== Using Conscrypt as TLS Provider +===== Using Conscrypt as SSL/TLS Provider By default, the standard TLS provider that comes with the JDK is used. diff --git a/documentation/jetty-documentation/src/main/asciidoc/operations-guide/sessions/session-overview.adoc b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/sessions/session-overview.adoc index 83790e6f595a..9fa99bc774e0 100644 --- a/documentation/jetty-documentation/src/main/asciidoc/operations-guide/sessions/session-overview.adoc +++ b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/sessions/session-overview.adoc @@ -48,7 +48,7 @@ CachingSessionDataStore:: is an L2 cache of session data. A `SessionCache` can use a `CachingSessionDataStore` as its backing store. -More details on these concepts can be found in the link:{PROGGUIDE}/server/sessions/sessions[Programming Guide]. +More details on these concepts can be found in the xref:{prog_guide}#pg-server-session[Programming Guide]. [NOTE] ==== diff --git a/documentation/jetty-documentation/src/main/asciidoc/operations-guide/sessions/session-usecases.adoc b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/sessions/session-usecases.adoc index 5f530438c7b5..9b62d18f5d16 100644 --- a/documentation/jetty-documentation/src/main/asciidoc/operations-guide/sessions/session-usecases.adoc +++ b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/sessions/session-usecases.adoc @@ -22,7 +22,7 @@ If you wish to pare back support for sessions because you know your app doesn't * enable the xref:og-session-base[base sessions module] and xref:og-session-base[configure the scavenge interval] to 0 to prevent scavenging * enable the xref:og-session-cache-null[null session cache module] to prevent sessions being cached in memory -If you wish to do any further minimization, you should consult the link:{PROGGUIDE}[Programming Guide]. +If you wish to do any further minimization, you should consult the xref:{prog_guide}#pg-server-session[Programming Guide]. ===== Clustering with a Sticky Load Balancer diff --git a/documentation/jetty-documentation/src/main/asciidoc/operations-guide/start/chapter.adoc b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/start/chapter.adoc index ae47c535dfcc..2f7498024d82 100644 --- a/documentation/jetty-documentation/src/main/asciidoc/operations-guide/start/chapter.adoc +++ b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/start/chapter.adoc @@ -39,12 +39,18 @@ include::start-start.adoc[] include::start-jpms.adoc[] include::start-stop.adoc[] -==== Logging and Debugging +==== Start Mechanism Logging The steps performed by the Jetty start mechanism are logged by the `StartLog` class, that outputs directly, by default, to `System.err`. This is necessary to avoid that the Jetty start mechanism depend on logging libraries that may clash with those defined by Jetty logging modules, when Jetty is started in-VM. +[NOTE] +==== +This section is about the logging performed by the Jetty start mechanism _before_ it configures and starts Jetty. +See the xref:og-logging[logging section] for information about logging when Jetty starts. +==== + You can enable DEBUG level logging with the `--debug` command line option, for both the _tool_ and _start_ modes: ---- diff --git a/documentation/jetty-documentation/src/main/asciidoc/operations-guide/xml/chapter.adoc b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/xml/chapter.adoc index 9ce77fe09169..25f6fb3c842a 100644 --- a/documentation/jetty-documentation/src/main/asciidoc/operations-guide/xml/chapter.adoc +++ b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/xml/chapter.adoc @@ -14,6 +14,8 @@ [[og-xml]] === Jetty XML +// TODO: merge this small section into the syntax and maybe call it "Jetty XML Reference". + The Jetty XML format is a straightforward mapping of XML elements to Java APIs so that any object can be instantiated and getters, setters, and methods can be called. The Jetty XML format is very similar to that of frameworks like Spring or Plexus, although it predates all of them and it's typically more powerful as it can invoke any Java API. diff --git a/documentation/jetty-documentation/src/main/asciidoc/operations-guide/xml/xml-syntax.adoc b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/xml/xml-syntax.adoc index 93147c1bfb23..3958559955ba 100644 --- a/documentation/jetty-documentation/src/main/asciidoc/operations-guide/xml/xml-syntax.adoc +++ b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/xml/xml-syntax.adoc @@ -338,8 +338,7 @@ You must give a unique `id` attribute to the objects you want to reference. [[og-xml-syntax-property]] ===== `` -Element `` retrieves the value of the Jetty module property specified by the `name` attribute, and it is mostly used when creating xref:og-modules[custom Jetty modules] or when using xref:og-deploy-jetty[Jetty context XML files]. -// TODO: xref to the custom module section. +Element `` retrieves the value of the Jetty module property specified by the `name` attribute, and it is mostly used when creating xref:og-modules-custom[custom Jetty modules] or when using xref:og-deploy-jetty[Jetty context XML files]. The `deprecated` attribute allows you to specify a comma separated list of old, deprecated, property names for backward compatibility. diff --git a/documentation/jetty-documentation/src/main/asciidoc/programming-guide/arch-jmx.adoc b/documentation/jetty-documentation/src/main/asciidoc/programming-guide/arch-jmx.adoc index 5cbd22e59e43..a3df00599965 100644 --- a/documentation/jetty-documentation/src/main/asciidoc/programming-guide/arch-jmx.adoc +++ b/documentation/jetty-documentation/src/main/asciidoc/programming-guide/arch-jmx.adoc @@ -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: ---- -=== 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. diff --git a/documentation/jetty-documentation/src/main/asciidoc/programming-guide/arch.adoc b/documentation/jetty-documentation/src/main/asciidoc/programming-guide/arch.adoc index cade8ca903ad..beec25a94e4d 100644 --- a/documentation/jetty-documentation/src/main/asciidoc/programming-guide/arch.adoc +++ b/documentation/jetty-documentation/src/main/asciidoc/programming-guide/arch.adoc @@ -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[] diff --git a/documentation/jetty-documentation/src/main/asciidoc/programming-guide/client/client.adoc b/documentation/jetty-documentation/src/main/asciidoc/programming-guide/client/client.adoc index 8c2245470787..01137ce62446 100644 --- a/documentation/jetty-documentation/src/main/asciidoc/programming-guide/client/client.adoc +++ b/documentation/jetty-documentation/src/main/asciidoc/programming-guide/client/client.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[] diff --git a/documentation/jetty-documentation/src/main/asciidoc/programming-guide/client/http/client-http-api.adoc b/documentation/jetty-documentation/src/main/asciidoc/programming-guide/client/http/client-http-api.adoc index 8c367e845185..b355c362864d 100644 --- a/documentation/jetty-documentation/src/main/asciidoc/programming-guide/client/http/client-http-api.adoc +++ b/documentation/jetty-documentation/src/main/asciidoc/programming-guide/client/http/client-http-api.adoc @@ -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 diff --git a/documentation/jetty-documentation/src/main/asciidoc/programming-guide/client/http/client-http-authentication.adoc b/documentation/jetty-documentation/src/main/asciidoc/programming-guide/client/http/client-http-authentication.adoc index 548ab0889fd3..31ff197ba512 100644 --- a/documentation/jetty-documentation/src/main/asciidoc/programming-guide/client/http/client-http-authentication.adoc +++ b/documentation/jetty-documentation/src/main/asciidoc/programming-guide/client/http/client-http-authentication.adoc @@ -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 diff --git a/documentation/jetty-documentation/src/main/asciidoc/programming-guide/client/http/client-http-configuration.adoc b/documentation/jetty-documentation/src/main/asciidoc/programming-guide/client/http/client-http-configuration.adoc index 4314f5a8a6fe..21aa23e96829 100644 --- a/documentation/jetty-documentation/src/main/asciidoc/programming-guide/client/http/client-http-configuration.adoc +++ b/documentation/jetty-documentation/src/main/asciidoc/programming-guide/client/http/client-http-configuration.adoc @@ -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 diff --git a/documentation/jetty-documentation/src/main/asciidoc/programming-guide/client/http/client-http-cookie.adoc b/documentation/jetty-documentation/src/main/asciidoc/programming-guide/client/http/client-http-cookie.adoc index cbc41a9bd137..8f11ea5905f0 100644 --- a/documentation/jetty-documentation/src/main/asciidoc/programming-guide/client/http/client-http-cookie.adoc +++ b/documentation/jetty-documentation/src/main/asciidoc/programming-guide/client/http/client-http-cookie.adoc @@ -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 `;`. diff --git a/documentation/jetty-documentation/src/main/asciidoc/programming-guide/client/http/client-http-intro.adoc b/documentation/jetty-documentation/src/main/asciidoc/programming-guide/client/http/client-http-intro.adoc index ea3d1ecfe403..9f6614337b2f 100644 --- a/documentation/jetty-documentation/src/main/asciidoc/programming-guide/client/http/client-http-intro.adoc +++ b/documentation/jetty-documentation/src/main/asciidoc/programming-guide/client/http/client-http-intro.adoc @@ -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. diff --git a/documentation/jetty-documentation/src/main/asciidoc/programming-guide/client/http/client-http-proxy.adoc b/documentation/jetty-documentation/src/main/asciidoc/programming-guide/client/http/client-http-proxy.adoc index 77feb7907d61..ea146b18aaec 100644 --- a/documentation/jetty-documentation/src/main/asciidoc/programming-guide/client/http/client-http-proxy.adoc +++ b/documentation/jetty-documentation/src/main/asciidoc/programming-guide/client/http/client-http-proxy.adoc @@ -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]. diff --git a/documentation/jetty-documentation/src/main/asciidoc/programming-guide/client/http/client-http-transport.adoc b/documentation/jetty-documentation/src/main/asciidoc/programming-guide/client/http/client-http-transport.adoc index de6c430fbb80..505269065b47 100644 --- a/documentation/jetty-documentation/src/main/asciidoc/programming-guide/client/http/client-http-transport.adoc +++ b/documentation/jetty-documentation/src/main/asciidoc/programming-guide/client/http/client-http-transport.adoc @@ -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). diff --git a/documentation/jetty-documentation/src/main/asciidoc/programming-guide/client/http2/client-http2.adoc b/documentation/jetty-documentation/src/main/asciidoc/programming-guide/client/http2/client-http2.adoc index 0484aaa75ef5..f0e20e3afd50 100644 --- a/documentation/jetty-documentation/src/main/asciidoc/programming-guide/client/http2/client-http2.adoc +++ b/documentation/jetty-documentation/src/main/asciidoc/programming-guide/client/http2/client-http2.adoc @@ -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. diff --git a/documentation/jetty-documentation/src/main/asciidoc/programming-guide/client/websocket/client-websocket.adoc b/documentation/jetty-documentation/src/main/asciidoc/programming-guide/client/websocket/client-websocket.adoc index c4257bbbc7a9..96fe9e3e7874 100644 --- a/documentation/jetty-documentation/src/main/asciidoc/programming-guide/client/websocket/client-websocket.adoc +++ b/documentation/jetty-documentation/src/main/asciidoc/programming-guide/client/websocket/client-websocket.adoc @@ -12,6 +12,6 @@ // [[pg-client-websocket]] -=== WebSocket Client Libraries +=== WebSocket Client TODO diff --git a/documentation/jetty-documentation/src/main/asciidoc/programming-guide/index-docinfo.html b/documentation/jetty-documentation/src/main/asciidoc/programming-guide/index-docinfo.html new file mode 100644 index 000000000000..006245974c73 --- /dev/null +++ b/documentation/jetty-documentation/src/main/asciidoc/programming-guide/index-docinfo.html @@ -0,0 +1,3 @@ + + + diff --git a/documentation/jetty-documentation/src/main/asciidoc/programming-guide/index.adoc b/documentation/jetty-documentation/src/main/asciidoc/programming-guide/index.adoc index 27524e0262fa..7c28883bfc60 100644 --- a/documentation/jetty-documentation/src/main/asciidoc/programming-guide/index.adoc +++ b/documentation/jetty-documentation/src/main/asciidoc/programming-guide/index.adoc @@ -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[] diff --git a/documentation/jetty-documentation/src/main/asciidoc/programming-guide/server/http/server-http-application.adoc b/documentation/jetty-documentation/src/main/asciidoc/programming-guide/server/http/server-http-application.adoc index a9620bc6422a..b6b793332d63 100644 --- a/documentation/jetty-documentation/src/main/asciidoc/programming-guide/server/http/server-http-application.adoc +++ b/documentation/jetty-documentation/src/main/asciidoc/programming-guide/server/http/server-http-application.adoc @@ -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: diff --git a/documentation/jetty-documentation/src/main/asciidoc/programming-guide/server/http/server-http-connector.adoc b/documentation/jetty-documentation/src/main/asciidoc/programming-guide/server/http/server-http-connector.adoc index c6c62600147c..a736a9ddfd7f 100644 --- a/documentation/jetty-documentation/src/main/asciidoc/programming-guide/server/http/server-http-connector.adoc +++ b/documentation/jetty-documentation/src/main/asciidoc/programming-guide/server/http/server-http-connector.adoc @@ -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. diff --git a/documentation/jetty-documentation/src/main/asciidoc/programming-guide/server/http/server-http-handler-implement.adoc b/documentation/jetty-documentation/src/main/asciidoc/programming-guide/server/http/server-http-handler-implement.adoc index 1f8c091ab2b0..69cd850b961f 100644 --- a/documentation/jetty-documentation/src/main/asciidoc/programming-guide/server/http/server-http-handler-implement.adoc +++ b/documentation/jetty-documentation/src/main/asciidoc/programming-guide/server/http/server-http-handler-implement.adoc @@ -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: diff --git a/documentation/jetty-documentation/src/main/asciidoc/programming-guide/server/http/server-http-handler-use.adoc b/documentation/jetty-documentation/src/main/asciidoc/programming-guide/server/http/server-http-handler-use.adoc index 67abdf77123b..91661d07c8c7 100644 --- a/documentation/jetty-documentation/src/main/asciidoc/programming-guide/server/http/server-http-handler-use.adoc +++ b/documentation/jetty-documentation/src/main/asciidoc/programming-guide/server/http/server-http-handler-use.adoc @@ -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. diff --git a/documentation/jetty-documentation/src/main/asciidoc/programming-guide/server/http/server-http-handler.adoc b/documentation/jetty-documentation/src/main/asciidoc/programming-guide/server/http/server-http-handler.adoc index 54eff38ccef2..f001341d575e 100644 --- a/documentation/jetty-documentation/src/main/asciidoc/programming-guide/server/http/server-http-handler.adoc +++ b/documentation/jetty-documentation/src/main/asciidoc/programming-guide/server/http/server-http-handler.adoc @@ -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. diff --git a/documentation/jetty-documentation/src/main/asciidoc/programming-guide/server/http/server-http-security.adoc b/documentation/jetty-documentation/src/main/asciidoc/programming-guide/server/http/server-http-security.adoc index 301cc30dd7d1..bf6d4aa686be 100644 --- a/documentation/jetty-documentation/src/main/asciidoc/programming-guide/server/http/server-http-security.adoc +++ b/documentation/jetty-documentation/src/main/asciidoc/programming-guide/server/http/server-http-security.adoc @@ -12,7 +12,7 @@ // [[pg-server-http-security]] -==== Securing HTTP Server Applications +===== Securing HTTP Server Applications // TODO: ConstraintSecurityHandler and Authenticators and LoginServices TODO diff --git a/documentation/jetty-documentation/src/main/asciidoc/programming-guide/server/http2/server-http2.adoc b/documentation/jetty-documentation/src/main/asciidoc/programming-guide/server/http2/server-http2.adoc index 50faf07ca244..7a73aa8d82c9 100644 --- a/documentation/jetty-documentation/src/main/asciidoc/programming-guide/server/http2/server-http2.adoc +++ b/documentation/jetty-documentation/src/main/asciidoc/programming-guide/server/http2/server-http2.adoc @@ -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] diff --git a/documentation/jetty-documentation/src/main/asciidoc/programming-guide/server/sessions/session-architecture.adoc b/documentation/jetty-documentation/src/main/asciidoc/programming-guide/server/sessions/session-architecture.adoc index 394fbc2a5f52..8a8920474c7d 100644 --- a/documentation/jetty-documentation/src/main/asciidoc/programming-guide/server/sessions/session-architecture.adoc +++ b/documentation/jetty-documentation/src/main/asciidoc/programming-guide/server/sessions/session-architecture.adoc @@ -12,7 +12,6 @@ // [[pg-server-session-architecture]] - ==== Session Architecture Terminology:: diff --git a/documentation/jetty-documentation/src/main/asciidoc/programming-guide/server/sessions/session-sessioncache.adoc b/documentation/jetty-documentation/src/main/asciidoc/programming-guide/server/sessions/session-sessioncache.adoc index 6f047cf9488e..23bafa827fd2 100644 --- a/documentation/jetty-documentation/src/main/asciidoc/programming-guide/server/sessions/session-sessioncache.adoc +++ b/documentation/jetty-documentation/src/main/asciidoc/programming-guide/server/sessions/session-sessioncache.adoc @@ -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`. diff --git a/documentation/jetty-documentation/src/main/asciidoc/programming-guide/server/sessions/session-sessiondatastore-mongo.adoc b/documentation/jetty-documentation/src/main/asciidoc/programming-guide/server/sessions/session-sessiondatastore-mongo.adoc index 51a07c055b8d..ab3260edd3e4 100644 --- a/documentation/jetty-documentation/src/main/asciidoc/programming-guide/server/sessions/session-sessiondatastore-mongo.adoc +++ b/documentation/jetty-documentation/src/main/asciidoc/programming-guide/server/sessions/session-sessiondatastore-mongo.adoc @@ -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]. diff --git a/documentation/jetty-documentation/src/main/asciidoc/programming-guide/server/sessions/session-sessionhandler.adoc b/documentation/jetty-documentation/src/main/asciidoc/programming-guide/server/sessions/session-sessionhandler.adoc index 5bffcb3b924e..06e559b38ea2 100644 --- a/documentation/jetty-documentation/src/main/asciidoc/programming-guide/server/sessions/session-sessionhandler.adoc +++ b/documentation/jetty-documentation/src/main/asciidoc/programming-guide/server/sessions/session-sessionhandler.adoc @@ -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` `` 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 `` 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`: diff --git a/documentation/jetty-documentation/src/main/asciidoc/programming-guide/server/sessions/session-sessionidmgr.adoc b/documentation/jetty-documentation/src/main/asciidoc/programming-guide/server/sessions/session-sessionidmgr.adoc index 61cb2d377f39..a40a5f6cded1 100644 --- a/documentation/jetty-documentation/src/main/asciidoc/programming-guide/server/sessions/session-sessionidmgr.adoc +++ b/documentation/jetty-documentation/src/main/asciidoc/programming-guide/server/sessions/session-sessionidmgr.adoc @@ -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. diff --git a/documentation/jetty-documentation/src/main/asciidoc/programming-guide/server/sessions/sessions.adoc b/documentation/jetty-documentation/src/main/asciidoc/programming-guide/server/sessions/sessions.adoc index e7028264b8b7..2ec7ca017b8f 100644 --- a/documentation/jetty-documentation/src/main/asciidoc/programming-guide/server/sessions/sessions.adoc +++ b/documentation/jetty-documentation/src/main/asciidoc/programming-guide/server/sessions/sessions.adoc @@ -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. diff --git a/documentation/jetty-documentation/src/main/asciidoc/styles.css b/documentation/jetty-documentation/src/main/asciidoc/styles.css index c23f06fecf74..0f4d3804df67 100644 --- a/documentation/jetty-documentation/src/main/asciidoc/styles.css +++ b/documentation/jetty-documentation/src/main/asciidoc/styles.css @@ -11,6 +11,10 @@ * ======================================================================== */ +#header, #content, #footnotes, #footer { + max-width: 80em; +} + .listingblock > .title { font-style: normal; }