Updated plugin to redact the Jetty version.
This allows to generate the documentation for a version different than the POM's. Updated Asciidoctor attributes, removing the unused ones and converting them all to kebab-case (lower case separated by dash), as Asciidoctor requires them to be lowercase. Signed-off-by: Simone Bordet <simone.bordet@gmail.com>
This commit is contained in:
Simone Bordet
parent
8f80c59946
commit
f240d7ac42
|
|
@ -89,12 +89,13 @@ public class JettyIncludeExtension implements ExtensionRegistry
|
|||
{
|
||||
try
|
||||
{
|
||||
Path jettyDocsPath = Path.of((String)document.getAttribute("project.basedir"));
|
||||
// Document attributes are converted by Asciidoctor to lowercase.
|
||||
Path jettyDocsPath = Path.of((String)document.getAttribute("project-basedir"));
|
||||
Path jettyHome = jettyDocsPath.resolve("../../jetty-home/target/jetty-home").normalize();
|
||||
|
||||
JettyHomeTester jetty = JettyHomeTester.Builder.newInstance()
|
||||
.jettyHome(jettyHome)
|
||||
.mavenLocalRepository((String)document.getAttribute("maven.local.repo"))
|
||||
.mavenLocalRepository((String)document.getAttribute("maven-local-repo"))
|
||||
.build();
|
||||
|
||||
String setupModules = (String)attributes.get("setupModules");
|
||||
|
|
@ -125,7 +126,7 @@ public class JettyIncludeExtension implements ExtensionRegistry
|
|||
try (JettyHomeTester.Run run = jetty.start(args.split(" ")))
|
||||
{
|
||||
run.awaitFor(15, TimeUnit.SECONDS);
|
||||
String output = captureOutput(attributes, run);
|
||||
String output = captureOutput(document, attributes, run);
|
||||
reader.push_include(output, "jettyHome_run", target, 1, attributes);
|
||||
}
|
||||
}
|
||||
|
|
@ -136,13 +137,14 @@ public class JettyIncludeExtension implements ExtensionRegistry
|
|||
}
|
||||
}
|
||||
|
||||
private String captureOutput(Map<String, Object> attributes, JettyHomeTester.Run run)
|
||||
private String captureOutput(Document document, Map<String, Object> attributes, JettyHomeTester.Run run)
|
||||
{
|
||||
Stream<String> lines = run.getLogs().stream()
|
||||
.map(line -> redactPath(line, System.getProperty("java.home"), "/path/to/java.home"))
|
||||
.map(line -> redactPath(line, run.getConfig().getMavenLocalRepository(), "/path/to/maven.repository"))
|
||||
.map(line -> redactPath(line, run.getConfig().getJettyHome().toString(), "/path/to/jetty.home"))
|
||||
.map(line -> redactPath(line, run.getConfig().getJettyBase().toString(), "/path/to/jetty.base"));
|
||||
.map(line -> redact(line, System.getProperty("java.home"), "/path/to/java.home"))
|
||||
.map(line -> redact(line, run.getConfig().getMavenLocalRepository(), "/path/to/maven.repository"))
|
||||
.map(line -> redact(line, run.getConfig().getJettyHome().toString(), "/path/to/jetty.home"))
|
||||
.map(line -> redact(line, run.getConfig().getJettyBase().toString(), "/path/to/jetty.base"))
|
||||
.map(line -> redact(line, (String)document.getAttribute("project-version"), (String)document.getAttribute("version")));
|
||||
lines = replace(lines, (String)attributes.get("replace"));
|
||||
lines = delete(lines, (String)attributes.get("delete"));
|
||||
lines = denoteLineStart(lines);
|
||||
|
|
@ -151,9 +153,11 @@ public class JettyIncludeExtension implements ExtensionRegistry
|
|||
return lines.collect(Collectors.joining(System.lineSeparator()));
|
||||
}
|
||||
|
||||
private String redactPath(String line, String target, String replacement)
|
||||
private String redact(String line, String target, String replacement)
|
||||
{
|
||||
return line.replace(target, replacement);
|
||||
if (target != null && replacement != null)
|
||||
return line.replace(target, replacement);
|
||||
return line;
|
||||
}
|
||||
|
||||
private Stream<String> replace(Stream<String> lines, String replace)
|
||||
|
|
|
|||
|
|
@ -44,19 +44,13 @@
|
|||
<require>asciidoctor-diagram</require>
|
||||
</requires>
|
||||
<attributes>
|
||||
<project.basedir>${project.basedir}</project.basedir>
|
||||
<maven.local.repo>${settings.localRepository}</maven.local.repo>
|
||||
<prog_guide>../programming-guide/index.html</prog_guide>
|
||||
<JDURL>https://www.eclipse.org/jetty/javadoc/jetty-10</JDURL>
|
||||
<SRCDIR>${basedir}/..</SRCDIR>
|
||||
<GITBROWSEURL>https://github.com/eclipse/jetty.project/tree/master</GITBROWSEURL>
|
||||
<GITDOCURL>https://github.com/eclipse/jetty.project/tree/jetty-10.0.x-doc-refactor/jetty-documentation/src/main/asciidoc</GITDOCURL>
|
||||
<OPGUIDE>../operations-guide/index.html</OPGUIDE>
|
||||
<GSTARTGUIDE>../gettingstarted-guide/index.html</GSTARTGUIDE>
|
||||
<CONTRIBGUIDE>../contribution-guide/index.html</CONTRIBGUIDE>
|
||||
<MVNCENTRAL>https://repo1.maven.org/maven2</MVNCENTRAL>
|
||||
<VERSION>${project.version}</VERSION>
|
||||
<TIMESTAMP>${maven.build.timestamp}</TIMESTAMP>
|
||||
<project-basedir>${project.basedir}</project-basedir>
|
||||
<project-version>${project.version}</project-version>
|
||||
<maven-local-repo>${settings.localRepository}</maven-local-repo>
|
||||
<version>${project.version}</version>
|
||||
<prog-guide>../programming-guide/index.html</prog-guide>
|
||||
<op-guide>../operations-guide/index.html</op-guide>
|
||||
<javadoc-url>https://www.eclipse.org/jetty/javadoc/jetty-10</javadoc-url>
|
||||
</attributes>
|
||||
</configuration>
|
||||
<executions>
|
||||
|
|
|
|||
|
|
@ -54,7 +54,7 @@ Here's an example context xml file that calls this method:
|
|||
<Set name="configurationDiscovered">false</Set> <2>
|
||||
</Configure>
|
||||
----
|
||||
<1> Configures a link:{JDURL}/org/eclipse/jetty/webapp/WebAppContext.html[`WebAppContext`], which is the Jetty component that represents a standard Servlet web application.
|
||||
<1> Configures a link:{javadoc-url}/org/eclipse/jetty/webapp/WebAppContext.html[`WebAppContext`], which is the Jetty component that represents a standard Servlet web application.
|
||||
<2> Specifies that scanning should not take place.
|
||||
|
||||
However, despite `metadata-complete=true`, scanning of classes may _still_ occur because of http://docs.oracle.com/javaee/6/api/javax/servlet/ServletContainerInitializer.html[javax.servlet.ServletContainerInitializer]s.
|
||||
|
|
@ -85,7 +85,7 @@ Here's an example from a context xml file that includes any jar whose name start
|
|||
</Call>
|
||||
</Configure>
|
||||
----
|
||||
<1> Configures a link:{JDURL}/org/eclipse/jetty/webapp/WebAppContext.html[`WebAppContext`], which is the Jetty component that represents a standard Servlet web application.
|
||||
<1> Configures a link:{javadoc-url}/org/eclipse/jetty/webapp/WebAppContext.html[`WebAppContext`], which is the Jetty component that represents a standard Servlet web application.
|
||||
<2> Specifies a context attribute.
|
||||
<3> Specifies the name of the context attribute.
|
||||
<4> Specifies the value of the context attribute.
|
||||
|
|
@ -115,7 +115,7 @@ Here's an example of a context xml file that sets a pattern that matches any jar
|
|||
</Call>
|
||||
</Configure>
|
||||
----
|
||||
<1> Configures a link:{JDURL}/org/eclipse/jetty/webapp/WebAppContext.html[`WebAppContext`], which is the Jetty component that represents a standard Servlet web application.
|
||||
<1> Configures a link:{javadoc-url}/org/eclipse/jetty/webapp/WebAppContext.html[`WebAppContext`], which is the Jetty component that represents a standard Servlet web application.
|
||||
<2> Specifies a context attribute.
|
||||
<3> Specifies the name of the context attribute.
|
||||
<4> Specifies the value of the context attribute.
|
||||
|
|
@ -181,7 +181,7 @@ Here's an example of setting the context attribute in a context xml file:
|
|||
</Call>
|
||||
</Configure>
|
||||
----
|
||||
<1> Configures a link:{JDURL}/org/eclipse/jetty/webapp/WebAppContext.html[`WebAppContext`], which is the Jetty component that represents a standard Servlet web application.
|
||||
<1> Configures a link:{javadoc-url}/org/eclipse/jetty/webapp/WebAppContext.html[`WebAppContext`], which is the Jetty component that represents a standard Servlet web application.
|
||||
<2> Specifies a context attribute.
|
||||
<3> Specifies the name of the context attribute.
|
||||
<4> Specifies the value of the context attribute.
|
||||
|
|
@ -212,7 +212,7 @@ Here is an example context xml file that ensures the `com.example.PrioritySCI` w
|
|||
</Call>
|
||||
</Configure>
|
||||
----
|
||||
<1> Configures a link:{JDURL}/org/eclipse/jetty/webapp/WebAppContext.html[`WebAppContext`], which is the Jetty component that represents a standard Servlet web application.
|
||||
<1> Configures a link:{javadoc-url}/org/eclipse/jetty/webapp/WebAppContext.html[`WebAppContext`], which is the Jetty component that represents a standard Servlet web application.
|
||||
<2> Specifies a context attribute.
|
||||
<3> Specifies the name of the context attribute.
|
||||
<4> Specifies the value of the context attribute.
|
||||
|
|
|
|||
|
|
@ -33,7 +33,7 @@ A simple Jetty context XML file, for example named `wiki.xml` is the following:
|
|||
<Set name="war">/opt/myapps/myapp.war</Set> <3>
|
||||
</Configure>
|
||||
----
|
||||
<1> Configures a link:{JDURL}/org/eclipse/jetty/webapp/WebAppContext.html[`WebAppContext`], which is the Jetty component that represents a standard Servlet web application.
|
||||
<1> Configures a link:{javadoc-url}/org/eclipse/jetty/webapp/WebAppContext.html[`WebAppContext`], which is the Jetty component that represents a standard Servlet web application.
|
||||
<2> Specifies the web application `contextPath`, which may be different from the `+*.war+` file name.
|
||||
<3> Specifies the file system path of the `+*.war+` file.
|
||||
|
||||
|
|
|
|||
|
|
@ -23,7 +23,7 @@ By using virtual hosts, you will be able to have the first web application avail
|
|||
|
||||
Another typical case is when you want to use different subdomains for different web application, for example a project website is at `+http://project.org/+` and the project documentation is at `+http://docs.project.org+`.
|
||||
|
||||
Virtual hosts can be used with any context that is a subclass of link:{JDURL}/org/eclipse/jetty/server/handler/ContextHandler.html[ContextHandler].
|
||||
Virtual hosts can be used with any context that is a subclass of link:{javadoc-url}/org/eclipse/jetty/server/handler/ContextHandler.html[ContextHandler].
|
||||
|
||||
[[og-deploy-virtual-hosts-names]]
|
||||
===== Virtual Host Names
|
||||
|
|
@ -42,7 +42,7 @@ An IP address may be set as a virtual host to indicate that a web application sh
|
|||
|
||||
`@ConnectorName`::
|
||||
A Jetty `ServerConnector` name to indicate that a web application should handle requests received on the `ServerConnector` with that name, and therefore received on a specific IP port.
|
||||
A `ServerConnector` name can be set via link:{JDURL}/org/eclipse/jetty/server/AbstractConnector.html#setName(java.lang.String)[].
|
||||
A `ServerConnector` name can be set via link:{javadoc-url}/org/eclipse/jetty/server/AbstractConnector.html#setName(java.lang.String)[].
|
||||
|
||||
`www.√integral.com`::
|
||||
Non-ASCII and https://en.wikipedia.org/wiki/Internationalized_domain_name[IDN] domain names can be set as virtual hosts using https://en.wikipedia.org/wiki/Punycode[Puny Code] equivalents that may be obtained from a https://www.punycoder.com/[Punycode/IDN converters].
|
||||
|
|
|
|||
|
|
@ -157,15 +157,15 @@ Refer to the https://docs.oracle.com/javase/7/docs/api/javax/security/auth/login
|
|||
[[og-jaas-loginmodules]]
|
||||
==== Provided LoginModules
|
||||
|
||||
* link:{JDURL}/org/eclipse/jetty/jaas/spi/JDBCLoginModule.html[`org.eclipse.jetty.jaas.spi.JDBCLoginModule`]
|
||||
* link:{JDURL}/org/eclipse/jetty/jaas/spi/PropertyFileLoginModule.html[`org.eclipse.jetty.jaas.spi.PropertyFileLoginModule`]
|
||||
* link:{JDURL}/org/eclipse/jetty/jaas/spi/DataSourceLoginModule.html[`org.eclipse.jetty.jaas.spi.DataSourceLoginModule`]
|
||||
* link:{JDURL}/org/eclipse/jetty/jaas/spi/LdapLoginModule.html[`org.eclipse.jetty.jaas.ldap.LdapLoginModule`]
|
||||
* link:{javadoc-url}/org/eclipse/jetty/jaas/spi/JDBCLoginModule.html[`org.eclipse.jetty.jaas.spi.JDBCLoginModule`]
|
||||
* link:{javadoc-url}/org/eclipse/jetty/jaas/spi/PropertyFileLoginModule.html[`org.eclipse.jetty.jaas.spi.PropertyFileLoginModule`]
|
||||
* link:{javadoc-url}/org/eclipse/jetty/jaas/spi/DataSourceLoginModule.html[`org.eclipse.jetty.jaas.spi.DataSourceLoginModule`]
|
||||
* link:{javadoc-url}/org/eclipse/jetty/jaas/spi/LdapLoginModule.html[`org.eclipse.jetty.jaas.ldap.LdapLoginModule`]
|
||||
|
||||
____
|
||||
[NOTE]
|
||||
Passwords can be stored in clear text, obfuscated or checksummed.
|
||||
The class link:{JDURL}/org/eclipse/jetty/util/security/Password.html[`org.eclipse.jetty.util.security.Password`] should be used to generate all varieties of passwords,the output from which can be put in to property files or entered into database tables.
|
||||
The class link:{javadoc-url}/org/eclipse/jetty/util/security/Password.html[`org.eclipse.jetty.util.security.Password`] should be used to generate all varieties of passwords,the output from which can be put in to property files or entered into database tables.
|
||||
____
|
||||
|
||||
===== JDBCLoginModule
|
||||
|
|
|
|||
|
|
@ -245,7 +245,7 @@ The transaction manager is looked up by the application as `java:comp/UserTransa
|
|||
|
||||
Jetty does not ship with a JTA manager, but _does_ provide the infrastructure to plug in the JTA manager of your choice.
|
||||
|
||||
Use the link:{JDURL}/org/eclipse/jetty/plus/jndi/Transaction.html[org.eclipse.jetty.plus.jndi.Transaction] object in a link:#og-jndi-xml[Jetty XML file] to configure the JTA manager.
|
||||
Use the link:{javadoc-url}/org/eclipse/jetty/plus/jndi/Transaction.html[org.eclipse.jetty.plus.jndi.Transaction] object in a link:#og-jndi-xml[Jetty XML file] to configure the JTA manager.
|
||||
|
||||
The following example configures the http://www.atomikos.com/[Atomikos] transaction manager:
|
||||
|
||||
|
|
|
|||
|
|
@ -203,7 +203,7 @@ Here's an example of using a context xml file to add in a pattern to match files
|
|||
</Call>
|
||||
</Configure>
|
||||
----
|
||||
<1> Configures a link:{JDURL}/org/eclipse/jetty/webapp/WebAppContext.html[`WebAppContext`], which is the Jetty component that represents a standard Servlet web application.
|
||||
<1> Configures a link:{javadoc-url}/org/eclipse/jetty/webapp/WebAppContext.html[`WebAppContext`], which is the Jetty component that represents a standard Servlet web application.
|
||||
<2> Specifies a context attribute.
|
||||
<3> Specifies the name of the context attribute.
|
||||
<4> Adds the additional pattern `+.*/jsf-[^/]*\.jar$+` to those already existing.
|
||||
|
|
|
|||
|
|
@ -92,9 +92,9 @@ Among the configurable properties, the most relevant are:
|
|||
Configures the compliance to HTTP specifications.
|
||||
The value could be:
|
||||
|
||||
* One of the predefined link:{JDURL}/org/eclipse/jetty/http/HttpCompliance.html[`HttpCompliance`] constants, such as `RFC7230` or `RFC2616`.
|
||||
* One of the predefined link:{javadoc-url}/org/eclipse/jetty/http/HttpCompliance.html[`HttpCompliance`] constants, such as `RFC7230` or `RFC2616`.
|
||||
For example: `jetty.httpConfig.compliance=RFC2616`.
|
||||
* A comma-separated list of violations to allow or forbid, as specified by the link:{JDURL}/org/eclipse/jetty/http/HttpCompliance.html#from(java.lang.String)[`HttpCompliance.from(String)`] method.
|
||||
* A comma-separated list of violations to allow or forbid, as specified by the link:{javadoc-url}/org/eclipse/jetty/http/HttpCompliance.html#from(java.lang.String)[`HttpCompliance.from(String)`] method.
|
||||
For example, `jetty.httpConfig.compliance=RFC7230,MULTIPLE_CONTENT_LENGTHS` means that the HTTP compliance is that defined by `RFC7230`, but also allows the `HttpCompliance.Violation.MULTIPLE_CONTENT_LENGTHS`, so that requests that have multiple `Content-Length` headers are accepted (they would be rejected when using just `HttpCompliance.RFC7230`).
|
||||
+
|
||||
For more information about `HttpCompliance` see also xref:pg-server-compliance-http[this section].
|
||||
|
|
@ -103,9 +103,9 @@ For more information about `HttpCompliance` see also xref:pg-server-compliance-h
|
|||
Configures the compliance to URI specifications.
|
||||
The value could be:
|
||||
|
||||
* One of the predefined link:{JDURL}/org/eclipse/jetty/http/UriCompliance.html[`UriCompliance`] constants, such as `DEFAULT` or `RFC3986`.
|
||||
* One of the predefined link:{javadoc-url}/org/eclipse/jetty/http/UriCompliance.html[`UriCompliance`] constants, such as `DEFAULT` or `RFC3986`.
|
||||
For example: `jetty.httpConfig.compliance=RFC3986`.
|
||||
* A comma-separated list of violations to allow or forbid, as specified by the link:{JDURL}/org/eclipse/jetty/http/UriCompliance.html#from(java.lang.String)[`UriCompliance.from(String)`] method.
|
||||
* A comma-separated list of violations to allow or forbid, as specified by the link:{javadoc-url}/org/eclipse/jetty/http/UriCompliance.html#from(java.lang.String)[`UriCompliance.from(String)`] method.
|
||||
For example, `jetty.httpConfig.uriCompliance=RFC3986,-AMBIGUOUS_PATH_SEPARATOR` means that the URI compliance is that defined by `RFC3986`, but also does not allow the `UriCompliance.Violation.AMBIGUOUS_PATH_SEPARATOR`, so that requests that have URIs such as `/foo/bar%2Fbaz` (where `%2F` is the URL-encoded `/` character) are rejected (they would be accepted when using just `UriCompliance.RFC3986`).
|
||||
+
|
||||
For more information about `UriCompliance` see also xref:pg-server-compliance-uri[this section].
|
||||
|
|
@ -115,9 +115,9 @@ For more information about `UriCompliance` see also xref:pg-server-compliance-ur
|
|||
Configures the compliance to HTTP cookie specifications.
|
||||
The value could be:
|
||||
|
||||
* One of the predefined link:{JDURL}/org/eclipse/jetty/http/CookieCompliance.html[`CookieCompliance`] constants, such as `RFC6265`.
|
||||
* One of the predefined link:{javadoc-url}/org/eclipse/jetty/http/CookieCompliance.html[`CookieCompliance`] constants, such as `RFC6265`.
|
||||
For example: `jetty.httpConfig.compliance=RFC6265`.
|
||||
* A comma-separated list of violations to allow or forbid, as specified by the link:{JDURL}/org/eclipse/jetty/http/CookieCompliance.html#from(java.lang.String)[`CookieCompliance.from(String)`] method.
|
||||
* A comma-separated list of violations to allow or forbid, as specified by the link:{javadoc-url}/org/eclipse/jetty/http/CookieCompliance.html#from(java.lang.String)[`CookieCompliance.from(String)`] method.
|
||||
For example, `jetty.httpConfig.requestCookieCompliance=RFC6265,-RESERVED_NAMES_NOT_DOLLAR_PREFIXED` means that the cookie compliance is that defined by `RFC6265`, but also does not allow the `CookieCompliance.Violation.RESERVED_NAMES_NOT_DOLLAR_PREFIXED`, so that requests that have cookie headers such as `Cookie: $foo=bar` are rejected (they would be accepted when using just `CookieCompliance.RFC6265`).
|
||||
+
|
||||
For more information about `CookieCompliance` see also xref:pg-server-compliance-cookie[this section].
|
||||
|
|
|
|||
|
|
@ -131,7 +131,7 @@ In the cases where you need to enhance Jetty with a custom functionality, you ca
|
|||
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 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]:
|
||||
|
||||
|
|
|
|||
|
|
@ -69,7 +69,7 @@ You want to create the `$JETTY_BASE/etc/tls-config.xml` with the following templ
|
|||
|
||||
The `tls-config.xml` file references the `sslContextFactory` component (created by the `ssl` Jetty module) that configures the KeyStore and TLS parameters, so that you can now call its APIs via XML, and you will have full flexibility for any advanced configuration you want (see below for few examples).
|
||||
|
||||
Refer to the link:{JDURL}/org/eclipse/jetty/util/ssl/SslContextFactory.html[SslContextFactory javadocs] for the list of methods that you can call through the Jetty XML file.
|
||||
Refer to the link:{javadoc-url}/org/eclipse/jetty/util/ssl/SslContextFactory.html[SslContextFactory javadocs] for the list of methods that you can call through the Jetty XML file.
|
||||
|
||||
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.
|
||||
|
||||
|
|
|
|||
|
|
@ -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 xref:{prog_guide}#pg-server-session[Programming Guide].
|
||||
More details on these concepts can be found in the xref:{prog-guide}#pg-server-session[Programming Guide].
|
||||
|
||||
[NOTE]
|
||||
====
|
||||
|
|
|
|||
|
|
@ -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 xref:{prog_guide}#pg-server-session[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
|
||||
|
||||
|
|
|
|||
|
|
@ -19,9 +19,9 @@ Jetty libraries (both client and server) use Java NIO to handle I/O, so that at
|
|||
[[pg-arch-io-selector-manager]]
|
||||
==== Jetty I/O: `SelectorManager`
|
||||
|
||||
The core class of Jetty I/O is link:{JDURL}/org/eclipse/jetty/io/SelectorManager.html[`SelectorManager`].
|
||||
The core class of Jetty I/O is link:{javadoc-url}/org/eclipse/jetty/io/SelectorManager.html[`SelectorManager`].
|
||||
|
||||
`SelectorManager` manages internally a configurable number of link:{JDURL}/org/eclipse/jetty/io/ManagedSelector.html[`ManagedSelector`]s.
|
||||
`SelectorManager` manages internally a configurable number of link:{javadoc-url}/org/eclipse/jetty/io/ManagedSelector.html[`ManagedSelector`]s.
|
||||
Each `ManagedSelector` wraps an instance of `java.nio.channels.Selector` that in turn manages a number of `java.nio.channels.SocketChannel` instances.
|
||||
|
||||
NOTE: TODO: add image
|
||||
|
|
@ -48,7 +48,7 @@ include::{doc_code}/org/eclipse/jetty/docs/programming/SelectorManagerDocs.java[
|
|||
[[pg-arch-io-endpoint-connection]]
|
||||
==== Jetty I/O: `EndPoint` and `Connection`
|
||||
|
||||
``SocketChannel``s that are passed to `SelectorManager` are wrapped into two related components: an link:{JDURL}/org/eclipse/jetty/io/EndPoint.html[`EndPoint`] and a link:{JDURL}/org/eclipse/jetty/io/Connection.html[`Connection`].
|
||||
``SocketChannel``s that are passed to `SelectorManager` are wrapped into two related components: an link:{javadoc-url}/org/eclipse/jetty/io/EndPoint.html[`EndPoint`] and a link:{javadoc-url}/org/eclipse/jetty/io/Connection.html[`Connection`].
|
||||
|
||||
`EndPoint` is the Jetty abstraction for a `SocketChannel`: you can read bytes from an `EndPoint` via `EndPoint.fill(ByteBuffer)`, you can write bytes to an `EndPoint` via `EndPoint.flush(ByteBuffer...)` and `EndPoint.write(Callback, ByteBuffer...)`, you can close an `EndPoint` via `EndPoint.close()`, etc.
|
||||
|
||||
|
|
@ -60,7 +60,7 @@ Conversely, an HTTP/1.1 client-side `Connection` implementation is responsible t
|
|||
|
||||
The writing side for a specific protocol _may_ be implemented in the `Connection` but may also be implemented in other components, although eventually the bytes to be written will be written through the `EndPoint`.
|
||||
|
||||
While there is primarily just one implementation of `EndPoint`,link:{JDURL}/org/eclipse/jetty/io/SocketChannelEndPoint.html[`SocketChannelEndPoint`] (used both on the client-side and on the server-side), there are many implementations of `Connection`, typically two for each protocol (one for the client-side and one for the server-side).
|
||||
While there is primarily just one implementation of `EndPoint`,link:{javadoc-url}/org/eclipse/jetty/io/SocketChannelEndPoint.html[`SocketChannelEndPoint`] (used both on the client-side and on the server-side), there are many implementations of `Connection`, typically two for each protocol (one for the client-side and one for the server-side).
|
||||
|
||||
The `EndPoint` and `Connection` pairs can be chained, for example in case of encrypted communication using the TLS protocol.
|
||||
There is an `EndPoint` and `Connection` TLS pair where the `EndPoint` reads the encrypted bytes from the network and the `Connection` decrypts them; next in the chain there is an `EndPoint` and `Connection` pair where the `EndPoint` "reads" decrypted bytes (provided by the previous `Connection`) and the `Connection` deserializes them into specific protocol objects (for example HTTP/2 frame objects).
|
||||
|
|
@ -73,11 +73,11 @@ NOTE: TODO: add a section on `UpgradeFrom` and `UpgradeTo`?
|
|||
|
||||
`SelectorManager` is an abstract class because while it knows how to create concrete `EndPoint` instances, it does not know how to create protocol specific `Connection` instances.
|
||||
|
||||
Creating `Connection` instances is performed on the server-side by link:{JDURL}/org/eclipse/jetty/server/ConnectionFactory.html[`ConnectionFactory`]s and on the client-side by link:{JDURL}/org/eclipse/jetty/io/ClientConnectionFactory.html[`ClientConnectionFactory`]s
|
||||
Creating `Connection` instances is performed on the server-side by link:{javadoc-url}/org/eclipse/jetty/server/ConnectionFactory.html[`ConnectionFactory`]s and on the client-side by link:{javadoc-url}/org/eclipse/jetty/io/ClientConnectionFactory.html[`ClientConnectionFactory`]s
|
||||
|
||||
On the server-side, the component that aggregates a `SelectorManager` with a set of ``ConnectionFactory``s is link:{JDURL}/org/eclipse/jetty/server/ServerConnector.html[`ServerConnector`]s, see xref:pg-server-io-arch[].
|
||||
On the server-side, the component that aggregates a `SelectorManager` with a set of ``ConnectionFactory``s is link:{javadoc-url}/org/eclipse/jetty/server/ServerConnector.html[`ServerConnector`]s, see xref:pg-server-io-arch[].
|
||||
|
||||
On the client-side, the components that aggregates a `SelectorManager` with a set of ``ClientConnectionFactory``s are link:{JDURL}/org/eclipse/jetty/client/HttpClientTransport.html[`HttpClientTransport`] subclasses, see xref:pg-client-io-arch[].
|
||||
On the client-side, the components that aggregates a `SelectorManager` with a set of ``ClientConnectionFactory``s are link:{javadoc-url}/org/eclipse/jetty/client/HttpClientTransport.html[`HttpClientTransport`] subclasses, see xref:pg-client-io-arch[].
|
||||
|
||||
[[pg-arch-io-endpoint]]
|
||||
==== Jetty I/O: `EndPoint`
|
||||
|
|
|
|||
|
|
@ -27,9 +27,9 @@ There are conceptually two layers that compose the Jetty client libraries:
|
|||
==== Client Libraries Network Layer
|
||||
|
||||
The Jetty client libraries use the common I/O design described in xref:pg-arch-io[this section].
|
||||
The main client-side component is the link:{JDURL}/org/eclipse/jetty/io/ClientConnector.html[`ClientConnector`].
|
||||
The main client-side component is the link:{javadoc-url}/org/eclipse/jetty/io/ClientConnector.html[`ClientConnector`].
|
||||
|
||||
The `ClientConnector` primarily wraps the link:{JDURL}/org/eclipse/jetty/io/SelectorManager.html[`SelectorManager`] and aggregates other four components:
|
||||
The `ClientConnector` primarily wraps the link:{javadoc-url}/org/eclipse/jetty/io/SelectorManager.html[`SelectorManager`] and aggregates other four components:
|
||||
|
||||
* a thread pool (in form of an `java.util.concurrent.Executor`)
|
||||
* a scheduler (in form of `org.eclipse.jetty.util.thread.Scheduler`)
|
||||
|
|
@ -76,7 +76,7 @@ For generic Internet hosts (e.g. when you are implementing a web spider) you wan
|
|||
* `ClientConnector.connectTimeout`: the duration of time after which `ClientConnector` aborts a connection attempt to the server (defaults to `5` seconds).
|
||||
This time includes the DNS lookup time _and_ the TCP connect time.
|
||||
|
||||
Please refer to the `ClientConnector` link:{JDURL}/org/eclipse/jetty/io/ClientConnector.html[javadocs] for the complete list of configurable parameters.
|
||||
Please refer to the `ClientConnector` link:{javadoc-url}/org/eclipse/jetty/io/ClientConnector.html[javadocs] for the complete list of configurable parameters.
|
||||
|
||||
[[pg-client-io-arch-protocol]]
|
||||
==== Client Libraries Protocol Layer
|
||||
|
|
@ -89,7 +89,7 @@ On the client side, a `ClientConnectionFactory` implementation is the component
|
|||
|
||||
Applications use `ClientConnector.connect(SocketAddress, Map<String, Object>)` to establish a TCP connection to the server, and must tell `ClientConnector` how to create the `Connection` for that particular TCP connection, and how to notify back the application when the connection creation succeeds or fails.
|
||||
|
||||
This is done by passing a link:{JDURL}/org/eclipse/jetty/io/ClientConnectionFactory.html[`ClientConnectionFactory`] (that creates `Connection` instances) and a link:{JDURL}/org/eclipse/jetty/util/Promise.html[`Promise`] (that is notified of connection creation success or failure) in the context `Map` as follows:
|
||||
This is done by passing a link:{javadoc-url}/org/eclipse/jetty/io/ClientConnectionFactory.html[`ClientConnectionFactory`] (that creates `Connection` instances) and a link:{javadoc-url}/org/eclipse/jetty/util/Promise.html[`Promise`] (that is notified of connection creation success or failure) in the context `Map` as follows:
|
||||
|
||||
[source,java,indent=0]
|
||||
----
|
||||
|
|
|
|||
|
|
@ -133,7 +133,7 @@ include::../../{doc_code}/org/eclipse/jetty/docs/programming/client/http/HTTPCli
|
|||
|
||||
This makes Jetty HTTP client suitable for HTTP load testing because, for example, you can accurately time every step of the request/response conversation (thus knowing where the request/response time is really spent).
|
||||
|
||||
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.
|
||||
Have a look at the link:{javadoc-url}/org/eclipse/jetty/client/api/Request.Listener.html[`Request.Listener`] class to know about request events, and to the link:{javadoc-url}/org/eclipse/jetty/client/api/Response.Listener.html[`Response.Listener`] class to know about response events.
|
||||
|
||||
[[pg-client-http-content-request]]
|
||||
===== Request Content Handling
|
||||
|
|
|
|||
|
|
@ -15,7 +15,7 @@
|
|||
==== 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.
|
||||
Please refer to the `HttpClient` link:{javadoc-url}/org/eclipse/jetty/client/HttpClient.html[javadocs] for the complete list of configurable parameters.
|
||||
|
||||
The most common parameters are:
|
||||
|
||||
|
|
@ -61,7 +61,7 @@ You can enable certificate validation at the application level:
|
|||
include::../../{doc_code}/org/eclipse/jetty/docs/programming/client/http/HTTPClientDocs.java[tags=tlsAppValidation]
|
||||
----
|
||||
|
||||
Please refer to the `SslContextFactory.Client` link:{JDURL}/org/eclipse/jetty/util/ssl/SslContextFactory.Client.html[javadocs] for the complete list of configurable parameters.
|
||||
Please refer to the `SslContextFactory.Client` link:{javadoc-url}/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
|
||||
|
|
|
|||
|
|
@ -96,7 +96,7 @@ include::../../{doc_code}/org/eclipse/jetty/docs/programming/client/http2/HTTP2C
|
|||
----
|
||||
|
||||
The `Session.Listener` is notified of session events originated by the server such as receiving a `SETTINGS` frame from the server, or the server closing the connection, or the client timing out the connection due to idleness.
|
||||
Please refer to the `Session.Listener` link:{JDURL}/org/eclipse/jetty/http2/api/Session.Listener.html[javadocs] for the complete list of events.
|
||||
Please refer to the `Session.Listener` link:{javadoc-url}/org/eclipse/jetty/http2/api/Session.Listener.html[javadocs] for the complete list of events.
|
||||
|
||||
Once a `Session` has been established, the communication with the server happens by exchanging _frames_, as specified in the link:https://tools.ietf.org/html/rfc7540#section-4[HTTP/2 specification].
|
||||
|
||||
|
|
@ -116,7 +116,7 @@ include::../../{doc_code}/org/eclipse/jetty/docs/programming/client/http2/HTTP2C
|
|||
|
||||
Note how `Session.newStream(...)` takes a `Stream.Listener` parameter.
|
||||
This listener is notified of stream events originated by the server such as receiving `HEADERS` or `DATA` frames that are part of the response, discussed in more details in the xref:pg-client-http2-response[section below].
|
||||
Please refer to the `Stream.Listener` link:{JDURL}/org/eclipse/jetty/http2/api/Stream.Listener.html[javadocs] for the complete list of events.
|
||||
Please refer to the `Stream.Listener` link:{javadoc-url}/org/eclipse/jetty/http2/api/Stream.Listener.html[javadocs] for the complete list of events.
|
||||
|
||||
HTTP requests may have content, which is sent using the `Stream` APIs:
|
||||
|
||||
|
|
|
|||
|
|
@ -133,7 +133,7 @@ httpConnector::
|
|||
Optional.
|
||||
NOTE to configure a https connector, you will need to use xml configuration files instead, setting the `jettyXmls` parameter.
|
||||
This parameter can only be used to configure a standard http connector.
|
||||
If not specified, Jetty will create a link:{JDURL}/org/eclipse/jetty/server/ServerConnector.html[ServerConnector] instance listening on port 8080.
|
||||
If not specified, Jetty will create a link:{javadoc-url}/org/eclipse/jetty/server/ServerConnector.html[ServerConnector] instance listening on port 8080.
|
||||
You can change this default port number by using the system property `jetty.http.port` on the command line, for example, `mvn -Djetty.http.port=9999 jetty:run`.
|
||||
Alternatively, you can use this configuration element to set up the information for the ServerConnector.
|
||||
The following are the valid configuration sub-elements:
|
||||
|
|
@ -168,7 +168,7 @@ There are three other ways to configure the RequestLog:
|
|||
See link:#configuring-jetty-request-logs[Configuring Request Logs] for more information.
|
||||
server::
|
||||
Optional as of Jetty 9.3.1.
|
||||
This would configure an instance of the link:{GITBROWSEURL}/jetty-server/src/main/java/org/eclipse/jetty/server/Server.java[`org.eclipse.jetty.server.Server`] for the plugin to use, however it is usually _not_ necessary to configure this, as the plugin will automatically configure one for you.
|
||||
This would configure an instance of `org.eclipse.jetty.server.Server` for the plugin to use, however it is usually _not_ necessary to configure this, as the plugin will automatically configure one for you.
|
||||
In particular, if you use the `jettyXmls` element, then you generally _don't_ want to define this element, as you are probably using the `jettyXmls` file/s to configure up a Server with a special constructor argument, such as a custom threadpool.
|
||||
If you define both a `server` element and use a `jettyXmls` element which points to a config file that has a line like `<Configure id="Server" class="org.eclipse.jetty.server.Server">` then the the xml configuration will override what you configure for the `server` in the `pom.xml`.
|
||||
useProvidedScope::
|
||||
|
|
@ -338,7 +338,7 @@ Here is an example, which turns on scanning for changes every ten seconds, and s
|
|||
===== Configuration
|
||||
|
||||
webApp::
|
||||
This is an instance of link:{JDURL}/org/eclipse/jetty/maven/plugin/MavenWebAppContext.html[org.eclipse.jetty.maven.plugin.MavenWebAppContext], which is an extension to the class link:{JDURL}/org/eclipse/jetty/webapp/WebAppContext.hml[`org.eclipse.jetty.webapp.WebAppContext`].
|
||||
This is an instance of link:{javadoc-url}/org/eclipse/jetty/maven/plugin/MavenWebAppContext.html[org.eclipse.jetty.maven.plugin.MavenWebAppContext], which is an extension to the class link:{javadoc-url}/org/eclipse/jetty/webapp/WebAppContext.hml[`org.eclipse.jetty.webapp.WebAppContext`].
|
||||
You can use any of the setter methods on this object to configure your webapp.
|
||||
Here are a few of the most useful ones:
|
||||
+
|
||||
|
|
@ -565,7 +565,7 @@ This goal will generate output from jetty into the `target/jetty-start.out` file
|
|||
These configuration parameters are available:
|
||||
|
||||
webApp::
|
||||
This is an instance of link:{JDURL}/org/eclipse/jetty/maven/plugin/MavenWebAppContext.html[org.eclipse.jetty.maven.plugin.MavenWebAppContext], which is an extension to the class link:{JDURL}/org/eclipse/jetty/webapp/WebAppContext.hml[`org.eclipse.jetty.webapp.WebAppContext`].
|
||||
This is an instance of link:{javadoc-url}/org/eclipse/jetty/maven/plugin/MavenWebAppContext.html[org.eclipse.jetty.maven.plugin.MavenWebAppContext], which is an extension to the class link:{javadoc-url}/org/eclipse/jetty/webapp/WebAppContext.hml[`org.eclipse.jetty.webapp.WebAppContext`].
|
||||
You can use any of the setter methods on this object to configure your webapp.
|
||||
Here are a few of the most useful ones:
|
||||
+
|
||||
|
|
|
|||
|
|
@ -16,9 +16,9 @@
|
|||
|
||||
The standards for Cookies have varied greatly over time from a non-specified but de-facto standard (implemented by the first browsers), through link:https://tools.ietf.org/html/rfc2965[RFC 2965] and currently to link:https://tools.ietf.org/html/rfc6265[RFC 6265].
|
||||
|
||||
The link:{JDURL}/org/eclipse/jetty/http/CookieCompliance.Violation.html[CookieCompliance.Violation] enumeration defines the RFC requirements that may be optionally enforced by Jetty when parsing the `Cookie` HTTP header in requests and when generating the `Set-Cookie` HTTP header in responses.
|
||||
The link:{javadoc-url}/org/eclipse/jetty/http/CookieCompliance.Violation.html[CookieCompliance.Violation] enumeration defines the RFC requirements that may be optionally enforced by Jetty when parsing the `Cookie` HTTP header in requests and when generating the `Set-Cookie` HTTP header in responses.
|
||||
|
||||
These violations are then grouped into modes by the link:{JDURL}/org/eclipse/jetty/http/CookieCompliance.html[`CookieCompliance`] class, which also defines several named modes that support common deployed sets of violations, with the default being link:{JDURL}/org/eclipse/jetty/http/CookieCompliance.html#RFC6265[`CookieCompliance.RFC6265`].
|
||||
These violations are then grouped into modes by the link:{javadoc-url}/org/eclipse/jetty/http/CookieCompliance.html[`CookieCompliance`] class, which also defines several named modes that support common deployed sets of violations, with the default being link:{javadoc-url}/org/eclipse/jetty/http/CookieCompliance.html#RFC6265[`CookieCompliance.RFC6265`].
|
||||
|
||||
For example:
|
||||
|
||||
|
|
@ -27,7 +27,7 @@ For example:
|
|||
include::../../{doc_code}/org/eclipse/jetty/docs/programming/server/ServerDocs.java[tags=cookieCompliance]
|
||||
----
|
||||
|
||||
If you want to customize the violations that you want to allow, you can create your own mode using the link:{JDURL}/org/eclipse/jetty/http/CookieCompliance.html#from(java.lang.String)[`CookieCompliance.from(String)`] method:
|
||||
If you want to customize the violations that you want to allow, you can create your own mode using the link:{javadoc-url}/org/eclipse/jetty/http/CookieCompliance.html#from(java.lang.String)[`CookieCompliance.from(String)`] method:
|
||||
|
||||
[source,java,indent=0]
|
||||
----
|
||||
|
|
|
|||
|
|
@ -25,7 +25,7 @@ In 1995, when Jetty was first implemented, there were no RFC specification of HT
|
|||
In addition to these evolving requirements, some earlier version of Jetty did not completely or strictly implement the RFC at the time (for example, case-insensitive HTTP methods).
|
||||
Therefore, upgrading to a newer Jetty version may cause runtime behavior differences that may break your applications.
|
||||
|
||||
The link:{JDURL}/org/eclipse/jetty/http/HttpCompliance.Violation.html[`HttpCompliance.Violation`] enumeration defines the RFC requirements that may be optionally enforced by Jetty, to support legacy deployments. These possible violations are grouped into modes by the link:{JDURL}/org/eclipse/jetty/http/HttpCompliance.html[`HttpCompliance`] class, which also defines several named modes that support common deployed sets of violations (with the default being link:{JDURL}/org/eclipse/jetty/http/HttpCompliance.html#RFC7230[`HttpCompliance.RFC7230`]).
|
||||
The link:{javadoc-url}/org/eclipse/jetty/http/HttpCompliance.Violation.html[`HttpCompliance.Violation`] enumeration defines the RFC requirements that may be optionally enforced by Jetty, to support legacy deployments. These possible violations are grouped into modes by the link:{javadoc-url}/org/eclipse/jetty/http/HttpCompliance.html[`HttpCompliance`] class, which also defines several named modes that support common deployed sets of violations (with the default being link:{javadoc-url}/org/eclipse/jetty/http/HttpCompliance.html#RFC7230[`HttpCompliance.RFC7230`]).
|
||||
|
||||
For example:
|
||||
|
||||
|
|
@ -34,7 +34,7 @@ For example:
|
|||
include::../../{doc_code}/org/eclipse/jetty/docs/programming/server/ServerDocs.java[tags=httpCompliance]
|
||||
----
|
||||
|
||||
If you want to customize the violations that you want to allow, you can create your own mode using the link:{JDURL}/org/eclipse/jetty/http/HttpCompliance.html#from(java.lang.String)[`HttpCompliance.from(String)`] method:
|
||||
If you want to customize the violations that you want to allow, you can create your own mode using the link:{javadoc-url}/org/eclipse/jetty/http/HttpCompliance.html#from(java.lang.String)[`HttpCompliance.from(String)`] method:
|
||||
|
||||
[source,java,indent=0]
|
||||
----
|
||||
|
|
|
|||
|
|
@ -33,9 +33,9 @@ However, if the URI raw path is passed to some other APIs (for example, file sys
|
|||
|
||||
In order to avoid ambiguous URIs, Jetty imposes additional URI requirements in excess of what is required by link:https://datatracker.ietf.org/doc/html/rfc3986[RFC 3986] compliance.
|
||||
|
||||
These additional requirements may optionally be violated and are defined by the link:{JDURL}/org/eclipse/jetty/http/UriCompliance.Violation.html[`UriCompliance.Violation`] enumeration.
|
||||
These additional requirements may optionally be violated and are defined by the link:{javadoc-url}/org/eclipse/jetty/http/UriCompliance.Violation.html[`UriCompliance.Violation`] enumeration.
|
||||
|
||||
These violations are then grouped into modes by the link:{JDURL}/org/eclipse/jetty/http/UriCompliance.html[`UriCompliance`] class, which also defines several named modes that support common deployed sets of violations, with the default being link:{JDURL}/org/eclipse/jetty/http/UriCompliance.html#DEFAULT[`UriCompliance.DEFAULT`].
|
||||
These violations are then grouped into modes by the link:{javadoc-url}/org/eclipse/jetty/http/UriCompliance.html[`UriCompliance`] class, which also defines several named modes that support common deployed sets of violations, with the default being link:{javadoc-url}/org/eclipse/jetty/http/UriCompliance.html#DEFAULT[`UriCompliance.DEFAULT`].
|
||||
|
||||
For example:
|
||||
|
||||
|
|
@ -44,7 +44,7 @@ For example:
|
|||
include::../../{doc_code}/org/eclipse/jetty/docs/programming/server/ServerDocs.java[tags=uriCompliance]
|
||||
----
|
||||
|
||||
If you want to customize the violations that you want to allow, you can create your own mode using the link:{JDURL}/org/eclipse/jetty/http/UriCompliance.html#from(java.lang.String)[`UriCompliance.from(String)`] method:
|
||||
If you want to customize the violations that you want to allow, you can create your own mode using the link:{javadoc-url}/org/eclipse/jetty/http/UriCompliance.html#from(java.lang.String)[`UriCompliance.from(String)`] method:
|
||||
|
||||
[source,java,indent=0]
|
||||
----
|
||||
|
|
|
|||
|
|
@ -26,7 +26,7 @@ There are compliance modes provided for:
|
|||
|
||||
Compliance modes can be configured to allow violations from the RFC requirements, or in some cases to allow additional behaviors that Jetty has implemented in excess of the RFC (for example, to allow xref:pg-server-compliance-uri[ambiguous URIs]).
|
||||
|
||||
For example, the HTTP RFCs require that request HTTP methods are link:https://datatracker.ietf.org/doc/html/rfc7230#section-3.1.1[case sensitive], however Jetty can allow case-insensitive HTTP methods by including the link:{JDURL}/org/eclipse/jetty/http/HttpCompliance.Violation.html#CASE_INSENSITIVE_METHOD[`HttpCompliance.Violation.CASE_INSENSITIVE_METHOD`] in the link:{JDURL}/org/eclipse/jetty/http/HttpCompliance.html[`HttpCompliance`] set of allowed violations.
|
||||
For example, the HTTP RFCs require that request HTTP methods are link:https://datatracker.ietf.org/doc/html/rfc7230#section-3.1.1[case sensitive], however Jetty can allow case-insensitive HTTP methods by including the link:{javadoc-url}/org/eclipse/jetty/http/HttpCompliance.Violation.html#CASE_INSENSITIVE_METHOD[`HttpCompliance.Violation.CASE_INSENSITIVE_METHOD`] in the link:{javadoc-url}/org/eclipse/jetty/http/HttpCompliance.html[`HttpCompliance`] set of allowed violations.
|
||||
|
||||
include::server-compliance-http.adoc[]
|
||||
include::server-compliance-uri.adoc[]
|
||||
|
|
|
|||
|
|
@ -205,7 +205,7 @@ The Maven artifact coordinates are:
|
|||
|
||||
The Jetty Server Libraries provide rules for the most common usages, but you can write your own rules by extending the `org.eclipse.jetty.rewrite.handler.Rule` class.
|
||||
|
||||
Please refer to the `jetty-rewrite` module link:{JDURL}/org/eclipse/jetty/rewrite/handler/package-summary.html[javadocs] for the complete list of available rules.
|
||||
Please refer to the `jetty-rewrite` module link:{javadoc-url}/org/eclipse/jetty/rewrite/handler/package-summary.html[javadocs] for the complete list of available rules.
|
||||
|
||||
You typically want to configure `RewriteHandler` at the server level, although it is possible to configure it on a per-context basis.
|
||||
|
||||
|
|
|
|||
|
|
@ -144,7 +144,7 @@ Currently, the following events are available:
|
|||
* `responseEnd`
|
||||
* `complete`
|
||||
|
||||
Please refer to the `HttpChannel.Listener` link:{JDURL}/org/eclipse/jetty/server/HttpChannel.Listener.html[javadocs] for the complete list of events.
|
||||
Please refer to the `HttpChannel.Listener` link:{javadoc-url}/org/eclipse/jetty/server/HttpChannel.Listener.html[javadocs] for the complete list of events.
|
||||
|
||||
Server applications can register `HttpChannel.Listener` by adding them as xref:pg-arch-bean[beans] to the `Connector`:
|
||||
|
||||
|
|
|
|||
|
|
@ -57,7 +57,7 @@ Where server applications using the xref:pg-server-http[high-level server librar
|
|||
|
||||
The `ServerSessionListener` interface defines a number of methods that are invoked by the implementation upon the occurrence of HTTP/2 events, and that server applications can override to react to those events.
|
||||
|
||||
Please refer to the `ServerSessionListener`link:{JDURL}/org/eclipse/jetty/http2/api/server/ServerSessionListener.html[javadocs] for the complete list of events.
|
||||
Please refer to the `ServerSessionListener`link:{javadoc-url}/org/eclipse/jetty/http2/api/server/ServerSessionListener.html[javadocs] for the complete list of events.
|
||||
|
||||
The first event is the _accept_ event and happens when a client opens a new TCP connection to the server and the server accepts the connection.
|
||||
This is the first occasion where server applications have access to the HTTP/2 `Session` object:
|
||||
|
|
|
|||
|
|
@ -25,11 +25,11 @@ CachingSessionDataStore "1" *-down- "1" SessionDataStore
|
|||
SessionDataMap <|-- MemcachedSessionDataMap
|
||||
----
|
||||
|
||||
The link:{JDURL}/org/eclipse/jetty/server/session/CachingSessionDataStore.html[CachingSessionDataStore] is a special type of `SessionDataStore` that checks an L2 cache for `SessionData` before checking a delegate `SessionDataStore`.
|
||||
The link:{javadoc-url}/org/eclipse/jetty/server/session/CachingSessionDataStore.html[CachingSessionDataStore] is a special type of `SessionDataStore` that checks an L2 cache for `SessionData` before checking a delegate `SessionDataStore`.
|
||||
This can improve the performance of slow stores.
|
||||
|
||||
The L2 cache is an instance of a link:{JDURL}/org/eclipse/jetty/server/session/SessionDataMap.html[SessionDataMap].
|
||||
Jetty provides one implementation of this L2 cache based on `memcached`, link:{JDURL}/org/eclipse/jetty/memcached/session/MemcachedSessionDataMap.html[MemcachedSessionDataMap].
|
||||
The L2 cache is an instance of a link:{javadoc-url}/org/eclipse/jetty/server/session/SessionDataMap.html[SessionDataMap].
|
||||
Jetty provides one implementation of this L2 cache based on `memcached`, link:{javadoc-url}/org/eclipse/jetty/memcached/session/MemcachedSessionDataMap.html[MemcachedSessionDataMap].
|
||||
|
||||
====== Configuration
|
||||
|
||||
|
|
|
|||
|
|
@ -31,7 +31,7 @@ You are responsible for configuring both the `SessionCache` instance and its `Se
|
|||
More on ``SessionDataStore``s xref:pg-server-session-datastore[later], in this section we will concentrate on the `SessionCache` and `SessionCacheFactory`.
|
||||
|
||||
|
||||
The link:{JDURL}/org/eclipse/jetty/server/session/AbstractSessionCache.html[AbstractSessionCache] provides most of the behaviour of ``SessionCache``s.
|
||||
The link:{javadoc-url}/org/eclipse/jetty/server/session/AbstractSessionCache.html[AbstractSessionCache] provides most of the behaviour of ``SessionCache``s.
|
||||
If you are implementing a custom `SessionCache` we strongly recommend you extend this base class, as the Servlet Specification has many subtleties and extending the base class ensures that your implementation will take account of them.
|
||||
|
||||
Some of the important behaviours of ``SessionCache``s are:
|
||||
|
|
@ -68,40 +68,40 @@ To prevent his, enable this feature and the `SessionCache` will ensure that if a
|
|||
invalidateOnShutdown::
|
||||
Some applications want to ensure that all cached sessions are removed when the server shuts down.
|
||||
This option will ensure that all cached sessions are invalidated.
|
||||
The `AbstractSessionCache` does not implement this behaviour, a subclass must implement the link:{JDURL}/org/eclipse/jetty/server/session/SessionCache.html#shutdown()[SessionCache.shutdown()] method.
|
||||
The `AbstractSessionCache` does not implement this behaviour, a subclass must implement the link:{javadoc-url}/org/eclipse/jetty/server/session/SessionCache.html#shutdown()[SessionCache.shutdown()] method.
|
||||
|
||||
flushOnResponseCommit::
|
||||
This forces a "dirty" session to be written to the `SessionDataStore` just before a response is returned to the client, rather than waiting until the request is finished.
|
||||
A "dirty" session is one whose attributes have changed, or it has been freshly created.
|
||||
Using this option ensures that all subsequent requests - either to the same or a different node - will see the latest changes to the session.
|
||||
|
||||
Jetty provides two `SessionCache` implementations: the link:{JDURL}/org/eclipse/jetty/server/session/DefaultSessionCache.html[DefaultSessionCache] and the link:{JDURL}/org/eclipse/jetty/server/session/NullSessionCache.html[NullSessionCache].
|
||||
Jetty provides two `SessionCache` implementations: the link:{javadoc-url}/org/eclipse/jetty/server/session/DefaultSessionCache.html[DefaultSessionCache] and the link:{javadoc-url}/org/eclipse/jetty/server/session/NullSessionCache.html[NullSessionCache].
|
||||
|
||||
[[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`.
|
||||
The link:{javadoc-url}/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.
|
||||
|
||||
It implements the link:{JDURL}/org/eclipse/jetty/server/session/SessionCache.html#shutdown()[SessionCache.shutdown()] method.
|
||||
It implements the link:{javadoc-url}/org/eclipse/jetty/server/session/SessionCache.html#shutdown()[SessionCache.shutdown()] method.
|
||||
|
||||
It also provides some statistics on sessions, which are convenient to access either directly in code or remotely via jmx:
|
||||
|
||||
current sessions::
|
||||
The link:{JDURL}/org/eclipse/jetty/server/session/DefaultSessionCache.html#getSessionsCurrent()[DefaultSessionCache.getSessionsCurrent()] reports the number of sessions in the cache at the time of the method call.
|
||||
The link:{javadoc-url}/org/eclipse/jetty/server/session/DefaultSessionCache.html#getSessionsCurrent()[DefaultSessionCache.getSessionsCurrent()] reports the number of sessions in the cache at the time of the method call.
|
||||
|
||||
max sessions::
|
||||
The link:{JDURL}/org/eclipse/jetty/server/session/DefaultSessionCache.html#getSessionsCurrent()[DefaultSessionCache.getSessionsMax()] reports the highest number of sessions in the cache at the time of the method call.
|
||||
The link:{javadoc-url}/org/eclipse/jetty/server/session/DefaultSessionCache.html#getSessionsCurrent()[DefaultSessionCache.getSessionsMax()] reports the highest number of sessions in the cache at the time of the method call.
|
||||
|
||||
|
||||
total sessions::
|
||||
The link:{JDURL}/org/eclipse/jetty/server/session/DefaultSessionCache.html#getSessionsTotal()[DefaultSessionCache.getSessionsTotal()] reports the cumulative total of the number of sessions in the cache at the time of the method call.
|
||||
The link:{javadoc-url}/org/eclipse/jetty/server/session/DefaultSessionCache.html#getSessionsTotal()[DefaultSessionCache.getSessionsTotal()] reports the cumulative total of the number of sessions in the cache at the time of the method call.
|
||||
|
||||
reset::
|
||||
The link:{JDURL}/org/eclipse/jetty/server/session/DefaultSessionCache.html#resetStats()[DefaultSessionCache.resetStats()] zeros out the statistics counters.
|
||||
The link:{javadoc-url}/org/eclipse/jetty/server/session/DefaultSessionCache.html#resetStats()[DefaultSessionCache.resetStats()] zeros out the statistics counters.
|
||||
|
||||
If you create a link:{JDURL}/org/eclipse/jetty/server/session/DefaultSessionCacheFactory.html[DefaultSessionFactory] and register it as `Server` bean, a `SessionHandler` will be able to lazily create a `DefaultSessionCache`.
|
||||
If you create a link:{javadoc-url}/org/eclipse/jetty/server/session/DefaultSessionCacheFactory.html[DefaultSessionFactory] and register it as `Server` bean, a `SessionHandler` will be able to lazily create a `DefaultSessionCache`.
|
||||
The `DefaultSessionCacheFactory` has all of the same configuration setters as a `DefaultSessionCache`.
|
||||
Alternatively, if you only have a single `SessionHandler`, or you need to configure a `DefaultSessionCache` differently for every `SessionHandler`, then you could dispense with the `DefaultSessionCacheFactory` and simply instantiate, configure and pass in the `DefaultSessionCache` yourself.
|
||||
|
||||
|
|
@ -115,12 +115,12 @@ 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.
|
||||
The link:{javadoc-url}/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.
|
||||
|
||||
As no sessions are actually cached, of course functions like `invalidateOnShutdown` and all of the eviction strategies have no meaning for the `NullSessionCache`.
|
||||
|
||||
There is a link:{JDURL}/org/eclipse/jetty/server/session/NullSessionCacheFactory.html[NullSessionCacheFactory] which you can instantiate, configure and set as a `Server` bean to enable the `SessionHandler` to automatically create new ``NullCache``s as needed.
|
||||
There is a link:{javadoc-url}/org/eclipse/jetty/server/session/NullSessionCacheFactory.html[NullSessionCacheFactory] which you can instantiate, configure and set as a `Server` bean to enable the `SessionHandler` to automatically create new ``NullCache``s as needed.
|
||||
All of the same configuration options are available on the `NullSessionCacheFactory` as the `NullSessionCache` itself.
|
||||
Alternatively, if you only have a single `SessionHandler`, or you need to configure a `NullSessionCache` differently for every `SessionHandler`, then you could dispense with the `NullSessionCacheFactory` and simply instantiate, configure and pass in the `NullSessionCache` yourself.
|
||||
|
||||
|
|
@ -133,7 +133,7 @@ include::../../{doc_code}/org/eclipse/jetty/docs/programming/server/session/Sess
|
|||
[[pg-server-session-customcache]]
|
||||
===== Implementing a Custom SessionCache
|
||||
|
||||
As previously mentioned, we highly recommend that you extend the link:{JDURL}/org/eclipse/jetty/server/session/AbstractSessionCache.html[AbstractSessionCache].
|
||||
As previously mentioned, we highly recommend that you extend the link:{javadoc-url}/org/eclipse/jetty/server/session/AbstractSessionCache.html[AbstractSessionCache].
|
||||
|
||||
===== Heterogeneous Caching
|
||||
|
||||
|
|
|
|||
|
|
@ -47,7 +47,7 @@ Putting all of the above together as an example, a session with an id of `node0e
|
|||
|
||||
====== Configuration
|
||||
|
||||
You can configure either a link:{JDURL}/org/eclipse/jetty/server/session/FileSessionDataStore.html[FileSessionDataStore] individually, or a `FileSessionDataStoreFactory` if you want multiple ``SessionHandler``s to use ``FileSessionDataStore``s that are identically configured.
|
||||
You can configure either a link:{javadoc-url}/org/eclipse/jetty/server/session/FileSessionDataStore.html[FileSessionDataStore] individually, or a `FileSessionDataStoreFactory` if you want multiple ``SessionHandler``s to use ``FileSessionDataStore``s that are identically configured.
|
||||
The configuration methods are:
|
||||
|
||||
storeDir::
|
||||
|
|
|
|||
|
|
@ -56,7 +56,7 @@ Many databases use different keywords for the `long`, `blob` and `varchar` types
|
|||
|
||||
====== Configuration
|
||||
|
||||
The link:{JDURL}/org/eclipse/jetty/server/session/JDBCSessionDataStore.html[JDBCSessionDataStore] and corresponding link:{JDURL}/org/eclipse/jetty/server/session/JDBCSessionDataStoreFactory.html[JDBCSessionDataStoreFactory] supports the following configuration:
|
||||
The link:{javadoc-url}/org/eclipse/jetty/server/session/JDBCSessionDataStore.html[JDBCSessionDataStore] and corresponding link:{javadoc-url}/org/eclipse/jetty/server/session/JDBCSessionDataStoreFactory.html[JDBCSessionDataStoreFactory] supports the following configuration:
|
||||
|
||||
include::session-sessiondatastore.adoc[tag=common-datastore-config]
|
||||
|
||||
|
|
|
|||
|
|
@ -16,7 +16,7 @@
|
|||
|
||||
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].
|
||||
The best description for the document model for session information is found in the javadoc for the link:{javadoc-url}/org/eclipse/jetty/nosql/mongodb/MongoSessionDataStore.html[MongoSessionDataStore].
|
||||
In overview, it can be represented thus:
|
||||
|
||||
[plantuml]
|
||||
|
|
@ -68,7 +68,7 @@ An object that is updated every time a session is written out for a context.
|
|||
|
||||
====== Configuration
|
||||
|
||||
You can configure either a link:{JDURL}/org/eclipse/jetty/nosql/mongodb/MongoSessionDataStore.html[MongoSessionDataStore] individually, or a link:{JDURL}/org/eclipse/jetty/nosql/mongodb/MongoSessionDataStore.html[MongoSessionDataStoreFactory] if you want multiple ``SessionHandler``s to use ``MongoSessionDataStore``s that are identically configured.
|
||||
You can configure either a link:{javadoc-url}/org/eclipse/jetty/nosql/mongodb/MongoSessionDataStore.html[MongoSessionDataStore] individually, or a link:{javadoc-url}/org/eclipse/jetty/nosql/mongodb/MongoSessionDataStore.html[MongoSessionDataStoreFactory] if you want multiple ``SessionHandler``s to use ``MongoSessionDataStore``s that are identically configured.
|
||||
The configuration methods for the `MongoSessionDataStoreFactory` are:
|
||||
|
||||
include::session-sessiondatastore.adoc[tag=common-datastore-config]
|
||||
|
|
|
|||
|
|
@ -14,7 +14,7 @@
|
|||
[[pg-server-session-datastore]]
|
||||
==== The SessionDataStore
|
||||
|
||||
A link:{JDURL}/org/eclipse/jetty/server/session/SessionDataStore.html[SessionDataStore] mediates the storage, retrieval and deletion of `SessionData`.
|
||||
A link:{javadoc-url}/org/eclipse/jetty/server/session/SessionDataStore.html[SessionDataStore] mediates the storage, retrieval and deletion of `SessionData`.
|
||||
There is one `SessionDataStore` per `SessionCache`.
|
||||
The server libraries provide a number of alternative `SessionDataStore` implementations.
|
||||
|
||||
|
|
@ -43,7 +43,7 @@ AbstractSessionDataStore <|-- MongoSessionDataStore
|
|||
SessionDataStore <|-- CachingSessionDataStore
|
||||
----
|
||||
|
||||
The link:{JDURL}/org/eclipse/jetty/server/session/AbstractSessionDataStore.html[AbstractSessionDataStore] provides most of the behaviour common to ``SessionDataStore``s:
|
||||
The link:{javadoc-url}/org/eclipse/jetty/server/session/AbstractSessionDataStore.html[AbstractSessionDataStore] provides most of the behaviour common to ``SessionDataStore``s:
|
||||
|
||||
passivation::
|
||||
Supporting passivation means that session data is serialized.
|
||||
|
|
@ -73,5 +73,5 @@ Thus, we use the `gracePeriod` to provide a bit of leeway around the moment of e
|
|||
* infrequently the `AbstractSessionDataStore` searches for and summarily deletes sessions - from any context - that expired at least 10 ``gracePeriod``s ago
|
||||
//end::common-datastore-config[]
|
||||
|
||||
NOTE:: The trivial link:{JDURL}/org/eclipse/jetty/server/session/NullSessionDataStore.html[NullSessionDataStore] - which does not persist sessions - is the default used by the `SessionHandler`.
|
||||
NOTE:: The trivial link:{javadoc-url}/org/eclipse/jetty/server/session/NullSessionDataStore.html[NullSessionDataStore] - which does not persist sessions - is the default used by the `SessionHandler`.
|
||||
|
||||
|
|
|
|||
|
|
@ -20,7 +20,7 @@ It also calls the context-level session listeners at appropriate points in the s
|
|||
|
||||
===== 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.
|
||||
The majority of configuration for the link:{javadoc-url}/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:
|
||||
|
||||
checkingRemoteSessionIdEncoding::
|
||||
|
|
|
|||
|
|
@ -19,7 +19,7 @@ Its purpose is to generate fresh, unique session ids and to coordinate the re-us
|
|||
|
||||
The `SessionIdManager` is agnostic with respect to the type of clustering technology chosen.
|
||||
|
||||
Jetty provides a default implementation - the link:{JDURL}/org/eclipse/jetty/server/session/DefaultSessionIdManager.html[DefaultSessionIdManager] - which should meet the needs of most users.
|
||||
Jetty provides a default implementation - the link:{javadoc-url}/org/eclipse/jetty/server/session/DefaultSessionIdManager.html[DefaultSessionIdManager] - which should meet the needs of most users.
|
||||
|
||||
NOTE: If you do not explicitly configure a `SessionIdManager`, then when the `SessionHandler` starts, it will use an instance of the `DefaultSessionIdManager`.
|
||||
|
||||
|
|
@ -64,8 +64,8 @@ This restriction is important to support cross-context dispatch.
|
|||
[[pg-server-session-housekeeper]]
|
||||
===== The HouseKeeper
|
||||
|
||||
There is a maximum of one link:{JDURL}/org/eclipse/jetty/server/session/HouseKeeper.html[HouseKeeper] per `SessionIdManager`.
|
||||
Its purpose is to periodically poll the link:{JDURL}/org/eclipse/jetty/server/session/SessionHandler.html[SessionHandlers] to clean out expired sessions.
|
||||
There is a maximum of one link:{javadoc-url}/org/eclipse/jetty/server/session/HouseKeeper.html[HouseKeeper] per `SessionIdManager`.
|
||||
Its purpose is to periodically poll the link:{javadoc-url}/org/eclipse/jetty/server/session/SessionHandler.html[SessionHandlers] to clean out expired sessions.
|
||||
This operation is usually referred to as "scavenging" expired sessions.
|
||||
The scavenging interval is configured by the `setIntervalSec(long)` method.
|
||||
The default value is ``600``sec, ie ``10``mins.
|
||||
|
|
|
|||
|
|
@ -150,7 +150,7 @@ You want to do this as soon as you have access to the `Session` object, typicall
|
|||
include::{doc_code}/org/eclipse/jetty/docs/programming/WebSocketDocs.java[tags=sessionConfigure]
|
||||
----
|
||||
|
||||
Please refer to the `Session` link:{JDURL}/org/eclipse/jetty/websocket/api/Session.html[javadocs] for the complete list of configuration APIs.
|
||||
Please refer to the `Session` link:{javadoc-url}/org/eclipse/jetty/websocket/api/Session.html[javadocs] for the complete list of configuration APIs.
|
||||
|
||||
[[pg-websocket-session-send]]
|
||||
===== Sending Data
|
||||
|
|
|
|||
Loading…
Reference in New Issue