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

Merge branch 'jetty-9.4.x'

This commit is contained in:
Jesse McConnell 2016-05-25 11:39:40 -05:00
parent 0272001f7a 6819455c16
commit fd059f2189
5 changed files with 37 additions and 33 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

21
jetty-documentation/src/main/asciidoc/quick-start/configuring/how-to-configure.adoc
View File

@ -28,7 +28,7 @@ This can be achieved by:
* Writing Java code to directly instantiate and assemble Jetty objects. This is referred to as xref:embedding-jetty[]. * Writing Java code to directly instantiate and assemble Jetty objects. This is referred to as xref:embedding-jetty[].
* Using Jetty XML configuration, which is an http://en.wikipedia.org/wiki/Inversion_of_Control[Inversion of Control (IoC)] framework, to instantiate and assemble Jetty objects as XML objects. * Using Jetty XML configuration, which is an http://en.wikipedia.org/wiki/Inversion_of_Control[Inversion of Control (IoC)] framework, to instantiate and assemble Jetty objects as XML objects.
The `etc/jetty.xml` file is the main Jetty XML configuration file, but there are many other `etc/jetty-`__feature__`.xml` files included in the Jetty distribution. The `etc/jetty.xml` file is the main Jetty XML configuration file, but there are many other `etc/jetty-__feature__.xml` files included in the Jetty distribution.
* Using a third party http://en.wikipedia.org/wiki/Inversion_of_Control[IoC] framework like http://en.wikipedia.org/wiki/Spring_Framework[Spring], to instantiate and assemble Jetty objects as Spring beans. * Using a third party http://en.wikipedia.org/wiki/Inversion_of_Control[IoC] framework like http://en.wikipedia.org/wiki/Spring_Framework[Spring], to instantiate and assemble Jetty objects as Spring beans.
Because the main Jetty configuration is done by IoC, the link:{JDURL}/[Jetty API documentation] is the ultimate configuration reference. Because the main Jetty configuration is done by IoC, the link:{JDURL}/[Jetty API documentation] is the ultimate configuration reference.
@ -37,7 +37,7 @@ Because the main Jetty configuration is done by IoC, the link:{JDURL}/[Jetty API
The Jetty distribution uses the following configuration files to instantiate, inject and start server via the start.jar mechanism. The Jetty distribution uses the following configuration files to instantiate, inject and start server via the start.jar mechanism.
`ini files`:: `ini` files::
The Jetty Start mechanism uses the command line, the `$JETTY_BASE/start.ini` and/or `$JETTY_BASE/start.d/*.ini` files to create an effective command line of arguments. The Jetty Start mechanism uses the command line, the `$JETTY_BASE/start.ini` and/or `$JETTY_BASE/start.d/*.ini` files to create an effective command line of arguments.
Arguments may be: Arguments may be:
@ -48,14 +48,14 @@ The Jetty distribution uses the following configuration files to instantiate, in
* Other start.jar options (see `java -jar start.jar --help`) * Other start.jar options (see `java -jar start.jar --help`)
* Some JVM options in combination with `--exec`, such as `-Xbootclasspath`. * Some JVM options in combination with `--exec`, such as `-Xbootclasspath`.
+ +
It is the `ini` files located in the Jetty base directory (if different from Jetty home) that are typically edited to change the configuration (e.g. change ports). As of Jetty 9 it is the `ini` files located in the Jetty base directory (if different from Jetty home) that are typically edited to change the configuration (e.g. change ports).
`mod files`:: `mod` files::
The `$JETTY_HOME/modules/*.mod` files contain the definition of modules that can be activated by ``--module=name`. The `$JETTY_HOME/modules/*.mod` files contain the definition of modules that can be activated by `--module=name`.
Each `mod` file defines: Each `mod` file defines:
* Module dependencies for ordering and activation * Module dependencies for ordering and activation
* The libraries needed by the module to be added to the `classpath` * The libraries needed by the module to be added to the classpath
* The XML files needed by the module to be added to the effective command line * The XML files needed by the module to be added to the effective command line
* Files needed by the activated module * Files needed by the activated module
* A template `ini` file to be used when activating the `--add-to-start=name` option * A template `ini` file to be used when activating the `--add-to-start=name` option
@ -65,11 +65,16 @@ The `*.mod` files are normally located in `$JETTY_HOME/modules/`, but extra or e
If module changes are required, it is best practice to copy the particular `*.mod` file from `$JETTY_HOME/modules/` to `$JETTY_BASE/modules/` before being modified. If module changes are required, it is best practice to copy the particular `*.mod` file from `$JETTY_HOME/modules/` to `$JETTY_BASE/modules/` before being modified.
XML files:: XML files::
XML files in link:#jetty-xml-syntax[Jetty IoC XML format] or Spring IoC format are listed either on the command line, in `ini` files or are added to the effective command line by a module definition. XML files in link:#jetty-xml-syntax[Jetty IoC XML format] or Spring IoC format are listed either on the command line, in `ini` files, or are added to the effective command line by a module definition.
The XML files instantiate and inject the actual Java objects that comprise the server, connectors and contexts. Because Jetty IoC XML files use properties, most common configuration tasks can be accomplished without editing these XML files and can instead be achieved by editing the property in the corresponding `ini` files. The XML files instantiate and inject the actual Java objects that comprise the server, connectors and contexts.
Because Jetty IoC XML files use properties, most common configuration tasks can be accomplished without editing these XML files and can instead be achieved by editing the property in the corresponding `ini` files.
XML files are normally located in `$JETTY_HOME/etc/`, but extra or edited XML files may be added to `$JETTY_BASE/etc/`. XML files are normally located in `$JETTY_HOME/etc/`, but extra or edited XML files may be added to `$JETTY_BASE/etc/`.
If XML configuration changes are required, it is best practice to copy the XML file from `$JETTY_HOME/etc/` to `$JETTY_BASE/etc/` before being modified. If XML configuration changes are required, it is best practice to copy the XML file from `$JETTY_HOME/etc/` to `$JETTY_BASE/etc/` before being modified.
Below is an illustration of how the various Jetty configuration files (`ini`, `mod` and XML) are related:
image:images/Jetty_Configuration_File_Relationships.png[image,width=693]
==== Other Configuration Files ==== Other Configuration Files
In addition to the configuration files described above, the configuration of the server can use the following file types: In addition to the configuration files described above, the configuration of the server can use the following file types:

BIN
jetty-documentation/src/main/asciidoc/quick-start/configuring/images/Jetty_Configuration_File_Relationships.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 20 KiB

12
jetty-documentation/src/main/asciidoc/quick-start/configuring/what-to-configure.adoc
View File

@ -25,11 +25,11 @@ However, for most purposes, configuration is a matter of identifying the correct
==== Configuring the Server ==== Configuring the Server
The Server instance is the central coordination object of a Jetty server; it provides services and life cycle management for all other Jetty server components. The Server instance is the central coordination object of a Jetty server; it provides services and life cycle management for all other Jetty server components.
In the standard Jetty distribution, the core server configuration is in `etc/jetty.xml` file, but you can mix in other server configuration which can include: In the standard Jetty distribution, the core server configuration is in `etc/jetty.xml` file, but you can mix in other server configurations which can include:
ThreadPool:: ThreadPool::
The Server instance provides a ThreadPool instance that is the default Executor service other Jetty server components use. The Server instance provides a ThreadPool instance that is the default Executor service other Jetty server components use.
The prime configuration of the thread pool is the maximum and minimum size and is set in `etc/jetty.xml.` The prime configuration of the thread pool is the maximum and minimum size and is set in `start.ini`.
Handlers:: Handlers::
A Jetty server can have only a single Handler instance to handle incoming HTTP requests. A Jetty server can have only a single Handler instance to handle incoming HTTP requests.
However a handler may be a container or wrapper of other handlers forming a tree of handlers that typically However a handler may be a container or wrapper of other handlers forming a tree of handlers that typically
@ -42,7 +42,7 @@ Server Attributes::
The server holds a generic attribute map of strings to objects so that other Jetty components can associate named objects with the server, and if the value objects implement the LifeCycle interface, they are started and stopped with the server. The server holds a generic attribute map of strings to objects so that other Jetty components can associate named objects with the server, and if the value objects implement the LifeCycle interface, they are started and stopped with the server.
Typically server attributes hold server-wide default values. Typically server attributes hold server-wide default values.
Server fields:: Server fields::
The server also has some specific configuration fields that you set in ` etc/jetty.xml` for controlling among other things, the sending of dates and versions in HTTP responses. The server also has some specific configuration fields that you set in `start.ini` for controlling among other things, the sending of dates and versions in HTTP responses.
Connectors:: Connectors::
The server holds a collection of connectors that receive connections for HTTP and the other protocols that Jetty supports. The server holds a collection of connectors that receive connections for HTTP and the other protocols that Jetty supports.
The next section, xref:intro-jetty-configuration-connectors[] describes configuration of the connectors themselves. The next section, xref:intro-jetty-configuration-connectors[] describes configuration of the connectors themselves.
@ -55,7 +55,7 @@ Services::
==== Configuring Connectors ==== Configuring Connectors
A Jetty Server Connector is a network end point that accepts connections for one or more protocols which produce requests and/or messages for the Jetty server. A Jetty Server Connector is a network end point that accepts connections for one or more protocols which produce requests and/or messages for the Jetty server.
In the standard Jetty server distribution, several provided configuration files add connectors to the server for various protocols and combinations of protocols: `jetty-http.xml, jetty-https.xml` and `jetty-spdy.xml`. In the standard Jetty server distribution, several provided configuration files add connectors to the server for various protocols and combinations of protocols: `http.ini`, `https.ini` and `jetty-spdy.xml`.
The configuration needed for connectors is typically: The configuration needed for connectors is typically:
Port:: Port::
@ -101,8 +101,8 @@ Configuration values that are common to all contexts are:
contextPath:: contextPath::
The contextPath is a URL prefix that identifies which context a HTTP request is destined for. The contextPath is a URL prefix that identifies which context a HTTP request is destined for.
For example, if a context has a context path `/foo`, it handles requests to ` /foo`, `/foo/index.html`, For example, if a context has a context path `/foo`, it handles requests to `/foo`, `/foo/index.html`,
`/foo/bar/`, and `/foo/bar/image.png` but it does not handle requests like `/`, ` /other/`, or `/favicon.ico`. `/foo/bar/`, and `/foo/bar/image.png` but it does not handle requests like `/`, `/other/`, or `/favicon.ico`.
A context with a context path of / is called the root context. A context with a context path of / is called the root context.
+ +
The context path can be set by default from the deployer (which uses the filename as the basis for the context path); or in code; or it can be set by a Jetty IoC XML that is either applied by the deployer or found in the `WEB-INF/jetty-web.xml` file of a standard web app context. The context path can be set by default from the deployer (which uses the filename as the basis for the context path); or in code; or it can be set by a Jetty IoC XML that is either applied by the deployer or found in the `WEB-INF/jetty-web.xml` file of a standard web app context.

36
jetty-documentation/src/main/asciidoc/quick-start/getting-started/jetty-running.adoc
View File

@ -20,7 +20,7 @@
To start Jetty on the default port of 8080, run the following command: To start Jetty on the default port of 8080, run the following command:
[source, screen] [source, screen]
.... ----
> cd $JETTY_HOME > cd $JETTY_HOME
> java -jar start.jar > java -jar start.jar
2015-06-04 10:50:44.806:INFO::main: Logging initialized @334ms 2015-06-04 10:50:44.806:INFO::main: Logging initialized @334ms
@ -29,7 +29,7 @@ To start Jetty on the default port of 8080, run the following command:
2015-06-04 10:50:45.012:INFO:oejdp.ScanningAppProvider:main: Deployment monitor [file:///opt/jetty-distribution-9.3.0.v20150601/webapps/] at interval 1 2015-06-04 10:50:45.012:INFO:oejdp.ScanningAppProvider:main: Deployment monitor [file:///opt/jetty-distribution-9.3.0.v20150601/webapps/] at interval 1
2015-06-04 10:50:45.030:INFO:oejs.ServerConnector:main: Started ServerConnector@19dfb72a{HTTP/1.1,[http/1.1]}{0.0.0.0:8080} 2015-06-04 10:50:45.030:INFO:oejs.ServerConnector:main: Started ServerConnector@19dfb72a{HTTP/1.1,[http/1.1]}{0.0.0.0:8080}
2015-06-04 10:50:45.030:INFO:oejs.Server:main: Started @558ms 2015-06-04 10:50:45.030:INFO:oejs.Server:main: Started @558ms
.... ----
You can point a browser at this server at link:http://localhost:8080[]. You can point a browser at this server at link:http://localhost:8080[].
However, as there are no webapps deployed in the $JETTY_HOME directory, you will see a 404 error page served by Jetty. However, as there are no webapps deployed in the $JETTY_HOME directory, you will see a 404 error page served by Jetty.
@ -42,7 +42,7 @@ Instead, see how to link:#creating-jetty-base[create a Jetty Base] below.
Within the standard jetty distribution there is the `demo-base` directory, which demonstrates the recommended way to run Jetty in a directory separately from $JETTY_HOME: Within the standard jetty distribution there is the `demo-base` directory, which demonstrates the recommended way to run Jetty in a directory separately from $JETTY_HOME:
[source, screen] [source, screen]
.... ----
> cd $JETTY_HOME/demo-base/ > cd $JETTY_HOME/demo-base/
> java -jar $JETTY_HOME/start.jar > java -jar $JETTY_HOME/start.jar
2015-06-04 10:55:24.161:INFO::main: Logging initialized @308ms 2015-06-04 10:55:24.161:INFO::main: Logging initialized @308ms
@ -66,7 +66,7 @@ Within the standard jetty distribution there is the `demo-base` directory, which
2015-06-04 10:55:26.259:INFO:oejus.SslContextFactory:main: x509={jetty.eclipse.org=jetty} wild={} alias=null for SslContextFactory@23941fb4(file:///opt/jetty-distribution-9.3.0.v20150601/demo-base/etc/keystore,file:///opt/jetty-distribution-9.3.0.v20150601/demo-base/etc/keystore) 2015-06-04 10:55:26.259:INFO:oejus.SslContextFactory:main: x509={jetty.eclipse.org=jetty} wild={} alias=null for SslContextFactory@23941fb4(file:///opt/jetty-distribution-9.3.0.v20150601/demo-base/etc/keystore,file:///opt/jetty-distribution-9.3.0.v20150601/demo-base/etc/keystore)
2015-06-04 10:55:26.269:INFO:oejs.ServerConnector:main: Started ServerConnector@5d908d47{SSL,[ssl, http/1.1]}{0.0.0.0:8443} 2015-06-04 10:55:26.269:INFO:oejs.ServerConnector:main: Started ServerConnector@5d908d47{SSL,[ssl, http/1.1]}{0.0.0.0:8443}
2015-06-04 10:55:26.270:INFO:oejs.Server:main: Started @2417ms 2015-06-04 10:55:26.270:INFO:oejs.Server:main: Started @2417ms
.... ----
You can see this demo server by pointing a browser at link:http://localhost:8080[], will now show a welcome page and several demo/test web applications. You can see this demo server by pointing a browser at link:http://localhost:8080[], will now show a welcome page and several demo/test web applications.
@ -78,13 +78,13 @@ ____
You can see the configuration of the demo-base by using the following commands: You can see the configuration of the demo-base by using the following commands:
[source, screen] [source, screen]
.... ----
> cd $JETTY_HOME/demo-base/ > cd $JETTY_HOME/demo-base/
> java -jar $JETTY_HOME/start.jar --list-modules > java -jar $JETTY_HOME/start.jar --list-modules
... ...
> java -jar %JETTY_HOME/start.jar --list-config > java -jar %JETTY_HOME/start.jar --list-config
... ...
.... ----
[[creating-jetty-base]] [[creating-jetty-base]]
==== Creating a new Jetty Base ==== Creating a new Jetty Base
@ -101,15 +101,15 @@ jetty.base::
The `jetty.home` and `jetty.base` properties may be explicitly set on the command line, or they can be inferred from the environment if used with commands like: The `jetty.home` and `jetty.base` properties may be explicitly set on the command line, or they can be inferred from the environment if used with commands like:
[source, screen] [source, screen]
.... ----
> cd $JETTY_BASE > cd $JETTY_BASE
> java -jar $JETTY_HOME/start.jar > java -jar $JETTY_HOME/start.jar
.... ----
The following commands: create a new base directory; enables a HTTP connector and the web application deployer; copies a demo webapp to be deployed: The following commands: create a new base directory; enables a HTTP connector and the web application deployer; copies a demo webapp to be deployed:
[source, screen] [source, screen]
.... ----
> JETTY_BASE=/tmp/mybase > JETTY_BASE=/tmp/mybase
> mkdir $JETTY_BASE > mkdir $JETTY_BASE
> cd $JETTY_BASE > cd $JETTY_BASE
@ -138,7 +138,7 @@ INFO: Base directory was modified
2015-06-04 11:10:16.628:INFO:oejsh.ContextHandler:main: Started o.e.j.w.WebAppContext@1a407d53{/,[file:///tmp/jetty-0.0.0.0-8080-ROOT.war-_-any-4510228025526425427.dir/webapp/, jar:file:///tmp/jetty-0.0.0.0-8080-ROOT.war-_-any-4510228025526425427.dir/webapp/WEB-INF/lib/example-async-rest-jar-9.3.0.v20150601.jar!/META-INF/resources],AVAILABLE}{/ROOT.war} 2015-06-04 11:10:16.628:INFO:oejsh.ContextHandler:main: Started o.e.j.w.WebAppContext@1a407d53{/,[file:///tmp/jetty-0.0.0.0-8080-ROOT.war-_-any-4510228025526425427.dir/webapp/, jar:file:///tmp/jetty-0.0.0.0-8080-ROOT.war-_-any-4510228025526425427.dir/webapp/WEB-INF/lib/example-async-rest-jar-9.3.0.v20150601.jar!/META-INF/resources],AVAILABLE}{/ROOT.war}
2015-06-04 11:10:16.645:INFO:oejs.ServerConnector:main: Started ServerConnector@3abbfa04{HTTP/1.1,[http/1.1]}{0.0.0.0:8080} 2015-06-04 11:10:16.645:INFO:oejs.ServerConnector:main: Started ServerConnector@3abbfa04{HTTP/1.1,[http/1.1]}{0.0.0.0:8080}
2015-06-04 11:10:16.646:INFO:oejs.Server:main: Started @634ms 2015-06-04 11:10:16.646:INFO:oejs.Server:main: Started @634ms
.... ----
[[quickstart-changing-jetty-port]] [[quickstart-changing-jetty-port]]
==== Changing the Jetty Port ==== Changing the Jetty Port
@ -146,11 +146,11 @@ INFO: Base directory was modified
You can configure Jetty to run on a different port by setting the `jetty.http.port` Property on the command line: You can configure Jetty to run on a different port by setting the `jetty.http.port` Property on the command line:
[source, screen] [source, screen]
.... ----
> cd $JETTY_BASE > cd $JETTY_BASE
> java -jar $JETTY_HOME/start.jar jetty.http.port=8081 > java -jar $JETTY_HOME/start.jar jetty.http.port=8081
... ...
.... ----
Alternatively, property values can be added to the effective command line built from either the `start.ini` file or `start.d/http.ini` files. Alternatively, property values can be added to the effective command line built from either the `start.ini` file or `start.d/http.ini` files.
By default, the jetty distribution defines the jetty.http.port property in the `start.d/http.ini` file, which may be edited to set another value. By default, the jetty distribution defines the jetty.http.port property in the `start.d/http.ini` file, which may be edited to set another value.
@ -174,14 +174,14 @@ ____
To add the HTTPS connector to a jetty configuration, the https module can be activated by the following command: To add the HTTPS connector to a jetty configuration, the https module can be activated by the following command:
[source, screen] [source, screen]
.... ----
> java -jar $JETTY_HOME/start.jar --add-to-startd=https,http2 > java -jar $JETTY_HOME/start.jar --add-to-startd=https,http2
[...] [...]
> java -jar $JETTY_HOME/start.jar > java -jar $JETTY_HOME/start.jar
[...] [...]
2015-06-04 13:52:01.933:INFO:oejs.ServerConnector:main: Started ServerConnector@6f1fba17{SSL,[ssl, alpn, h2, http/1.1]}{0.0.0.0:8443} 2015-06-04 13:52:01.933:INFO:oejs.ServerConnector:main: Started ServerConnector@6f1fba17{SSL,[ssl, alpn, h2, http/1.1]}{0.0.0.0:8443}
[...] [...]
.... ----
The --add-to-startd command sets up the effective command line in the ini files to run an ssl connection that supports the HTTPS and HTTP2 protocols as follows: The --add-to-startd command sets up the effective command line in the ini files to run an ssl connection that supports the HTTPS and HTTP2 protocols as follows:
@ -202,10 +202,10 @@ ____
You can configure the SSL connector to run on a different port by setting the `jetty.ssl.port` property on the command line: You can configure the SSL connector to run on a different port by setting the `jetty.ssl.port` property on the command line:
[source, screen] [source, screen]
.... ----
> cd $JETTY_BASE > cd $JETTY_BASE
> java -jar $JETTY_HOME/start.jar jetty.ssl.port=8444 > java -jar $JETTY_HOME/start.jar jetty.ssl.port=8444
.... ----
Alternatively, property values can be added to the effective command line built from the `start.ini` file and `start.d/*.ini` files. Alternatively, property values can be added to the effective command line built from the `start.ini` file and `start.d/*.ini` files.
If you used the --add-to-startd command to enable https, then you can edit this property in the `start.d/https.ini` file. If you used the --add-to-startd command to enable https, then you can edit this property in the `start.d/https.ini` file.
@ -217,6 +217,6 @@ The job of the `start.jar` is to interpret the command line, `start.ini` and `st
The `start.jar` mechanism has many options which are documented in the xref:startup[] administration section and you can see them in summary by using the command: The `start.jar` mechanism has many options which are documented in the xref:startup[] administration section and you can see them in summary by using the command:
[source, screen] [source, screen]
.... ----
> java -jar $JETTY_HOME/start.jar --help > java -jar $JETTY_HOME/start.jar --help
.... ----

1
jetty-documentation/src/main/docbkx-stylesheet/html/docbook.xsl
View File

@ -231,7 +231,6 @@ xmlns:date="http://exslt.org/dates-and-times"
<xsl:element name="pre"> <xsl:element name="pre">
<xsl:attribute name="class">screen</xsl:attribute> <xsl:attribute name="class">screen</xsl:attribute>
<xsl:value-of select="text()"/> <xsl:value-of select="text()"/>
<xsl:apply-templates/>
</xsl:element> </xsl:element>
</xsl:element> </xsl:element>
</xsl:when> </xsl:when>