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

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

@ -18,10 +18,10 @@
== Starting Jetty == Starting Jetty
include::startup-overview.adoc[] include::startup-overview.adoc[]
include::start-jar.adoc[]
include::startup-base-vs-home.adoc[]
include::startup-xml-config.adoc[] include::startup-xml-config.adoc[]
include::startup-classpath.adoc[] include::startup-classpath.adoc[]
include::startup-modules.adoc[] include::startup-modules.adoc[]
include::startup-base-vs-home.adoc[]
include::start-jar.adoc[]
include::startup-unix-service.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 Environment:
----------------- -----------------
java.home = /lib/jvm/jdk-8u45/jre java.home = /lib/jvm/jdk-8u92/jre
java.vm.vendor = Oracle Corporation 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.name = Java HotSpot(TM) 64-Bit Server VM
java.vm.info = mixed mode java.vm.info = mixed mode
java.runtime.name = Java(TM) SE Runtime Environment 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 java.io.tmpdir = /tmp
user.dir = /home/jetty/mybase user.dir = /home/jetty/mybase
user.language = en 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}"] [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 ... WARNING: Nothing to start, exiting ...
Usage: java -jar start.jar [options] [properties] [configs] Usage: java -jar start.jar [options] [properties] [configs]

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

@ -17,9 +17,7 @@
[[start-jar]] [[start-jar]]
=== Using start.jar === Using start.jar
The most basic way of starting the Jetty standalone server is to execute 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 `start.jar`, which is a bootstrap for starting Jetty with the
configuration you want.
[source, screen, subs="{sub-order}"] [source, screen, subs="{sub-order}"]
.... ....
@ -28,86 +26,58 @@ configuration you want.
... ...
.... ....
Jetty is a highly modularized web server container. Very little is Jetty is a highly modularized web server container.
mandatory and required, and most components are optional; you enable or Very little is mandatory and required, and most components are optional; you enable or disable them according to the needs of your environment.
disable them according to the needs of your environment.
At its most basic, you configure Jetty from two elements: At its most basic, you configure Jetty from two elements:
1. A set of libraries and directories that make up the server 1. A set of libraries and directories that make up the server classpath.
classpath. 2. A set of Jetty XML configuration files (IoC style) that establish how to build the Jetty server and its components.
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 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).
(these are merely syntactic sugar that eventually resolve into the two
basic configuration components).
Jetty 9.1 Startup Features include: Jetty 9.1 Startup Features include:
* A separation of the Jetty distribution binaries in `${jetty.home}` and * 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.])
the environment specific configurations (and binaries) found in * You can enable a set of libraries and XML configuration files via the newly introduced link:#startup-modules[module system.]
`${jetty.base}` (detailed in * 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]).
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
These are powerful new features, made to support a variety of styles of 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.
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 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.
upgrade the Jetty distribution without having to remake your entire tree 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.
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 [[executing-startjar]]
command line arguments.
==== 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. * Loads and parses `${jetty.base}/start.ini` as command line arguments.
* Parses actual command line arguments used to execute `start.jar` * Parses actual command line arguments used to execute `start.jar` itself.
itself. * Resolves any XML configuration files, modules, and libraries using base vs. home resolution steps:
* 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}.` 1. Checks whether file exists as relative reference to `${jetty.base}.`
2. Checks whether file exists as relative reference to `${jetty.home}.` 2. Checks whether file exists as relative reference to `${jetty.home}.`
3. Uses default behavior of `java.io.File.` 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).
(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. * Builds out server classpath.
* Determines run mode: * Determines run mode:
** Shows informational command line options and exit. ** Shows informational command line options and exit.
** Executes Jetty normally, waits for Jetty to stop. ** Executes Jetty normally, waits for Jetty to stop.
** Executes a forked JVM to run Jetty in, waits for forked JVM to exit. ** 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 ==== start.jar Command Line Options
--help:: --help::
Obtains the current list of command line options and some basic usage Obtains the current list of command line options and some basic usage help.
help.
--version:: --version::
Shows the list of server classpath entries, and prints version Shows the list of server classpath entries, and prints version information found for each entry.
information found for each entry.
--list-classpath:: --list-classpath::
Similar to --version, shows the server classpath. Similar to --version, shows the server classpath.
--list-config:: --list-config::
Lists the resolved configuration that will start Jetty. Lists the resolved configuration that will start Jetty.
+ +
* Java environment * Java environment
* Jetty environment * Jetty environment
@ -116,64 +86,53 @@ module system).
* Server classpath * Server classpath
* Server XML configuration files * Server XML configuration files
--dry-run:: --dry-run::
Prints the resolved command line that `start.jar` should use to start Prints the resolved command line that `start.jar` should use to start a forked instance of Jetty.
a forked instance of Jetty.
--exec:: --exec::
Starts a forked instance of Jetty. Starts a forked instance of Jetty.
--debug:: --debug::
Enables debugging output of the startup procedure. Enables debugging output of the startup procedure.
+ +
Note: This does not set up debug logging for Jetty itself. *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>:: --start-log-file=<filename>::
Sends all startup output to the filename specified. Sends all startup output to the filename specified.
+ +
Filename is relative to `${jetty.base}`. 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.
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:: --list-modules::
Lists all the modules defined by the system. Lists all the modules defined by the system.
+ +
Looks for module files using the link:#startup-base-and-home[normal Looks for module files using the link:#startup-base-and-home[normal `${jetty.base}` and `${jetty.home}` resolution logic].
`${jetty.base}` and `${jetty.home}` resolution logic].
+ +
Also lists enabled state based on information present on the command Also lists enabled state based on information present on the command line, and all active startup INI files.
line, and all active startup INI files.
--module=<name>,(<name>)*:: --module=<name>,(<name>)*::
Enables one or more modules by name (use --list-modules to see the Enables one or more modules by name (use `--list-modules` to see the list of available modules).
list of available modules).
+ +
This enables all transitive (dependent) modules from the module system This enables all transitive (dependent) modules from the module system as well.
as well.
+ +
If you use this from the shell command line, it is considered a If you use this from the shell command line, it is considered a temporary effect, useful for testing out a scenario.
temporary effect, useful for testing out a scenario. If you want this If you want this module to always be enabled, add this command to your `${jetty.base}/start.ini.`
module to always be enabled, add this command to your
`${jetty.base}/start.ini.`
--add-to-start=<name>,(<name>)*:: --add-to-start=<name>,(<name>)*::
Enables a module by appending lines to the `${jetty.base}/start.ini` Enables a module by appending lines to the `${jetty.base}/start.ini` file.
file.
+ +
The lines that are added are provided by the module-defined INI The lines that are added are provided by the module-defined INI templates.
templates.
+ +
Note: Transitive modules are also appended. Note: Transitive modules are also appended.
--add-to-startd=<name>,(<name>)*:: --add-to-startd=<name>,(<name>)*::
Enables a module via creation of a module-specific INI file in the Enables a module via creation of a module-specific INI file in the `${jetty.base}/start.d/` directory.
`${jetty.base}/start.d/` directory.
+ +
The content of the new INI is provided by the module-defined ini The content of the new INI is provided by the module-defined ini templates.
templates.
+ +
Note: Transitive modules are also created in the same directory as Note: Transitive modules are also created in the same directory as their own INI files.
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>:: --write-module-graph=<filename>::
Advanced feature: Creates a graphviz 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}`.
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}"] [source, screen, subs="{sub-order}"]
.... ....
@ -184,22 +143,17 @@ $ java -jar start.jar --module=websocket --write-module-graph=modules.dot
$ dot -Tpng -o modules.png modules.dot $ dot -Tpng -o modules.png modules.dot
.... ....
+ +
See http://graphviz.org/[graphviz.org] for details on 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.
http://graphviz.org/content/command-line-invocation[how to
post-process this dotty file] into the output best suited for your
needs.
--stop:: --stop::
Sends a stop signal to the running Jetty instance. Sends a stop signal to the running Jetty instance.
+ +
Note: The server must have been started with various stop properties Note: The server must have been started with various stop properties for this to work.
for this to work.
+
STOP.PORT=<number>;; STOP.PORT=<number>;;
The port to use to stop the running Jetty server. This is an The port to use to stop the running Jetty server.
internal port, opened on localhost, used solely for stopping the This is an internal port, opened on localhost, used solely for stopping the running Jetty server.
running Jetty server. Choose a port that you do not use to serve web Choose a port that you do not use to serve web traffic.
traffic.
+ +
Required for --stop to function. Required for --stop to function.
STOP.KEY=<alphanumeric>;; STOP.KEY=<alphanumeric>;;
@ -207,9 +161,7 @@ $ dot -Tpng -o modules.png modules.dot
+ +
Required for --stop to function. Required for --stop to function.
STOP.WAIT=<number>;; STOP.WAIT=<number>;;
The time (in seconds) to wait for confirmation that the running The time (in seconds) to wait for confirmation that the running Jetty server has stopped.
Jetty server has stopped. If not specified, the stopper waits If not specified, the stopper waits indefinitely for the server to stop.
indefinitely for the server to stop.
+ +
If the time specified elapses, without a confirmation of server If the time specified elapses, without a confirmation of server stop, then the `--stop` command exits with a non-zero return code.
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]] [[startup-base-and-home]]
=== Managing Jetty Base and Jetty Home === Managing Jetty Base and Jetty Home
Starting with Jetty 9.1, it is now possible to maintain a separation 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}`).
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:: Jetty Base::
Also known as the `${jetty.base}` property * Also known as the `${jetty.base}` property.
+ * This is the location for your configurations and customizations to the Jetty distribution.
This is the location for your configurations and customizations to the
Jetty distribution.
Jetty Home:: Jetty Home::
Also known as the `${jetty.home}` property. * Also known as the `${jetty.home}` property.
+ * This is the location for the Jetty distribution binaries, default XML IoC configurations, and default module definitions.
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. Potential configuration is resolved from these 2 directory locations.
Check Jetty Base:: Check Jetty Base::
If the referenced configuration exists, relative to the defined Jetty If the referenced configuration exists, relative to the defined Jetty base, use it.
Base, use it.
Check Jetty Home:: Check Jetty Home::
If the referenced configuration exists, relative to the defined Jetty If the referenced configuration exists, relative to the defined Jetty home, use it.
Home, use it.
Use java.io.File(String pathname) Logic:: Use java.io.File(String pathname) Logic::
Lastly, use the reference as a `java.io.File(String Lastly, use the reference as a `java.io.File(String pathname)` reference, following the default resolution rules outlined by that constructor.
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).
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]]
==== Demo-Base in the Jetty Distribution ==== Demo-Base in the Jetty Distribution
The Jetty Distribution comes with an example $\{jetty.base} which The Jetty Distribution comes with an example `${jetty.base}` which enables the various demonstration webapps and server configurations.
enables the various demonstration webapps and server configurations.
How to use the demo-base directory as a Jetty Base directory. How to use the demo-base directory as a Jetty Base directory.
[source, screen, subs="{sub-order}"] [source, screen, subs="{sub-order}"]
.... ....
[jetty-distribution-{VERSION}]$ ls -la [jetty-distribution-{VERSION}]$ ls -la
total 496 total 496
drwxrwxr-x 11 user group 4096 Oct 8 15:23 ./ drwxrwxr-x 11 user group 4096 Oct 8 15:23 ./
drwxr-xr-x 14 user group 4096 Oct 8 13:04 ../ 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 71921 Sep 30 19:55 start.jar
-rw-rw-r-- 1 user group 336468 Sep 30 19:55 VERSION.txt -rw-rw-r-- 1 user group 336468 Sep 30 19:55 VERSION.txt
drwxrwxr-x 2 user group 4096 Oct 8 06:54 webapps/ drwxrwxr-x 2 user group 4096 Oct 8 06:54 webapps/
[jetty-distribution-{VERSION}]$ cd demo-base [jetty-distribution-{VERSION}]$ cd demo-base
[demo-base]$ java -jar $JETTY_HOME/start.jar [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.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.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 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 As you can see above, you are executing the demo-base configuration using the Jetty base concepts.
using the Jetty Base concepts.
If you want to see what the Jetty Base looks like without executing If you want to see what the Jetty base looks like without executing Jetty, you can simply list the configuration
Jetty, you can simply list the configuration
[source, screen, subs="{sub-order}"] [source, screen, subs="{sub-order}"]
.... ....
@ -210,22 +197,17 @@ Jetty Active XMLs:
${jetty.base}/etc/test-realm.xml ${jetty.base}/etc/test-realm.xml
.... ....
This demonstrates the powerful `--list-config` command line option and 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.
how you can use it to see what the configuration will look like when 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.
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.
Of note, is that the output will make it known where the 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}`.
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 If you look at the `${jetty.base}/start.ini` you will see a layout similar to below.
the following.
[source, screen, subs="{sub-order}"] [source, screen, subs="{sub-order}"]
.... ....
[my-base]$ cat start.ini [my-base]$ cat start.ini
# Enable security via jaas, and configure it # Enable security via jaas, and configure it
--module=jaas --module=jaas
jaas.login.conf=etc/login.conf jaas.login.conf=etc/login.conf
@ -259,71 +241,64 @@ jetty.dump.stop=false
--module=annotations --module=annotations
.... ....
The $\{jetty.base}/start.ini is the main startup configuration entry The `${jetty.base}/start.ini` is the main startup configuration entry point for Jetty.
point for Jetty. In this example you will see that we are enabling a few 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)
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 When Jetty's `start.jar` resolves the entries in the `start.ini`, it will follow the link:#base-vs-home-resolution[resolution rules above].
follow the link:#base-vs-home-resolution[resolution rules above].
For example, the reference to `etc/demo-rewrite-rules.xml` was found in For example, the reference to `etc/demo-rewrite-rules.xml` was found in `${jetty.base}/etc/demo-rewrite-rules.xml`.
`${jetty.base}/etc/demo-rewrite-rules.xml`.
==== Declaring Jetty Base ==== Declaring Jetty Base
The Jetty Distribution's start.jar is the component that manages the The Jetty distribution's `start.jar` is the component that manages the behavior of this separation.
behavior of this separation.
The Jetty start.jar and XML files always assume that both The Jetty `start.jar` and XML files always assume that both `${jetty.home}` and `${jetty.base}` are defined when starting Jetty.
`${jetty.home}` and `${jetty.base}` are defined when starting Jetty.
You can opt to manually define the `${jetty.home}` and `${jetty.base}` You can opt to manually define the `${jetty.home}` and `${jetty.base}` directories, such as this:
directories, such as this:
[source, screen, subs="{sub-order}"] [source, screen, subs="{sub-order}"]
.... ....
[jetty-distribution-{VERSION}]$ pwd [jetty-distribution-{VERSION}]$ pwd
/home/user/jetty-distribution-{VERSION} /home/user/jetty-distribution-{VERSION}
[jetty-distribution-{VERSION}]$ java -jar start.jar \ [jetty-distribution-{VERSION}]$ java -jar start.jar \
jetty.home=/home/user/jetty-distribution-{VERSION} \ jetty.home=/home/user/jetty-distribution-{VERSION} \
jetty.base=/home/user/my-base 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.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 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 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 parent directory of wherever start.jar itself is, and a manual
declaration of `${jetty.base}`.
[source, screen, subs="{sub-order}"] [source, screen, subs="{sub-order}"]
.... ....
[jetty-distribution-{VERSION}]$ pwd [jetty-distribution-{VERSION}]$ pwd
/home/user/jetty-distribution-{VERSION} /home/user/jetty-distribution-{VERSION}
[jetty-distribution-{VERSION}]$ java -jar start.jar jetty.base=/home/user/my-base [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.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 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 But Jetty recommends that you always start Jetty from the directory that is your `${jetty.base}` and starting Jetty by referencing
directory that is your $\{jetty.base} and starting Jetty by referencing the `start.jar` in your `{$jetty.home}` remotely.
the start.jar remotely.
The following demonstrates this by allowing default discovery of 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}`.
`${jetty.home}` via locating the `start.jar`, and using the `user.dir`
System Property for `${jetty.base}`.
[source, screen, subs="{sub-order}"] [source, screen, subs="{sub-order}"]
.... ....
[jetty-distribution-{VERSION}]$ pwd [jetty-distribution-{VERSION}]$ pwd
/home/user/jetty-distribution-{VERSION} /home/user/jetty-distribution-{VERSION}
[jetty-distribution-{VERSION}]$ cd /home/user/my-base [jetty-distribution-{VERSION}]$ cd /home/user/my-base
[my-base]$ java -jar /home/user/jetty-distribution-{VERSION}/start.jar [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.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 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] [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. 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. Jetty Server Classpath is determined by a combination of factors.
The java.class.path System Property:: The java.class.path System Property::
If you start Jetty with a JVM specified classpath, then Jetty will use If you start Jetty with a JVM specified classpath, then Jetty will use the java.class.path System Property to populate the initial classpath.
the java.class.path System Property to populate the initial classpath.
Module specified Libraries:: Module specified Libraries::
With Jetty 9.1+ the module system declares various libraries that are The module system declares various libraries that are required for that module to operate.
required for that module to operate, these module defined libraries These module defined libraries are added to the Jetty Server classpath when any module is activated with library declarations.
are added to the Jetty Server classpath when any module is activated
with library declarations.
Command Line Libraries:: Command Line Libraries::
The command line option `--lib=<path>`can be used as a final means to The command line option `--lib=<path>` can be used as a final means to add arbitrary entries to the Jetty Server classpath.
add arbitrary entries to the Jetty Server classpath.
Of special note, there are 2 structural modules defined to ease some of Of special note, there are 2 structural modules defined to ease some of this for you.
this for you.
--module=ext:: --module=ext::
The `ext` module will enable the `lib/ext/*.jar` logic. The `ext` module will enable the `lib/ext/*.jar` logic.
+ +
If this module is activated, then all jar files found in the lib/ext/ If this module is activated, then all jar files found in the lib/ext/ paths will be automatically added to the Jetty Server Classpath.
paths will be automatically added to the Jetty Server Classpath.
--module=resources:: --module=resources::
The `resources` module will add the `resources/` directory the The `resources` module will add the `resources/` directory the classpath.
classpath.
+ +
If you have 3rd party libraries that lookup resources from the If you have 3rd party libraries that lookup resources from the classpath, put your files in here.
classpath, put your files in here.
+ +
Logging libraries often have classpath lookup of their configuration 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.
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] [NOTE]
@ -58,14 +47,11 @@ ____
==== Interrogating the Server Classpath ==== Interrogating the Server Classpath
The Jetty start.jar has the ability to resolve the classpath from the 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.
command line + modules + configuration, and list the classpath entries
it will use to start jetty.
The `--list-classpath` command line option is used as such. The `--list-classpath` command line option is used as such.
(Demonstrated with the link:#demo-base[demo-base from the Jetty (Demonstrated with the link:#demo-base[demo-base from the Jetty Distribution])
Distribution])
[source, screen, subs="{sub-order}"] [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 41: {VERSION} | ${jetty.home}/lib/websocket/websocket-servlet-{VERSION}.jar
.... ....
Of note is that an attempt is made to list the internally declared 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.
version of each artifact on the Server Classpath, of potential help when
diagnosing classpath issues.

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

@ -17,152 +17,94 @@
[[startup-modules]] [[startup-modules]]
=== Managing Startup Modules === Managing Startup Modules
Starting with Jetty 9.1, a new Module system was introduced. (It Starting with Jetty 9.1, a new Module system was introduced, replacing the previous `start.config` + `OPTIONS` techniques from past Jetty Distributions.
replaced the old `start.config` + `OPTIONS` techniques from past Jetty
Distributions).
The standard Jetty Distribution ships with several modules defined in The standard Jetty Distribution ships with several modules defined in `${jetty.home}/modules/`.
`${jetty.home}/modules/`
What a Jetty Startup Module Defines: What a Jetty Startup Module Defines:
A Module Name:: A Module Name::
The name of the module is the keyword used by the `--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 dependent modules.
command line argument to activate/enable modules, and also find The filename of the module defines its name (eg: server.mod becomes the module named "server").
dependant modules.
+
The filename of the module defines its name. (eg: server.mod becomes
the module named "server")
List of Dependant Modules:: List of Dependant Modules::
All modules can declare that they depend on other modules with the All modules can declare that they depend on other modules with the `[depend]` section.
`[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.
The list of dependencies is used to transitively resolve other modules 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.
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.
List of Libraries:: List of Libraries::
Module can optionally declare that they have libraries that they need Module can optionally declare that they have libraries that they need to function properly.
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].
+
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:: List of Jetty IoC XML Configurations::
A Module can optionally declare a 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.
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.
The `[xml]` section declares a set of pathnames that follow the Allowing for a simplified configuration of Jetty for the vast majority of deployments.
link:#base-vs-home-resolution[Jetty Base and Jetty Home path The execution order of the Jetty IoC XML configurations is determined by the graph of active module dependencies resolved via the `[depend]` sections.
resolution rules]. 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}`.
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:: Jetty INI Template::
Each module can optionally declare a startup ini template that is used 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`.
to insert/append/inject sample configuration elements into the Commonly used to present some of the parameterized property options from the Jetty IoC XML configuration files also referenced in the same module.
`start.ini` or `start.d/*.ini` files when using the The `[ini-template]` section declares this section of sample configuration.
`--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:: Required Files and Directories::
If the activation of a module requires some paths to exist, the If the activation of a module requires some paths to exist, the `[files]` section defines them.
`[files]` section defines them.
+
There are 2 modes of operation of the entries in this section. There are 2 modes of operation of the entries in this section.
+
Ensure Directory Exists;; Ensure Directory Exists;;
If you add a pathname that ends in `"/"` (slash), such as 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).
`"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;; Download File;;
There is a special syntax to allow you to download a file into a There is a special syntax to allow you to download a file into a specific location if it doesn't exist yet: `<url>:<pathname>`.
specific location if it doesn't exist yet. 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].
`<url>:<pathname>` 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
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
`http://repo.corp.com/maven/corp-security-policy-1.0.jar` `http://repo.corp.com/maven/corp-security-policy-1.0.jar`
[[enabling-modules]] [[enabling-modules]]
==== Enabling Modules ==== Enabling Modules
Jetty ships with many modules defined, and a small subset predefined in Jetty ships with many modules defined, and a small subset predefined in the `start.ini` found in the jetty distribution.
the `start.ini` found in the jetty distribution.
____ ____
[TIP] [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. 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. 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>` 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.
syntax on the command line (or start.ini) to enable that module and all
of its dependant modules.
An example of this, with a new, empty, base directory. 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 include::screen-empty-base.adoc[]
after all).
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 include::screen-empty-base-listconfig.adoc[]
(hot deploy), and a single basic HTTP/1.1 connector.
That just created what we need in the `${jetty.base}` directory. Lets Lets try adding some basic support for webapps, with automatic deploy (hot deploy), and a single basic HTTP/1.1 connector.
see what it looks like configuration wise.
You now have a configured and functional server, albiet with no webapps include::screen-http-webapp-deploy.adoc[]
deployed. At this point you can toss a webapp (war file) into
`mybase/webapps/` directory and and start Jetty 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]] [[startup-listing-modules]]
==== Listing Available and Active Modules ==== Listing Available and Active Modules
To see which modules are __available__, use the `--list-modules` command To see which modules are __available__, use the `--list-modules` command line argument.
line argument. This command will also show you which modules are This command will also show you which modules are __enabled__.
__enabled__. Here's an example 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 Since being introduced in Jetty 9.1 the modules provided in the Jetty distribution has expanded greatly.
Jetty 9 Below is a graphical representation of the standard modules and their dependencies.
image:images/modules-9.3-simplified.png[image,width=768] 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]]
=== Startup Overview === Startup Overview
The `start.jar` bootstrap manages the startup of standalone Jetty. It is The `start.jar` bootstrap manages the startup of standalone Jetty.
responsible for: It is responsible for:
Building the classpath:: Building the classpath::
The `start.jar` bootstrap builds a classpath for all the required The `start.jar` bootstrap builds a classpath for all the required Jetty features and their dependencies.
Jetty features and their dependencies. It builds the classpath using 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).
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:: Instantiating the Server Components::
The server and its components are instantiated using either Jetty IoC The server and its components are instantiated using either Jetty IoC XML or Spring.
XML or spring. The Jetty server is just a collection of java POJOs for The Jetty server is a collection of POJOs for the server, connectors, session managers and others.
the server, connectors, session managers and others. These are These are instantiated, injected, and wired up together in XML files, commonly one per module/feature, that are passed as arguments to `start.jar`.
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:: Resolving Server Filesystem Locations::
The `start.jar` mechanism resolves canonical locations for the The `start.jar` mechanism resolves canonical locations for the `${jetty.home}` and the `${jetty.base}` directories.
`${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 If you want to modify the Jetty distribution, base and home can be the same directory.
distribution of Jetty. 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.
+
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.
Parameterizing the Server Configuration:: Parameterizing the Server Configuration::
XML files primarily determine the server configuration. Many of these XML files primarily determine the server configuration.
files are parameterized to allow simple injection of host names, Many of these files are parameterized to allow simple injection of host names, ports, passwords and more.
ports, passwords and more. The `start.jar` mechanism allows you to set The `start.jar` mechanism allows you to set parameters on the command line or in properties files.
parameters on the command line or in properties files.
To achieve these start up mechanisms, the `start.jar` uses: To achieve these start up mechanisms, the `start.jar` uses:
Command line arguments:: Command line arguments::
You can configure the entire server with command line arguments that You can configure the entire server with command line arguments that specify libraries, properties and XML files.
specify libraries, properties and XML files. However in practice the However in practice the INI and modules mechanisms (below) reduce the verbosity of the command line.
INI and modules mechanisms (below) reduce the verbosity of the command
line.
INI files:: INI files::
The `start.jar` mechanism uses the contents of the 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.
`${jetty.base}/start.ini` and `${jetty.base}/start.d/*.ini` files with This means that either a global `start.ini` file or multiple `start.d/feature.ini` files control the configuration of the server.
each line equivalent to a `start.jar` command line argument. This [NOTE]
means that either a global `start.ini` file or multiple --
`start.d/feature.ini` files control the configuration of the server. 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:: Modules::
Instead of explicitly listing all the libraries, properties and XML Instead of explicitly listing all the libraries, properties and XML files for a feature, the `start.jar` mechanism allows you to create modules.
files for a feature, the `start.jar` mechanism allows you to create A module is defined in a `modules/*.mod` file, including the libraries, dependencies, XML, and template INI files for a Jetty feature.
modules. You define a module in a `modules/*.mod` file, including the 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.
libraries, dependencies, XML, and template INI files for a Jetty Modules also use their dependencies to control the ordering of libraries and XML files.
feature. Thus you can use a single `--module=name` command line option 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.
as the equivalent of specifying many `--lib=location`, feature.xml, These module files should *only* be edited if you are making structural changes to the way the feature will perform.
name=value arguments for a feature and all its dependencies. Modules For more information, refer to the section on <<startup-modules,managing startup modules>> later in this chapter.
also use their dependencies to control the ordering of libraries and
XML files.
XML Files:: XML Files::
XML files in either Jetty IoC or Spring format instantiate the actual XML files in either Jetty IoC or Spring format instantiate the actual POJO components of the server.
POJO components of the server. This includes all major components such This includes all major components such as connectors, keystores, session managers, and data sources.
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.
Typically there are one or more XML files per module, and these are
defined and activated in the corresponding module.
==== Startup Example ==== Startup Example
The simplest way to start Jetty is via the `start.jar` mechanism using The simplest way to start Jetty is via the `start.jar` mechanism using the following Java command line:
the following Java command line:
[source, screen, subs="{sub-order}"] [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 [jetty-distribution-{VERSION}]$ java -jar start.jar --module=http jetty.http.port=8080
.... ....
This command uses the `start.jar` mechanism to bootstrap the classpath, This command uses the `start.jar` mechanism to bootstrap the classpath, properties, and XML files with the metadata obtained from the `http` module.
properties, and XML files with the metadata obtained from the `http` Specifically the `http` module is defined in the `${jetty.home}/modules/http.mod` file, and includes the following:
module. Specifically the `http` module is defined in the
`${jetty.home}/modules/http.mod` file, and includes the following:
[source, screen, subs="{sub-order}"] [source, screen, subs="{sub-order}"]
.... ....
@ -112,14 +92,10 @@ jetty.http.port=8080
http.timeout=30000 http.timeout=30000
.... ....
The `http` module declares that `http` depends on the server module, 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.
uses the `jetty-http.xml` file, and can be parameterized with 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.
`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` Following the server dependency, the `${jetty.home}/modules/server.mod` file includes:
file includes:
[source, screen, subs="{sub-order}"] [source, screen, subs="{sub-order}"]
.... ....
@ -140,13 +116,10 @@ threads.min=10
threads.max=200 threads.max=200
.... ....
The `server` module declares the libraries the server needs and t0 use The `server` module declares the libraries the server needs and to use `jetty.xml` file.
`jetty.xml` file. The combined metadata of the `http` and `server` The combined metadata of the `http` and `server` modules results in `start.jar` generating the effective Java command line required to start Jetty.
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 Another way to see this is by asking Jetty what its configuration looks like by appending --list-config to the command line:
like:
[source, screen, subs="{sub-order}"] [source, screen, subs="{sub-order}"]
.... ....
@ -201,14 +174,11 @@ Jetty Active XMLs:
${jetty.home}/etc/jetty-http.xml ${jetty.home}/etc/jetty-http.xml
.... ....
This represents the entirety of the configuration that is applied to This represents the entirety of the configuration that is applied to start Jetty.
start Jetty.
If you don't want to use the `start.jar` bootstrap, you can start Jetty If you don't want to use the `start.jar` bootstrap, you can start Jetty using a traditional Java command line.
using a traditional Java command line.
The following is the equivalent `java` command line for what the The following is the equivalent Java command line for what the `start.jar` bootstrap above performs.
`start.jar` bootstrap above performs.
[source, screen, subs="{sub-order}"] [source, screen, subs="{sub-order}"]
.... ....
@ -233,14 +203,9 @@ $JETTY_HOME/etc/jetty.xml \
$JETTY_HOME/etc/jetty-http.xml $JETTY_HOME/etc/jetty-http.xml
.... ....
The java command line sets up the classpath with the core Jetty jars and 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 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 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:
template defined by the modules to create a `start.ini` file with the
command:
[source, screen, subs="{sub-order}"] [source, screen, subs="{sub-order}"]
.... ....
@ -251,11 +216,14 @@ command:
total 8 total 8
drwxrwxr-x 2 user webgroup 4096 Oct 4 11:49 ./ drwxrwxr-x 2 user webgroup 4096 Oct 4 11:49 ./
drwxrwxr-x 12 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 [example-base]$ java -jar $JETTY_HOME/start.jar --add-to-start=http
WARNING: http initialised in ${jetty.base}/start.ini (appended) WARNING: http initialised in ${jetty.base}/start.ini (appended)
WARNING: http enabled in ${jetty.base}/start.ini WARNING: http enabled in ${jetty.base}/start.ini
WARNING: server initialised in ${jetty.base}/start.ini (appended) WARNING: server initialised in ${jetty.base}/start.ini (appended)
WARNING: server enabled in ${jetty.base}/start.ini WARNING: server enabled in ${jetty.base}/start.ini
[example-base]$ ls -la [example-base]$ ls -la
total 12 total 12
drwxrwxr-x 2 user webgroup 4096 Oct 4 11:55 ./ 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 -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 Once complete, you can edit the `start.ini` file to modify any parameters and you can run the server with the simple command:
parameters and you can run the server with the simple command:
[source, screen, subs="{sub-order}"] [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]] [[startup-xml-config]]
=== Managing XML Based Startup Configuration === Managing XML Based Startup Configuration
When you see XML files on the command line for startup of Jetty, they When you see XML files on the command line for startup of Jetty, they are always part of the Jetty IoC Configuration mechanism.
are always part of the Jetty IoC Configuration mechanism.
Internally, Jetty uses these XML files to build up Jetty with the Internally, Jetty uses these XML files to build up Jetty with the features that you wan to use.
features that you wan to use.
The module mechanism present in Jetty determines the load order of the The module mechanism present in Jetty determines the load order of the XML files.
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.
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.

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

@ -17,73 +17,43 @@
[[jsp-support]] [[jsp-support]]
=== Configuring JSP === Configuring JSP
This document provides information about configuring Java Server Pages This document provides information about configuring Java Server Pages (JSP) for Jetty.
for Jetty.
[[which-jsp-implementation]] [[which-jsp-implementation]]
==== Which JSP Implementation ==== Which JSP Implementation
From jetty-9.2 onwards, we are using Jasper from 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.
http://tomcat.apache.org/tomcat-8.0-doc/jasper-howto.html[Apache] as the In previous versions Jasper from http://jsp.java.net[Glassfish] was used, and if you wish to, you can continue to do so.
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.
The jetty-distribution by default enables the jsp 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.
link:#startup-modules[module], and by default, this To change to use Glassfish Jasper instead, edit the `{jetty.home}/modules/jsp.mod` file and change the line indicated:
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:
[source, plain, subs="{sub-order}"] [source, plain, subs="{sub-order}"]
---- ----
include::{SRCDIR}/jetty-distribution/src/main/resources/modules/jsp.mod[] include::{SRCDIR}/jetty-distribution/src/main/resources/modules/jsp.mod[]
---- ----
Note that the availability of some JSP features may depend on which JSP Note that the availability of some JSP features may depend on which JSP container implementation you are using.
container implementation you are using. Note also that it may not be Note also that it may not be possible to precompile your JSPs with one container and deploy to the other.
possible to precompile your jsps with one container and deploy to the
other.
===== JSPs and Embedding ===== JSPs and Embedding
If you have an embedded setup for your webapp and wish to use jsps, you 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.
will need to ensure that a JSP engine is correctly initialized.
For both Apache and Glassfish JSP engines, a Servlet Specification 3.1 For both Apache and Glassfish JSP engines, a Servlet Specification 3.1 style link:#servlet-container-initializers[ServletContainerInitializer] is used to accomplish this.
style link:#servlet-container-initializers[ServletContainerInitializer] 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.
is used to accomplish this. You will need to ensure that this The link:#embedded-examples[Embedded Examples] section includes a link:#embedded-webapp-jsp[worked code example] of how to do 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 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].
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 ==== Precompiling JSPs
You can either follow the instructions on precompilation provided by the 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.
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 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.
package prefix (which is `org.apache.jsp` by default), you should You can do this using a servlet context init-param called `org.eclipse.jetty.servlet.jspPackagePrefix`.
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 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:
package prefix of `com.acme`, then you would add the following lines to
your web.xml file:
[source, xml, subs="{sub-order}"] [source, xml, subs="{sub-order}"]
---- ----
@ -95,22 +65,19 @@ your web.xml file:
____ ____
[NOTE] [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]] [[compiling-jsps]]
==== Runtime Compiling JSPs ==== Runtime Compiling JSPs
Depending on which JSP container you elect to use, the configuration and Depending on which JSP container you elect to use, the configuration and compilation characteristics will be different.
compilation characteristics will be different.
===== Apache JSP Container ===== Apache JSP Container
By default, the Apache JSP container will look for the Eclipse Java By default, the Apache JSP container will look for the Eclipse Java Compiler (jdt).
Compiler (jdt). The jetty distribution ships a copy of this in The Jetty distribution ships a copy of this in `{$jetty.home}/lib/apache-jsp`.
$JETTY_HOME/lib/apache-jsp. If you wish to use a different compiler, you 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.
will need to configure the `compilerClassName` init-param on the
`JspServlet` with the name of the class.
.Understanding Apache JspServlet Parameters .Understanding Apache JspServlet Parameters
[cols=",,,",options="header",] [cols=",,,",options="header",]
@ -203,44 +170,32 @@ resource usage. |- |–
===== Glassfish JSP Container ===== Glassfish JSP Container
To compile `.jsp` files into Java classes, you need a Java compiler. You To compile `.jsp` files into Java classes, you need a Java compiler.
can acquire a Java compiler from the JVM if you are using a full JDK, or You can acquire a Java compiler from the JVM if you are using a full JDK, or from a third party Jar.
from a third party Jar.
By default, the Glassfish JSP container tries to use the compiler that By default, the Glassfish JSP container tries to use the compiler that is part of the JDK.
is part of the JDK. *NOTE:* when using the JDK compiler, the system does *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.
_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 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/.`
Compiler that Jetty ships in the distro in `$JETTY_HOME/lib/jsp/.`You You need to define a SystemProperty that prevents the Glassfish JSP engine from defaulting to the in-JVM compiler.
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 // 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]:
System property `org.apache.jasper.compiler.disablejsr199` in the jsp //
link:#startup-modules[module]: // [source,text]
// ----
// -Dorg.apache.jasper.compiler.disablejsr199=true
// ----
[source,text] For embedded usages, simply define this as a normal System property.
----
-Dorg.apache.jasper.compiler.disablejsr199=true
----
Or for embedded usages, simply define this as a normal System property.
[[configuring-jsp-for-jetty]] [[configuring-jsp-for-jetty]]
===== Configuration ===== Configuration
The JSP engine has many configuration parameters. Some parameters affect The JSP engine has many configuration parameters.
only precompilation, and some affect runtime recompilation checking. Some parameters affect only precompilation, and some affect runtime recompilation checking.
Parameters also differ among the various versions of the JSP engine. Parameters also differ among the various versions of the JSP engine.
This page lists the configuration parameters, their meanings, and their This page lists the configuration parameters, their meanings, and their default settings.
default settings. Set all parameters on the Set all parameters on the `org.apache.jasper.JspServlet` instance defined in the link:#webdefault-xml[`webdefault.xml`] file.
`org.apache.jasper.JspServlet` instance defined in the
link:#webdefault-xml[`webdefault.xml`] file.
____ ____
[NOTE] [NOTE]
@ -325,10 +280,8 @@ and `development=false`. |– |–
mapping the name of the JSP to class and JSP file. |– |– mapping the name of the JSP to class and JSP file. |– |–
|======================================================================= |=======================================================================
Much confusion generally ensues about the `development`, `checkInterval` Much confusion generally ensues about the `development`, `checkInterval` and `modificationTestInterval` parameters and JSP runtime recompilation.
and ` Here is a factoring out of the various options:
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: * 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-name>development></param-name>
<param-value>true></param-value> <param-value>true></param-value>
</init-param> </init-param>
---- ----
* Only check approximately every N seconds, where a request triggers the * Only check approximately every N seconds, where a request triggers the time-lapse calculation.
time-lapse calculation. This example checks every 60 seconds: This example checks every 60 seconds:
+ +
[source, xml, subs="{sub-order}"] [source, xml, subs="{sub-order}"]
---- ----
<init-param> <init-param>
<param-name>development></param-name> <param-name>development></param-name>
<param-value>true></param-value> <param-value>true></param-value>
@ -356,30 +306,22 @@ time-lapse calculation. This example checks every 60 seconds:
<param-name>modificationTestInterval></param-name> <param-name>modificationTestInterval></param-name>
<param-value>60></param-value> <param-value>60></param-value>
</init-param> </init-param>
---- ----
* Do no checking whatsoever, but still compile the JSP on the very first * Do no checking whatsoever, but still compile the JSP on the very first hit (Be aware that this `reload-interval` parameter is shorthand for
hit. (Be aware that this ''reload-interval'' parameter is shorthand for a `development=false` and `checkInterval=0` combination):
a ''development=false'' and ''checkInterval=0'' combination.):
+ +
[source, xml, subs="{sub-order}"] [source, xml, subs="{sub-order}"]
---- ----
<init-param> <init-param>
<param-name>reload-interval></param-name> <param-name>reload-interval></param-name>
<param-value>-1></param-value> <param-value>-1></param-value>
</init-param> </init-param>
---- ----
* Don't do any request-time checking, but instead start a background * Don't do any request-time checking, but instead start a background thread to do checks every N seconds.
thread to do checks every N seconds. This example checks every 60 This example checks every 60 seconds:
seconds:
+ +
[source, xml, subs="{sub-order}"] [source, xml, subs="{sub-order}"]
---- ----
<init-param> <init-param>
<param-name>development></param-name> <param-name>development></param-name>
<param-value>false></param-value> <param-value>false></param-value>
@ -388,28 +330,21 @@ seconds:
<param-name>checkInterval></param-name> <param-name>checkInterval></param-name>
<param-value>60></param-value> <param-value>60></param-value>
</init-param> </init-param>
---- ----
[[modifying-configuration]] [[modifying-configuration]]
==== Modifying Configuration ==== Modifying Configuration
Regardless of which JSP container you are using, there are several Regardless of which JSP container you are using, there are several options for modifying the JspServlet configuration.
options for modifying the JspServlet configuration.
[[overriding-webdefault.xml]] [[overriding-webdefault.xml]]
===== Overriding `webdefault.xml` ===== Overriding `webdefault.xml`
You can make a copy of the 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.
link:#webdefault-xml[$JETTY_HOME/etc/webdefault.xml] that ships with The example below shows how to do this when using the Jetty Maven plugin.
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}"] [source, xml, subs="{sub-order}"]
---- ----
<plugin> <plugin>
<groupId>org.eclipse.jetty</groupId> <groupId>org.eclipse.jetty</groupId>
<artifactId>jetty-maven-plugin</artifactId> <artifactId>jetty-maven-plugin</artifactId>
@ -418,18 +353,12 @@ plugin.
<defaultsDescriptor>src/main/resources/webdefault.xml</defaultsDescriptor> <defaultsDescriptor>src/main/resources/webdefault.xml</defaultsDescriptor>
</webApp> </webApp>
</plugin> </plugin>
---- ----
If you are using the Jetty distro, and you want to change the JSP 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:
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}"] [source, xml, subs="{sub-order}"]
---- ----
<Configure class=>"org.eclipse.jetty.webapp.WebAppContext"> <Configure class=>"org.eclipse.jetty.webapp.WebAppContext">
<Set name=>"contextPath">/foo</Set> <Set name=>"contextPath">/foo</Set>
@ -437,25 +366,19 @@ file as the defaultsDescriptor for your webapp. Here's a snippet:
<Set name=>"defaultsDescriptor">/home/smith/dev/webdefault.xml</Set> <Set name=>"defaultsDescriptor">/home/smith/dev/webdefault.xml</Set>
</Configure> </Configure>
---- ----
If you want to change the JSP settings for all webapps, edit If you want to change the JSP settings for all webapps, edit the `{$jetty.home}/etc/webdefaults.xml` file directly instead.
the` $JETTY_HOME/etc/webdefaults.xml` file directly instead.
[[configuring-jsp-servlet-in-web.xml]] [[configuring-jsp-servlet-in-web.xml]]
===== Configuring the JSP Servlet in `web.xml` ===== Configuring the JSP Servlet in `web.xml`
Another option is to add an entry for the JSPServlet to the 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.
`WEB-INF/web.xml` file of your webapp and change or add init-params. You You may also add (but not remove) servlet-mappings.
may also add (but not remove) servlet-mappings. You can use the entry in You can use the entry in link:#webdefault-xml[{$jetty.home}/etc/webdefault.xml] as a starting point.
link:#webdefault-xml[$JETTY_HOME/etc/webdefault.xml] as a starting
point.
[source, xml, subs="{sub-order}"] [source, xml, subs="{sub-order}"]
---- ----
<servlet id="jsp"> <servlet id="jsp">
<servlet-name>jsp</servlet-name> <servlet-name>jsp</servlet-name>
<servlet-class>org.apache.jasper.servlet.JspServlet</servlet-class> <servlet-class>org.apache.jasper.servlet.JspServlet</servlet-class>
@ -492,60 +415,37 @@ point.
<servlet-name>myServlet</servlet-name> <servlet-name>myServlet</servlet-name>
<servlet-class>com.acme.servlet.MyServlet</servlet-class> <servlet-class>com.acme.servlet.MyServlet</servlet-class>
... ...
---- ----
[[using-jstl-taglibs-for-jetty7-jetty8]] [[using-jstl-taglibs-for-jetty7-jetty8]]
==== Using JSTL Taglibs ==== Using JSTL Taglibs
The JavaServer Pages Standlard Tag Library (JSTL) is part of the Jetty 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].
distribution and is automatically put on the classpath when you It is also automatically on the classpath for the Jetty Maven plugin, which uses the Apache JSP engine as of Jetty 9.2.
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 ===== Embedding
If you are using jetty in an embedded scenario, and you need to use 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.
JSTL, then you must ensure that the JSTL jars are included on the This is a restriction that arises from the JavaEE specification.
_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.
The jars that you will include will depend on the flavour of JSP that The jars that you will include will depend on the flavor of JSP that you are using.
you are using.
====== With Glassfish JSP ====== With Glassfish JSP
You will need to put the jstl jars that are present in You will need to put the JSTL jars that are present in `{$jetty.home/lib/jsp}` onto the _container's_ classpath.
$jetty.home/lib/jsp onto the _container's_ classpath. The Glassfish JSP The Glassfish JSP engine will find the JSTL tag definitions inside these jars during startup.
engine will find the jstl tag definitions inside these jars during
startup.
====== With Apache JSP ====== With Apache JSP
You will need to put the jars that are present in the You will need to put the jars that are present in the `{$jetty.home}/lib/apache-jstl` directory onto the _container's_ classpath.
$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.
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 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.
to find the tags, and pre-feed them into the Apache JSP engine. This is 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.
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 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.
link:#container-include-jar-pattern[org.eclipse.jetty.server.webapp.ContainerIncludeJarPattern] The link:#embedded-examples[Embedded Examples] section includes a link:#embedded-webapp-jsp[worked code example] of how to do this.
to include a Below is a snippet from the example:
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:
[source, java, subs="{sub-order}"] [source, java, subs="{sub-order}"]
---- ----
@ -555,29 +455,22 @@ a snippet from it:
[[using-jsf-taglibs]] [[using-jsf-taglibs]]
==== Using JSF Taglibs ==== Using JSF Taglibs
The following sections provide information about using JSF taglibs with The following sections provide information about using JSF TagLibs with Jetty Standalone and the Jetty Maven Plugin.
Jetty Standalone and the Jetty Maven Plugin.
[[using-jsf-taglibs-with-jetty-standalone]] [[using-jsf-taglibs-with-jetty-standalone]]
===== Using JSF Taglibs with Jetty Distribution ===== Using JSF Taglibs with Jetty Distribution
If you want to use JSF with your webapp, you need to copy the JSF 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.
implementation Jar (whichever Jar contains the `META-INF/*.tld` files 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`.
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]]
===== 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 You should make your JSF jars dependencies of the plugin and _not_ the webapp itself.
webapp itself. For example: For example:
[source, xml, subs="{sub-order}"] [source, xml, subs="{sub-order}"]
---- ----
<plugin> <plugin>
<groupId>org.eclipse.jetty</groupId> <groupId>org.eclipse.jetty</groupId>
<artifactId>jetty-maven-plugin</artifactId> <artifactId>jetty-maven-plugin</artifactId>
@ -600,6 +493,4 @@ webapp itself. For example:
</dependency> </dependency>
</dependencies> </dependencies>
</plugin> </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. 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: 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 * 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 * 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 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 * The client's Kerberos system is authenticated to a domain controller