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

Merge pull request #712 from WalkerWatch/jetty-9.3.x 

Chapter 8 and 9 cleanup.
This commit is contained in:
Joakim Erdfelt 2016-07-12 16:32:35 -07:00 committed by GitHub
parent c77562bc95 00551d73b2
commit 27195a3b04
11 changed files with 352 additions and 641 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
jetty-documentation/src/main/asciidoc/administration/startup/chapter.adoc
View File

@ -18,10 +18,10 @@
== Starting Jetty
include::startup-overview.adoc[]
include::start-jar.adoc[]
include::startup-base-vs-home.adoc[]
include::startup-xml-config.adoc[]
include::startup-classpath.adoc[]
include::startup-modules.adoc[]
include::startup-base-vs-home.adoc[]
include::start-jar.adoc[]
include::startup-unix-service.adoc[]
include::startup-windows-service.adoc[]
include::startup-windows-service.adoc[]

6
jetty-documentation/src/main/asciidoc/administration/startup/screen-empty-base-listconfig.adoc
View File

@ -20,13 +20,13 @@
Java Environment:
-----------------
java.home = /lib/jvm/jdk-8u45/jre
java.home = /lib/jvm/jdk-8u92/jre
java.vm.vendor = Oracle Corporation
java.vm.version = 25.45-b02
java.vm.version = 25.45-b14
java.vm.name = Java HotSpot(TM) 64-Bit Server VM
java.vm.info = mixed mode
java.runtime.name = Java(TM) SE Runtime Environment
java.runtime.version = 1.8.0_45-b14
java.runtime.version = 1.8.0_92-b14
java.io.tmpdir = /tmp
user.dir = /home/jetty/mybase
user.language = en

8
jetty-documentation/src/main/asciidoc/administration/startup/screen-empty-base.adoc
View File

@ -16,6 +16,14 @@
[source, screen, subs="{sub-order}"]
....
[jetty]$ mkdir mybase
[jetty]$ cd mybase
[mybase]$ ls -la
total 0
drwxr-xr-x 2 staff staff 68 Jul 12 17:29 .
drwxr-xr-x 20 staff staff 680 Jul 12 17:29 ..
[mybase]$ java -jar $JETTY_HOME/start.jar
WARNING: Nothing to start, exiting ...
Usage: java -jar start.jar [options] [properties] [configs]

240
jetty-documentation/src/main/asciidoc/administration/startup/start-jar.adoc
View File

@ -17,9 +17,7 @@
[[start-jar]]
=== Using start.jar
The most basic way of starting the Jetty standalone server is to execute
the `start.jar`, which is a bootstrap for starting Jetty with the
configuration you want.
The most basic way of starting the Jetty standalone server is to execute the `start.jar`, which is a bootstrap for starting Jetty with the configuration you want.
[source, screen, subs="{sub-order}"]
....
@ -28,153 +26,114 @@ configuration you want.
...
....
Jetty is a highly modularized web server container. Very little is
mandatory and required, and most components are optional; you enable or
disable them according to the needs of your environment.
Jetty is a highly modularized web server container.
Very little is mandatory and required, and most components are optional; you enable or disable them according to the needs of your environment.
At its most basic, you configure Jetty from two elements:
1. A set of libraries and directories that make up the server
classpath.
2. A set of Jetty XML configuration files (IoC style) that establish
how to build the Jetty server and its components.
1. A set of libraries and directories that make up the server classpath.
2. A set of Jetty XML configuration files (IoC style) that establish how to build the Jetty server and its components.
Starting with Jetty 9.1 you have more options on how to configure Jetty
(these are merely syntactic sugar that eventually resolve into the two
basic configuration components).
Instead of editing these directly, Jetty 9.1 introduced more options on how to configure Jetty (these are merely syntactic sugar that eventually resolve into the two basic configuration components).
Jetty 9.1 Startup Features include:
* A separation of the Jetty distribution binaries in `${jetty.home}` and
the environment specific configurations (and binaries) found in
`${jetty.base}` (detailed in
link:#startup-jetty-base-and-jetty-home[Managing Jetty Base and Jetty
Home.])
* You can enable a set of libraries and XML configuration files via the
newly introduced link:#startup-modules[module system.]
* All of the pre-built XML configuration files shipped in Jetty are now
parameterized with properties that you can specify in your
`${jetty.base}/start.ini` (demonstrated in
link:#quick-start-configure[Quick Start Configuration]).
+
There is no longer a
* A separation of the Jetty distribution binaries in `${jetty.home}` and the environment specific configurations (and binaries) found in `${jetty.base}` (detailed in link:#startup-jetty-base-and-jetty-home[Managing Jetty Base and Jetty Home.])
* You can enable a set of libraries and XML configuration files via the newly introduced link:#startup-modules[module system.]
* All of the pre-built XML configuration files shipped in Jetty are now parameterized with properties that you can specify in your `${jetty.base}/start.ini` (demonstrated in link:#quick-start-configure[Quick Start Configuration]).
These are powerful new features, made to support a variety of styles of
configuring Jetty, from a simple property based configuration, to
handling multiple installations on a server, to customized stacks of
technology on top of Jetty, and even the classic, custom XML
configurations of old.
These are powerful new features, made to support a variety of styles of configuring Jetty, from a simple property based configuration, to handling multiple installations on a server, to customized stacks of technology on top of Jetty, and even the classic, custom XML configurations of old.
For example, if you use the `${jetty.base}` concepts properly, you can
upgrade the Jetty distribution without having to remake your entire tree
of modifications to Jetty. Simply separate out your specific
modifications to the `${jetty.base}`, and in the future, just upgrade
your `${jetty.home}` directory with a new Jetty distribution.
For example, if you use the `${jetty.base}` concepts properly, you can upgrade the Jetty distribution without having to remake your entire tree of modifications to Jetty.
Simply separate out your specific modifications to the `${jetty.base}`, and in the future, just upgrade your `${jetty.home}` directory with a new Jetty distribution.
* Loads and parses all INIs found in `${jetty.base}/start.d/*.ini` as
command line arguments.
[[executing-startjar]]
==== Executing start.jar
When executed `start.jar` performs the following actions:
* Loads and parses all INIs found in `${jetty.base}/start.d/*.ini` as command line arguments.
* Loads and parses `${jetty.base}/start.ini` as command line arguments.
* Parses actual command line arguments used to execute `start.jar`
itself.
* Resolves any XML configuration files, modules, and libraries using
base vs. home resolution steps:
* Parses actual command line arguments used to execute `start.jar` itself.
* Resolves any XML configuration files, modules, and libraries using base vs. home resolution steps:
1. Checks whether file exists as relative reference to `${jetty.base}.`
2. Checks whether file exists as relative reference to `${jetty.home}.`
3. Uses default behavior of `java.io.File.`
+
(Relative to `System.getProperty` ("user.dir") and then as absolute file
system path)
* Loads any dependent modules (merges XXNK, library, and properties
results with active command line).
3. Uses default behavior of `java.io.File` (Relative to `System.getProperty` ("user.dir") and then as absolute file system path).
* Loads any dependent modules (merges XXNK, library, and properties results with active command line).
* Builds out server classpath.
* Determines run mode:
** Shows informational command line options and exit.
** Executes Jetty normally, waits for Jetty to stop.
** Executes a forked JVM to run Jetty in, waits for forked JVM to exit.
* If you want to start Jetty:
** Load each XML configuration (in the order determined by the INIs and
module system).
** Let XML configuration start Jetty.
==== start.jar Command Line Options
--help::
Obtains the current list of command line options and some basic usage
help.
Obtains the current list of command line options and some basic usage help.
--version::
Shows the list of server classpath entries, and prints version
information found for each entry.
Shows the list of server classpath entries, and prints version information found for each entry.
--list-classpath::
Similar to --version, shows the server classpath.
Similar to --version, shows the server classpath.
--list-config::
Lists the resolved configuration that will start Jetty.
+
* Java environment
* Jetty environment
* JVM arguments
* Properties
* Server classpath
* Server XML configuration files
--dry-run::
Prints the resolved command line that `start.jar` should use to start
a forked instance of Jetty.
--exec::
Starts a forked instance of Jetty.
Lists the resolved configuration that will start Jetty.
+
* Java environment
* Jetty environment
* JVM arguments
* Properties
* Server classpath
* Server XML configuration files
--dry-run::
Prints the resolved command line that `start.jar` should use to start a forked instance of Jetty.
--exec::
Starts a forked instance of Jetty.
--debug::
Enables debugging output of the startup procedure.
+
Note: This does not set up debug logging for Jetty itself.
Enables debugging output of the startup procedure.
+
*Note*: This does not set up debug logging for Jetty itself.
For information on logging, please see the section on <<configuring-jetty-logging, Configuring Jetty Logging.>>
--start-log-file=<filename>::
Sends all startup output to the filename specified.
+
Filename is relative to `${jetty.base}`.
+
This is useful for capturing startup issues where the Jetty-specific
logger has not yet kicked in due to a possible startup configuration
error.
+
Filename is relative to `${jetty.base}`.
This is useful for capturing startup issues where the Jetty-specific logger has not yet kicked in due to a possible startup configuration error.
--list-modules::
Lists all the modules defined by the system.
+
Looks for module files using the link:#startup-base-and-home[normal
`${jetty.base}` and `${jetty.home}` resolution logic].
+
Also lists enabled state based on information present on the command
line, and all active startup INI files.
Lists all the modules defined by the system.
+
Looks for module files using the link:#startup-base-and-home[normal `${jetty.base}` and `${jetty.home}` resolution logic].
+
Also lists enabled state based on information present on the command line, and all active startup INI files.
--module=<name>,(<name>)*::
Enables one or more modules by name (use --list-modules to see the
list of available modules).
+
This enables all transitive (dependent) modules from the module system
as well.
+
If you use this from the shell command line, it is considered a
temporary effect, useful for testing out a scenario. If you want this
module to always be enabled, add this command to your
`${jetty.base}/start.ini.`
Enables one or more modules by name (use `--list-modules` to see the list of available modules).
+
This enables all transitive (dependent) modules from the module system as well.
+
If you use this from the shell command line, it is considered a temporary effect, useful for testing out a scenario.
If you want this module to always be enabled, add this command to your `${jetty.base}/start.ini.`
--add-to-start=<name>,(<name>)*::
Enables a module by appending lines to the `${jetty.base}/start.ini`
file.
+
The lines that are added are provided by the module-defined INI
templates.
+
Note: Transitive modules are also appended.
Enables a module by appending lines to the `${jetty.base}/start.ini` file.
+
The lines that are added are provided by the module-defined INI templates.
+
Note: Transitive modules are also appended.
--add-to-startd=<name>,(<name>)*::
Enables a module via creation of a module-specific INI file in the
`${jetty.base}/start.d/` directory.
+
The content of the new INI is provided by the module-defined ini
templates.
+
Note: Transitive modules are also created in the same directory as
their own INI files.
Enables a module via creation of a module-specific INI file in the `${jetty.base}/start.d/` directory.
+
The content of the new INI is provided by the module-defined ini templates.
+
Note: Transitive modules are also created in the same directory as their own INI files.
[NOTE]
--
With respect to `start.ini` and `start.d/*.ini` files, only *one* of these methods should be implemented.
Mixing a `start.ini` with module specific ini files in the `{$jetty.base}/start.d` directory can lead to server issues unless great care is taken.
--
--write-module-graph=<filename>::
Advanced feature: Creates a graphviz
http://graphviz.org/content/dot-language[dot file] of the module graph
as it exists for the active `${jetty.base}`.
+
Advanced feature: Creates a graphviz http://graphviz.org/content/dot-language[dot file] of the module graph as it exists for the active `${jetty.base}`.
+
[source, screen, subs="{sub-order}"]
....
# generate module.dot
@ -183,33 +142,26 @@ $ java -jar start.jar --module=websocket --write-module-graph=modules.dot
# post process to a PNG file
$ dot -Tpng -o modules.png modules.dot
....
+
See http://graphviz.org/[graphviz.org] for details on
http://graphviz.org/content/command-line-invocation[how to
post-process this dotty file] into the output best suited for your
needs.
+
See http://graphviz.org/[graphviz.org] for details on http://graphviz.org/content/command-line-invocation[how to post-process this dotty file] into the output best suited for your needs.
--stop::
Sends a stop signal to the running Jetty instance.
+
Note: The server must have been started with various stop properties
for this to work.
+
STOP.PORT=<number>;;
The port to use to stop the running Jetty server. This is an
internal port, opened on localhost, used solely for stopping the
running Jetty server. Choose a port that you do not use to serve web
traffic.
+
Required for --stop to function.
STOP.KEY=<alphanumeric>;;
The passphrase defined to stop the server.
+
Required for --stop to function.
STOP.WAIT=<number>;;
The time (in seconds) to wait for confirmation that the running
Jetty server has stopped. If not specified, the stopper waits
indefinitely for the server to stop.
+
If the time specified elapses, without a confirmation of server
stop, then the --stop command exits with a non-zero return code.
Sends a stop signal to the running Jetty instance.
+
Note: The server must have been started with various stop properties for this to work.
STOP.PORT=<number>;;
The port to use to stop the running Jetty server.
This is an internal port, opened on localhost, used solely for stopping the running Jetty server.
Choose a port that you do not use to serve web traffic.
+
Required for --stop to function.
STOP.KEY=<alphanumeric>;;
The passphrase defined to stop the server.
+
Required for --stop to function.
STOP.WAIT=<number>;;
The time (in seconds) to wait for confirmation that the running Jetty server has stopped.
If not specified, the stopper waits indefinitely for the server to stop.
+
If the time specified elapses, without a confirmation of server stop, then the `--stop` command exits with a non-zero return code.

110
jetty-documentation/src/main/asciidoc/administration/startup/startup-base-vs-home.adoc
View File

@ -17,53 +17,40 @@
[[startup-base-and-home]]
=== Managing Jetty Base and Jetty Home
Starting with Jetty 9.1, it is now possible to maintain a separation
between the binary installation of the standalone Jetty (known as
`${jetty.home}`), and the customizations for your specific environment
(known as `${jetty.base}`).
Starting with Jetty 9.1, it is possible to maintain a separation between the binary installation of the standalone Jetty (known as `${jetty.home}`), and the customizations for your specific environment (known as `${jetty.base}`).
Jetty Base::
Also known as the `${jetty.base}` property
+
This is the location for your configurations and customizations to the
Jetty distribution.
* Also known as the `${jetty.base}` property.
* This is the location for your configurations and customizations to the Jetty distribution.
Jetty Home::
Also known as the `${jetty.home}` property.
+
This is the location for the Jetty distribution binaries, default XML
IoC configurations, and default module definitions.
* Also known as the `${jetty.home}` property.
* This is the location for the Jetty distribution binaries, default XML IoC configurations, and default module definitions.
Potential configuration is resolved from these 2 directory locations.
Check Jetty Base::
If the referenced configuration exists, relative to the defined Jetty
Base, use it.
If the referenced configuration exists, relative to the defined Jetty base, use it.
Check Jetty Home::
If the referenced configuration exists, relative to the defined Jetty
Home, use it.
If the referenced configuration exists, relative to the defined Jetty home, use it.
Use java.io.File(String pathname) Logic::
Lastly, use the reference as a `java.io.File(String
pathname)` reference, following the default resolution rules
outlined by that constructor.
+
In brief, the reference will be used as-is, be it relative (to current
working directory, aka $\{user.dir}) or absolute path, or even network
reference (such as on Windows and use of UNC paths).
Lastly, use the reference as a `java.io.File(String pathname)` reference, following the default resolution rules outlined by that constructor.
For more details on how startup with start.jar works, see
link:#execute-start-jar[Using start.jar: Executing]
+
In brief, the reference will be used as-is, be it relative (to current working directory, aka $\{user.dir}) or absolute path, or even network reference (such as on Windows and use of UNC paths).
For more details on how startup with start.jar works, see link:#execute-start-jar[Using start.jar: Executing]
[[demo-base]]
==== Demo-Base in the Jetty Distribution
The Jetty Distribution comes with an example $\{jetty.base} which
enables the various demonstration webapps and server configurations.
The Jetty Distribution comes with an example `${jetty.base}` which enables the various demonstration webapps and server configurations.
How to use the demo-base directory as a Jetty Base directory.
[source, screen, subs="{sub-order}"]
....
[jetty-distribution-{VERSION}]$ ls -la
total 496
drwxrwxr-x 11 user group 4096 Oct 8 15:23 ./
drwxr-xr-x 14 user group 4096 Oct 8 13:04 ../
@ -82,8 +69,10 @@ drwxrwxr-x 2 user group 4096 Oct 8 06:54 start.d/
-rw-rw-r-- 1 user group 71921 Sep 30 19:55 start.jar
-rw-rw-r-- 1 user group 336468 Sep 30 19:55 VERSION.txt
drwxrwxr-x 2 user group 4096 Oct 8 06:54 webapps/
[jetty-distribution-{VERSION}]$ cd demo-base
[demo-base]$ java -jar $JETTY_HOME/start.jar
2013-10-16 09:08:47.800:WARN::main: demo test-realm is deployed. DO NOT USE IN PRODUCTION!
2013-10-16 09:08:47.802:INFO:oejs.Server:main: jetty-{VERSION}
2013-10-16 09:08:47.817:INFO:oejdp.ScanningAppProvider:main: Deployment monitor [file:/home/user/jetty-distribution-{VERSION}/demo-base/webapps/] at interval 1
@ -91,11 +80,9 @@ drwxrwxr-x 2 user group 4096 Oct 8 06:54 webapps/
...
....
As you can see above, you are executing the demo-base configuration
using the Jetty Base concepts.
As you can see above, you are executing the demo-base configuration using the Jetty base concepts.
If you want to see what the Jetty Base looks like without executing
Jetty, you can simply list the configuration
If you want to see what the Jetty base looks like without executing Jetty, you can simply list the configuration
[source, screen, subs="{sub-order}"]
....
@ -210,22 +197,17 @@ Jetty Active XMLs:
${jetty.base}/etc/test-realm.xml
....
This demonstrates the powerful `--list-config` command line option and
how you can use it to see what the configuration will look like when
starting Jetty. From the Java environment, to the system properties, to
the classpath, and finally the Active Jetty IoC XML used to build up
your Jetty server configuration.
This demonstrates the powerful `--list-config` command line option and how you can use it to see what the configuration will look like when starting Jetty.
From the Java environment, to the system properties, to the classpath, and finally the Active Jetty IoC XML used to build up the Jetty server configuration.
Of note, is that the output will make it known where the configuration
elements came from, be it in either in `${jetty.home}` or
`${jetty.base}`.
Of note, is that the output will make it known where the configuration elements came from, be it in either in `${jetty.home}` or `${jetty.base}`.
If you look at the $\{jetty.base}/start.ini you will see something like
the following.
If you look at the `${jetty.base}/start.ini` you will see a layout similar to below.
[source, screen, subs="{sub-order}"]
....
[my-base]$ cat start.ini
# Enable security via jaas, and configure it
--module=jaas
jaas.login.conf=etc/login.conf
@ -259,71 +241,64 @@ jetty.dump.stop=false
--module=annotations
....
The $\{jetty.base}/start.ini is the main startup configuration entry
point for Jetty. In this example you will see that we are enabling a few
modules for Jetty, specifying some properties, and also referencing some
Jetty IoC XML files (namely the `etc/demo-rewrite-rules.xml` and
`etc/test-realm.xml` files)
The `${jetty.base}/start.ini` is the main startup configuration entry point for Jetty.
In this example you will see that we are enabling a few modules for Jetty, specifying some properties, and also referencing some Jetty IoC XML files (namely the `etc/demo-rewrite-rules.xml` and `etc/test-realm.xml` files)
When Jetty's `start.jar` resolves the entries in the start.ini, it will
follow the link:#base-vs-home-resolution[resolution rules above].
When Jetty's `start.jar` resolves the entries in the `start.ini`, it will follow the link:#base-vs-home-resolution[resolution rules above].
For example, the reference to `etc/demo-rewrite-rules.xml` was found in
`${jetty.base}/etc/demo-rewrite-rules.xml`.
For example, the reference to `etc/demo-rewrite-rules.xml` was found in `${jetty.base}/etc/demo-rewrite-rules.xml`.
==== Declaring Jetty Base
The Jetty Distribution's start.jar is the component that manages the
behavior of this separation.
The Jetty distribution's `start.jar` is the component that manages the behavior of this separation.
The Jetty start.jar and XML files always assume that both
`${jetty.home}` and `${jetty.base}` are defined when starting Jetty.
The Jetty `start.jar` and XML files always assume that both `${jetty.home}` and `${jetty.base}` are defined when starting Jetty.
You can opt to manually define the `${jetty.home}` and `${jetty.base}`
directories, such as this:
You can opt to manually define the `${jetty.home}` and `${jetty.base}` directories, such as this:
[source, screen, subs="{sub-order}"]
....
[jetty-distribution-{VERSION}]$ pwd
/home/user/jetty-distribution-{VERSION}
[jetty-distribution-{VERSION}]$ java -jar start.jar \
jetty.home=/home/user/jetty-distribution-{VERSION} \
jetty.base=/home/user/my-base
2013-10-16 09:08:47.802:INFO:oejs.Server:main: jetty-{VERSION}
2013-10-16 09:08:47.817:INFO:oejdp.ScanningAppProvider:main: Deployment monitor [file:/home/user/my-base/webapps/] at interval 1
...
....
Or you can declare one directory and let the other one be discovered.
Alternately, you can declare one directory and let the other one be discovered.
The following example uses default discovery of `${jetty.home}` by using
the parent directory of wherever start.jar itself is, and a manual
declaration of `${jetty.base}`.
The following example uses default discovery of `${jetty.home}` by using the parent directory of wherever `start.jar` itself is, and a manual declaration of `${jetty.base}`.
[source, screen, subs="{sub-order}"]
....
[jetty-distribution-{VERSION}]$ pwd
/home/user/jetty-distribution-{VERSION}
[jetty-distribution-{VERSION}]$ java -jar start.jar jetty.base=/home/user/my-base
2013-10-16 09:08:47.802:INFO:oejs.Server:main: jetty-{VERSION}
2013-10-16 09:08:47.817:INFO:oejdp.ScanningAppProvider:main: Deployment monitor [file:/home/user/my-base/webapps/] at interval 1
...
....
But Jetty recommends that you always start Jetty by sitting in the
directory that is your $\{jetty.base} and starting Jetty by referencing
the start.jar remotely.
But Jetty recommends that you always start Jetty from the directory that is your `${jetty.base}` and starting Jetty by referencing
the `start.jar` in your `{$jetty.home}` remotely.
The following demonstrates this by allowing default discovery of
`${jetty.home}` via locating the `start.jar`, and using the `user.dir`
System Property for `${jetty.base}`.
The following demonstrates this by allowing default discovery of `${jetty.home}` via locating the `start.jar`, and using the `user.dir` System Property for `${jetty.base}`.
[source, screen, subs="{sub-order}"]
....
[jetty-distribution-{VERSION}]$ pwd
/home/user/jetty-distribution-{VERSION}
[jetty-distribution-{VERSION}]$ cd /home/user/my-base
[my-base]$ java -jar /home/user/jetty-distribution-{VERSION}/start.jar
2013-10-16 09:08:47.802:INFO:oejs.Server:main: jetty-{VERSION}
2013-10-16 09:08:47.817:INFO:oejdp.ScanningAppProvider:main: Deployment monitor [file:/home/user/my-base/webapps/] at interval 1
...
@ -331,7 +306,6 @@ System Property for `${jetty.base}`.
____
[IMPORTANT]
Be aware of the `user.dir` system property, it can only be safely set when the JVM starts, and many 3rd party libraries (especially logging) use this system property.
+
Be aware of the `user.dir` system property, as it can only be safely set when the JVM starts and many 3rd party libraries (especially logging) use this system property.
It is strongly recommended that you sit in the directory that is your desired `${jetty.base}` when starting Jetty to have consistent behavior and use of the `user.dir` system property.
____

40
jetty-documentation/src/main/asciidoc/administration/startup/startup-classpath.adoc
View File

@ -20,36 +20,25 @@
Jetty Server Classpath is determined by a combination of factors.
The java.class.path System Property::
If you start Jetty with a JVM specified classpath, then Jetty will use
the java.class.path System Property to populate the initial classpath.
If you start Jetty with a JVM specified classpath, then Jetty will use the java.class.path System Property to populate the initial classpath.
Module specified Libraries::
With Jetty 9.1+ the module system declares various libraries that are
required for that module to operate, these module defined libraries
are added to the Jetty Server classpath when any module is activated
with library declarations.
The module system declares various libraries that are required for that module to operate.
These module defined libraries are added to the Jetty Server classpath when any module is activated with library declarations.
Command Line Libraries::
The command line option `--lib=<path>`can be used as a final means to
add arbitrary entries to the Jetty Server classpath.
The command line option `--lib=<path>` can be used as a final means to add arbitrary entries to the Jetty Server classpath.
Of special note, there are 2 structural modules defined to ease some of
this for you.
Of special note, there are 2 structural modules defined to ease some of this for you.
--module=ext::
The `ext` module will enable the `lib/ext/*.jar` logic.
+
If this module is activated, then all jar files found in the lib/ext/
paths will be automatically added to the Jetty Server Classpath.
If this module is activated, then all jar files found in the lib/ext/ paths will be automatically added to the Jetty Server Classpath.
--module=resources::
The `resources` module will add the `resources/` directory the
classpath.
The `resources` module will add the `resources/` directory the classpath.
+
If you have 3rd party libraries that lookup resources from the
classpath, put your files in here.
If you have 3rd party libraries that lookup resources from the classpath, put your files in here.
+
Logging libraries often have classpath lookup of their configuration
files (eg: `log4j.properties`, `log4j.xml`, `logging.properties`, and
`logback.xml`), so this would be the ideal setup for this sort of
configuration demand.
Logging libraries often have classpath lookup of their configuration files (eg: `log4j.properties`, `log4j.xml`, `logging.properties`, and `logback.xml`), so this would be the ideal setup for this sort of configuration demand.
____
[NOTE]
@ -58,14 +47,11 @@ ____
==== Interrogating the Server Classpath
The Jetty start.jar has the ability to resolve the classpath from the
command line + modules + configuration, and list the classpath entries
it will use to start jetty.
The Jetty `start.jar` has the ability to resolve the classpath from the command line, modules and configuration, and to list the classpath entries it will use to start jetty.
The `--list-classpath` command line option is used as such.
(Demonstrated with the link:#demo-base[demo-base from the Jetty
Distribution])
(Demonstrated with the link:#demo-base[demo-base from the Jetty Distribution])
[source, screen, subs="{sub-order}"]
....
@ -120,6 +106,4 @@ Note: order presented here is how they would appear on the classpath.
41: {VERSION} | ${jetty.home}/lib/websocket/websocket-servlet-{VERSION}.jar
....
Of note is that an attempt is made to list the internally declared
version of each artifact on the Server Classpath, of potential help when
diagnosing classpath issues.
Of note is that an attempt is made to list the internally declared version of each artifact on the Server Classpath, which can potentially help when diagnosing classpath issues.

164
jetty-documentation/src/main/asciidoc/administration/startup/startup-modules.adoc
View File

@ -17,152 +17,94 @@
[[startup-modules]]
=== Managing Startup Modules
Starting with Jetty 9.1, a new Module system was introduced. (It
replaced the old `start.config` + `OPTIONS` techniques from past Jetty
Distributions).
Starting with Jetty 9.1, a new Module system was introduced, replacing the previous `start.config` + `OPTIONS` techniques from past Jetty Distributions.
The standard Jetty Distribution ships with several modules defined in
`${jetty.home}/modules/`
The standard Jetty Distribution ships with several modules defined in `${jetty.home}/modules/`.
What a Jetty Startup Module Defines:
A Module Name::
The name of the module is the keyword used by the `--module=<name>`
command line argument to activate/enable modules, and also find
dependant modules.
+
The filename of the module defines its name. (eg: server.mod becomes
the module named "server")
The name of the module is the keyword used by the `--module=<name>` command line argument to activate/enable modules, and also find dependent modules.
The filename of the module defines its name (eg: server.mod becomes the module named "server").
List of Dependant Modules::
All modules can declare that they depend on other modules with the
`[depend]` section.
+
The list of dependencies is used to transitively resolve other modules
that are deemed to be required based on the modules that you activate.
+
The order of modules defined in the graph of active modules is used to
determine various execution order for configuration, such as Jetty IoC
XML configurations, and to resolve conflicting property declarations.
+
Of note: there is a special section `[optional]` used to describe
structurally dependant modules that are not technically required, but
might be of use to your specific configuration.
All modules can declare that they depend on other modules with the `[depend]` section.
The list of dependencies is used to transitively resolve other modules that are deemed to be required based on the modules that you activate.
The order of modules defined in the graph of active modules is used to determine various execution order for configuration, such as Jetty IoC XML configurations, and to resolve conflicting property declarations.
Of note: there is a special section `[optional]` used to describe structurally dependent modules that are not technically required, but might be of use to your specific configuration.
List of Libraries::
Module can optionally declare that they have libraries that they need
to function properly.
+
The `[lib]` section declares a set of pathnames that follow the
link:#base-vs-home-resolution[Jetty Base and Jetty Home path
resolution rules].
Module can optionally declare that they have libraries that they need to function properly.
The `[lib]` section declares a set of pathnames that follow the link:#base-vs-home-resolution[Jetty Base and Jetty Home path resolution rules].
List of Jetty IoC XML Configurations::
A Module can optionally declare a list of Jetty IoC XML configurations
used to wire up the functionality that this module defines.
+
The `[xml]` section declares a set of pathnames that follow the
link:#base-vs-home-resolution[Jetty Base and Jetty Home path
resolution rules].
+
Ideally, all XML files are parameterized to accept properties to
configure the various elements of the standard configuration. Allowing
for a simplified configuration of Jetty for the vast majority of
deployments.
+
The execution order of the Jetty IoC XML configurations is determined
by the graph of active module dependencies resolved via the `[depend]`
sections.
+
If the default XML is not sufficient to satisfy your needs, you can
override this XML by making your own in the $\{jetty.base}/etc/
directory, with the same name. The resolution steps for Jetty Base and
Jetty Home will ensure that your copy from $\{jetty.base} will be
picked up over the default one in $\{jetty.home}.
A Module can optionally declare a list of Jetty IoC XML configurations used to wire up the functionality that this module defines.
The `[xml]` section declares a set of pathnames that follow the link:#base-vs-home-resolution[Jetty Base and Jetty Home path resolution rules].
Ideally, all XML files are parameterized to accept properties to configure the various elements of the standard configuration.
Allowing for a simplified configuration of Jetty for the vast majority of deployments.
The execution order of the Jetty IoC XML configurations is determined by the graph of active module dependencies resolved via the `[depend]` sections.
If the default XML is not sufficient to satisfy your needs, you can override this XML by making your own in the `${jetty.base}/etc/` directory, with the same name.
The resolution steps for Jetty Base and Jetty Home will ensure that your copy from `${jetty.base}` will be picked up over the default one in `${jetty.home}`.
Jetty INI Template::
Each module can optionally declare a startup ini template that is used
to insert/append/inject sample configuration elements into the
`start.ini` or `start.d/*.ini` files when using the
`--add-to-start=<name>` or `--add-to-startd=<name>` command line
arguments in `start.jar`.
+
Commonly used to present some of the parameterized property options
from the Jetty IoC XML configuration files also referenced in the same
module.
+
The `[ini-template]` section declares this section of sample
configuration.
Each module can optionally declare a startup ini template that is used to insert/append/inject sample configuration elements into the `start.ini` or `start.d/*.ini` files when using the `--add-to-start=<name>` or `--add-to-startd=<name>` command line arguments in `start.jar`.
Commonly used to present some of the parameterized property options from the Jetty IoC XML configuration files also referenced in the same module.
The `[ini-template]` section declares this section of sample configuration.
Required Files and Directories::
If the activation of a module requires some paths to exist, the
`[files]` section defines them.
+
If the activation of a module requires some paths to exist, the `[files]` section defines them.
There are 2 modes of operation of the entries in this section.
+
Ensure Directory Exists;;
If you add a pathname that ends in `"/"` (slash), such as
`"webapps/"`, then that directory will be created if it does not yet
exist in `${jetty.base}/<pathname>` (eg: `"webapps/"` will result in
`${jetty.base}/webapps/` being created)
Download File;;
There is a special syntax to allow you to download a file into a
specific location if it doesn't exist yet.
+
`<url>:<pathname>`
+
Currently, the `<url>` must be a `http://` scheme URL
(link:#bugs[file a bug] if you want more schemes supported). The
`<pathname>` portion follows the link:#base-vs-home-resolution[Jetty
Base and Jetty Home path resolution rules].
+
Example:
+
`http://repo.corp.com/maven/corp-security-policy-1.0.jar:lib/corp-security-policy.jar`
+
This will check for the existence of `lib/corp-security-policy.jar`,
and if it doesn't exist, it will download the jar file from
Ensure Directory Exists;;
If you add a pathname that ends in `"/"` (slash), such as `"webapps/"`, then that directory will be created if it does not yet exist in `${jetty.base}/<pathname>` (eg: `"webapps/"` will result in `${jetty.base}/webapps/` being created).
Download File;;
There is a special syntax to allow you to download a file into a specific location if it doesn't exist yet: `<url>:<pathname>`.
Currently, the `<url>` must be a `http://` scheme URL (please link:#bugs[let us know] if you need more schemes supported).
The `<pathname>` portion follows the link:#base-vs-home-resolution[Jetty Base and Jetty Home path resolution rules].
Example: `http://repo.corp.com/maven/corp-security-policy-1.0.jar:lib/corp-security-policy.jar`
This will check for the existence of `lib/corp-security-policy.jar`, and if it doesn't exist, it will download the jar file from
`http://repo.corp.com/maven/corp-security-policy-1.0.jar`
[[enabling-modules]]
==== Enabling Modules
Jetty ships with many modules defined, and a small subset predefined in
the `start.ini` found in the jetty distribution.
Jetty ships with many modules defined, and a small subset predefined in the `start.ini` found in the jetty distribution.
____
[TIP]
The default distribution has a co-mingled `${jetty.home}` and `${jetty.base}`. Where the directories for `${jetty.home}` and `${jetty.base}` point to the same location.
+
It is highly encouraged that you learn about the differences in link:#startup-base-and-home[Jetty Base vs Jetty Home] and take full advantage of this setup.
____
When you want enable a module, you can use the `--module=<modulename>`
syntax on the command line (or start.ini) to enable that module and all
of its dependant modules.
When you want enable a module, you can use the `--module=<modulename>` syntax on the command line to enable that module and all of its dependent modules.
An example of this, with a new, empty, base directory.
We can see from this output, that the directory is new.
We can see from this output, that the directory is new (it is empty
after all).
include::screen-empty-base.adoc[]
Lets see what the configuration looks like so far
Lets see what the configuration looks like so far:
Lets try adding some basic support for webapps, with automatic deploy
(hot deploy), and a single basic HTTP/1.1 connector.
include::screen-empty-base-listconfig.adoc[]
That just created what we need in the `${jetty.base}` directory. Lets
see what it looks like configuration wise.
Lets try adding some basic support for webapps, with automatic deploy (hot deploy), and a single basic HTTP/1.1 connector.
You now have a configured and functional server, albiet with no webapps
deployed. At this point you can toss a webapp (war file) into
`mybase/webapps/` directory and and start Jetty
include::screen-http-webapp-deploy.adoc[]
This created the webapps directory in our `mybase` directory and appended the `start.ini` file with the ini template arguments from the associated module files.
Additionally, where needed, Jetty enabled any module dependencies and added their module ini template properties.
Lets see what it looks like configuration wise.
include::screen-http-webapp-deploy-listconfig.adoc[]
You now have a configured and functional server, albeit with no webapps deployed.
At this point you can place a webapp (war file) in the `mybase/webapps/` directory and and start Jetty.
[[startup-listing-modules]]
==== Listing Available and Active Modules
To see which modules are __available__, use the `--list-modules` command
line argument. This command will also show you which modules are
__enabled__. Here's an example
To see which modules are __available__, use the `--list-modules` command line argument.
This command will also show you which modules are __enabled__.
Here's an example:
Wow, are there really that many modules available?
include::screen-list-modules.adoc[]
Yes, the module system has grown a fair bit since it was introduced in
Jetty 9
Since being introduced in Jetty 9.1 the modules provided in the Jetty distribution has expanded greatly.
Below is a graphical representation of the standard modules and their dependencies.
image:images/modules-9.3-simplified.png[image,width=768]

137
jetty-documentation/src/main/asciidoc/administration/startup/startup-overview.adoc
View File

@ -17,75 +17,57 @@
[[startup-overview]]
=== Startup Overview
The `start.jar` bootstrap manages the startup of standalone Jetty. It is
responsible for:
The `start.jar` bootstrap manages the startup of standalone Jetty.
It is responsible for:
Building the classpath::
The `start.jar` bootstrap builds a classpath for all the required
Jetty features and their dependencies. It builds the classpath using
either the `--lib` option to `start.jar` to add an individual
classpath entry, or with the `--module` option that includes all the
libs and their dependencies for a module (a named Jetty feature).
The `start.jar` bootstrap builds a classpath for all the required Jetty features and their dependencies.
It builds the classpath using either the `--lib` option to `start.jar` to add an individual classpath entry, or with the `--module` option that includes all the libs and their dependencies for a module (a named Jetty feature).
Instantiating the Server Components::
The server and its components are instantiated using either Jetty IoC
XML or spring. The Jetty server is just a collection of java POJOs for
the server, connectors, session managers and others. These are
instantiated, injected, and wired up together in XML files, commonly
one per module/feature, that are passed as arguments to `start.jar`.
The server and its components are instantiated using either Jetty IoC XML or Spring.
The Jetty server is a collection of POJOs for the server, connectors, session managers and others.
These are instantiated, injected, and wired up together in XML files, commonly one per module/feature, that are passed as arguments to `start.jar`.
Resolving Server Filesystem Locations::
The `start.jar` mechanism resolves canonical locations for the
`${jetty.home}` and the `${jetty.base}` directories.
The `start.jar` mechanism resolves canonical locations for the `${jetty.home}` and the `${jetty.base}` directories.
The `${jetty.home}` directory is the location of the standard distribution of Jetty.
The `${jetty.base}` directory is the location of the local server customization and configurations.
+
The `${jetty.home}` directory is the location of the standard
distribution of Jetty.
+
The `${jetty.base}` directory is the location of the local server
customization and configurations.
+
If you want to modify the Jetty distribution, base and home can be the
same directory. Separating the base and home directories allows the
distribution to remain unmodified, with all customizations in the base
directory, and thus simplifies subsequent server version upgrades.
If you want to modify the Jetty distribution, base and home can be the same directory.
Separating the base and home directories allows the distribution to remain unmodified, with all customizations in the base directory, and thus simplifies subsequent server version upgrades.
Parameterizing the Server Configuration::
XML files primarily determine the server configuration. Many of these
files are parameterized to allow simple injection of host names,
ports, passwords and more. The `start.jar` mechanism allows you to set
parameters on the command line or in properties files.
XML files primarily determine the server configuration.
Many of these files are parameterized to allow simple injection of host names, ports, passwords and more.
The `start.jar` mechanism allows you to set parameters on the command line or in properties files.
To achieve these start up mechanisms, the `start.jar` uses:
Command line arguments::
You can configure the entire server with command line arguments that
specify libraries, properties and XML files. However in practice the
INI and modules mechanisms (below) reduce the verbosity of the command
line.
You can configure the entire server with command line arguments that specify libraries, properties and XML files.
However in practice the INI and modules mechanisms (below) reduce the verbosity of the command line.
INI files::
The `start.jar` mechanism uses the contents of the
`${jetty.base}/start.ini` and `${jetty.base}/start.d/*.ini` files with
each line equivalent to a `start.jar` command line argument. This
means that either a global `start.ini` file or multiple
`start.d/feature.ini` files control the configuration of the server.
The `start.jar` mechanism uses the contents of the `${jetty.base}/start.ini` and `${jetty.base}/start.d/*.ini` files with each line equivalent to a `start.jar` command line argument.
This means that either a global `start.ini` file or multiple `start.d/feature.ini` files control the configuration of the server.
[NOTE]
--
It is important to chose *either* `${jetty.base}/start.ini` or `${jetty.base}/start.d/*.ini` to manage configuration.
Using both is not recommended and can lead to issues with your server.
--
Modules::
Instead of explicitly listing all the libraries, properties and XML
files for a feature, the `start.jar` mechanism allows you to create
modules. You define a module in a `modules/*.mod` file, including the
libraries, dependencies, XML, and template INI files for a Jetty
feature. Thus you can use a single `--module=name` command line option
as the equivalent of specifying many `--lib=location`, feature.xml,
name=value arguments for a feature and all its dependencies. Modules
also use their dependencies to control the ordering of libraries and
XML files.
Instead of explicitly listing all the libraries, properties and XML files for a feature, the `start.jar` mechanism allows you to create modules.
A module is defined in a `modules/*.mod` file, including the libraries, dependencies, XML, and template INI files for a Jetty feature.
Thus you can use a single `--module=name` command line option as the equivalent of specifying `--lib=location`, `feature.xml` or `name=value` arguments for a feature and all its dependencies.
Modules also use their dependencies to control the ordering of libraries and XML files.
There are several module files included with the Jetty distribution that cover the most common server features, such as HTTP, HTTPS, SSL, Logging, Annotations...etc.
These module files should *only* be edited if you are making structural changes to the way the feature will perform.
For more information, refer to the section on <<startup-modules,managing startup modules>> later in this chapter.
XML Files::
XML files in either Jetty IoC or Spring format instantiate the actual
POJO components of the server. This includes all major components such
as connectors, keystores, session managers, and data sources.
Typically there are one or more XML files per module, and these are
defined and activated in the corresponding module.
XML files in either Jetty IoC or Spring format instantiate the actual POJO components of the server.
This includes all major components such as connectors, keystores, session managers, and data sources.
Typically there are one or more XML files per module, and these are defined and activated in the corresponding module.
==== Startup Example
The simplest way to start Jetty is via the `start.jar` mechanism using
the following Java command line:
The simplest way to start Jetty is via the `start.jar` mechanism using the following Java command line:
[source, screen, subs="{sub-order}"]
....
@ -93,10 +75,8 @@ the following Java command line:
[jetty-distribution-{VERSION}]$ java -jar start.jar --module=http jetty.http.port=8080
....
This command uses the `start.jar` mechanism to bootstrap the classpath,
properties, and XML files with the metadata obtained from the `http`
module. Specifically the `http` module is defined in the
`${jetty.home}/modules/http.mod` file, and includes the following:
This command uses the `start.jar` mechanism to bootstrap the classpath, properties, and XML files with the metadata obtained from the `http` module.
Specifically the `http` module is defined in the `${jetty.home}/modules/http.mod` file, and includes the following:
[source, screen, subs="{sub-order}"]
....
@ -112,14 +92,10 @@ jetty.http.port=8080
http.timeout=30000
....
The `http` module declares that `http` depends on the server module,
uses the `jetty-http.xml` file, and can be parameterized with
`jetty.http.port` and `http.timeout` parameters. The INI-template
section is not actually used by the command above, so the
`jetty.http.port` must still be defined on the command line.
The `http` module declares that `http` depends on the server module, uses the `jetty-http.xml` file, and can be parameterized with `jetty.http.port` and `http.timeout` parameters.
The INI-template section is not actually used by the command above, so the `jetty.http.port` must still be defined on the command line.
Following the server dependency, the `${jetty.home}/modules/server.mod`
file includes:
Following the server dependency, the `${jetty.home}/modules/server.mod` file includes:
[source, screen, subs="{sub-order}"]
....
@ -140,13 +116,10 @@ threads.min=10
threads.max=200
....
The `server` module declares the libraries the server needs and t0 use
`jetty.xml` file. The combined metadata of the `http` and `server`
modules results in `start.jar` generating the effective Java command
line required to start Jetty.
The `server` module declares the libraries the server needs and to use `jetty.xml` file.
The combined metadata of the `http` and `server` modules results in `start.jar` generating the effective Java command line required to start Jetty.
Another way to see this is by asking Jetty what its configuration looks
like:
Another way to see this is by asking Jetty what its configuration looks like by appending --list-config to the command line:
[source, screen, subs="{sub-order}"]
....
@ -201,14 +174,11 @@ Jetty Active XMLs:
${jetty.home}/etc/jetty-http.xml
....
This represents the entirety of the configuration that is applied to
start Jetty.
This represents the entirety of the configuration that is applied to start Jetty.
If you don't want to use the `start.jar` bootstrap, you can start Jetty
using a traditional Java command line.
If you don't want to use the `start.jar` bootstrap, you can start Jetty using a traditional Java command line.
The following is the equivalent `java` command line for what the
`start.jar` bootstrap above performs.
The following is the equivalent Java command line for what the `start.jar` bootstrap above performs.
[source, screen, subs="{sub-order}"]
....
@ -233,14 +203,9 @@ $JETTY_HOME/etc/jetty.xml \
$JETTY_HOME/etc/jetty-http.xml
....
The java command line sets up the classpath with the core Jetty jars and
the servlet API, executes the XmlConfiguration class, and passes it some
XML files that define the server and an HTTP connector running on the
port defined in the `jetty.properties` file.
The Java command line sets up the classpath with the core Jetty jars and the servlet API, executes the XmlConfiguration class and passes it some XML files that define the server and an HTTP connector running on the port defined in the `jetty.properties` file.
You can further simplify the startup of this server by using the INI
template defined by the modules to create a `start.ini` file with the
command:
You can further simplify the startup of this server by using the INI template defined by the modules to create a `start.ini` file with the command:
[source, screen, subs="{sub-order}"]
....
@ -251,11 +216,14 @@ command:
total 8
drwxrwxr-x 2 user webgroup 4096 Oct 4 11:49 ./
drwxrwxr-x 12 user webgroup 4096 Oct 4 11:49 ../
[example-base]$ java -jar $JETTY_HOME/start.jar --add-to-start=http
WARNING: http initialised in ${jetty.base}/start.ini (appended)
WARNING: http enabled in ${jetty.base}/start.ini
WARNING: server initialised in ${jetty.base}/start.ini (appended)
WARNING: server enabled in ${jetty.base}/start.ini
[example-base]$ ls -la
total 12
drwxrwxr-x 2 user webgroup 4096 Oct 4 11:55 ./
@ -263,8 +231,7 @@ drwxrwxr-x 12 user webgroup 4096 Oct 4 11:49 ../
-rw-rw-r-- 1 user webgroup 250 Oct 4 11:55 start.ini
....
Once complete, you can edit the `start.ini` file to modify any
parameters and you can run the server with the simple command:
Once complete, you can edit the `start.ini` file to modify any parameters and you can run the server with the simple command:
[source, screen, subs="{sub-order}"]
....

15
jetty-documentation/src/main/asciidoc/administration/startup/startup-xml-config.adoc
View File

@ -17,16 +17,9 @@
[[startup-xml-config]]
=== Managing XML Based Startup Configuration
When you see XML files on the command line for startup of Jetty, they
are always part of the Jetty IoC Configuration mechanism.
When you see XML files on the command line for startup of Jetty, they are always part of the Jetty IoC Configuration mechanism.
Internally, Jetty uses these XML files to build up Jetty with the
features that you wan to use.
Internally, Jetty uses these XML files to build up Jetty with the features that you wan to use.
The module mechanism present in Jetty determines the load order of the
XML files.
The Jetty Base and Jetty Home resolution logic also applies, which
allows you to override a XML file declared by a module with your XML by
simply having the same named XML in your `${jetty.base}` directory
location.
The module mechanism present in Jetty determines the load order of the XML files.
The Jetty Base and Jetty Home resolution logic also applies, which allows you to override a XML file declared by a module with your XML by simply having the same named XML in your `${jetty.base}/etc` directory location.

265
jetty-documentation/src/main/asciidoc/configuring/jsp/configuring-jsp.adoc
View File

@ -17,73 +17,43 @@
[[jsp-support]]
=== Configuring JSP
This document provides information about configuring Java Server Pages
for Jetty.
This document provides information about configuring Java Server Pages (JSP) for Jetty.
[[which-jsp-implementation]]
==== Which JSP Implementation
From jetty-9.2 onwards, we are using Jasper from
http://tomcat.apache.org/tomcat-8.0-doc/jasper-howto.html[Apache] as the
default JSP container implementation. In previous versions we used
Jasper from http://jsp.java.net[Glassfish], and if you wish to, you can
continue to do so.
As of Jetty 9.2, Jetty is using Jasper from http://tomcat.apache.org/tomcat-8.0-doc/jasper-howto.html[Apache] as the default JSP container implementation.
In previous versions Jasper from http://jsp.java.net[Glassfish] was used, and if you wish to, you can continue to do so.
The jetty-distribution by default enables the jsp
link:#startup-modules[module], and by default, this
link:#startup-modules[module] is set to Apache Jasper. To change to use
Glassfish Jasper instead, edit the `$JETTY_HOME/start.d/jsp.mod` file
and change the line indicated:
By default the Jetty distribution enables the JSP link:#startup-modules[module], and by default, this link:#startup-modules[module] is set to Apache Jasper.
To change to use Glassfish Jasper instead, edit the `{jetty.home}/modules/jsp.mod` file and change the line indicated:
[source, plain, subs="{sub-order}"]
----
include::{SRCDIR}/jetty-distribution/src/main/resources/modules/jsp.mod[]
----
Note that the availability of some JSP features may depend on which JSP
container implementation you are using. Note also that it may not be
possible to precompile your jsps with one container and deploy to the
other.
Note that the availability of some JSP features may depend on which JSP container implementation you are using.
Note also that it may not be possible to precompile your JSPs with one container and deploy to the other.
===== JSPs and Embedding
If you have an embedded setup for your webapp and wish to use jsps, you
will need to ensure that a JSP engine is correctly initialized.
If you have an embedded setup for your webapp and wish to use JSPs, you will need to ensure that a JSP engine is correctly initialized.
For both Apache and Glassfish JSP engines, a Servlet Specification 3.1
style link:#servlet-container-initializers[ServletContainerInitializer]
is used to accomplish this. You will need to ensure that this
ServletContainerInitializer is run by jetty. Perhaps the easiest way to
do this is to enable annotations processing so that jetty automatically
discovers and runs it. The link:#embedded-examples[Embedded Examples]
section includes a link:#embedded-webapp-jsp[worked code example] of how
to do this.
For both Apache and Glassfish JSP engines, a Servlet Specification 3.1 style link:#servlet-container-initializers[ServletContainerInitializer] is used to accomplish this.
You will need to ensure that this ServletContainerInitializer is run by jetty. Perhaps the easiest way to do this is to enable annotations processing so that Jetty automatically discovers and runs it.
The link:#embedded-examples[Embedded Examples] section includes a link:#embedded-webapp-jsp[worked code example] of how to do this.
Alternatively, you can manually wire in the appropriate
ServletContainerInitializer as shown in the
https://github.com/jetty-project/embedded-jetty-jsp/blob/master/src/main/java/org/eclipse/jetty/demo/Main.java[embedded-jetty-jsp]
example on https://github.com/jetty-project[github], in which case you
will not need the jetty-annotations jar on your classpath, nor include
the AnnotationConfiguration in the list of
link:#webapp-configurations[configuration classes].
Alternatively, you can manually wire in the appropriate ServletContainerInitializer as shown in the https://github.com/jetty-project/embedded-jetty-jsp/blob/master/src/main/java/org/eclipse/jetty/demo/Main.java[embedded-jetty-jsp] example on https://github.com/jetty-project[GitHub], in which case you will not need the jetty-annotations jar on your classpath, nor include the AnnotationConfiguration in the list of link:#webapp-configurations[configuration classes].
==== Precompiling JSPs
You can either follow the instructions on precompilation provided by the
JSP container of your choice (either http://jsp.java.net[Glassfish] or
http://tomcat.apache.org/tomcat-8.0-doc/jasper-howto.html[Apache]), or
if you are using maven for your builds, you can use the
link:#jetty-jspc-maven-plugin[jetty-jspc-maven] plugin to do it for you.
You can either follow the instructions on precompilation provided by the JSP container of your choice (either http://jsp.java.net[Glassfish] or http://tomcat.apache.org/tomcat-8.0-doc/jasper-howto.html[Apache]), or if you are using maven for your builds, you can use the link:#jetty-jspc-maven-plugin[jetty-jspc-maven] plugin to do it for you.
If you have precompiled your jsps, and have customized the output
package prefix (which is `org.apache.jsp` by default), you should
configure your webapp context to tell Jetty about this custom package
name. You can do this using a servlet context init-param called
`org.eclipse.jetty.servlet.jspPackagePrefix`.
If you have precompiled your JSPs, and have customized the output package prefix (which is `org.apache.jsp` by default), you should configure your webapp context to tell Jetty about this custom package name.
You can do this using a servlet context init-param called `org.eclipse.jetty.servlet.jspPackagePrefix`.
For example, suppose you have precompiled your jsps with the custom
package prefix of `com.acme`, then you would add the following lines to
your web.xml file:
For example, suppose you have precompiled your JSPs with the custom package prefix of `com.acme`, then you would add the following lines to your `web.xml` file:
[source, xml, subs="{sub-order}"]
----
@ -95,22 +65,19 @@ your web.xml file:
____
[NOTE]
Both jetty maven plugins - link:#jetty-jspc-maven-plugin[jetty-jspc-maven-plugin] and the link:#jetty-maven-plugin[jetty-maven-plugin] - will only use Apache Jasper.
Both Jetty Maven plugins - link:#jetty-jspc-maven-plugin[jetty-jspc-maven-plugin] and the link:#jetty-maven-plugin[jetty-maven-plugin] - will only use Apache Jasper.
____
[[compiling-jsps]]
==== Runtime Compiling JSPs
Depending on which JSP container you elect to use, the configuration and
compilation characteristics will be different.
Depending on which JSP container you elect to use, the configuration and compilation characteristics will be different.
===== Apache JSP Container
By default, the Apache JSP container will look for the Eclipse Java
Compiler (jdt). The jetty distribution ships a copy of this in
$JETTY_HOME/lib/apache-jsp. If you wish to use a different compiler, you
will need to configure the `compilerClassName` init-param on the
`JspServlet` with the name of the class.
By default, the Apache JSP container will look for the Eclipse Java Compiler (jdt).
The Jetty distribution ships a copy of this in `{$jetty.home}/lib/apache-jsp`.
If you wish to use a different compiler, you will need to configure the `compilerClassName` init-param on the `JspServlet` with the name of the class.
.Understanding Apache JspServlet Parameters
[cols=",,,",options="header",]
@ -203,44 +170,32 @@ resource usage. |- |–
===== Glassfish JSP Container
To compile `.jsp` files into Java classes, you need a Java compiler. You
can acquire a Java compiler from the JVM if you are using a full JDK, or
from a third party Jar.
To compile `.jsp` files into Java classes, you need a Java compiler.
You can acquire a Java compiler from the JVM if you are using a full JDK, or from a third party Jar.
By default, the Glassfish JSP container tries to use the compiler that
is part of the JDK. *NOTE:* when using the JDK compiler, the system does
_not_ save your class files to disk unless you use the `saveBytecode`
init-param as described below.
By default, the Glassfish JSP container tries to use the compiler that is part of the JDK.
*NOTE:* when using the JDK compiler, the system does _not_ save your class files to disk unless you use the `saveBytecode` init-param as described below.
If you do not have a full JDK, you can configure the Eclipse Java
Compiler that Jetty ships in the distro in `$JETTY_HOME/lib/jsp/.`You
need to define a SystemProperty that prevents the Glassfish JSP engine
from defaulting to the in-JVM compiler.
If you do not have a full JDK, you can configure the Eclipse Java Compiler that Jetty ships in the distro in `{$jetty.home}/lib/jsp/.`
You need to define a SystemProperty that prevents the Glassfish JSP engine from defaulting to the in-JVM compiler.
This is best done when using the standalone distro by uncommenting the
System property `org.apache.jasper.compiler.disablejsr199` in the jsp
link:#startup-modules[module]:
// This is best done when using the standalone distro by uncommenting the System property `org.apache.jasper.compiler.disablejsr199` in the jsp link:#startup-modules[module]:
//
// [source,text]
// ----
// -Dorg.apache.jasper.compiler.disablejsr199=true
// ----
[source,text]
----
-Dorg.apache.jasper.compiler.disablejsr199=true
----
Or for embedded usages, simply define this as a normal System property.
For embedded usages, simply define this as a normal System property.
[[configuring-jsp-for-jetty]]
===== Configuration
The JSP engine has many configuration parameters. Some parameters affect
only precompilation, and some affect runtime recompilation checking.
The JSP engine has many configuration parameters.
Some parameters affect only precompilation, and some affect runtime recompilation checking.
Parameters also differ among the various versions of the JSP engine.
This page lists the configuration parameters, their meanings, and their
default settings. Set all parameters on the
`org.apache.jasper.JspServlet` instance defined in the
link:#webdefault-xml[`webdefault.xml`] file.
This page lists the configuration parameters, their meanings, and their default settings.
Set all parameters on the `org.apache.jasper.JspServlet` instance defined in the link:#webdefault-xml[`webdefault.xml`] file.
____
[NOTE]
@ -325,10 +280,8 @@ and `development=false`. |– |–
mapping the name of the JSP to class and JSP file. |– |–
|=======================================================================
Much confusion generally ensues about the `development`, `checkInterval`
and `
modificationTestInterval` parameters and JSP runtime
recompilation. Here is a factoring out of the various options:
Much confusion generally ensues about the `development`, `checkInterval` and `modificationTestInterval` parameters and JSP runtime recompilation.
Here is a factoring out of the various options:
* Check the JSP files for possible recompilation on every request:
+
@ -339,15 +292,12 @@ recompilation. Here is a factoring out of the various options:
<param-name>development></param-name>
<param-value>true></param-value>
</init-param>
----
* Only check approximately every N seconds, where a request triggers the
time-lapse calculation. This example checks every 60 seconds:
* Only check approximately every N seconds, where a request triggers the time-lapse calculation.
This example checks every 60 seconds:
+
[source, xml, subs="{sub-order}"]
----
<init-param>
<param-name>development></param-name>
<param-value>true></param-value>
@ -356,30 +306,22 @@ time-lapse calculation. This example checks every 60 seconds:
<param-name>modificationTestInterval></param-name>
<param-value>60></param-value>
</init-param>
----
* Do no checking whatsoever, but still compile the JSP on the very first
hit. (Be aware that this ''reload-interval'' parameter is shorthand for
a ''development=false'' and ''checkInterval=0'' combination.):
* Do no checking whatsoever, but still compile the JSP on the very first hit (Be aware that this `reload-interval` parameter is shorthand for
a `development=false` and `checkInterval=0` combination):
+
[source, xml, subs="{sub-order}"]
----
<init-param>
<param-name>reload-interval></param-name>
<param-value>-1></param-value>
</init-param>
----
* Don't do any request-time checking, but instead start a background
thread to do checks every N seconds. This example checks every 60
seconds:
* Don't do any request-time checking, but instead start a background thread to do checks every N seconds.
This example checks every 60 seconds:
+
[source, xml, subs="{sub-order}"]
----
<init-param>
<param-name>development></param-name>
<param-value>false></param-value>
@ -388,28 +330,21 @@ seconds:
<param-name>checkInterval></param-name>
<param-value>60></param-value>
</init-param>
----
[[modifying-configuration]]
==== Modifying Configuration
Regardless of which JSP container you are using, there are several
options for modifying the JspServlet configuration.
Regardless of which JSP container you are using, there are several options for modifying the JspServlet configuration.
[[overriding-webdefault.xml]]
===== Overriding `webdefault.xml`
You can make a copy of the
link:#webdefault-xml[$JETTY_HOME/etc/webdefault.xml] that ships with
Jetty, apply your changes, and use it instead of the shipped version.
The example below shows how to do this when using the Jetty Maven
plugin.
You can make a copy of the link:#webdefault-xml[{$jetty.home}/etc/webdefault.xml] that ships with Jetty, apply your changes, and use it instead of the shipped version.
The example below shows how to do this when using the Jetty Maven plugin.
[source, xml, subs="{sub-order}"]
----
<plugin>
<groupId>org.eclipse.jetty</groupId>
<artifactId>jetty-maven-plugin</artifactId>
@ -418,44 +353,32 @@ plugin.
<defaultsDescriptor>src/main/resources/webdefault.xml</defaultsDescriptor>
</webApp>
</plugin>
----
If you are using the Jetty distro, and you want to change the JSP
settings for just one or a few of your webapps, copy the
`$JETTY_HOME/etc/webdefault.xml` file somewhere, modify it, and then use
a link:#intro-jetty-configuration-contexts[context xml] file to set this
file as the defaultsDescriptor for your webapp. Here's a snippet:
If you are using the Jetty distribution, and you want to change the JSP settings for just one or a few of your webapps, copy the `{$jetty.home}/etc/webdefault.xml` file somewhere, modify it, and then use a link:#intro-jetty-configuration-contexts[context xml] file to set this file as the `defaultsDescriptor` for your webapp. Here's a snippet:
[source, xml, subs="{sub-order}"]
----
<Configure class=>"org.eclipse.jetty.webapp.WebAppContext">
<Set name=>"contextPath">/foo</Set>
<Set name=>"war"><SystemProperty name=>"jetty.home" >default=>"."/>/webapps/foobar.war</Set>
<Set name=>"defaultsDescriptor">/home/smith/dev/webdefault.xml</Set>
</Configure>
</Configure>
----
If you want to change the JSP settings for all webapps, edit
the` $JETTY_HOME/etc/webdefaults.xml` file directly instead.
If you want to change the JSP settings for all webapps, edit the `{$jetty.home}/etc/webdefaults.xml` file directly instead.
[[configuring-jsp-servlet-in-web.xml]]
===== Configuring the JSP Servlet in `web.xml`
Another option is to add an entry for the JSPServlet to the
`WEB-INF/web.xml` file of your webapp and change or add init-params. You
may also add (but not remove) servlet-mappings. You can use the entry in
link:#webdefault-xml[$JETTY_HOME/etc/webdefault.xml] as a starting
point.
Another option is to add an entry for the JSPServlet to the `WEB-INF/web.xml` file of your webapp and change or add init-params.
You may also add (but not remove) servlet-mappings.
You can use the entry in link:#webdefault-xml[{$jetty.home}/etc/webdefault.xml] as a starting point.
[source, xml, subs="{sub-order}"]
----
<servlet id="jsp">
<servlet-name>jsp</servlet-name>
<servlet-class>org.apache.jasper.servlet.JspServlet</servlet-class>
@ -472,10 +395,10 @@ point.
<param-value>>true</param-value>
</init-param>
...
<load-on-startup>0</load-on-startup>
</servlet>
<servlet-mapping>
<servlet-name>jsp</servlet-name>
<url-pattern>*.jsp</url-pattern>
@ -487,65 +410,42 @@ point.
<url-pattern>*.JSPX</url-pattern>
<url-pattern>*.XSP</url-pattern>
</servlet-mapping>
<servlet id="my-servlet">
<servlet-name>myServlet</servlet-name>
<servlet-class>com.acme.servlet.MyServlet</servlet-class>
...
----
[[using-jstl-taglibs-for-jetty7-jetty8]]
==== Using JSTL Taglibs
The JavaServer Pages Standlard Tag Library (JSTL) is part of the Jetty
distribution and is automatically put on the classpath when you
link:#which-jsp-implementation[select your flavour of JSP]. It is also
automatically on the classpath for the jetty maven plugin, which uses
the Apache JSP engine as of jetty-9.2.
The JavaServer Pages Standlard Tag Library (JSTL) is part of the Jetty distribution and is automatically put on the classpath when you link:#which-jsp-implementation[select your flavour of JSP].
It is also automatically on the classpath for the Jetty Maven plugin, which uses the Apache JSP engine as of Jetty 9.2.
===== Embedding
If you are using jetty in an embedded scenario, and you need to use
JSTL, then you must ensure that the JSTL jars are included on the
_container's_ classpath - that is the classpath that is the _parent_ of
the webapp's classpath. This is a restriction that arises from the Java
EE specification.
If you are using Jetty in an embedded scenario, and you need to use JSTL, then you must ensure that the JSTL jars are included on the _container's_ classpath - that is the classpath that is the _parent_ of the webapp's classpath.
This is a restriction that arises from the JavaEE specification.
The jars that you will include will depend on the flavour of JSP that
you are using.
The jars that you will include will depend on the flavor of JSP that you are using.
====== With Glassfish JSP
You will need to put the jstl jars that are present in
$jetty.home/lib/jsp onto the _container's_ classpath. The Glassfish JSP
engine will find the jstl tag definitions inside these jars during
startup.
You will need to put the JSTL jars that are present in `{$jetty.home/lib/jsp}` onto the _container's_ classpath.
The Glassfish JSP engine will find the JSTL tag definitions inside these jars during startup.
====== With Apache JSP
You will need to put the jars that are present in the
$jetty.home/lib/apache-jstl directory onto the _container's_ classpath.
The Apache JSP engine will find the jstl tag definitions inside these
jars during startup.
You will need to put the jars that are present in the `{$jetty.home}/lib/apache-jstl` directory onto the _container's_ classpath.
The Apache JSP engine will find the JSTL tag definitions inside these jars during startup.
As an efficiency enhancement, you can have jetty examine the jstl jars
to find the tags, and pre-feed them into the Apache JSP engine. This is
more efficient, because jetty will only scan the jars you tell it to,
whereas the Apache JSP engine will scan every jar, which can be
time-consuming in applications with a lot of jars on the container
classpath.
As an efficiency enhancement, you can have jetty examine the JSTL jars to find the tags, and pre-feed them into the Apache JSP engine.
This is more efficient, because jetty will only scan the jars you tell it to, whereas the Apache JSP engine will scan every jar, which can be time-consuming in applications with a lot of jars on the container classpath.
To take advantage of this efficiency enhancement, set up the
link:#container-include-jar-pattern[org.eclipse.jetty.server.webapp.ContainerIncludeJarPattern]
to include a
http://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html[pattern]
that will match the names of the jstl jars. The
link:#embedded-examples[Embedded Examples] section includes a
link:#embedded-webapp-jsp[worked code example] of how to do this, here's
a snippet from it:
To take advantage of this efficiency enhancement, set up the link:#container-include-jar-pattern[org.eclipse.jetty.server.webapp.ContainerIncludeJarPattern] to include a http://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html[pattern] that will match the names of the JSTL jars.
The link:#embedded-examples[Embedded Examples] section includes a link:#embedded-webapp-jsp[worked code example] of how to do this.
Below is a snippet from the example:
[source, java, subs="{sub-order}"]
----
@ -555,29 +455,22 @@ a snippet from it:
[[using-jsf-taglibs]]
==== Using JSF Taglibs
The following sections provide information about using JSF taglibs with
Jetty Standalone and the Jetty Maven Plugin.
The following sections provide information about using JSF TagLibs with Jetty Standalone and the Jetty Maven Plugin.
[[using-jsf-taglibs-with-jetty-standalone]]
===== Using JSF Taglibs with Jetty Distribution
If you want to use JSF with your webapp, you need to copy the JSF
implementation Jar (whichever Jar contains the `META-INF/*.tld` files
from your chosen JSF implementation) into Jetty's shared container lib
directory. You can either put them into the lib directory matching your
JSP container of choice (either $JETTY_HOME/lib/jsp for Glassfish JSP,
or $JETTY_HOME/lib/apache-jsp for Apache JSP), or put them into
$JETTY_HOME/lib/ext.
If you want to use JSF with your webapp, you need to copy the JSF implementation Jar (whichever Jar contains the `META-INF/*.tld` files from your chosen JSF implementation) into Jetty's shared container lib directory.
You can either put them into the lib directory matching your JSP container of choice (either `{$jetty.home}/lib/jsp` for Glassfish JSP, or `{$jetty.home}/lib/apache-jsp` for Apache JSP), or put them into `{$jetty.home}/lib/ext`.
[[using-jsf-taglibs-with-jetty-maven-plugin]]
===== Using JSF Taglibs with Jetty Maven Plugin
You should make your JSF jars dependencies of the plugin and _not_ the
webapp itself. For example:
You should make your JSF jars dependencies of the plugin and _not_ the webapp itself.
For example:
[source, xml, subs="{sub-order}"]
----
<plugin>
<groupId>org.eclipse.jetty</groupId>
<artifactId>jetty-maven-plugin</artifactId>
@ -600,6 +493,4 @@ webapp itself. For example:
</dependency>
</dependencies>
</plugin>
----

2
jetty-documentation/src/main/asciidoc/configuring/security/spnego-support.adoc
View File

@ -164,7 +164,7 @@ ____
You must go to the hostname and not the IP.
If you go to the IP it will default to NTLM authentication...the following conditions must be true for Spnego authentication to work:
* You must be within the Intranet Zone of the network
* Accessing the server using a Hostname rather thAn IP
* Accessing the server using a Hostname rather than IP
* Integrated Windows Authentication in IE is enabled and the host is trusted in Firefox
* The server is not local to the browser, it can't be running on localhost
* The client's Kerberos system is authenticated to a domain controller