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

Merged branch 'jetty-10.0.x' into 'jetty-11.0.x'. 

Signed-off-by: Simone Bordet <simone.bordet@gmail.com>
This commit is contained in:
Simone Bordet 2021-07-16 18:13:41 +02:00
parent a584423373 34c03ddf1d
commit 587c75068c
45 changed files with 368 additions and 366 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

24
documentation/jetty-asciidoctor-extensions/src/main/java/org/eclipse/jetty/docs/JettyIncludeExtension.java
View File

@ -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)

20
documentation/jetty-documentation/pom.xml
View File

@ -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-11</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-11</javadoc-url>
</attributes>
</configuration>
<executions>

10
documentation/jetty-documentation/src/main/asciidoc/operations-guide/annotations/chapter.adoc
View File

@ -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.

2
documentation/jetty-documentation/src/main/asciidoc/operations-guide/deploy/deploy-jetty.adoc
View File

@ -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.

6
documentation/jetty-documentation/src/main/asciidoc/operations-guide/deploy/deploy-jndi.adoc
View File

@ -15,7 +15,7 @@
==== Configuring JNDI Entries
A web application may _reference_ a JNDI entry, such as a JDBC `DataSource` from the web application `web.xml` file.
The JNDI entry must be _defined_ in a link:#og-jndi-xml[Jetty XML file], for example a context XML like so:
The JNDI entry must be _defined_ in a xref:og-jndi-xml[Jetty XML file], for example a context XML like so:
.mywebapp.xml
[source,xml,subs=normal]
@ -40,13 +40,13 @@ The JNDI entry must be _defined_ in a link:#og-jndi-xml[Jetty XML file], for exa
</Configure>
----
For more information and examples on how to use JNDI in Jetty, refer to the link:#og-jndi[JNDI] feature section.
For more information and examples on how to use JNDI in Jetty, refer to the xref:og-jndi[JNDI] feature section.
[IMPORTANT]
====
Class `com.mysql.cj.jdbc.MysqlConnectionPoolDataSource` is present in the MySQL JDBC driver file, `mysql-connector-java-<version>.jar`, which must be available on the server's classpath .
If the class is instead present _within_ the web application, then the JNDI entry must be declared in a `WEB-INF/jetty-env.xml` file - see the link:#og-jndi[JNDI] feature section for more information and examples.
If the class is instead present _within_ the web application, then the JNDI entry must be declared in a `WEB-INF/jetty-env.xml` file - see the xref:og-jndi[JNDI] feature section for more information and examples.
====
// TODO: add a link to reference the section about how

4
documentation/jetty-documentation/src/main/asciidoc/operations-guide/deploy/deploy-virtual-hosts.adoc
View 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].

1
documentation/jetty-documentation/src/main/asciidoc/operations-guide/index.adoc
View File

@ -27,7 +27,6 @@ include::start/chapter.adoc[]
include::modules/chapter.adoc[]
include::deploy/chapter.adoc[]
include::protocols/chapter.adoc[]
include::compliance/server-compliance.adoc[]
include::keystore/chapter.adoc[]
include::sessions/chapter.adoc[]
include::quickstart/chapter.adoc[]

181
documentation/jetty-documentation/src/main/asciidoc/operations-guide/jaas/chapter.adoc
View File

@ -25,10 +25,10 @@ JAAS authentication is performed in a pluggable fashion.
This permits applications to remain independent from underlying authentication technologies.
New or updated authentication technologies can be plugged under an application without requiring modifications to the application itself.
See Java Authentication and Authorization Service (JAAS) http://java.sun.com/javase/7/docs/technotes/guides/security/jaas/JAASRefGuide.html[Reference Guide] for more information about JAAS.
See Java Authentication and Authorization Service (JAAS) link:http://java.sun.com/javase/7/docs/technotes/guides/security/jaas/JAASRefGuide.html[Reference Guide] for more information about JAAS.
The Jetty JAAS support aims to dictate as little as possible whilst providing a sufficiently flexible infrastructure to allow users to drop either one of the link:#og-jaas-loginmodules[JAAS Login Modules that ships with Jetty], or their
own custom https://docs.oracle.com/javase/7/docs/api/javax/security/auth/spi/LoginModule.html[LoginModules].
The Jetty JAAS support aims to dictate as little as possible whilst providing a sufficiently flexible infrastructure to allow users to drop either one of the xref:og-jaas-loginmodules[JAAS Login Modules that ships with Jetty], or their
own custom link:https://docs.oracle.com/javase/7/docs/api/javax/security/auth/spi/LoginModule.html[LoginModule]s.
[[og-jaas-configuration]]
==== Configuration
@ -45,12 +45,12 @@ include::{JETTY_HOME}/modules/jaas.mod[]
The configurable items in the resulting `$jetty.base/start.d/jaas.ini` file are:
jetty.jaas.login.conf::
This is the location of the file that will be referenced by the System property `java.security.auth.login.config`: Jetty sets this System property for you based on the value of this property.
The value of this property is assumed to be _relative to the ``$jetty.base``_.
The default value is `etc/login.conf`, which resolves to `$jetty.base/etc/login.conf`.
If you don't want to put your login module configuration file here, you can change this property to point to where it is.
This is the location of the file that will be referenced by the system property `java.security.auth.login.config`: Jetty sets this system property for you based on the value of this property.
The value of this property is assumed to be _relative to ``$JETTY_BASE``_.
The default value is `etc/login.conf`, which resolves to `$JETTY_BASE/etc/login.conf`.
If you don't want to put your login module configuration file here, you can change this property to point to where it is.
See more about the contents of this file in the link:#og-jaas-loginconf[Configuring JAAS] section.
See more about the contents of this file in the xref:og-jaas-loginconf[Configuring JAAS] section.
[[og-jaas-webapp]]
===== Configure the webapp for JAAS
@ -63,7 +63,7 @@ For example, this `web.xml` contains a realm called `Test JAAS Realm`:
----
<login-config>
<auth-method>FORM</auth-method>
<realm-name>Test JAAS Realm</realm-name> <1>
<realm-name>Test JAAS Realm</realm-name> <!--1-->
<form-login-config>
<form-login-page>/login/login</form-login-page>
<form-error-page>/login/error</form-error-page>
@ -75,30 +75,29 @@ For example, this `web.xml` contains a realm called `Test JAAS Realm`:
We now need to declare an `org.eclipse.jetty.jaas.JAASLoginService` that references the realm name of `Test JAAS Realm`.
Here's an example of a suitable XML snippet:
[source, xml, subs=verbatim]
[source,xml,subs=verbatim]
----
<New class="org.eclipse.jetty.jaas.JAASLoginService">
<Set name="Name">Test JAAS Realm</Set> <1>
<Set name="LoginModuleName">xyz</Set> <2>
<Set name="Name">Test JAAS Realm</Set> <!--1-->
<Set name="LoginModuleName">xyz</Set> <!--2-->
</New>
----
<1> The name is the _same_ as that declared in the `<realm-name>` in `web.xml`.
<2> The name that identifies a set of `javax.security.auth.spi.LoginModule` configurations that comprise the link:#og-jaas-loginconf[JAAS config file] identified in the `jetty.jaas.login.conf` property of the link:#og-jaas-module[`jaas` module].
<2> The name that identifies a set of `javax.security.auth.spi.LoginModule` configurations that comprise the xref:og-jaas-loginconf[JAAS config file] identified in the `jetty.jaas.login.conf` property of the xref:og-jaas-module[`jaas` module].
The `org.eclipse.jetty.jaas.JAASLoginService` can be declared in a couple of different places, pick whichever suits your purposes best:
* If you have more than one webapp that you would like to use the same security infrastructure, then you can declare your `org.eclipse.jetty.jaas.JAASLoginService` as a bean that is added to the `org.eclipse.jetty.server.Server`.
The file in which you declare this needs to be on Jetty's execution path.
The recommended procedure is to create a file in your `$jetty.base/etc` directory and then ensure it is on the classpath either by adding it to the Jetty link:#og-start-jar[start command line], or more conveniently to a link:#custom-modules[custom module].
The recommended procedure is to create a file in your `$jetty.base/etc` directory and then ensure it is on the classpath either by adding it to the Jetty xref:og-start-jar[start command line], or more conveniently to a xref:custom-modules[custom module].
+
Here's an example of this type of XML file:
[source, xml, subs=verbatim]
+
[source,xml]
----
<?xml version="1.0"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "https://www.eclipse.org/jetty/configure_10_0.dtd">
<Configure id="Server" class="org.eclipse.jetty.server.Server">
<Call name="addBean">
<Arg>
<New class="org.eclipse.jetty.jaas.JAASLoginService">
@ -107,18 +106,16 @@ Here's an example of this type of XML file:
</New>
</Arg>
</Call>
</Configure>
----
* Alternatively, if you want to use JAAS with a specific webapp only, you declare your `org.eclipse.jetty.jaas.JAASLoginService` in a context XLM file specific to that webapp:
+
[source, xml, subs=verbatim]
[source,xml]
----
<?xml version="1.0"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "https://www.eclipse.org/jetty/configure_10_0.dtd">
<Configure class="org.eclipse.jetty.webapp.WebAppContext">
<Set name="securityHandler">
<New class="org.eclipse.jetty.security.ConstraintSecurityHandler">
<Set name="loginService">
@ -129,67 +126,65 @@ Here's an example of this type of XML file:
</Set>
</New>
</Set>
</Configure>
----
[[og-jaas-loginconf]]
===== Configure JAAS
We now need to setup the contents of the file we specified as the `jetty.jaas.login.conf` property when we link:#og-jaas-module[configured the `jaas` module].
Refer to the https://docs.oracle.com/javase/7/docs/api/javax/security/auth/login/Configuration.html[syntax rules] of this file for a full description.
We now need to setup the contents of the file we specified as the `jetty.jaas.login.conf` property when we xref:og-jaas-module[configured the `jaas` module].
Refer to the link:https://docs.oracle.com/javase/7/docs/api/javax/security/auth/login/Configuration.html[syntax rules] of this file for a full description.
Remembering the example we set up link:#og-jaas-webapp[previously], the contents of the `$jetty.base/etc/login.conf` file could look as follows:
Remembering the example we set up xref:og-jaas-webapp[previously], the contents of the `$jetty.base/etc/login.conf` file could look as follows:
[source, ini, subs=verbatim]
[source,subs=verbatim]
----
xyz { <1>
com.acme.SomeLoginModule required debug=true; <2>
com.other.OtherLoginModule optional; <3>
};
com.acme.SomeLoginModule required debug=true; <2>
com.other.OtherLoginModule optional; <3>
};
----
<1> The name of the configuration _exactly_ as specified in your `org.eclipse.jetty.jaas.JAASLoginService` declaration.
<2> The first `LoginModule` declaration, containing the classname of the `LoginModule` and its configuration properties.
<3> A second `LoginModule` declaration.
You can provide as many `LoginModule` alternatives as you like, with a minimum of one.
Refer to the https://docs.oracle.com/javase/7/docs/api/javax/security/auth/login/Configuration.html[JAAS documentation] for more information on the standard configuration properties, and how JAAS interprets this file.
Refer to the link:https://docs.oracle.com/javase/7/docs/api/javax/security/auth/login/Configuration.html[JAAS documentation] for more information on the standard configuration properties, and how JAAS interprets this file.
[[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
The `org.eclipse.jetty.jaas.spi.JDBCLoginModule` stores user passwords and roles in a database accessed via JDBC calls.
You can configure the JDBC connection information, as well as the names of the table and columns storing the username and credential, and the names of the table and columns storing the roles.
Here is an example link:#og-jaas-loginconf[login module configuration file] entry for it using an HSQLDB driver:
Here is an example xref:og-jaas-loginconf[login module configuration file] entry for it using an HSQLDB driver:
[source, ini, subs=verbatim]
[source,subs=verbatim]
----
jdbc { <1>
org.eclipse.jetty.jaas.spi.JDBCLoginModule required <2><3>
dbUrl="jdbc:hsqldb:." <4>
dbUserName="sa" <5>
dbDriver="org.hsqldb.jdbcDriver" <6>
userTable="myusers" <7>
userField="myuser" <8>
credentialField="mypassword" <9>
userRoleTable="myuserroles" <10>
userRoleUserField="myuser" <11>
userRoleRoleField="myrole"; <12>
};
org.eclipse.jetty.jaas.spi.JDBCLoginModule required <2><3>
dbUrl="jdbc:hsqldb:." <4>
dbUserName="sa" <5>
dbDriver="org.hsqldb.jdbcDriver" <6>
userTable="myusers" <7>
userField="myuser" <8>
credentialField="mypassword" <9>
userRoleTable="myuserroles" <10>
userRoleUserField="myuser" <11>
userRoleRoleField="myrole"; <12>
};
----
<1> The name of the configuration.
<2> The name of the `LoginModule` class.
@ -208,17 +203,15 @@ The properties *7*-*12* are used to format the following queries:
[source,sql]
----
select <credentialField> from <userTable>
where <userField> =?
select <userRoleRoleField> from <userRoleTable>
where <userRoleUserField> =?
select <credentialField> from <userTable> where <userField>=?
select <userRoleRoleField> from <userRoleTable> where <userRoleUserField>=?
----
Credential and role information is lazily read from the database when a previously unauthenticated user requests authentication.
Note that this information is _only_ cached for the length of the authenticated session.
When the user logs out or the session expires, the information is flushed from memory.
Note that passwords can be stored in the database in plain text or encoded formats - see the note on "Passwords/Credentials" above.
Note that passwords can be stored in the database in plain text or encoded formats -- see the note on "Passwords/Credentials" above.
===== DataSourceLoginModule
@ -227,19 +220,18 @@ The `javax.sql.DataSource` is obtained at runtime by performing a JNDI lookup on
A sample login module configuration for this `LoginModule`:
[source subs=verbatim]
[source,subs=verbatim]
----
ds { <1>
org.eclipse.jetty.jaas.spi.DataSourceLoginModule required <2><3>
dbJNDIName="ds" <4>
userTable="myusers" <5>
userField="myuser" <6>
credentialField="mypassword" <7>
userRoleTable="myuserroles" <8>
userRoleUserField="myuser" <9>
userRoleRoleField="myrole"; <10>
};
org.eclipse.jetty.jaas.spi.DataSourceLoginModule required <2><3>
dbJNDIName="ds" <4>
userTable="myusers" <5>
userField="myuser" <6>
credentialField="mypassword" <7>
userRoleTable="myuserroles" <8>
userRoleUserField="myuser" <9>
userRoleRoleField="myrole"; <10>
};
----
<1> The name of the configuration.
<2> The name of the `LoginModule` class.
@ -252,17 +244,16 @@ ds { <1>
<9> The name of the column holding the user name.
<10> The name of the column holding the user role.
===== PropertyFileLoginModule
With this login module implementation, the authentication and role information is read from a property file.
[source subs=verbatim]
[source,subs=verbatim]
----
props { <1>
org.eclipse.jetty.jaas.spi.PropertyFileLoginModule required <2><3>
file="/somewhere/somefile.props"; <4>
};
org.eclipse.jetty.jaas.spi.PropertyFileLoginModule required <2><3>
file="/somewhere/somefile.props"; <4>
};
----
<1> The name of the configuration.
<2> The name of the `LoginModule` class.
@ -271,14 +262,13 @@ props { <1>
The property file must be of the format:
[source,text subs=verbatim]
[source,text,subs=verbatim]
----
<username>: <password> [,<rolename> ...]
----
Here's an example:
[source,ini]
----
fred: OBF:1xmk1w261u9r1w1c1xmq,user,admin
harry: changeme,user,developer
@ -295,30 +285,29 @@ The LDAP connection information and structure of the authentication/authorizatio
Here's an example:
[source,ini]
[source,subs=verbatim]
----
example { <1>
org.eclipse.jetty.jaas.spi.LdapLoginModule required <2><3>
contextFactory="com.sun.jndi.ldap.LdapCtxFactory" <4>
hostname="ldap.example.com" <5>
port="389" <6>
bindDn="cn=Directory Manager" <7>
bindPassword="directory" <8>
authenticationMethod="simple" <9>
useLdaps="true" <10>
userBaseDn="ou=people,dc=alcatel" <11>
userRdnAttribute="uid" <12>
userIdAttribute="cn" <13>
userPasswordAttribute="userPassword" <14>
userObjectClass="inetOrgPerson" <15>
roleBaseDn="ou=groups,dc=example,dc=com" <16>
roleNameAttribute="cn" <17>
roleMemberAttribute="uniqueMember" <18>
roleObjectClass="groupOfUniqueNames"; <19>
forceBindingLogin="false" <20>
debug="false" <21>
};
org.eclipse.jetty.jaas.spi.LdapLoginModule required <2><3>
contextFactory="com.sun.jndi.ldap.LdapCtxFactory" <4>
hostname="ldap.example.com" <5>
port="389" <6>
bindDn="cn=Directory Manager" <7>
bindPassword="directory" <8>
authenticationMethod="simple" <9>
useLdaps="true" <10>
userBaseDn="ou=people,dc=alcatel" <11>
userRdnAttribute="uid" <12>
userIdAttribute="cn" <13>
userPasswordAttribute="userPassword" <14>
userObjectClass="inetOrgPerson" <15>
roleBaseDn="ou=groups,dc=example,dc=com" <16>
roleNameAttribute="cn" <17>
roleMemberAttribute="uniqueMember" <18>
roleObjectClass="groupOfUniqueNames"; <19>
forceBindingLogin="false" <20>
debug="false" <21>
};
----
<1> The name of the configuration.
<2> The name of the `LoginModule` class.

76
documentation/jetty-documentation/src/main/asciidoc/operations-guide/jndi/chapter.adoc
View File

@ -29,33 +29,33 @@ You must declare the objects you want bound into the environment so that you can
You make these declarations in Jetty XML files that are either _external_ or _internal_ to your webapp.
A server or context XML file is external to your webapp.
The special `WEB-INF/jetty-env.xml` file is internal to your webapp.
See the section on link:#og-jndi-xml[Jetty XML files] for more information on how to choose in which XML file to place your declarations.
See the section on xref:og-jndi-xml[Jetty XML files] for more information on how to choose in which XML file to place your declarations.
For now, let's look at _what_ you declare in the XML file, regardless of its location.
Declaring a JDNI resource to be referenced later in your webapp is accomplished by declaring new instances of the following types:
link:#og-jndi-env[`org.eclipse.jetty.plus.jndi.EnvEntry`]::
xref:og-jndi-env[`org.eclipse.jetty.plus.jndi.EnvEntry`]::
Used for `env-entry` type of entries
link:#og-jndi-resource[`org.eclipse.jetty.plus.jndi.Resource`]::
xref:og-jndi-resource[`org.eclipse.jetty.plus.jndi.Resource`]::
Used for most other type of resources
link:#og-jndi-tx[`org.eclipse.jetty.plus.jndi.Transaction`]::
xref:og-jndi-tx[`org.eclipse.jetty.plus.jndi.Transaction`]::
For a JTA manager
link:#og-jndi-link[`org.eclipse.jetty.plus.jndi.Link`]::
xref:og-jndi-link[`org.eclipse.jetty.plus.jndi.Link`]::
For the link between a `web.xml` resource name and a naming entry
Declarations of each of these types follow a similar pattern:
[source,xml,subs=verbatim]
----
<New class="org.eclipse.jetty.plus.jndi.xxxx"> <1>
<Arg><!-- scope --></Arg> <2>
<Arg><!-- name --></Arg> <3>
<Arg><!-- value --></Arg> <4>
<New class="org.eclipse.jetty.plus.jndi.xxxx"> <!--1-->
<Arg><!-- scope --></Arg> <!--2-->
<Arg><!-- name --></Arg> <!--3-->
<Arg><!-- value --></Arg> <!--4-->
</New>
----
<1> Defines a resource to Jetty.
<2> Specifies the link:#og-jndi-scope[scope] of the resource.
<2> Specifies the xref:og-jndi-scope[scope] of the resource.
<3> Specifies the name of the resource which will be looked up by the webapp relative to the `java:comp/env` namespace.
<4> Specifies the value of the resource.
@ -70,15 +70,15 @@ Here's an example that defines the equivalent of an `env-entry` called `mySpecia
[source,xml,subs=verbatim]
----
<New class="org.eclipse.jetty.plus.jndi.EnvEntry"> <1>
<Arg></Arg> <2>
<Arg>mySpecialValue</Arg> <3>
<Arg type="java.lang.Integer">4000</Arg> <4>
<Arg type="boolean">true</Arg> <5>
<New class="org.eclipse.jetty.plus.jndi.EnvEntry"> <!--1-->
<Arg></Arg> <!--2-->
<Arg>mySpecialValue</Arg> <!--3-->
<Arg type="java.lang.Integer">4000</Arg> <!--4-->
<Arg type="boolean">true</Arg> <!--5-->
</New>
----
<1> Define an `EnvEntry` that corresponds to an `<env-entry>`.
<2> link:#og-jndi-scope[Scoped] at the JVM level.
<2> xref:og-jndi-scope[Scoped] at the JVM level.
<3> The name of the entry, corresponding to a lookup by the webapp of `java:comp/env/mySpecialValue`.
<4> The value of the entry, in this case the integer value `4000`.
<5> `true` means to override the value of an `<env-entry>` of the same name in `web.xml`.
@ -100,8 +100,8 @@ The Servlet Specification allows binding only the following object types to an `
Jetty is a little more flexible and allows you to also bind:
* custom POJOs
* http://docs.oracle.com/javase/1.5.0/docs/api/javax/naming/Reference.html[`javax.naming.References`]
* http://docs.oracle.com/javase/1.5.0/docs/api/javax/naming/Referenceable.html[`javax.naming.Referenceables`]
* link:http://docs.oracle.com/javase/1.5.0/docs/api/javax/naming/Reference.html[`javax.naming.References`]
* link:http://docs.oracle.com/javase/1.5.0/docs/api/javax/naming/Referenceable.html[`javax.naming.Referenceables`]
Be aware that if you take advantage of this feature, your web application is __not portable__.
@ -116,7 +116,7 @@ Let's examine how to configure some of the most common types of resources.
====== DataSources
In this example, we'll configure a http://db.apache.org/derby[Derby] DataSource named `jdbc/myds`:
In this example, we'll configure a link:http://db.apache.org/derby[Derby] DataSource named `jdbc/myds`:
[source,xml,subs=verbatim]
----
@ -150,7 +150,7 @@ This would linked into the webapps JNDI namespace via an entry in a `web.xml` li
When configuring Resources, ensure that the type of object you configure matches the type of object you expect to look up in `java:comp/env`.
For database connection factories, this means that the object you register as a Resource _must_ implement the `javax.sql.DataSource` interface.
Also note that the http://jcp.org/aboutJava/communityprocess/pr/jsr244/index.html[J2EE Specification] recommends storing DataSources relative to `jdbc/` and thus looked up by the application as `java:comp/env/jdbc/xxx`.
Also note that the link:http://jcp.org/aboutJava/communityprocess/pr/jsr244/index.html[J2EE Specification] recommends storing DataSources relative to `jdbc/` and thus looked up by the application as `java:comp/env/jdbc/xxx`.
Eg The Datasource bound in Jetty as `jdbc/users` would be looked up by the application as `java:comp/env/jdbc/users`
====
@ -162,7 +162,7 @@ Eg The Datasource bound in Jetty as `jdbc/users` would be looked up by the appli
Jetty can bind any implementation of the JMS destinations and connection factories.
Here is an example of binding an http://activemq.apache.org[ActiveMQ] in-JVM connection factory:
Here is an example of binding an link:http://activemq.apache.org[ActiveMQ] in-JVM connection factory:
[source,xml,subs=verbatim]
----
@ -192,7 +192,7 @@ The corresponding entry in `web.xml` to bind the ConnectionFactory into the weba
[NOTE]
====
The http://jcp.org/aboutJava/communityprocess/pr/jsr244/index.html[J2EE Specification] recommends storing JMS connection factories under `jms/`.
The link:http://jcp.org/aboutJava/communityprocess/pr/jsr244/index.html[J2EE Specification] recommends storing JMS connection factories under `jms/`.
Eg The ConnectionFactory bound in Jetty as `jms/inqueue` would be looked up by the application as `java:comp/env/jms/inqueue`.
====
@ -207,10 +207,10 @@ To configure access to `javax.mail.Session` from within a webapp, declare an `or
<Arg><Ref refid="wac"/></Arg>
<Arg>mail/Session</Arg>
<Arg>
<New class="org.eclipse.jetty.jndi.factories.MailSessionReference"> <1>
<Set name="user">fred</Set> <2>
<Set name="password">OBF:1xmk1w261z0f1w1c1xmq</Set> <3>
<Set name="properties"> <4>
<New class="org.eclipse.jetty.jndi.factories.MailSessionReference"> <!--1-->
<Set name="user">fred</Set> <!--2-->
<Set name="password">OBF:1xmk1w261z0f1w1c1xmq</Set> <!--3-->
<Set name="properties"> <!--4-->
<New class="java.util.Properties">
<Put name="mail.smtp.host">XXX</Put>
<Put name="mail.from">me@me</Put>
@ -227,13 +227,13 @@ To configure access to `javax.mail.Session` from within a webapp, declare an `or
<3> Set the password for the mail instance - use Jetty's secure password obfuscation to obscure the password.
<4> Set all other applicable properties.
The webapp performs a lookup for `java:comp/env/mail/Session` at runtime and obtains a `javax.mail.Session` that has the correct configuration to permit it to send email via SMTP.
The webapp performs a lookup for `java:comp/env/mail/Session` at runtime and obtains a `javax.mail.Session` that has the correct configuration to permit it to send email via SMTP.
[NOTE]
====
Jetty does not provide the `javax.mail` and `javax.activation` jars.
Note also that the http://jcp.org/aboutJava/communityprocess/pr/jsr244/index.html[J2EE Specification] recommends storing JavaMail connection factories under `mail/`.
Note also that the link:http://jcp.org/aboutJava/communityprocess/pr/jsr244/index.html[J2EE Specification] recommends storing JavaMail connection factories under `mail/`.
Eg The `MailSessionReference` bound to jetty as `mail/smtp` would be looked up by the application as `java:comp/env/mail/smtp`.
====
@ -245,9 +245,9 @@ 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 xref:og-jndi-xml[Jetty XML file] to configure the JTA manager.
The following example configures the http://www.atomikos.com/[Atomikos] transaction manager:
The following example configures the link:http://www.atomikos.com/[Atomikos] transaction manager:
[source,xml,subs=verbatim]
----
@ -308,8 +308,8 @@ Create a `WEB-INF/jetty-env.xml` file with a `org.eclipse.jetty.plus.jndi.Link`
----
<New class="org.eclipse.jetty.plus.jndi.Link">
<Arg><Ref refid='wac'/></Arg>
<Arg>jdbc/employees</Arg> <1>
<Arg>jdbc/workforce</Arg> <2>
<Arg>jdbc/employees</Arg> <!--1-->
<Arg>jdbc/workforce</Arg> <!--2-->
</New>
----
<1> The name as referenced in the `web.xml` file.
@ -321,14 +321,14 @@ Create a `WEB-INF/jetty-env.xml` file with a `org.eclipse.jetty.plus.jndi.Link`
You can define naming resources in three places:
Server XML file::
Naming resources defined in a server XML file are link:#og-jndi-scope[scoped] at either the JVM level or the `org.eclipse.jetty.server.Server` level.
Naming resources defined in a server XML file are xref:og-jndi-scope[scoped] at either the JVM level or the `org.eclipse.jetty.server.Server` level.
The classes for the resource _must_ be visible at the Jetty *container* level.
If instead the classes for the resource only exist inside your webapp, you must declare it in a `WEB-INF/jetty-env.xml` file.
Context XML file::
Entries in a context XML file should be link:#og-jndi-scope[scoped] at the level of the webapp to which they apply (although it is possible to use a less strict scoping level of Server or JVM, but not recommended).
Entries in a context XML file should be xref:og-jndi-scope[scoped] at the level of the webapp to which they apply (although it is possible to use a less strict scoping level of Server or JVM, but not recommended).
As with resources declared in a server XML file, classes associated with the resource _must_ be visible on the *container's* classpath.
WEB-INF/jetty-env.xml::
Naming resources in a `WEB-INF/jetty-env.xml` file are link:#og-jndi-scope[scoped] to the webapp in which the file resides.
Naming resources in a `WEB-INF/jetty-env.xml` file are xref:og-jndi-scope[scoped] to the webapp in which the file resides.
While you can enter JVM or Server scopes if you choose, we do not recommend doing so.
The resources defined here may use classes from inside your webapp.
@ -344,7 +344,7 @@ For example:
[source,xml,subs=verbatim]
----
<New id="cf" class="org.eclipse.jetty.plus.jndi.Resource">
<Arg></Arg> <1>
<Arg></Arg> <!--1-->
<Arg>jms/connectionFactory</Arg>
<Arg>
<New class="org.apache.activemq.ActiveMQConnectionFactory">
@ -362,7 +362,7 @@ For example:
[source,xml,subs=verbatim]
----
<New id="cf" class="org.eclipse.jetty.plus.jndi.Resource">
<Arg><Ref refid="Server"/></Arg> <1>
<Arg><Ref refid="Server"/></Arg> <!--1-->
<Arg>jms/connectionFactory</Arg>
<Arg>
<New class="org.apache.activemq.ActiveMQConnectionFactory">
@ -380,7 +380,7 @@ For example:
[source,xml,subs=verbatim]
----
<New class="org.eclipse.jetty.plus.jndi.Resource">
<Arg><Ref refid='wac'/></Arg> <1>
<Arg><Ref refid='wac'/></Arg> <!--1-->
<Arg>jms/connectionFactory</Arg>
<Arg>
<New class="org.apache.activemq.ActiveMQConnectionFactory">

94
documentation/jetty-documentation/src/main/asciidoc/operations-guide/jsp/chapter.adoc
View File

@ -22,12 +22,12 @@ include::{JETTY_HOME}/modules/jsp.mod[]
Logging has been bridged to Jetty logging, so you can enable logging for the `org.apache.jasper` package, subpackages and classes as usual.
===== Configuration of the JSP servlet
==== Configuration of the JSP Servlet
The `org.eclipse.jetty.jsp.JettyJspServlet` is the servlet responsible for serving jsps.
The `org.eclipse.jetty.jsp.JettyJspServlet` is the servlet responsible for serving JSPs.
It is configured as the default jsp servlet in the link:{JETTY_HOME}/etc/webdefault.xml[webdefault.xml] file.
Notice that Jetty identifies the jsp servlet by the presence of the `id=jsp` attribute in the `<servlet>` declaration.
It is configured as the default jsp servlet in the `$JETTY_HOME/etc/webdefault.xml` file.
Notice that Jetty identifies the jsp servlet by the presence of the `id="jsp"` attribute in the `<servlet>` declaration.
That file maps the `org.eclipse.jetty.jsp.JettyJspServlet` to the following partial urls:
@ -46,13 +46,13 @@ Here's an example of adding an `<init-param>` to augment the definitions from th
[source,xml,subs=verbatim]
----
<servlet id="jsp"> <1>
<servlet-name>jsp</servlet-name> <2>
<init-param>
<param-name>keepgenerated</param-name> <3>
<param-value>true</param-value> <4>
</init-param>
</servlet>
<servlet id="jsp"> <!--1-->
<servlet-name>jsp</servlet-name> <!--2-->
<init-param>
<param-name>keepgenerated</param-name> <!--3-->
<param-value>true</param-value> <!--4-->
</init-param>
</servlet>
----
<1> This identifies this servlet as the jsp servlet to Jetty.
<2> This identifies this declaration as augmenting the already-defined servlet called `jsp`.
@ -63,20 +63,20 @@ Another element you might consider adding to the default setup is `async-support
[source,xml,subs=verbatim]
----
<servlet id="jsp"> <1>
<servlet-name>jsp</servlet-name> <2>
<async-supported>true</async-supported> <3>
<servlet id="jsp"> <!--1-->
<servlet-name>jsp</servlet-name> <!--2-->
<async-supported>true</async-supported> <!--3-->
</servlet>
----
<1> This identifies this servlet as the jsp servlet to Jetty.
<2> This identifies this declaration as augmenting the already-defined servlet called `jsp`.
<3> By default, the jsp servlet does not support async.
There are many configuration parameters for the Apache Jasper jsp servlet, here are some of them:
There are many configuration parameters for the Apache Jasper JSP Servlet, here are some of them:
.Jsp Servlet Parameters
[cols=",,,",options="header",]
|=======================================================================
.JSP Servlet Parameters
[cols=",,,",options="header"]
|===
|init param |Description |Default |`webdefault.xml`
|checkInterval |If non-zero and `development` is `false`, background jsp recompilation is enabled. This value is the interval in seconds between background recompile checks.
@ -84,7 +84,7 @@ There are many configuration parameters for the Apache Jasper jsp servlet, here
|classpath |The classpath is dynamically generated if the context has a URL classloader. The `org.apache.catalina.jsp_classpath`
context attribute is used to add to the classpath, but if this is not set, this `classpath` configuration item is added to the classpath instead.` |- |–
|classdebuginfo |Include debugging info in class file. |TRUE |–
|classdebuginfo |Include debugging info in class file. |true |–
|compilerClassName |If not set, defaults to the Eclipse jdt compiler. |- |–
@ -97,14 +97,14 @@ classpath. It is the classname of a compiler that Ant should invoke. |–
|compilerSourceVM |Sets source compliance level for the jdt compiler.
|1.8 |1.8
|development |If `true` recompilation checks occur at the frequency governed by `modificationTestInterval`. |TRUE |–
|development |If `true` recompilation checks occur at the frequency governed by `modificationTestInterval`. |true |–
|displaySourceFragment |Should a source fragment be included in
exception messages |TRUE |–
exception messages |true |–
|dumpSmap |Dump SMAP JSR45 info to a file. |FALSE |–
|dumpSmap |Dump SMAP JSR45 info to a file. |false |–
|enablePooling |Determines whether tag handler pooling is enabled. |TRUE |–
|enablePooling |Determines whether tag handler pooling is enabled. |true |–
|engineOptionsClass |Allows specifying the Options class used to
configure Jasper. If not present, the default EmbeddedServletOptions
@ -112,11 +112,11 @@ will be used. |- |–
|errorOnUseBeanInvalidClassAttribute |Should Jasper issue an error when
the value of the class attribute in an useBean action is not a valid
bean class |TRUE |–
bean class |true |–
|fork |Only relevant if you use Ant to compile jsps: by default Jetty will use the Eclipse jdt compiler.|TRUE |-
|fork |Only relevant if you use Ant to compile JSPs: by default Jetty will use the Eclipse jdt compiler.|true |-
|genStrAsCharArray |Option for generating Strings as char arrays. |FALSE |–
|genStrAsCharArray |Option for generating Strings as char arrays. |false |–
|ieClassId |The class-id value to be sent to Internet Explorer when
using <jsp:plugin> tags. |clsid:8AD9C840-044E-11D1-B3E9-00805F499D93 |–
@ -128,10 +128,10 @@ using <jsp:plugin> tags. |clsid:8AD9C840-044E-11D1-B3E9-00805F499D93 |–
it is unloaded. A value of zero or less indicates never unload. |-1 |–
|keepgenerated |Do you want to keep the generated Java files around?
|TRUE |–
|true |–
|mappedFile |Support for mapped Files. Generates a servlet that has a
print statement per line of the JSP file  |TRUE |–
print statement per line of the JSP file |true |–
|maxLoadedJsps |The maximum number of JSPs that will be loaded for a web
application. If more than this number of JSPs are loaded, the least
@ -143,35 +143,36 @@ indicates no limit. |-1 |–
recompilation checks, triggered by a request. |4 |–
|quoteAttributeEL | When EL is used in an attribute value on a JSP page, should the rules for quoting of attributes described in JSP.1.6 be applied to the expression
|TRUE |-
|true |-
|recompileOnFail |If a JSP compilation fails should the
modificationTestInterval be ignored and the next access trigger a
re-compilation attempt? Used in development mode only and is disabled by
default as compilation may be expensive and could lead to excessive
resource usage. |FALSE |–
resource usage. |false |–
|scratchDir |Directory where servlets are generated. The default is the value of the context attribute `javax.servlet.context.tempdir`, or the system property `java.io.tmpdir` if the context attribute is not set. |– |–
|strictQuoteEscaping |Should the quote escaping required by section JSP.1.6 of the JSP specification be applied to scriplet expression.
|TRUE|-
|true|-
|suppressSmap |Generation of SMAP info for JSR45 debugging. |FALSE |–
|suppressSmap |Generation of SMAP info for JSR45 debugging. |false |–
|trimSpaces |Should template text that consists entirely of whitespace be removed from the output (true), replaced with a single space (single) or left unchanged (false)? Note that if a JSP page or tag file specifies a trimDirectiveWhitespaces value of true, that will take precedence over this configuration setting for that page/tag.
trimmed? |FALSE |–
trimmed? |false |–
|xpoweredBy |Generate an X-Powered-By response header. |FALSE |FALSE
|xpoweredBy |Generate an X-Powered-By response header. |false |false
|=======================================================================
NOTE:: If the value you set doesn't take effect, try using all lower case instead of camel case, or capitalizing only some of the words in the name, as Jasper is inconsistent in its parameter naming strategy.
|===
[NOTE]
====
If the value you set doesn't take effect, try using all lower case instead of camel case, or capitalizing only some of the words in the name, as Jasper is inconsistent in its parameter naming strategy.
====
=== JavaServer Pages Standard Tag Libraries
The JavaServer Pages Standlard Tag Library (JSTL) is part of the Jetty distribution, and is available via the `jstl` module:
The JavaServer Pages Standard Tag Library (JSTL) is part of the Jetty distribution, and is available via the `jstl` module:
----
include::{JETTY_HOME}/modules/jstl.mod[]
@ -179,9 +180,9 @@ include::{JETTY_HOME}/modules/jstl.mod[]
When enabled, Jetty will make the JSTL tags available for your webapps.
=== JavaServer Faces Taglibs
=== JavaServer Faces TagLibs
If you want to use JSF with your webapp, you should copy the relevant jars from your implementation of choice into your `$jetty.base` directory, ideally into `$jetty.base/lib/ext`.
If you want to use JSF with your webapp, you should copy the relevant jars from your implementation of choice into your `$JETTY_BASE` directory, ideally into `$JETTY_BASE/lib/ext`.
If that directory does not exist, enable the `ext` module, which will create the directory and ensure all jars within it are put onto the container classpath.
@ -196,15 +197,14 @@ Here's an example of using a context xml file to add in a pattern to match files
<?xml version="1.0"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "https://www.eclipse.org/jetty/configure_10_0.dtd">
<Configure class="org.eclipse.jetty.webapp.WebAppContext"> <1>
<Call name="setAttribute"> <2>
<Arg>org.eclipse.jetty.server.webapp.ContainerIncludeJarPattern</Arg> <3>
<Arg.*/jetty-servlet-api-[^/]*\.jar$|.*/javax.servlet.jsp.jstl-.*\.jar$|.*/org.apache.taglibs.taglibs-standard-impl-.*\.jar$|.*/jsf-[^/]*\.jar$></Arg> <4>
<Configure class="org.eclipse.jetty.webapp.WebAppContext"> <!--1-->
<Call name="setAttribute"> <!--2-->
<Arg>org.eclipse.jetty.server.webapp.ContainerIncludeJarPattern</Arg> <!--3-->
<Arg>.*/jetty-servlet-api-[^/]*\.jar$|.*/javax.servlet.jsp.jstl-.*\.jar$|.*/org.apache.taglibs.taglibs-standard-impl-.*\.jar$|.*/jsf-[^/]*\.jar$</Arg> <!--4-->
</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.

19
documentation/jetty-documentation/src/main/asciidoc/operations-guide/modules/module-server.adoc
View File

@ -92,36 +92,35 @@ 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].
For more information about `HttpCompliance` see also xref:{prog-guide}#pg-server-compliance-http[this section].
`jetty.httpConfig.uriCompliance`::
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].
For more information about `UriCompliance` see also xref:{prog-guide}#pg-server-compliance-uri[this section].
`jetty.httpConfig.requestCookieCompliance`::
`jetty.httpConfig.responseCookieCompliance`::
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].
For more information about `CookieCompliance` see also xref:{prog-guide}#pg-server-compliance-cookie[this section].
[[og-module-scheduler-config]]
====== Server Scheduler Configuration Properties

2
documentation/jetty-documentation/src/main/asciidoc/operations-guide/modules/modules-custom.adoc
View File

@ -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]:

2
documentation/jetty-documentation/src/main/asciidoc/operations-guide/modules/modules-standard.adoc
View File

@ -14,6 +14,7 @@
[[og-modules-standard]]
==== Standard Modules
include::module-alpn.adoc[]
include::module-bytebufferpool.adoc[]
include::module-deploy.adoc[]
include::module-http.adoc[]
@ -21,6 +22,7 @@ include::module-http2.adoc[]
include::module-http2c.adoc[]
include::module-http-forwarded.adoc[]
include::module-https.adoc[]
include::module-jmx-remote.adoc[]
include::module-server.adoc[]
include::module-ssl.adoc[]
include::module-ssl-reload.adoc[]

2
documentation/jetty-documentation/src/main/asciidoc/operations-guide/protocols/protocols-ssl.adoc
View File

@ -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.

11
documentation/jetty-documentation/src/main/asciidoc/operations-guide/quickstart/chapter.adoc
View File

@ -21,7 +21,11 @@ However for production deployment, the need to scan the contents of many jars ca
The `quickstart` module allows a webapp to be pre-scanned, making startup predictable and faster.
During scanning all declarative configuration (ie from web.xml, web-fragment.xml and annotations) are encoded into an effective `web.xml`, called `WEB-INF/quickstart-web.xml`, which can be inspected to understand what will be deployed.
NOTE:: Programmatic configuration is _not_ encoded into the generated `quickstart-web.xml` file.
[NOTE]
====
Programmatic configuration is _not_ encoded into the generated `quickstart-web.xml` file.
====
With `quickstart`, webapps that took many seconds to scan and deploy can now be deployed in a few hundred milliseconds.
@ -29,11 +33,10 @@ With `quickstart`, webapps that took many seconds to scan and deploy can now be
Enable the `quickstart` module for your jetty base:
[source, screen, subs="{sub-order}"]
....
----
$ cd $JETTY-BASE
$ java -jar $JETTY_HOME/start.jar --add-module=quickstart
....
----
The `$JETTY-BASE/start.d/quickstart.ini` file contains these configurable parameters:

2
documentation/jetty-documentation/src/main/asciidoc/operations-guide/sessions/session-overview.adoc
View File

@ -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]
====

2
documentation/jetty-documentation/src/main/asciidoc/operations-guide/sessions/session-usecases.adoc
View File

@ -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

2
documentation/jetty-documentation/src/main/asciidoc/operations-guide/start/start-jpms.adoc
View File

@ -14,7 +14,7 @@
[[og-start-start-jpms]]
==== Starting Jetty using JPMS
Jetty modules are proper https://en.wikipedia.org/wiki/Java_Platform_Module_System[JPMS] modules: each Jetty module has a `module-info.class` file.
Jetty modules are proper link:https://en.wikipedia.org/wiki/Java_Platform_Module_System[JPMS] modules: each Jetty module has a `module-info.class` file.
This makes possible to run Jetty from the module-path, rather than the class-path.
To start Jetty on the module-path rather than the class-path, it is enough to add the `--jpms` option to the command line, for example:

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

@ -73,15 +73,13 @@ Below you can find a simple example of a Jetty Server Dump, with annotations for
[source,subs=verbatim,role=small,options=nowrap]
----
include::jetty[setupArgs="--add-modules=http",args="jetty.http.selectors=1 jetty.http.acceptors=1 jetty.threadPool.minThreads=4 jetty.server.dumpAfterStart=true",delete="^[0-9]{4}",callouts=" <$N>,Server@,= QueuedThreadPool,(?i)ACCEPTING,(?i)SELECTING,HandlerList@,= ServerConnector,ManagedSelector@,keys @,startJarLoader@,unmanaged"]
include::jetty[setupArgs="--add-modules=http",args="jetty.http.selectors=1 jetty.http.acceptors=1 jetty.threadPool.minThreads=4 jetty.server.dumpAfterStart=true",delete="^[0-9]{4}",callouts=" <$N>,Server@,= QueuedThreadPool,HandlerList@,= ServerConnector,ManagedSelector@,keys @,startJarLoader@,unmanaged"]
----
<1> The `Server` instance at the root of the tree
<2> The thread pool component
<3> The thread accepting connections
<4> The thread selecting connections
<5> The root of the `Handler` structure
<6> The connector listening on port `8080` for the HTTP/1.1 protocol
<7> A selector component that manages connections
<8> The connections currently managed by the selector component
<9> The server `ClassLoader` and its classpath
<10> The legend for the dump nodes
<3> The root of the `Handler` structure
<4> The connector listening on port `8080` for the HTTP/1.1 protocol
<5> A selector component that manages connections
<6> The connections currently managed by the selector component
<7> The server `ClassLoader` and its classpath
<8> The legend for the dump nodes

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

@ -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`

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

@ -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]
----

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

@ -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

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

@ -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

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

@ -24,7 +24,7 @@ However, when all you need to do is to perform a `GET` request to a resource, Je
Jetty's HTTP client supports xref:pg-client-http-transport[different transports]: HTTP/1.1, FastCGI and HTTP/2. This means that the semantic of an HTTP request: " ``GET`` the resource ``/index.html`` " can be carried over the network in different formats.
The most common and default format is HTTP/1.1. That said, Jetty's HTTP client can carry the same request using the FastCGI format or the HTTP/2 format.
The xref:pg-client-http-transport-fcgi[FastCGI transport] is heavily used in Jetty's xref:fastcgi[FastCGI support] that allows Jetty to work as a reverse proxy to PHP (exactly like Apache or Nginx do) and therefore be able to serve, for example, WordPress websites.
The xref:pg-client-http-transport-fcgi[FastCGI transport] is heavily used in Jetty's xref:pg-server-fastcgi[FastCGI support] that allows Jetty to work as a reverse proxy to PHP (exactly like Apache or Nginx do) and therefore be able to serve, for example, WordPress websites.
The HTTP/2 transport allows Jetty's HTTP client to perform requests using HTTP/2 to HTTP/2 enabled web sites, see also Jetty's xref:pg-client-http2[HTTP/2 support].

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

@ -97,9 +97,9 @@ The FastCGI transport can be configured in this way:
include::../../{doc_code}/org/eclipse/jetty/docs/programming/client/http/HTTPClientDocs.java[tag=fcgiTransport]
----
In order to make requests using the FastCGI transport, you need to have a FastCGI server such as https://en.wikipedia.org/wiki/PHP#PHPFPM[PHP-FPM] (see also http://php.net/manual/en/install.fpm.php).
In order to make requests using the FastCGI transport, you need to have a FastCGI server such as link:https://en.wikipedia.org/wiki/PHP#PHPFPM[PHP-FPM] (see also link:http://php.net/manual/en/install.fpm.php).
The FastCGI transport is primarily used by Jetty's xref:fastcgi[FastCGI support] to serve PHP pages (WordPress for example).
The FastCGI transport is primarily used by Jetty's xref:pg-server-fastcgi[FastCGI support] to serve PHP pages (WordPress for example).
[[pg-client-http-transport-dynamic]]
===== Dynamic Transport

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

@ -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:

18
documentation/jetty-documentation/src/main/asciidoc/programming-guide/maven/jetty-maven-helloworld.adoc
View File

@ -17,7 +17,7 @@
http://maven.apache.org/[Apache Maven] is a software project management and comprehension tool.
Based on the concept of a project object model (POM), Maven can manage a project's build, reporting and documentation from a central piece of information.
It is an ideal tool to build a web application project, and such projects can use the link:#jetty-maven-plugin[jetty-maven-plugin] to easily run the web application and save time in development.
It is an ideal tool to build a web application project, and such projects can use the xref:jetty-maven-plugin[jetty-maven-plugin] to easily run the web application and save time in development.
You can also use Maven to build, test and run a project which embeds Jetty.
[NOTE]
@ -27,18 +27,18 @@ Using Maven for Jetty implementations is a popular choice, but users encouraged
Other popular tools include Ant and Gradle.
====
First we'll have a look at a very simple HelloWorld java application that embeds Jetty, then a simple webapp which makes use of the link:#jetty-maven-plugin[jetty-maven-plugin] to speed up the development cycle.
First we'll have a look at a very simple HelloWorld java application that embeds Jetty, then a simple webapp which makes use of the xref:jetty-maven-plugin[jetty-maven-plugin] to speed up the development cycle.
[[configuring-embedded-jetty-with-maven]]
==== Using Embedded Jetty with Maven
To understand the basic operations of building and running against Jetty, first review:
* link:#advanced-embedding[Embedding with Jetty]
* link:#jetty-helloworld[Jetty HelloWorld example]
* xref:advanced-embedding[Embedding with Jetty]
* xref:jetty-helloworld[Jetty HelloWorld example]
Maven uses convention over configuration, so it is best to use the project structure Maven recommends.
You can use _link:#archetypes[http://maven.apache.org/guides/introduction/introduction-to-archetypes.html[archetypes]]_ to quickly setup Maven projects, but we will set up the structure manually for this simple tutorial example:
You can use _xref:archetypes[http://maven.apache.org/guides/introduction/introduction-to-archetypes.html[archetypes]]_ to quickly setup Maven projects, but we will set up the structure manually for this simple tutorial example:
----
> mkdir JettyMavenHelloWorld
@ -247,7 +247,7 @@ You need to declare this servlet in the deployment descriptor, so create the fil
===== Creating the POM Descriptor
The `pom.xml` file declares the project name and its dependencies.
Use an editor to create the file `pom.xml` with the following contents in the `JettyMavenHelloWarApp` directory, noting particularly the declaration of the link:#jetty-maven-plugin[jetty-maven-plugin]:
Use an editor to create the file `pom.xml` with the following contents in the `JettyMavenHelloWarApp` directory, noting particularly the declaration of the xref:jetty-maven-plugin[jetty-maven-plugin]:
[source,xml]
----
@ -291,7 +291,7 @@ Use an editor to create the file `pom.xml` with the following contents in the `J
[[building-and-running-web-application]]
===== Building and Running the Web Application
Now you can both build and run the web application without needing to assemble it into a war by using the link:#jetty-maven-plugin[jetty-maven-plugin] via the command:
Now you can both build and run the web application without needing to assemble it into a war by using the xref:jetty-maven-plugin[jetty-maven-plugin] via the command:
----
> mvn jetty:run
@ -300,7 +300,7 @@ Now you can both build and run the web application without needing to assemble i
You can see the static and dynamic content at `http://localhost:8080/hello`
There are a great deal of configuration options available for the jetty-maven-plugin to help you build and run your webapp.
The full reference is at link:#jetty-maven-plugin[Configuring the Jetty Maven Plugin].
The full reference is at xref:jetty-maven-plugin[Configuring the Jetty Maven Plugin].
[[building-war-file]]
===== Building a WAR file
@ -311,4 +311,4 @@ You can create a Web Application Archive (WAR) file from the project with the co
> mvn package
----
The resulting war file is in the `target` directory and may be deployed on any standard servlet server, including link:#configuring-deployment[Jetty].
The resulting war file is in the `target` directory and may be deployed on any standard servlet server, including xref:configuring-deployment[Jetty].

92
documentation/jetty-documentation/src/main/asciidoc/programming-guide/maven/jetty-maven-plugin.adoc
View File

@ -28,15 +28,15 @@ The plugin has been substantially re-architected in jetty-10 to:
There are now only 4 goals to run a webapp in jetty:
* link:#jetty-run-goal[jetty:run]
* link:#jetty-run-war-goal[jetty:run-war]
* link:#jetty-start-goal[jetty:start]
* link:#jetty-start-war-goal[jetty:start-war]
* xref:jetty-run-goal[jetty:run]
* xref:jetty-run-war-goal[jetty:run-war]
* xref:jetty-start-goal[jetty:start]
* xref:jetty-start-war-goal[jetty:start-war]
Plus two utility goals:
* link:#jetty-stop-goal[jetty:stop]
* link:#jetty-effective-web-xml-goal[jetty:effective-web-xml]
* xref:jetty-stop-goal[jetty:stop]
* xref:jetty-effective-web-xml-goal[jetty:effective-web-xml]
`jetty:run` and `jetty:start` are alike in that they both run an unassembled webapp in jetty,however `jetty:run` is designed to be used at the command line, whereas `jetty:start` is specifically designed to be bound to execution phases in the build lifecycle.
`jetty:run` will pause maven while jetty is running, echoing all output to the console, and then stop maven when jetty exits.
@ -51,7 +51,7 @@ However, `jetty:run-war` is designed to be run at the command line, whereas `jet
====
While the Jetty Maven Plugin can be very useful for development we do not recommend its use in a _production capacity_.
In order for the plugin to work it needs to leverage many internal Maven apis and Maven itself it not a production deployment tool.
We recommend either the traditional link:{DISTGUIDE}[distribution] deployment approach or using link:#advanced-embedding[embedded Jetty].
We recommend either the traditional link:{DISTGUIDE}[distribution] deployment approach or using xref:advanced-embedding[embedded Jetty].
====
[[get-up-and-running]]
@ -131,9 +131,9 @@ These extra configuration parameters are available:
httpConnector::
Optional.
NOTE to configure a https connector, you will need to use xml configuration files instead, setting the `jettyXmls` parameter.
Note that 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:
@ -144,17 +144,17 @@ host:::
The particular interface for the connector to listen on.
By default, all interfaces.
name:::
The name of the connector, which is useful for link:#serving-webapp-from-particular-port[configuring contexts to respond only on particular connectors].
The name of the connector, which is useful for xref:serving-webapp-from-particular-port[configuring contexts to respond only on particular connectors].
idleTimeout:::
Maximum idle time for a connection.
You could instead configure the connectors in a standard link:#jetty-xml-config[jetty xml config file] and put its location into the `jettyXml` parameter.
Note that since Jetty 9.0 it is no longer possible to configure a link:#maven-config-https[https connector] directly in the pom.xml: you need to link:#maven-config-https[use jetty xml config files to do it].
You could instead configure the connectors in a standard xref:jetty-xml-config[jetty xml config file] and put its location into the `jettyXml` parameter.
Note that since Jetty 9.0 it is no longer possible to configure a xref:maven-config-https[https connector] directly in the pom.xml: you need to xref:maven-config-https[use jetty xml config files to do it].
loginServices::
Optional.
A list of `org.eclipse.jetty.security.LoginService` implementations. Note that there is no default realm.
If you use a realm in your `web.xml` you can specify a corresponding realm here.
You could instead configure the login services in a jetty xml file and add its location to the `jettyXml` parameter.
See link:#configuring-security-settings[Configuring Security].
See xref:configuring-security-settings[Configuring Security].
requestLog::
Optional.
An implementation of the `org.eclipse.jetty.server.RequestLog` request log interface.
@ -165,10 +165,10 @@ There are three other ways to configure the RequestLog:
* In a context xml config file, as specified in the `contextXml` parameter.
* In the `webApp` element.
+
See link:#configuring-jetty-request-logs[Configuring Request Logs] for more information.
See xref: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::
@ -176,7 +176,7 @@ Default value is `false`.
If true, the dependencies with `<scope>provided</scope>` are placed onto the __container classpath__.
Be aware that this is _not_ the webapp classpath, as `provided` indicates that these dependencies would normally be expected to be provided by the container.
You should very rarely ever need to use this.
See link:#container-classpath[Container Classpath vs WebApp Classpath].
See xref:container-classpath[Container Classpath vs WebApp Classpath].
===== Forked
@ -200,7 +200,7 @@ Default value is `false`.
If true, the dependencies with `<scope>provided</scope>` are placed onto the __container classpath__.
Be aware that this is NOT the webapp classpath, as "provided" indicates that these dependencies would normally be expected to be provided by the container.
You should very rarely ever need to use this.
See link:#container-classpath[Container Classpath vs WebApp Classpath].
See xref:container-classpath[Container Classpath vs WebApp Classpath].
===== In a jetty distribution
@ -228,7 +228,7 @@ A space separated string representing arguments that should be passed to the jvm
modules::
Optional.
An array of names of additional jetty modules that the jetty child process will activate.
Use this to change the link:#container-classpath[container classpath] instead of `useProvidedScope`.
Use this to change the xref:container-classpath[container classpath] instead of `useProvidedScope`.
These modules are enabled by default: `server,http,webapp,deploy`.
@ -242,7 +242,7 @@ One of `EMBED`, `FORK` or `EXTERNAL`.
Default `EMBED`.
Can also be configured by setting the Maven property `jetty.deployMode`.
This parameter determines whether the webapp will run in jetty in-process with Maven, forked into a new process, or deployed into a jetty distribution.
See link:#deployment-modes[Deployment Modes].
See xref:deployment-modes[Deployment Modes].
jettyXmls::
Optional.
A comma separated list of locations of jetty xml files to apply in addition to any plugin configuration parameters.
@ -265,12 +265,12 @@ The plugin will refuse to start if the &lt;packaging&gt; type in the pom is not
systemProperties::
Optional.
Allows you to configure System properties for the execution of the plugin.
For more information, see link:#setting-system-properties[Setting System Properties].
For more information, see xref:setting-system-properties[Setting System Properties].
systemPropertiesFile::
Optional.
A file containing System properties to set for the execution of the plugin.
By default, settings that you make here *do not* override any system properties already set on the command line, by the JVM, or in the POM via `systemProperties`.
Read link:#setting-system-properties[Setting System Properties] for how to force overrides.
Read xref:setting-system-properties[Setting System Properties] for how to force overrides.
jettyProperties::
Optional.
A map of property name, value pairs.
@ -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:
+
@ -370,16 +370,16 @@ This is an array of directory locations, either as urls or file paths.
baseAppFirst;;
Defaults to "true".
Controls whether any overlaid wars are added before or after the original base resource(s) of the webapp.
See the section on link:#using-overlaid-wars[overlaid wars] for more information.
See the section on xref:using-overlaid-wars[overlaid wars] for more information.
containerIncludeJarPattern;;
Defaults to `.*/jetty-jakarta-servlet-api-[^/]*\.jar$|.*jakarta.servlet.jsp.jstl-[^/]*\.jar|.*taglibs-standard-impl-.*\.jar`.
This is a pattern that is applied to the names of the jars on the container's classpath (ie the classpath of the plugin, not that of the webapp) that should be scanned for fragments, tlds, annotations etc.
This is analogous to the context attribute link:#container-include-jar-pattern[org.eclipse.jetty.server.webapp.ContainerIncludeJarPattern] that is documented link:#container-include-jar-pattern[here].
This is analogous to the context attribute xref:container-include-jar-pattern[org.eclipse.jetty.server.webapp.ContainerIncludeJarPattern] that is documented xref:container-include-jar-pattern[here].
You can define extra patterns of jars that will be included in the scan.
webInfIncludeJarPattern;;
Defaults to matching _all_ of the dependency jars for the webapp (ie the equivalent of WEB-INF/lib).
You can make this pattern more restrictive to only match certain jars by using this setter.
This is analogous to the context attribute link:#web-inf-include-jar-pattern[org.eclipse.jetty.server.webapp.WebInfIncludeJarPattern] that is documented link:#web-inf-include-jar-pattern[here].
This is analogous to the context attribute xref:web-inf-include-jar-pattern[org.eclipse.jetty.server.webapp.WebInfIncludeJarPattern] that is documented xref:web-inf-include-jar-pattern[here].
contextXml::
The path to a context xml file that is applied to your webapp AFTER the `webApp` element.
classesDirectory::
@ -410,7 +410,7 @@ Include and exclude patterns that can be applied to the testClassesDirectory for
If a file or directory is excluded by the patterns then a change in that file (or subtree in the case of a directory) is ignored and will not cause the webapp to redeploy.
Patterns are specified as a relative path using a glob-like syntax as described in the http://docs.oracle.com/javase/8/docs/api/java/nio/file/FileSystem.html#getPathMatcher-java.lang.String-[javadoc] for http://docs.oracle.com/javase/8/docs/api/java/nio/file/FileSystem.html#getPathMatcher-java.lang.String-[FileSystem.getPathMatcher].
See link:#deployment-modes[Deployment Modes] for other configuration parameters available when using the `run` goal in EMBED, FORK or EXTERNAL modes.
See xref:deployment-modes[Deployment Modes] for other configuration parameters available when using the `run` goal in EMBED, FORK or EXTERNAL modes.
Here's an example of a pom configuration for the plugin with the `run` goal:
@ -492,12 +492,12 @@ You can use this to replace or add configuration.
containerIncludeJarPattern:::
Defaults to `.*/jetty-jakarta-servlet-api-[^/]*\.jar$|.*jakarta.servlet.jsp.jstl-[^/]*\.jar|.*taglibs-standard-impl-.*\.jar`.
This is a pattern that is applied to the names of the jars on the container's classpath (ie the classpath of the plugin, not that of the webapp) that should be scanned for fragments, tlds, annotations etc.
This is analogous to the context attribute link:#container-include-jar-pattern[org.eclipse.jetty.server.webapp.ContainerIncludeJarPattern] that is documented link:#container-include-jar-pattern[here].
This is analogous to the context attribute xref:container-include-jar-pattern[org.eclipse.jetty.server.webapp.ContainerIncludeJarPattern] that is documented xref:container-include-jar-pattern[here].
You can define extra patterns of jars that will be included in the scan.
webInfIncludeJarPattern:::
Defaults to matching _all_ of the dependency jars for the webapp (ie the equivalent of WEB-INF/lib).
You can make this pattern more restrictive to only match certain jars by using this setter.
This is analogous to the context attribute link:#web-inf-include-jar-pattern[org.eclipse.jetty.server.webapp.WebInfIncludeJarPattern] that is documented link:#web-inf-include-jar-pattern[here].
This is analogous to the context attribute xref:web-inf-include-jar-pattern[org.eclipse.jetty.server.webapp.WebInfIncludeJarPattern] that is documented xref:web-inf-include-jar-pattern[here].
tempDirectory:::
The path to a dir that Jetty can use to expand or copy jars and jsp compiles when your webapp is running.
The default is `${project.build.outputDirectory}/tmp`.
@ -512,7 +512,7 @@ scanTargetPatterns::
Optional.
List of directories with ant-style include/excludes patterns to specify other files to periodically scan for changes.
See link:#deployment-modes[Deployment Modes] for other configuration parameters available when using the `run-war` goal in EMBED, FORK or EXTERNAL modes.
See xref:deployment-modes[Deployment Modes] for other configuration parameters available when using the `run-war` goal in EMBED, FORK or EXTERNAL modes.
[[jetty-start-goal]]
==== jetty:start
@ -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:
+
@ -596,16 +596,16 @@ This is an array of directory names.
baseAppFirst;;
Defaults to "true".
Controls whether any overlaid wars are added before or after the original base resource(s) of the webapp.
See the section on link:#using-overlaid-wars[overlaid wars] for more information.
See the section on xref:using-overlaid-wars[overlaid wars] for more information.
containerIncludeJarPattern;;
Defaults to `.*/jetty-jakarta-servlet-api-[^/]*\.jar$|.*jakarta.servlet.jsp.jstl-[^/]*\.jar|.*taglibs-standard-impl-.*\.jar`.
This is a pattern that is applied to the names of the jars on the container's classpath (ie the classpath of the plugin, not that of the webapp) that should be scanned for fragments, tlds, annotations etc.
This is analogous to the context attribute link:#container-include-jar-pattern[org.eclipse.jetty.server.webapp.ContainerIncludeJarPattern] that is documented link:#container-include-jar-pattern[here].
This is analogous to the context attribute xref:container-include-jar-pattern[org.eclipse.jetty.server.webapp.ContainerIncludeJarPattern] that is documented xref:container-include-jar-pattern[here].
You can define extra patterns of jars that will be included in the scan.
webInfIncludeJarPattern;;
Defaults to matching _all_ of the dependency jars for the webapp (ie the equivalent of WEB-INF/lib).
You can make this pattern more restrictive to only match certain jars by using this setter.
This is analogous to the context attribute link:#web-inf-include-jar-pattern[org.eclipse.jetty.server.webapp.WebInfIncludeJarPattern] that is documented link:#web-inf-include-jar-pattern[here].
This is analogous to the context attribute xref:web-inf-include-jar-pattern[org.eclipse.jetty.server.webapp.WebInfIncludeJarPattern] that is documented xref:web-inf-include-jar-pattern[here].
contextXml::
The path to a context xml file that is applied to your webapp AFTER the `webApp` element.
classesDirectory::
@ -620,11 +620,11 @@ By default this is false.
stopPort::
Optional.
Port to listen on for stop commands.
Useful to use in conjunction with the link:#jetty-stop-goal[stop] and link:#jetty-start-goal[start] goals.
Useful to use in conjunction with the xref:jetty-stop-goal[stop] and xref:jetty-start-goal[start] goals.
stopKey::
Optional.
Used in conjunction with stopPort for stopping jetty.
Useful to use in conjunction with the link:#jetty-stop-goal[stop] and link:#jetty-start-goal[start] goals.
Useful to use in conjunction with the xref:jetty-stop-goal[stop] and xref:jetty-start-goal[start] goals.
These additional configuration parameters are available when running in `FORK` or `EXTERNAL` mode:
@ -672,12 +672,12 @@ You can use this to replace or add configuration.
containerIncludeJarPattern:::
Defaults to `.*/jetty-jakarta-servlet-api-[^/]*\.jar$|.*jakarta.servlet.jsp.jstl-[^/]*\.jar|.*taglibs-standard-impl-.*\.jar`.
This is a pattern that is applied to the names of the jars on the container's classpath (ie the classpath of the plugin, not that of the webapp) that should be scanned for fragments, tlds, annotations etc.
This is analogous to the context attribute link:#container-include-jar-pattern[org.eclipse.jetty.server.webapp.ContainerIncludeJarPattern] that is documented link:#container-include-jar-pattern[here].
This is analogous to the context attribute xref:container-include-jar-pattern[org.eclipse.jetty.server.webapp.ContainerIncludeJarPattern] that is documented xref:container-include-jar-pattern[here].
You can define extra patterns of jars that will be included in the scan.
webInfIncludeJarPattern:::
Defaults to matching _all_ of the dependency jars for the webapp (ie the equivalent of WEB-INF/lib).
You can make this pattern more restrictive to only match certain jars by using this setter.
This is analogous to the context attribute link:#web-inf-include-jar-pattern[org.eclipse.jetty.server.webapp.WebInfIncludeJarPattern] that is documented link:#web-inf-include-jar-pattern[here].
This is analogous to the context attribute xref:web-inf-include-jar-pattern[org.eclipse.jetty.server.webapp.WebInfIncludeJarPattern] that is documented xref:web-inf-include-jar-pattern[here].
tempDirectory:::
The path to a dir that Jetty can use to expand or copy jars and jsp compiles when your webapp is running.
The default is `${project.build.outputDirectory}/tmp`.
@ -686,11 +686,11 @@ The path to a context xml file that is applied to your webapp AFTER the `webApp`
stopPort::
Optional.
Port to listen on for stop commands.
Useful to use in conjunction with the link:#jetty-stop-goal[stop].
Useful to use in conjunction with the xref:jetty-stop-goal[stop].
stopKey::
Optional.
Used in conjunction with stopPort for stopping jetty.
Useful to use in conjunction with the link:#jetty-stop-goal[stop].
Useful to use in conjunction with the xref:jetty-stop-goal[stop].
These additional configuration parameters are available when running in FORK or EXTERNAL mode:
@ -753,7 +753,7 @@ No programmatic declarations of servlets, filters and listeners can be taken int
You can calculate the effective web.xml for any pre-built war file by setting the `&lt;webApp&gt;&lt;war&gt;` parameter, or you can calculate it for the unassembled webapp by setting all of the usual `&lt;webApp&gt;` parameters as for `jetty:run`.
Other useful information about your webapp that is produced as part of the analysis is also stored as context parameters in the effective-web.xml.
The effective-web.xml can be used in conjunction with the link:#quickstart-webapp[Quickstart] feature to quickly start your webapp (note that Quickstart is not appropriate for the mvn jetty goals).
The effective-web.xml can be used in conjunction with the xref:quickstart-webapp[Quickstart] feature to quickly start your webapp (note that Quickstart is not appropriate for the mvn jetty goals).
The effective web.xml from these combined sources is generated into a file, which by default is `target/effective-web.xml`, but can be changed by setting the `effectiveWebXml` configuration parameter.
@ -765,7 +765,7 @@ webApp::
war:::
The location of the built WAR file. This defaults to `${project.build.directory}/${project.build.finalName}.war`.
You can set it to the location of any pre-built war file.
Or you can leave it blank and set up the other `webApp` parameters as per link:#jetty-run-goal[jetty:run], as well as the `webAppSourceDirectory`, `classes` and `testClasses` parameters.
Or you can leave it blank and set up the other `webApp` parameters as per xref:jetty-run-goal[jetty:run], as well as the `webAppSourceDirectory`, `classes` and `testClasses` parameters.
contextPath:::
The context path for your webapp. By default, this is set to `/`.
If using a custom value for this parameter, you should include the leading `/`, example `/mycontext`.
@ -778,12 +778,12 @@ You can use this to replace or add configuration.
containerIncludeJarPattern:::
Defaults to `.*/jetty-jakarta-servlet-api-[^/]*\.jar$|.*jakarta.servlet.jsp.jstl-[^/]*\.jar|.*taglibs-standard-impl-.*\.jar`.
This is a pattern that is applied to the names of the jars on the container's classpath (ie the classpath of the plugin, not that of the webapp) that should be scanned for fragments, tlds, annotations etc.
This is analogous to the context attribute link:#container-include-jar-pattern[org.eclipse.jetty.server.webapp.ContainerIncludeJarPattern] that is documented link:#container-include-jar-pattern[here].
This is analogous to the context attribute xref:container-include-jar-pattern[org.eclipse.jetty.server.webapp.ContainerIncludeJarPattern] that is documented xref:container-include-jar-pattern[here].
You can define extra patterns of jars that will be included in the scan.
webInfIncludeJarPattern:::
Defaults to matching _all_ of the dependency jars for the webapp (ie the equivalent of WEB-INF/lib).
You can make this pattern more restrictive to only match certain jars by using this setter.
This is analogous to the context attribute link:#web-inf-include-jar-pattern[org.eclipse.jetty.server.webapp.WebInfIncludeJarPattern] that is documented link:#web-inf-include-jar-pattern[here].
This is analogous to the context attribute xref:web-inf-include-jar-pattern[org.eclipse.jetty.server.webapp.WebInfIncludeJarPattern] that is documented xref:web-inf-include-jar-pattern[here].
tempDirectory:::
The path to a dir that Jetty can use to expand or copy jars and jsp compiles when your webapp is running.
The default is `${project.build.outputDirectory}/tmp`.
@ -815,7 +815,7 @@ False by default. If true, will force the generation of the originAttribute onto
[[using-overlaid-wars]]
==== Using Overlaid wars
If your webapp depends on other war files, the link:#jetty-run-goal[jetty:run] and link:#jetty-start-goal[jetty:start] goals are able to merge resources from all of them.
If your webapp depends on other war files, the xref:jetty-run-goal[jetty:run] and xref:jetty-start-goal[jetty:start] goals are able to merge resources from all of them.
It can do so based on the settings of the http://maven.apache.org/plugins/maven-war-plugin/[maven-war-plugin], or if your project does not use the http://maven.apache.org/plugins/maven-war-plugin/[maven-war-plugin] to handle the overlays, it can fall back to a simple algorithm to determine the ordering of resources.
===== With maven-war-plugin
@ -898,7 +898,7 @@ Similarly as `baz.jsp` is excluded, a request for it would result in a 404 error
===== Without maven-war-plugin
The algorithm is fairly simple, is based on the ordering of declaration of the dependent wars, and does not support exclusions.
The configuration parameter `<baseAppFirst>` (see for example link:#jetty-run-goal[jetty:run] for more information) can be used to control whether your webapp's resources are placed first or last on the resource path at runtime.
The configuration parameter `<baseAppFirst>` (see for example xref:jetty-run-goal[jetty:run] for more information) can be used to control whether your webapp's resources are placed first or last on the resource path at runtime.
For example, suppose our webapp depends on these two wars:
@ -1116,7 +1116,7 @@ In the latter case, you can use the link:http://www.mojohaus.org/[maven properti
[NOTE]
====
If a System property is already set (for example, from the command line or by the JVM itself), then by default these configured properties *DO NOT* override them.
However, they can override system properties set from a file instead, see link:#specifying-properties-in-file[specifying system properties in a file].
However, they can override system properties set from a file instead, see xref:specifying-properties-in-file[specifying system properties in a file].
====
[[specifying-properties-in-pom]]

6
documentation/jetty-documentation/src/main/asciidoc/programming-guide/server/compliance/server-compliance-cookie.adoc
View File

@ -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]
----

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

@ -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]
----

6
documentation/jetty-documentation/src/main/asciidoc/programming-guide/server/compliance/server-compliance-uri.adoc
View File

@ -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]
----

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

@ -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[]

17
documentation/jetty-documentation/src/main/asciidoc/programming-guide/server/fastcgi/server-fastcgi.adoc Normal file
View File

@ -0,0 +1,17 @@
//
// ========================================================================
// Copyright (c) 1995-2021 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[pg-server-fastcgi]]
=== FastCGI Server Libraries
TODO

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

@ -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.

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

@ -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`:

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

@ -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:

6
documentation/jetty-documentation/src/main/asciidoc/programming-guide/server/sessions/session-cachingsessiondatastore.adoc
View File

@ -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

26
documentation/jetty-documentation/src/main/asciidoc/programming-guide/server/sessions/session-sessioncache.adoc
View File

@ -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

2
documentation/jetty-documentation/src/main/asciidoc/programming-guide/server/sessions/session-sessiondatastore-file.adoc
View File

@ -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::

2
documentation/jetty-documentation/src/main/asciidoc/programming-guide/server/sessions/session-sessiondatastore-jdbc.adoc
View File

@ -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]

4
documentation/jetty-documentation/src/main/asciidoc/programming-guide/server/sessions/session-sessiondatastore-mongo.adoc
View File

@ -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]

11
documentation/jetty-documentation/src/main/asciidoc/programming-guide/server/sessions/session-sessiondatastore.adoc
View File

@ -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.
@ -61,7 +61,6 @@ Normally, whenever the last concurrent request leaves a `Session`, the `SessionD
If the `savePeriod` is non-zero, the `SessionData` will not be persisted if no session attributes changed, _unless_ the time since the last save exceeds the `savePeriod`.
Setting a non-zero value can reduce the load on the persistence mechanism, but in a clustered environment runs the risk that other nodes will see the session as expired because it has not been persisted sufficiently recently.
[[pg-server-session-datastore-grace]]
gracePeriod::
The `gracePeriod` is an interval defined in seconds.
It is an attempt to deal with the non-transactional nature of sessions with regard to finding sessions that have expired.
@ -73,5 +72,7 @@ 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`.
====

10
documentation/jetty-documentation/src/main/asciidoc/programming-guide/server/sessions/session-sessionhandler.adoc
View File

@ -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::
@ -49,7 +49,7 @@ This can also be configured by:
refreshCookieAge::
Integer, seconds, default is `-1`.
This controls resetting the session cookie when `SessionCookieConfig.setMaxAge(int)` is non-zero.
See also xref:pg-server-session-maxAge[setting the max session cookie age with an init parameter].
See also xref:pg-server-session-handler-maxAge[setting the max session cookie age with an init parameter].
If the amount of time since the session cookie was last set exceeds this time, the session cookie is regenerated to keep the session cookie valid.
sameSite::
@ -78,7 +78,6 @@ It can alternatively be configured by:
* setting the `org.eclipse.jetty.servlet.SessionIdPathParameterName` context init parameter
sessionTrackingModes::
`Set<javax.servlet.SessionTrackingMode>`.
Default is `SessionTrackingMode.COOKIE`, `SessionTrackingMode.URL`.
@ -97,19 +96,17 @@ This can also be configured by:
* using the `setSessionTrackingModes(Set<javax.servlet.SessionTrackingMode>)` method
* using the `javax.servlet.ServletContext.setSessionTrackingModes<Set<javax.servlet.SessionTrackingMode>)` method
There are also a few session settings that do not have SessionHandler setters, but can be configured with context init parameters:
[[pg-server-session-handler-maxAge]]
org.eclipse.jetty.servlet.MaxAge::
This is the maximum number of seconds that the session cookie will be considered to be valid.
By default, the cookie has no maximum validity time.
See also xref:pg-server-session-refreshcookie[refreshing the session cookie].
See also xref:pg-server-session-handler-refreshcookie[refreshing the session cookie].
The value can also be configured by:
* calling the `SessionCookieConfig.setMaxAge(int)` method.
org.eclipse.jetty.servlet.SessionDomain::
String, default `null`.
This is the domain of the session cookie.
@ -118,7 +115,6 @@ This can also be configured by:
* using the `javax.servlet.SessionCookieConfig.setDomain(String)` method
* defining the `<session-config><cookie-config><domain/></cookie-config></session-config>` element in `web.xml`
org.eclipse.jetty.servlet.SessionPath::
String, default `null`.
This is used when creating a new session cookie.

6
documentation/jetty-documentation/src/main/asciidoc/programming-guide/server/sessions/session-sessionidmgr.adoc
View File

@ -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.

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

@ -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