Fixed cross references from "link:#" to "xref:".
Fixed links prepending "link:". Fixed Asciidoctor errors reported during build. Signed-off-by: Simone Bordet <simone.bordet@gmail.com>
This commit is contained in:
Simone Bordet
parent
f240d7ac42
commit
34c03ddf1d
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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[]
|
||||
|
|
|
|||
|
|
@ -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`.
|
||||
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,30 +126,29 @@ 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>
|
||||
};
|
||||
};
|
||||
----
|
||||
<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
|
||||
|
|
@ -162,22 +158,21 @@ Refer to the https://docs.oracle.com/javase/7/docs/api/javax/security/auth/login
|
|||
* 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:{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>
|
||||
|
|
@ -189,7 +184,7 @@ jdbc { <1>
|
|||
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,9 +220,8 @@ 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>
|
||||
|
|
@ -239,7 +231,7 @@ ds { <1>
|
|||
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>
|
||||
};
|
||||
};
|
||||
----
|
||||
<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,9 +285,8 @@ 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>
|
||||
|
|
@ -318,7 +307,7 @@ example { <1>
|
|||
roleObjectClass="groupOfUniqueNames"; <19>
|
||||
forceBindingLogin="false" <20>
|
||||
debug="false" <21>
|
||||
};
|
||||
};
|
||||
----
|
||||
<1> The name of the configuration.
|
||||
<2> The name of the `LoginModule` class.
|
||||
|
|
|
|||
|
|
@ -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:{javadoc-url}/org/eclipse/jetty/plus/jndi/Transaction.html[org.eclipse.jetty.plus.jndi.Transaction] object in a link:#og-jndi-xml[Jetty XML file] to configure the JTA manager.
|
||||
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">
|
||||
|
|
|
|||
|
|
@ -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>
|
||||
<servlet id="jsp"> <!--1-->
|
||||
<servlet-name>jsp</servlet-name> <!--2-->
|
||||
<init-param>
|
||||
<param-name>keepgenerated</param-name> <3>
|
||||
<param-value>true</param-value> <4>
|
||||
<param-name>keepgenerated</param-name> <!--3-->
|
||||
<param-value>true</param-value> <!--4-->
|
||||
</init-param>
|
||||
</servlet>
|
||||
</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,10 +197,10 @@ 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>
|
||||
----
|
||||
|
|
@ -207,4 +208,3 @@ Here's an example of using a context xml file to add in a pattern to match files
|
|||
<2> Specifies a context attribute.
|
||||
<3> Specifies the name of the context attribute.
|
||||
<4> Adds the additional pattern `+.*/jsf-[^/]*\.jar$+` to those already existing.
|
||||
|
||||
|
|
|
|||
|
|
@ -97,7 +97,7 @@ For example: `jetty.httpConfig.compliance=RFC2616`.
|
|||
* 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.
|
||||
|
|
@ -108,7 +108,7 @@ For example: `jetty.httpConfig.compliance=RFC3986`.
|
|||
* 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`::
|
||||
|
|
@ -120,8 +120,7 @@ For example: `jetty.httpConfig.compliance=RFC6265`.
|
|||
* 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
|
||||
|
|
|
|||
|
|
@ -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[]
|
||||
|
|
|
|||
|
|
@ -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:
|
||||
|
||||
|
|
|
|||
|
|
@ -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:
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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].
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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].
|
||||
|
|
|
|||
|
|
@ -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,7 +131,7 @@ 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:{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`.
|
||||
|
|
@ -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,7 +165,7 @@ 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 `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.
|
||||
|
|
@ -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 <packaging> 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.
|
||||
|
|
@ -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-servlet-api-[^/]*\.jar$|.*javax.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-servlet-api-[^/]*\.jar$|.*javax.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
|
||||
|
|
@ -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-servlet-api-[^/]*\.jar$|.*javax.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-servlet-api-[^/]*\.jar$|.*javax.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 `<webApp><war>` parameter, or you can calculate it for the unassembled webapp by setting all of the usual `<webApp>` 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-servlet-api-[^/]*\.jar$|.*javax.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]]
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
@ -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:{javadoc-url}/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`.
|
||||
====
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
Loading…
Reference in New Issue