From f240d7ac42f5099ad230cdd4aa94c9b723feebcf Mon Sep 17 00:00:00 2001 From: Simone Bordet Date: Fri, 16 Jul 2021 12:49:46 +0200 Subject: [PATCH] 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 --- .../jetty/docs/JettyIncludeExtension.java | 24 ++++++++++------- documentation/jetty-documentation/pom.xml | 20 +++++--------- .../operations-guide/annotations/chapter.adoc | 10 +++---- .../operations-guide/deploy/deploy-jetty.adoc | 2 +- .../deploy/deploy-virtual-hosts.adoc | 4 +-- .../operations-guide/jaas/chapter.adoc | 10 +++---- .../operations-guide/jndi/chapter.adoc | 2 +- .../operations-guide/jsp/chapter.adoc | 2 +- .../modules/module-server.adoc | 12 ++++----- .../modules/modules-custom.adoc | 2 +- .../protocols/protocols-ssl.adoc | 2 +- .../sessions/session-overview.adoc | 2 +- .../sessions/session-usecases.adoc | 2 +- .../asciidoc/programming-guide/arch-io.adoc | 14 +++++----- .../client/client-io-arch.adoc | 8 +++--- .../client/http/client-http-api.adoc | 2 +- .../http/client-http-configuration.adoc | 4 +-- .../client/http2/client-http2.adoc | 4 +-- .../maven/jetty-maven-plugin.adoc | 8 +++--- .../compliance/server-compliance-cookie.adoc | 6 ++--- .../compliance/server-compliance-http.adoc | 4 +-- .../compliance/server-compliance-uri.adoc | 6 ++--- .../server/compliance/server-compliance.adoc | 2 +- .../server/http/server-http-handler-use.adoc | 2 +- .../server/http/server-http.adoc | 2 +- .../server/http2/server-http2.adoc | 2 +- .../session-cachingsessiondatastore.adoc | 6 ++--- .../server/sessions/session-sessioncache.adoc | 26 +++++++++---------- .../session-sessiondatastore-file.adoc | 2 +- .../session-sessiondatastore-jdbc.adoc | 2 +- .../session-sessiondatastore-mongo.adoc | 4 +-- .../sessions/session-sessiondatastore.adoc | 6 ++--- .../sessions/session-sessionhandler.adoc | 2 +- .../server/sessions/session-sessionidmgr.adoc | 6 ++--- .../asciidoc/programming-guide/websocket.adoc | 2 +- 35 files changed, 106 insertions(+), 108 deletions(-) diff --git a/documentation/jetty-asciidoctor-extensions/src/main/java/org/eclipse/jetty/docs/JettyIncludeExtension.java b/documentation/jetty-asciidoctor-extensions/src/main/java/org/eclipse/jetty/docs/JettyIncludeExtension.java index 83abc712ffa..f9ace37ef6d 100644 --- a/documentation/jetty-asciidoctor-extensions/src/main/java/org/eclipse/jetty/docs/JettyIncludeExtension.java +++ b/documentation/jetty-asciidoctor-extensions/src/main/java/org/eclipse/jetty/docs/JettyIncludeExtension.java @@ -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 attributes, JettyHomeTester.Run run) + private String captureOutput(Document document, Map attributes, JettyHomeTester.Run run) { Stream 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 replace(Stream lines, String replace) diff --git a/documentation/jetty-documentation/pom.xml b/documentation/jetty-documentation/pom.xml index 5db1bbdbd17..01d3db94aff 100644 --- a/documentation/jetty-documentation/pom.xml +++ b/documentation/jetty-documentation/pom.xml @@ -44,19 +44,13 @@ asciidoctor-diagram - ${project.basedir} - ${settings.localRepository} - ../programming-guide/index.html - https://www.eclipse.org/jetty/javadoc/jetty-10 - ${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 - ../gettingstarted-guide/index.html - ../contribution-guide/index.html - https://repo1.maven.org/maven2 - ${project.version} - ${maven.build.timestamp} + ${project.basedir} + ${project.version} + ${settings.localRepository} + ${project.version} + ../programming-guide/index.html + ../operations-guide/index.html + https://www.eclipse.org/jetty/javadoc/jetty-10 diff --git a/documentation/jetty-documentation/src/main/asciidoc/operations-guide/annotations/chapter.adoc b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/annotations/chapter.adoc index 2465663d5d3..d70de1157ba 100644 --- a/documentation/jetty-documentation/src/main/asciidoc/operations-guide/annotations/chapter.adoc +++ b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/annotations/chapter.adoc @@ -54,7 +54,7 @@ Here's an example context xml file that calls this method: false <2> ---- -<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 ---- -<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 ---- -<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: ---- -<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 ---- -<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. diff --git a/documentation/jetty-documentation/src/main/asciidoc/operations-guide/deploy/deploy-jetty.adoc b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/deploy/deploy-jetty.adoc index dc041112e96..0fb1cfab197 100644 --- a/documentation/jetty-documentation/src/main/asciidoc/operations-guide/deploy/deploy-jetty.adoc +++ b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/deploy/deploy-jetty.adoc @@ -33,7 +33,7 @@ A simple Jetty context XML file, for example named `wiki.xml` is the following: /opt/myapps/myapp.war <3> ---- -<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. diff --git a/documentation/jetty-documentation/src/main/asciidoc/operations-guide/deploy/deploy-virtual-hosts.adoc b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/deploy/deploy-virtual-hosts.adoc index c773ad36e11..7e63f26756a 100644 --- a/documentation/jetty-documentation/src/main/asciidoc/operations-guide/deploy/deploy-virtual-hosts.adoc +++ b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/deploy/deploy-virtual-hosts.adoc @@ -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]. diff --git a/documentation/jetty-documentation/src/main/asciidoc/operations-guide/jaas/chapter.adoc b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/jaas/chapter.adoc index 9359a6e02e1..d52127a1e05 100644 --- a/documentation/jetty-documentation/src/main/asciidoc/operations-guide/jaas/chapter.adoc +++ b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/jaas/chapter.adoc @@ -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 diff --git a/documentation/jetty-documentation/src/main/asciidoc/operations-guide/jndi/chapter.adoc b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/jndi/chapter.adoc index a927dc407ec..ceac95f4671 100644 --- a/documentation/jetty-documentation/src/main/asciidoc/operations-guide/jndi/chapter.adoc +++ b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/jndi/chapter.adoc @@ -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: diff --git a/documentation/jetty-documentation/src/main/asciidoc/operations-guide/jsp/chapter.adoc b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/jsp/chapter.adoc index 0e3a2efa6e0..103b93cd66a 100644 --- a/documentation/jetty-documentation/src/main/asciidoc/operations-guide/jsp/chapter.adoc +++ b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/jsp/chapter.adoc @@ -203,7 +203,7 @@ Here's an example of using a context xml file to add in a pattern to match files ---- -<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. diff --git a/documentation/jetty-documentation/src/main/asciidoc/operations-guide/modules/module-server.adoc b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/modules/module-server.adoc index f0ec2850aeb..bd98abde7b8 100644 --- a/documentation/jetty-documentation/src/main/asciidoc/operations-guide/modules/module-server.adoc +++ b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/modules/module-server.adoc @@ -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]. 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 6e208c99482..826570e42e1 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 @@ -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]: 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 8d959b8a0eb..dd0a7beab0e 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 @@ -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. 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 9fa99bc774e..f8fc7baa817 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 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] ==== 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 9b62d18f5d1..62f3b5f934f 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 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 diff --git a/documentation/jetty-documentation/src/main/asciidoc/programming-guide/arch-io.adoc b/documentation/jetty-documentation/src/main/asciidoc/programming-guide/arch-io.adoc index e6c0ec8e3db..5b2b8a6a995 100644 --- a/documentation/jetty-documentation/src/main/asciidoc/programming-guide/arch-io.adoc +++ b/documentation/jetty-documentation/src/main/asciidoc/programming-guide/arch-io.adoc @@ -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` diff --git a/documentation/jetty-documentation/src/main/asciidoc/programming-guide/client/client-io-arch.adoc b/documentation/jetty-documentation/src/main/asciidoc/programming-guide/client/client-io-arch.adoc index d9c3c3e02db..2d1c53642bf 100644 --- a/documentation/jetty-documentation/src/main/asciidoc/programming-guide/client/client-io-arch.adoc +++ b/documentation/jetty-documentation/src/main/asciidoc/programming-guide/client/client-io-arch.adoc @@ -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)` 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] ---- 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 b355c362864..53127b862cb 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 @@ -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 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 21aa23e9682..d45be4fe4ed 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 @@ -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 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 f0e20e3afd5..b3d569a37ac 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 @@ -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: diff --git a/documentation/jetty-documentation/src/main/asciidoc/programming-guide/maven/jetty-maven-plugin.adoc b/documentation/jetty-documentation/src/main/asciidoc/programming-guide/maven/jetty-maven-plugin.adoc index c9e9ebc5542..f5f03224619 100644 --- a/documentation/jetty-documentation/src/main/asciidoc/programming-guide/maven/jetty-maven-plugin.adoc +++ b/documentation/jetty-documentation/src/main/asciidoc/programming-guide/maven/jetty-maven-plugin.adoc @@ -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 `` 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: + diff --git a/documentation/jetty-documentation/src/main/asciidoc/programming-guide/server/compliance/server-compliance-cookie.adoc b/documentation/jetty-documentation/src/main/asciidoc/programming-guide/server/compliance/server-compliance-cookie.adoc index 0c48ed4b4f4..51471738c1d 100644 --- a/documentation/jetty-documentation/src/main/asciidoc/programming-guide/server/compliance/server-compliance-cookie.adoc +++ b/documentation/jetty-documentation/src/main/asciidoc/programming-guide/server/compliance/server-compliance-cookie.adoc @@ -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] ---- diff --git a/documentation/jetty-documentation/src/main/asciidoc/programming-guide/server/compliance/server-compliance-http.adoc b/documentation/jetty-documentation/src/main/asciidoc/programming-guide/server/compliance/server-compliance-http.adoc index 993f438850c..bfaa753465b 100644 --- a/documentation/jetty-documentation/src/main/asciidoc/programming-guide/server/compliance/server-compliance-http.adoc +++ b/documentation/jetty-documentation/src/main/asciidoc/programming-guide/server/compliance/server-compliance-http.adoc @@ -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] ---- diff --git a/documentation/jetty-documentation/src/main/asciidoc/programming-guide/server/compliance/server-compliance-uri.adoc b/documentation/jetty-documentation/src/main/asciidoc/programming-guide/server/compliance/server-compliance-uri.adoc index c4f03e641bf..386c6c35d5e 100644 --- a/documentation/jetty-documentation/src/main/asciidoc/programming-guide/server/compliance/server-compliance-uri.adoc +++ b/documentation/jetty-documentation/src/main/asciidoc/programming-guide/server/compliance/server-compliance-uri.adoc @@ -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] ---- diff --git a/documentation/jetty-documentation/src/main/asciidoc/programming-guide/server/compliance/server-compliance.adoc b/documentation/jetty-documentation/src/main/asciidoc/programming-guide/server/compliance/server-compliance.adoc index 9d072330310..c9fbefdcf11 100644 --- a/documentation/jetty-documentation/src/main/asciidoc/programming-guide/server/compliance/server-compliance.adoc +++ b/documentation/jetty-documentation/src/main/asciidoc/programming-guide/server/compliance/server-compliance.adoc @@ -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[] 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 91661d07c8c..8af91e68d61 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 @@ -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. diff --git a/documentation/jetty-documentation/src/main/asciidoc/programming-guide/server/http/server-http.adoc b/documentation/jetty-documentation/src/main/asciidoc/programming-guide/server/http/server-http.adoc index 47f2110dc78..2974c617e99 100644 --- a/documentation/jetty-documentation/src/main/asciidoc/programming-guide/server/http/server-http.adoc +++ b/documentation/jetty-documentation/src/main/asciidoc/programming-guide/server/http/server-http.adoc @@ -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`: 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 7a73aa8d82c..d5399cca7d0 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 @@ -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: diff --git a/documentation/jetty-documentation/src/main/asciidoc/programming-guide/server/sessions/session-cachingsessiondatastore.adoc b/documentation/jetty-documentation/src/main/asciidoc/programming-guide/server/sessions/session-cachingsessiondatastore.adoc index a3d6c20aba1..4a403c3bd29 100644 --- a/documentation/jetty-documentation/src/main/asciidoc/programming-guide/server/sessions/session-cachingsessiondatastore.adoc +++ b/documentation/jetty-documentation/src/main/asciidoc/programming-guide/server/sessions/session-cachingsessiondatastore.adoc @@ -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 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 23bafa827fd..3ceb425f17e 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 @@ -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 diff --git a/documentation/jetty-documentation/src/main/asciidoc/programming-guide/server/sessions/session-sessiondatastore-file.adoc b/documentation/jetty-documentation/src/main/asciidoc/programming-guide/server/sessions/session-sessiondatastore-file.adoc index 116681e7e0a..c51939f4a22 100644 --- a/documentation/jetty-documentation/src/main/asciidoc/programming-guide/server/sessions/session-sessiondatastore-file.adoc +++ b/documentation/jetty-documentation/src/main/asciidoc/programming-guide/server/sessions/session-sessiondatastore-file.adoc @@ -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:: diff --git a/documentation/jetty-documentation/src/main/asciidoc/programming-guide/server/sessions/session-sessiondatastore-jdbc.adoc b/documentation/jetty-documentation/src/main/asciidoc/programming-guide/server/sessions/session-sessiondatastore-jdbc.adoc index c0a6fcbd072..4cd400368ad 100644 --- a/documentation/jetty-documentation/src/main/asciidoc/programming-guide/server/sessions/session-sessiondatastore-jdbc.adoc +++ b/documentation/jetty-documentation/src/main/asciidoc/programming-guide/server/sessions/session-sessiondatastore-jdbc.adoc @@ -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] 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 ab3260edd3e..4fd5c9245de 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 @@ -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] diff --git a/documentation/jetty-documentation/src/main/asciidoc/programming-guide/server/sessions/session-sessiondatastore.adoc b/documentation/jetty-documentation/src/main/asciidoc/programming-guide/server/sessions/session-sessiondatastore.adoc index c0b8c258aa3..74a65b53b38 100644 --- a/documentation/jetty-documentation/src/main/asciidoc/programming-guide/server/sessions/session-sessiondatastore.adoc +++ b/documentation/jetty-documentation/src/main/asciidoc/programming-guide/server/sessions/session-sessiondatastore.adoc @@ -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`. 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 06e559b38ea..fc9706ed752 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 @@ -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` `` 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` `` declarations, or the `javax.servlet.SessionCookieConfig` api. There are also a few jetty-specific configuration options that we will cover here: checkingRemoteSessionIdEncoding:: 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 a40a5f6cded..1b67e3d7cc0 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 @@ -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. diff --git a/documentation/jetty-documentation/src/main/asciidoc/programming-guide/websocket.adoc b/documentation/jetty-documentation/src/main/asciidoc/programming-guide/websocket.adoc index 4181873eea6..42171af4e03 100644 --- a/documentation/jetty-documentation/src/main/asciidoc/programming-guide/websocket.adoc +++ b/documentation/jetty-documentation/src/main/asciidoc/programming-guide/websocket.adoc @@ -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