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:
Joakim Erdfelt 2016-07-08 08:40:28 -07:00
parent 52f0858485 369a105524
commit 2cfc5b1665
26 changed files with 427 additions and 156 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
examples/embedded/src/main/java/org/eclipse/jetty/embedded/SplitFileServer.java
View File

@ -55,20 +55,22 @@ public class SplitFileServer
// our jetty maven testing utilities to get the proper resource
// directory, you needn't use these, you simply need to supply the paths
// you are looking to serve content from.
ResourceHandler rh0 = new ResourceHandler();
ContextHandler context0 = new ContextHandler();
context0.setContextPath("/");
ResourceHandler rh0 = new ResourceHandler();
File dir0 = MavenTestingUtils.getTestResourceDir("dir0");
rh0.setBaseResource(Resource.newResource(dir0));
context0.setBaseResource(Resource.newResource(dir0));
context0.setHandler(rh0);
// Rinse and repeat the previous item, only specifying a different
// resource base.
ResourceHandler rh1 = new ResourceHandler();
ContextHandler context1 = new ContextHandler();
context1.setContextPath("/");
ResourceHandler rh1 = new ResourceHandler();
File dir1 = MavenTestingUtils.getTestResourceDir("dir1");
rh1.setBaseResource(Resource.newResource(dir1));
context1.setBaseResource(Resource.newResource(dir1));
context1.setHandler(rh1);
// Create a ContextHandlerCollection and set the context handlers to it.

8
jetty-documentation/src/main/asciidoc/administration/extras/resource-handler.adoc
View File

@ -32,7 +32,7 @@ This handler will serve static content and handle If-Modified-Since headers and
____
[IMPORTANT]
There is no caching done with this handler so if you are looking for a more featureful way of serving static content look to the xred:default-servlet[].
There is no caching done with this handler, so if you are looking for a more fully featured way of serving static content look to the xref:default-servlet[].
____
____
@ -42,12 +42,12 @@ ____
==== Improving the Look and Feel
The resource handler has a default stylesheet which you can change by calling `setStyleSheet(String location)` with the location of a file on the system that it can locate through the resource loading system.
The default css is called jetty-dir.css and is located in the jetty-util package, pulled as a classpath resource from the jetty-util jar when requested through the ResourceHandler.
The resource handler has a default stylesheet which you can change by calling `setStyleSheet(String location)` with the location of a file on the system that it can locate through the resource loading system.
The default css is called `jetty-dir.css` and is located in the `jetty-util` package, pulled as a classpath resource from the `jetty-util` jar when requested through the `ResourceHandler`.
==== Embedded Example
The following is an example of a split fileserver, able to serve static content from multiple directory locations.
The following is an example of a split fileserver, able to serve static content from multiple directory locations.
Since this handler does not return 404's on content you are able to iteratively try multiple resource handlers to resolve content.
[source, java, subs="{sub-order}"]

1
jetty-documentation/src/main/asciidoc/administration/part.adoc
View File

@ -13,6 +13,7 @@
//
// You may elect to redistribute this code under either of these licenses.
// ========================================================================
[[jetty-admin-guide]]
= Jetty Administration Guide

18
jetty-documentation/src/main/asciidoc/configuring/contexts/configuring-virtual-hosts.adoc
View File

@ -17,15 +17,15 @@
[[configuring-virtual-hosts]]
=== Configuring Virtual Hosts
A virtual host is an alternative name, registered in DNS, for an IP address such that multiple domain names will resolve to the same IP of a shared server instance.
If the content to be served to the aliases names is link:#different-virtual-hosts-different-contexts[different], then a virtual host needs to be configured for each deployed link:{JDURL}/org/eclipse/jetty/server/handler/ContextHandler.html[context] to indicate which names a context will respond to.
A virtual host is an alternative name, registered in DNS, for an IP address such that multiple domain names will resolve to the same IP of a shared server instance.
If the content to be served to the aliases names is link:#different-virtual-hosts-different-contexts[different], then a virtual host needs to be configured for each deployed link:{JDURL}/org/eclipse/jetty/server/handler/ContextHandler.html[context] to indicate which names a context will respond to.
Virtual hosts are set on a link:{JDURL}/org/eclipse/jetty/server/handler/ContextHandler.html[context] by calling the link:{JDURL}/org/eclipse/jetty/server/handler/ContextHandler.html#setVirtualHosts-java.lang.String:A-[`setVirtualHosts`] or link:{JDURL}/org/eclipse/jetty/server/handler/ContextHandler.html#addVirtualHosts-java.lang.String:A-[`addVirtualHost`] method which can be done in several ways:
* Using a link:#deployable-descriptor-file[context XML] file in the webapps directory (see the example in link:{SRCDIR}/tests/test-webapps/test-jetty-webapp/src/main/config/demo-base/webapps/test.xml[test.xml] in the Jetty distribution).
* Using a `WEB-INF/jetty-web.xml` file (deprecated).
* Creating a link:#deployment-architecture[custom deployer] with a binding to configure virtual hosts for all contexts found in the same `webapps` directory.
* Calling the link:{JDURL}/org/eclipse/jetty/server/handler/ContextHandler.html#setVirtualHosts-java.lang.String:A-[API] directly on an link:#advanced-embedding[embedded] usage.
* Using a `WEB-INF/jetty-web.xml` file (now deprecated).
[[configuring-a-virtual-host]]
==== Virtual Host Names
@ -35,20 +35,20 @@ Jetty supports the following styles of virtual host name:
www.hostname.com::
A fully qualified host name. It is important to list all variants as a site may receive traffic from both www.hostname.com and just hostname.com
*.hostname.com::
A wildcard qualified host which will match only one level of arbitrary names.
A wildcard qualified host which will match only one level of arbitrary names.
*.foo.com will match www.foo.com and m.foo.com, but not www.other.foo.com
10.0.0.2::
An IP address may be given as a virtual host name to indicate that a context should handle requests received on that server port that do not have a host name specified (HTTP/0.9 or HTTP/1.0).
@ConnectorName::
A connector name, which is not strictly a virtual host, but instead will only match requests that are received on connectors that have a matching name set with link:{JDURL}/org/eclipse/jetty/server/AbstractConnector.html#setName(java.lang.String)[Connector.setName(String)].
www.√integral.com::
Non-ASCII and http://en.wikipedia.org/wiki/Internationalized_domain_name[IDN] domain names can be set as virtual hosts using http://en.wikipedia.org/wiki/Punycode[Puny Code] equivalents that may be obtained from a http://network-tools.com/idn-convert.asp[Punycode/IDN converters].
Non-ASCII and http://en.wikipedia.org/wiki/Internationalized_domain_name[IDN] domain names can be set as virtual hosts using http://en.wikipedia.org/wiki/Punycode[Puny Code] equivalents that may be obtained from a http://network-tools.com/idn-convert.asp[Punycode/IDN converters].
For example if the non-ASCII domain name `www.√integral.com` is given to a browser, then it will make a request that uses the domain name `www.xn--integral-7g7d.com`, which is the name that should be added as the virtual host name.
==== Example Virtual Host Configuration
Virtual hosts can be used with any context that is a subclass of link:{JDURL}/org/eclipse/jetty/server/handler/ContextHandler.html[ContextHandler].
Lets look at an example where we configure a web application -represented by the link:{JDURL}/org/eclipse/jetty/webapp/WebAppContext.html[WebAppContext] class - with virtual hosts.
Lets look at an example where we configure a web application - represented by the link:{JDURL}/org/eclipse/jetty/webapp/WebAppContext.html[WebAppContext] class - with virtual hosts.
You supply a list of IP addresses and names at which the web application is reachable, such as the following:
* `333.444.555.666`
@ -57,7 +57,7 @@ You supply a list of IP addresses and names at which the web application is reac
* `www.blah.net`
* `www.blah.org`
Suppose you have a webapp called `blah.war`, that you want all of the above names and addresses to be served at path "`/blah`".
Suppose you have a webapp called `blah.war`, that you want all of the above names and addresses to be served at path "`/blah`".
Here's how you would configure the virtual hosts with a link:#deployable-descriptor-file[context XML] file:
[source, xml, subs="{sub-order}"]
@ -96,7 +96,7 @@ For example, suppose your imaginary machine has these DNS names:
Suppose also you have 2 webapps, one called `blah.war` that you would like served from the `*.blah.*` names, and one called `other.war` that you want served only from the `*.other.*` names.
Using the method of preparing link:#deployable-descriptor-files[contextXML] files, one for each webapp yields the following:
Using the method of preparing link:#deployable-descriptor-file[contextXML] files, one for each webapp yields the following:
For `blah` webapp:
@ -153,7 +153,7 @@ These URLs now resolve to the other context (i.e. `other.war`):
[[different-virtual-hosts-different-context-same-path]]
==== Using Different Sets of Virtual Hosts to Select Different Contexts at the Same Context Path
In the previous section we setup 2 different contexts to be served from different virtual hosts at _different_ context paths.
In the previous section we setup 2 different contexts to be served from different virtual hosts at _different_ context paths.
However, there is no requirement that the context paths must be distinct: you may use the same context path for multiple contexts, and use virtual hosts to determine which one is served for a given request.
Consider an example where we have the same set of DNS names as before, and the same webapps `blah.war` and `other.war`. We still want `blah.war` to be served in response to hostnames of `*.blah.*`, and we still want `other.war` to be served in response to `*.other.*` names.

24
jetty-documentation/src/main/asciidoc/configuring/contexts/custom-error-pages.adoc
View File

@ -21,7 +21,7 @@ The following sections describe several ways to create custom error pages in Jet
==== Defining error pages in web.xml
You can use the standard webapp configuration file located in `webapp/WEB-INF/web.xml` to map errors to specific URLs with the `error-page` element.
You can use the standard webapp configuration file located in `webapp/WEB-INF/web.xml` to map errors to specific URLs with the `error-page` element.
This element creates a mapping between the error-code or exception-type to the location of a resource in the web application.
* `error-code` - an integer value
@ -50,7 +50,7 @@ Exception example:
----
The error page mappings created with the error-page element will redirect to a normal URL within the web application and will be handled as a normal request to that location and thus may be static content, a JSP or a filter and/or servlet.
The error page mappings created with the error-page element will redirect to a normal URL within the web application and will be handled as a normal request to that location and thus may be static content, a JSP or a filter and/or servlet.
When handling a request generated by an error redirection, the following request attributes are set and are available to generate dynamic content:
javax.servlet.error.exception::
@ -69,8 +69,8 @@ javax.servlet.error.status_code::
==== Configuring error pages context files
You can use context IoC XML files to configure the default error page mappings with more flexibility than is available with `web.xml`, specifically with the support of error code ranges.
Context files are normally located in `${jetty.home}/webapps/` (see `DeployerManager` for more details) and an example of more flexible error page mapping is below:
You can use context IoC XML files to configure the default error page mappings with more flexibility than is available with `web.xml`, specifically with the support of error code ranges.
Context files are normally located in `${jetty.base}/webapps/` (see `DeployerManager` for more details) and an example of more flexible error page mapping is below:
[source, xml, subs="{sub-order}"]
----
@ -80,7 +80,7 @@ Context files are normally located in `${jetty.home}/webapps/` (see `DeployerMan
<Configure class="org.eclipse.jetty.webapp.WebAppContext">
<Set name="contextPath">/test</Set>
<Set name="war">
<SystemProperty name="jetty.home" default="."/>/webapps/test
<SystemProperty name="jetty.base" default="."/>/webapps/test
</Set>
<!-- by Code -->
@ -117,7 +117,7 @@ Context files are normally located in `${jetty.home}/webapps/` (see `DeployerMan
==== Custom ErrorHandler class
If no error page mapping is defined, or if the error page resource itself has an error, then the error page will be generated by an instance of `ErrorHandler` configured either the Context or the Server.
If no error page mapping is defined, or if the error page resource itself has an error, then the error page will be generated by an instance of `ErrorHandler` configured either the Context or the Server.
An `ErrorHandler` may extend the `ErrorHandler` class and may totally replace the handle method to generate an error page, or it can implement some or all of the following methods to partially modify the error pages:
[source, java, subs="{sub-order}"]
@ -131,7 +131,7 @@ void writeErrorPageMessage(HttpServletRequest request, Writer writer, int code,
void writeErrorPageStacks(HttpServletRequest request, Writer writer) throws IOException
----
An `ErrorHandler` instance may be set on a Context by calling the `ContextHandler.setErrorHandler` method. This can be done by embedded code or via context IoC XML.
An `ErrorHandler` instance may be set on a Context by calling the `ContextHandler.setErrorHandler` method. This can be done by embedded code or via context IoC XML.
For example:
[source, xml, subs="{sub-order}"]
@ -145,8 +145,8 @@ For example:
</Configure>
----
An `ErrorHandler` instance may be set on the entire server by setting it as a dependent bean on the Server instance.
This can be done by calling `Server.addBean(Object)` via embedded code or in `jetty.xml` IoC XML like:
An `ErrorHandler` instance may be set on the entire server by setting it as a dependent bean on the Server instance.
This can be done by calling `Server.addBean(Object)` via embedded code or in `jetty.xml` IoC XML:
[source, xml, subs="{sub-order}"]
----
@ -163,9 +163,9 @@ This can be done by calling `Server.addBean(Object)` via embedded code or in `je
==== Server level 404 error
It is possible to get a 'page not found' when a request is made to the server for a resource that is outside of any registered contexts.
As an example, you have a domain name pointing to your public server IP, yet no context is registered with Jetty to serve pages for that domain.
It is possible to get a 'page not found' when a request is made to the server for a resource that is outside of any registered contexts.
As an example, you have a domain name pointing to your public server IP, yet no context is registered with Jetty to serve pages for that domain.
As a consequence, the server, by default, gives a listing of all contexts running on the server.
One of the quickest ways to avoid this behavior is to create a catch all context.
One of the quickest ways to avoid this behavior is to create a catch all context.
Create a "root" web app mapped to the "/" URI, and use the `index.html` redirect to whatever place with a header directive.

28
jetty-documentation/src/main/asciidoc/configuring/contexts/serving-webapp-from-particular-port.adoc
View File

@ -17,23 +17,35 @@
[[serving-webapp-from-particular-port]]
=== Serving a WebApp from a Particular Port/Connector
Sometimes it is required to serve different web applications from different ports/connectors.
The simplest way to do this is to create multiple `Server` instances.
Sometimes it is required to serve different web applications from different ports/connectors.
The simplest way to do this is to create multiple `Server` instances.
However, if contexts need to share resources (eg data sources, authentication), or if the mapping of ports to web applications is not cleanly divided, then the named connector mechanism can be used.
[[creating-server-instances]]
==== Creating Multiple Server Instances
Creating multiple server instances is a straight forward process that includes embedding Jetty code by creating multiples instances of the Server class and configuring them as needed.
This is also easy to achieve if you are configuring your servers in XML.
The `id` field in the Configure element of `jetty.xml` files is used to identify the instance that the configuration applies to, so to run two instances of the Server, you can copy the `jetty.xml`, jetty-http.xml and other jetty configuration files used and change the "Server" id to a new name.
Creating multiple server instances is a straight forward process that includes embedding Jetty code by creating multiples instances of the Server class and configuring them as needed.
This is also easy to achieve if you are configuring Jetty servers via XML.
The `id` field in the Configure element of `jetty.xml` files is used to identify the instance that the configuration applies to, so to run two instances of the Server, you can copy the `jetty.xml`, jetty-http.xml and other jetty configuration files used and change the "Server" id to a new name.
This can be done in the same style and layout as the existing `jetty.xml` files or the multiple XML files may be combined to a single file.
When creating new configurations for alternative server:
* Change all `id="Server"` to the new server name: `<Configure id="OtherServer" class="org.eclipse.jetty.server.Server">`
* For all connectors for the new server change the `refid` in the server argument: `<Arg name="server"><Ref refid="OtherServer" /></Arg>`
* Make sure that any references to properties like `jetty.http.port` are either renamed or replaced with absolute values
* Change all `id="Server"` to the new server name:
[source, xml, subs="{sub-order}"]
----
<Configure id="OtherServer" class="org.eclipse.jetty.server.Server">
----
* For all connectors for the new server change the `refid` in the server argument:
[source, xml, subs="{sub-order}"]
----
<Arg name="server"><Ref refid="OtherServer" /></Arg>
----
* Make sure that any references to properties like `jetty.http.port` are either renamed or replaced with absolute values.
* Make sure that any deployers `AppProviders` refer to a different "webapps" directory so that a different set of applications are deployed.
[[jetty-otherserver.xml]]

8
jetty-documentation/src/main/asciidoc/configuring/contexts/setting-form-size.adoc
View File

@ -17,9 +17,9 @@
[[setting-form-size]]
=== Setting Max Form Size
Jetty limits the amount of data that can post back from a browser or other client to the server.
Jetty limits the amount of data that can post back from a browser or other client to the server.
This helps protect the server against denial of service attacks by malicious clients sending huge amounts of data.
The default maximum size Jetty permits is 200000 bytes.
The default maximum size Jetty permits is 200000 bytes.
You can change this default for a particular webapp, for all webapps on a particular Server instance, or all webapps within the same JVM.
==== For a Single Webapp
@ -56,5 +56,5 @@ Set an attribute on the Server instance for which you want to modify the maximum
==== For All Apps in the JVM
Use the system property `org.eclipse.jetty.server.Request.maxFormContentSize`.
This can be set on the command line or in the `start.ini` file.
Use the system property `org.eclipse.jetty.server.Request.maxFormContentSize`.
This can be set on the command line or in the `start.ini` or `start.d\server.ini` file.

20
jetty-documentation/src/main/asciidoc/configuring/contexts/temporary-directories.adoc
View File

@ -77,8 +77,8 @@ context.setAttribute("org.eclipse.jetty.webapp.basetempdir", "/tmp/foo");
There are several ways to use a particular directory as the temporary directory:
*Call WebAppContext.setTempDirectory(String dir)*
Like before this can be accomplished with an xml file or directly in code. Here's an example of setting the temp directory in xml:
====== Call WebAppContext.setTempDirectory(String dir)
As before this can be accomplished with an xml file or directly in code. Here's an example of setting the temp directory in xml:
[source, xml, subs="{sub-order}"]
----
@ -101,7 +101,7 @@ context.setWar("foo.war");
context.setTempDirectory(new File("/some/dir/foo"));
----
*Set the `javax.servlet.context.tempdir` context attribute*
====== Set the javax.servlet.context.tempdir context attribute
You should set this context attribute with the name of directory you want to use as the temp directory. Again, you can do this in xml:
[source, xml, subs="{sub-order}"]
@ -129,27 +129,27 @@ context.setWar("foo.war");
context.setAttribute("javax.servlet.context.tempdir", "/some/dir/foo");
----
Once a temporary directory has been created by either of these methods, a File instance for it is set as the value of the `javax.servlet.context.tempdir` attribute of the web application.
Once a temporary directory has been created by either of these methods, a file instance for it is set as the value of the `javax.servlet.context.tempdir` attribute of the web application.
____
[NOTE]
Be wary of setting an explicit temp directory if you are likely to change the jars in WEB-INF/lib between redeployments.
There is a JVM bug concerning caching of jar contents: http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=4774421
There is a JVM bug concerning link:http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=4774421[caching of jar contents.]
____
==== The "work" directory
Mostly for backward compatibility, from jetty-9.1.1 onwards, it is be possible to create a directory named "work" in the `$\{jetty.base}` directory.
If such a directory is found, it is assumed you want to use it as the parent directory for all of the temporary directories of the webapps in that `$\{jetty.base}`.
Moreover, as has historically been the case, these temp directories inside the work directory are not cleaned up when jetty exists (or more correctly speaking, the `temp` directory corresponding to a context is not cleaned up when that context stops).
Mostly for backward compatibility, from Jetty 9.1.1 onwards, it is possible to create a directory named "work" in the `$\{jetty.base}` directory.
If such a directory is found, it is assumed you want to use it as the parent directory for all of the temporary directories of the webapps in `$\{jetty.base}`.
Moreover, as has historically been the case, these temp directories inside the work directory are not cleaned up when Jetty exits (or more correctly speaking, the `temp` directory corresponding to a context is not cleaned up when that context stops).
When a work directory is used, the algorithm for generating the name of the context-specific temp directories omits the random digit string.
This ensures the name of the directory remains consistent across context restarts.
==== Persisting the temp directory
Sometimes you may find it useful to keep the contents of the temporary directory between restarts of the web application.
By default, Jetty will _not_ persist the temp directory.
Sometimes it is useful to keep the contents of the temporary directory between restarts of the web application.
By default, Jetty will *not* persist the temp directory.
To configure Jetty to keep it, use link:{JDURL}/org/eclipse/jetty/webapp/WebAppContext.html[WebAppContext.setPersistTempDirectory(true)].
____

6
jetty-documentation/src/main/asciidoc/configuring/deploying/automatic-webapp-deployment.adoc
View File

@ -17,7 +17,7 @@
[[automatic-webapp-deployment]]
=== Automatic Web Application Deployment
The most basic technique for deploying Web Applications is to put a WAR file or Exploded WAR directory into the `${jetty.home}/webapps/` directory and let Jetty's deployment scanner find it and deploy it under a Context path of the same name.
The most basic technique for deploying Web Applications is to put a WAR file or Exploded WAR directory into the `${jetty.base}/webapps/` directory and let Jetty's deployment scanner find it and deploy it under a Context path of the same name.
Only Web Applications that follow the Web Application Layout will be detected by Jetty and deployed this way.
@ -34,7 +34,7 @@ The Context Path assigned to this automatic deployment is based the filename (or
|`/webapps/belaying-pins/WEB-INF/web.xml` |http://host/belaying-pins/
|`/webapps/root.war` _(special name)_ |http://host/
|`/webapps/root.war` _(reserved name)_ |http://host/
|`/webapps/root/WEB-INF/web.xml` _(special name)_ |http://host/
|`/webapps/root/WEB-INF/web.xml` _(reserved name)_ |http://host/
|=======================================================================

22
jetty-documentation/src/main/asciidoc/configuring/deploying/configuring-specific-webapp-deployment.adoc
View File

@ -17,7 +17,7 @@
[[configuring-specific-webapp-deployment]]
=== Configuring a Specific Web Application Deployment
Using the Automatic Web Application Deployment model is quick and easy, but sometimes you might need to tune certain deployment properties (for example, you want to deploy with a context path that is not based on the file name, or you want to define a special database connection pool just for this web application).
Using the Automatic Web Application Deployment model is quick and easy, but sometimes you might need to tune certain deployment properties (for example, you want to deploy with a context path that is not based on the file name, or you want to define a special database connection pool just for this web application).
You can use a xref:deployable-descriptor-file[] to accomplish such tuning.
[[deployable-descriptor-file]]
@ -28,10 +28,10 @@ Jetty supports deploying Web Applications via XML files which will build an inst
[[using-basic-descriptor-files]]
==== Using Basic Descriptor Files
In a default Jetty installation, Jetty scans its `$JETTY_HOME/webapps` directory for context deployment descriptor files.
In a default Jetty installation, Jetty scans its `$JETTY_HOME/webapps` directory for context deployment descriptor files.
To deploy a web application using such a file, simply place the file in that directory.
The deployment descriptor file itself is an xml file that configures a link:{JDURL}/org/eclipse/jetty/webapp/WebAppContext.html[`WebAppContext`] class.
The deployment descriptor file itself is an xml file that configures a link:{JDURL}/org/eclipse/jetty/webapp/WebAppContext.html[`WebAppContext`] class.
For a basic installation only two properties need configured:
war::
@ -69,7 +69,7 @@ ____
</Configure>
----
If the home path for an application needs altered, only the system property needs changed.
If the home path for an application needs altered, only the system property needs changed.
This is useful if the version of an app is frequently changed.
[[configuring-advanced-descriptor-files]]
@ -78,7 +78,7 @@ This is useful if the version of an app is frequently changed.
Official documentation for the for the link:{JDURL}/org/eclipse/jetty/webapp/WebAppContext.html[`WebAppContext`] class lists all the properties that can be set.
Here are some examples that configure advanced options in the descriptor file.
This first example tells Jetty not to expand the WAR file when deploying it.
This first example tells Jetty not to expand the WAR file when deploying it.
This can help make it clear that users should not make changes to the temporary unpacked WAR because such changes do not persist, and therefore do not apply the next time the web application deploys.
[source, xml, subs="{sub-order}"]
@ -93,8 +93,8 @@ This can help make it clear that users should not make changes to the temporary
</Configure>
----
The next example retrieves the JavaEE Servlet context and sets an initialization parameter on it.
The `setAttribute` method can also be used to set a Servlet context attribute.
The next example retrieves the JavaEE Servlet context and sets an initialization parameter on it.
The `setAttribute` method can also be used to set a Servlet context attribute.
However, since the `web.xml` for the web application is processed after the deployment descriptor, the `web.xml` values overwrite identically named attributes from the deployment descriptor.
[source, xml, subs="{sub-order}"]
@ -114,8 +114,8 @@ However, since the `web.xml` for the web application is processed after the depl
</Configure>
----
The following example sets a special `web.xml` override descriptor.
This descriptor is processed after the web application's `web.xml`, so it may override identically named attributes.
The following example sets a special `web.xml` override descriptor.
This descriptor is processed after the web application's `web.xml`, so it may override identically named attributes.
This feature is useful when adding parameters or additional Servlet mappings without breaking open a packed WAR file.
[source, xml, subs="{sub-order}"]
@ -130,7 +130,7 @@ This feature is useful when adding parameters or additional Servlet mappings wit
</Configure>
----
The next example configures not only the web application context, but also a database connection pool (see xref:jndi-datasource-examples[] that the application can then use.
The next example configures not only the web application context, but also a database connection pool (see xref:jndi-datasource-examples[]) that the application can then use.
If the `web.xml` does not include a reference to this data source, an override descriptor mechanism (as shown in the previous example) can be used to include it.
[source, xml, subs="{sub-order}"]
@ -158,5 +158,5 @@ If the `web.xml` does not include a reference to this data source, an override d
----
There are many other settings that can be changed in a link:{JDURL}/org/eclipse/jetty/webapp/WebAppContext.html[`WebAppContext`].
The link:{JDURL}/org/eclipse/jetty/webapp/WebAppContext.html[javadoc] for `WebAppContext` is a good source of information.
The link:{JDURL}/org/eclipse/jetty/webapp/WebAppContext.html[javadoc] for `WebAppContext` is a good source of information.
Also see the documentation on link:#troubleshooting-zip-exceptions[avoiding zip file exceptions] for a description of `WebAppContext` settings that determine such things as whether or not the war is automatically unpacked during deployment, or whether certain sections of a webapp are copied to a temporary location.

36
jetty-documentation/src/main/asciidoc/configuring/deploying/deployment-architecture.adoc
View File

@ -19,9 +19,9 @@
Jetty is built around an extensible Deployment Manager architecture complete with formal LifeCycle for Web Applications going through it.
For Jetty to serve content (static or dynamic), a link:{JDURL}/org/eclipse/jetty/server/handler/ContextHandler.html[ContextHandler] needs to be configured and added to Jetty in the appropriate location.
A pluggable `DeploymentManager` exists in Jetty 7 and later to make this process easier.
The Jetty distribution contains example `DeploymentManager` configurations to deploy WAR files found in a directory to Jetty, and to deploy Jetty `context.xml` files into Jetty as well.
For Jetty to serve content (static or dynamic), a link:{JDURL}/org/eclipse/jetty/server/handler/ContextHandler.html[ContextHandler] needs to be configured and added to Jetty in the appropriate location.
A pluggable `DeploymentManager` exists to make this process easier.
The Jetty distribution contains example `DeploymentManager` configurations to deploy WAR files found in a directory to Jetty, and to deploy Jetty context xml files into Jetty as well.
The `DeploymentManager` is the heart of the typical webapp deployment mechanism; it operates as a combination of an Application LifeCycle Graph, Application Providers that find and provide Applications into the Application LifeCycle Graph, and a set of bindings in the graph that control the deployment process.
@ -40,7 +40,7 @@ The core feature of the `DeploymentManager` is the link:{JDURL}/org/eclipse/jett
image:images/Jetty_DeployManager_AppLifeCycle-1.png[image,width=340]
The nodes and edges of this graph are pre-defined in Jetty along the most common actions and states found.
The nodes and edges of this graph are pre-defined in Jetty along the most common actions and states found.
These nodes and edges are not hardcoded; they can be adjusted and added to depending on need (for example, any complex requirements for added workflow, approvals, staging, distribution, coordinated deploys for a cluster or cloud, etc.).
New applications enter this graph at the Undeployed node, and the link:{JDURL}/org/eclipse/jetty/deploy/DeploymentManager.html#requestAppGoal(org.eclipse.jetty.deploy.App[`java.lang.String DeploymentManager.requestAppGoal(App,String)`] method pushes them through the graph.
@ -48,7 +48,7 @@ New applications enter this graph at the Undeployed node, and the link:{JDURL}/o
[[udm-lifecycle-bindings]]
==== LifeCycle Bindings
A set of default link:{JDURL}/org/eclipse/jetty/deploy/AppLifeCycle.Binding.html[`AppLifeCycle.Bindings`] defines standard behavior, and handles deploying, starting, stopping, and undeploying applications.
A set of default link:{JDURL}/org/eclipse/jetty/deploy/AppLifeCycle.Binding.html[`AppLifeCycle.Bindings`] defines standard behavior, and handles deploying, starting, stopping, and undeploying applications.
If desired, custom `AppLifeCycle.Bindings` can be written and assigned anywhere on the Application LifeCycle graph.
Examples of new `AppLifeCycle.Binding` implementations that can be developed include:
@ -73,7 +73,7 @@ A fifth, non-standard binding, called link:{JDURL}/org/eclipse/jetty/deploy/bind
[[default-web-app-provider]]
==== Understanding the Default WebAppProvider
The link:{JDURL}/org/eclipse/jetty/deploy/providers/WebAppProvider.html[WebAppProvider] is used for the deployment of Web Applications packaged as WAR files, expanded as a directory, or declared in a xref:deployable-descriptor-file[].
The link:{JDURL}/org/eclipse/jetty/deploy/providers/WebAppProvider.html[WebAppProvider] is used for the deployment of Web Applications packaged as WAR files, expanded as a directory, or declared in a xref:deployable-descriptor-file[].
It supports hot (re)deployment.
The basic operation of the `WebAppProvider` is to periodically scan a directory for deployables.
@ -110,14 +110,14 @@ In the standard Jetty Distribution, this is configured in the `${jetty.home}/etc
The above configuration will create a `DeploymentManager` tracked as a Server LifeCycle Bean, with the following configuration.
contexts::
A passed in reference to the HandlerContainer into which the discovered webapps are deployed.
A passed in reference to the HandlerContainer into which the discovered webapps are deployed.
This is normally a reference that points to the `id="Contexts"` found in the `${jetty.home}/etc/jetty.xml` file, which itself is an instance of `ContextHandlerCollection`.
monitoredDirName::
The file path or URL to the directory to scan for web applications.
+
Scanning follows these rules:
+
1. A base directory must exist.
2. Hidden Files (starting with `"."`) are ignored.
3. Directories with names ending in `".d"` are ignored.
@ -131,19 +131,19 @@ monitoredDirName::
10. In the special case where both a Directory and XML file of the same name exists, the XML file is assumed to configure and reference the Directory.
11. All other directories are subject to automatic deployment.
12. If automatic deployment is used, and the special filename `root.war/ROOT.war` or directory name `root/ROOT` will result in a deployment to the `"/"` context path.
defaultsDescriptor::
Specifies the default Servlet web descriptor to use for all Web Applications.
The intent of this descriptor is to include common configuration for the Web Application before the Web Application's own `/WEB-INF/web.xml` is applied.
Specifies the default Servlet web descriptor to use for all Web Applications.
The intent of this descriptor is to include common configuration for the Web Application before the Web Application's own `/WEB-INF/web.xml` is applied.
The `${jetty.home}/etc/webdefault.xml` that comes with the Jetty distribution controls the configuration of the JSP and Default servlets, along with MIME-types and other basic metadata.
scanInterval::
The period in seconds between sweeps of the `monitoredDirName` for changes: new contexts to deploy, changed contexts to redeploy, or removed contexts to undeploy.
extractWars::
If parameter is true, any packed WAR or zip files are first extracted to a temporary directory before being deployed.
If parameter is true, any packed WAR or zip files are first extracted to a temporary directory before being deployed.
This is advisable if there are uncompiled JSPs in the web apps.
parentLoaderPriority::
Parameter is a boolean that selects whether the standard Java link:#jetty-classloading[parent first delegation] is used or the link:#jetty-classloading[servlet specification webapp classloading priority].
Parameter is a boolean that selects whether the standard Java link:#jetty-classloading[parent first delegation] is used or the link:#jetty-classloading[servlet specification webapp classloading priority].
The latter is the default.

56
jetty-documentation/src/main/asciidoc/configuring/deploying/deployment-processing-webapps.adoc
View File

@ -17,8 +17,8 @@
[[configuring-webapps]]
=== Deployment Processing of WebAppContexts
Web applications require a certain amount of processing before they can go into service: they may need to be unpacked, a special classloader created for their jar files, `web.xml` and `web-fragment.xml` descriptors processed, and classes scanned for annotations amongst other things.
As web applications have become more complex, Jetty has added ways to assist with customization by either broadening or lessening the amount of processing that is done at deployment time.
Web applications require a certain amount of processing before they can go into service: they may need to be unpacked, a special classloader created for their jar files, `web.xml` and `web-fragment.xml` descriptors processed, and classes scanned for annotations amongst other things.
As web applications have become more complex, Jetty has added ways to assist with customization by either broadening or lessening the amount of processing that is done at deployment time.
This section will examine this processing and it can be tailored to fit individual needs.
If instead you're looking for information on how to configure a specific `WebAppContext` - such as its context path, whether it should be unpacked or not - then you can find that in the section entitled link:#configuring-specific-webapp-deployment[Configuring a Specific WebApp Deployment].
@ -26,8 +26,8 @@ If instead you're looking for information on how to configure a specific `WebApp
[[webapp-configurations]]
==== Configuration Classes
As a webapp is being deployed, a series of link:{JDURL}/org/eclipse/jetty/webapp/Configuration.html[org.eclipse.jetty.webapp.Configuration] classes are applied to it, each one performing a specific function.
The ordering of these Configurations is significant as subsequent Configurations tend to build on information extracted or setup in foregoing Configurations.
As a webapp is being deployed, a series of link:{JDURL}/org/eclipse/jetty/webapp/Configuration.html[org.eclipse.jetty.webapp.Configuration] classes are applied to it, each one performing a specific function.
The ordering of these Configurations is significant as subsequent Configurations tend to build on information extracted or setup in foregoing Configurations.
These are the default list, in order, of Configurations that are applied to each link:{JDURL}/org/eclipse/jetty/webapp/WebAppContext.html[org.eclipse.jetty.webapp.WebAppContex]t:
.Default Configuration classes
@ -55,31 +55,31 @@ META-INF/web-fragment.xml
A Configuration class is called 5 times in different phases of the link:http://download.eclipse.org/jetty/stable-9/apidocs/org/eclipse/jetty/webapp/WebAppContext.html[`WebAppContext's`] lifecycle:
preConfigure::
As the `WebAppContext` is starting up this phase is executed.
As the `WebAppContext` is starting up this phase is executed.
The `Configuration` should discover any of the resources it will need during the subsequent phases.
configure::
This phase is where the work of the class is done, usually using the resources discovered during the `preConfigure` phase.
postConfigure::
This phase allows the `Configuration` to clear down any resources that may have been created during the previous 2 phases that are not needed for the lifetime of the `WebAppContext`.
deconfigure::
This phase occurs whenever a `WebAppContext` is being stopped and allows the Configuration to undo any resources/metadata that it created.
This phase occurs whenever a `WebAppContext` is being stopped and allows the Configuration to undo any resources/metadata that it created.
A `WebAppContext` should be able to be cleanly start/stopped multiple times without resources being held.
destroy::
This phase is called when a `WebAppContext` is actually removed from service.
This phase is called when a `WebAppContext` is actually removed from service.
For example, the war file associated with it is deleted from the $JETTY_HOME/webapps directory.
Each phase is called on each `Configuration` class in the order in which the `Configuration` class is listed.
Using the default `Configuration` classes as an example, `preConfigure()` will be called on `WebInfConfiguration`, `WebXmlConfiguration`, `MetaInfConfiguration`, `FragmentConfiguration` and then `JettyWebXmlConfiguration`.
The cycle begins again for the `configure()` phase and again for the `postConfigure()` phases.
Each phase is called on each `Configuration` class in the order in which the `Configuration` class is listed.
Using the default `Configuration` classes as an example, `preConfigure()` will be called on `WebInfConfiguration`, `WebXmlConfiguration`, `MetaInfConfiguration`, `FragmentConfiguration` and then `JettyWebXmlConfiguration`.
The cycle begins again for the `configure()` phase and again for the `postConfigure()` phases.
The cycle is repeated _in reverse order_ for the `deconfigure()` and eventually the `destroy()` phases.
===== Extending Container Support by Creating Extra Configurations
As shown, there is a default set of Configurations that support basic deployment of a webapp.
As shown, there is a default set of Configurations that support basic deployment of a webapp.
JavaEE features such as JNDI and advanced servlet spec features such as annotations have not been mentioned.
Jetty's philosophy is to allow the user to tailor the container exactly to their needs.
If these features are not needed, then Jetty does not pay the price for them - an important consideration because features such as annotations require extensive and time-consuming scanning of `WEB-INF/lib` jars.
As modern webapps may have scores of these jars, it can be a source of significant deployment delay.
Jetty's philosophy is to allow the user to tailor the container exactly to their needs.
If these features are not needed, then Jetty does not pay the price for them - an important consideration because features such as annotations require extensive and time-consuming scanning of `WEB-INF/lib` jars.
As modern webapps may have scores of these jars, it can be a source of significant deployment delay.
We will see in the section link:#webapp-context-attributes[Other Configuration] another helpful webapp facility that Jetty provides for cutting down the time spent analyzing jars.
Jetty makes use of the flexibility of Configurations to make JNDI and annotation support pluggable.
@ -89,7 +89,7 @@ Firstly, lets look at how Configurations help enable JNDI.
[[jndi-configuration-classes]]
====== Example: JNDI Configurations
JNDI lookups within web applications require the container to hookup resources defined in the container's environment to that of the web application.
JNDI lookups within web applications require the container to hookup resources defined in the container's environment to that of the web application.
To achieve that, we use 2 extra Configurations:
.JNDI Configuration classes
@ -102,7 +102,7 @@ To achieve that, we use 2 extra Configurations:
|Processes JNDI related aspects of `WEB-INF/web.xml` and hooks up naming entries
|=======================================================================
These configurations must be added in _exactly_ the order shown above and should be inserted _immediately before_ the link:{JDURL}/org/eclipse/jetty/webapp/JettyWebXmlConfiguration.html[org.eclipse.jetty.webapp.JettyWebXmlConfiguration] class in the list of configurations.
These configurations must be added in _exactly_ the order shown above and should be inserted _immediately before_ the link:{JDURL}/org/eclipse/jetty/webapp/JettyWebXmlConfiguration.html[org.eclipse.jetty.webapp.JettyWebXmlConfiguration] class in the list of configurations.
To fully support JNDI additional configuration is required, full details of which can be found link:#jndi[here].
====== Example: Annotation Configurations
@ -117,7 +117,7 @@ We need just one extra Configuration class to help provide servlet annotation sc
@WebListener etc
|=======================================================================
The above configuration class must be _inserted immediately before_ the link:{JDURL}/org/eclipse/jetty/webapp/JettyWebXmlConfiguration.html[org.eclipse.jetty.webapp.JettyWebXmlConfiguration] class in the list of configurations.
The above configuration class must be _inserted immediately before_ the link:{JDURL}/org/eclipse/jetty/webapp/JettyWebXmlConfiguration.html[org.eclipse.jetty.webapp.JettyWebXmlConfiguration] class in the list of configurations.
To fully support annotations additional configuration is require, details of which can be found link:#webapp-context-attributes[below.]
===== How to Set the List of Configurations
@ -126,7 +126,7 @@ You have a number of options for how to make Jetty use a different list of Confi
====== Setting the list directly on the WebAppContext
If you have only one webapp that you wish to affect, this may be the easiest option.
If you have only one webapp that you wish to affect, this may be the easiest option.
You will, however, either need to have a context xml file that represents your web app, or you need to call the equivalent in code.
Let's see an example of how we would add in the Configurations for both JNDI _and_ annotations:
@ -137,7 +137,7 @@ Let's see an example of how we would add in the Configurations for both JNDI _an
<Configure class="org.eclipse.jetty.webapp.WebAppContext">
<Set name="war"><SystemProperty name="jetty.home" default="."/>/webapps/my-cool-webapp</Set>
<Set name="war"><SystemProperty name="jetty.base" default="."/>/webapps/my-cool-webapp</Set>
<Set name="configurationClasses">
<Array type="java.lang.String">
@ -159,7 +159,7 @@ Of course, you can also use this method to reduce the Configurations applied to
====== Setting the list for all webapps via the Deployer
If you use the link:#deployment-architecture[deployer], you can set up the list of Configuration classes on the link:#default-web-app-provider[WebAppProvider].
If you use the link:#deployment-architecture[deployer], you can set up the list of Configuration classes on the link:#default-web-app-provider[WebAppProvider].
They will then be applied to each `WebAppContext` deployed by the deployer:
[source, xml, subs="{sub-order}"]
@ -178,7 +178,7 @@ They will then be applied to each `WebAppContext` deployed by the deployer:
<Call id="webappprovider" name="addAppProvider">
<Arg>
<New class="org.eclipse.jetty.deploy.providers.WebAppProvider">
<Set name="monitoredDirName"><Property name="jetty.home" default="." />/webapps</Set>
<Set name="monitoredDirName"><Property name="jetty.base" default="." />/webapps</Set>
<Set name="configurationClasses">
<Array type="java.lang.String">
<Item>org.eclipse.jetty.webapp.WebInfConfiguration</Item>
@ -202,8 +202,8 @@ They will then be applied to each `WebAppContext` deployed by the deployer:
====== Adding or inserting to an existing list
Instead of having to enumerate the list in its entirety, you can simply nominate classes that you want to add, and indicate whereabouts in the list you want them inserted.
Let's look at an example of using this method to add in Configuration support for JNDI - as usual you can either do this in an xml file, or via equivalent code.
Instead of having to enumerate the list in its entirety, you can simply nominate classes that you want to add, and indicate whereabouts in the list you want them inserted.
Let's look at an example of using this method to add in Configuration support for JNDI - as usual you can either do this in an xml file, or via equivalent code.
This example uses an xml file, in fact it is the `$JETTY_HOME/etc/jetty-plus.xml` file from the Jetty distribution:
[source, xml, subs="{sub-order}"]
@ -247,9 +247,9 @@ addBefore::
This is a link:#context_attributes[context attribute] that can be set on link:{JDURL}/org/eclipse/jetty/webapp/WebAppContext.html[an org.eclipse.jetty.webapp.WebAppContext] to control which parts of the _container's_ classpath should be processed for things like annotations, `META-INF/resources`, `META-INF/web-fragment.xml` and `tlds` inside `META-INF`.
Normally, nothing from the container classpath will be included for processing.
However, sometimes you will need to include some.
For example, you may have some libraries that are shared amongst your webapps and thus you have put them into a `$JETTY_HOME/lib` directory.
Normally, nothing from the container classpath will be included for processing.
However, sometimes you will need to include some.
For example, you may have some libraries that are shared amongst your webapps and thus you have put them into a `$JETTY_HOME/lib` directory.
The libraries contain annotations and therefore must be scanned.
The value of this attribute is a regexp that defines which _jars_ and _class directories_ from the container's classpath should be examined.
@ -276,8 +276,8 @@ Note that the order of the patterns defines the ordering of the scanning of the
[[web-inf-include-jar-pattern]]
===== org.eclipse.jetty.server.webapp.WebInfIncludeJarPattern
Similarly to the previous link:#context_attributes[context attribute], this attribute controls which jars are processed for things like annotations, `META-INF/resources`, `META-INF/web-fragment.xml` and `tlds` in `META-INF`.
However, this attribute controls which jars from the _webapp's_ classpath (usually `WEB-INF/lib`) are processed.
Similarly to the previous link:#context_attributes[context attribute], this attribute controls which jars are processed for things like annotations, `META-INF/resources`, `META-INF/web-fragment.xml` and `tlds` in `META-INF`.
However, this attribute controls which jars from the _webapp's_ classpath (usually `WEB-INF/lib`) are processed.
This can be particularly useful when you have dozens of jars in `WEB-INF/lib`, but you know that only a few need to be scanned.
Here's an example in a xml file of a pattern that matches any jar that starts with `spring-`:

17
jetty-documentation/src/main/asciidoc/configuring/deploying/hot-deployment.adoc
View File

@ -17,9 +17,9 @@
[[hot-deployment]]
=== Hot Deployment
Jetty allows for deploying an arbitrary context or web application by monitoring a directory for changes.
If a web application or a context descriptor is added to the directory, Jetty's DeploymentManager (DM) deploys a new context.
If a context descriptor is touched or updated, the DM stops, reconfigures, and redeploys its context.
Jetty allows for deploying an arbitrary context or web application by monitoring a directory for changes.
If a web application or a context descriptor is added to the directory, Jetty's DeploymentManager (DM) deploys a new context.
If a context descriptor is touched or updated, the DM stops, reconfigures, and redeploys its context.
If a context is removed, the DM stops it and removes it from the server.
This behavior can be controlled by configuring `WebAppProvider` properties.
@ -35,7 +35,8 @@ The default location for this configuration is in the `${jetty.home}/etc/jetty-d
[source, xml, subs="{sub-order}"]
----
<?xml version="1.0"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure_9_0.dtd">
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure_9_3.dtd">
<Configure id="Server" class="org.eclipse.jetty.server.Server">
<Call name="addBean">
@ -46,16 +47,16 @@ The default location for this configuration is in the `${jetty.home}/etc/jetty-d
</Set>
<Call name="setContextAttribute">
<Arg>org.eclipse.jetty.server.webapp.ContainerIncludeJarPattern</Arg>
<Arg>.*/servlet-api-[^/]*\.jar$</Arg>
<Arg>.*/[^/]*servlet-api-[^/]*\.jar$|.*/javax.servlet.jsp.jstl-.*\.jar$|.*/org.apache.taglibs.taglibs-standard-impl-.*\.jar$</Arg>
</Call>
<Call id="webappprovider" name="addAppProvider">
<Arg>
<New class="org.eclipse.jetty.deploy.providers.WebAppProvider">
<Set name="monitoredDirName"><Property name="jetty.home" default="." />/webapps</Set>
<Set name="monitoredDirName"><Property name="jetty.base" default="." />/<Property name="jetty.deploy.monitoredDir" deprecated="jetty.deploy.monitoredDirName" default="webapps"/></Set>
<Set name="defaultsDescriptor"><Property name="jetty.home" default="." />/etc/webdefault.xml</Set>
<Set name="scanInterval">1</Set>
<Set name="extractWars">true</Set>
<Set name="scanInterval"><Property name="jetty.deploy.scanInterval" default="1"/></Set>
<Set name="extractWars"><Property name="jetty.deploy.extractWars" default="true"/></Set>
</New>
</Arg>
</Call>

42
jetty-documentation/src/main/asciidoc/configuring/deploying/overlay-deployer.adoc
View File

@ -19,10 +19,10 @@
____
[NOTE]
This feature is reintroduced in Jetty 9.0.4
This feature was reintroduced in Jetty 9.0.4
____
The Jetty Overlay Deployer allows multiple WAR files to be overlaid so that a web application can be customized, configured, and deployed without unpacking, modifying and repacking the WAR file.
The Jetty Overlay Deployer allows multiple WAR files to be overlaid so that a web application can be customized, configured, and deployed without unpacking, modifying and repacking the WAR file.
This has the following benefits:
* WAR files can be kept immutable, even signed, so that it is clear which version is deployed.
@ -44,27 +44,27 @@ Customizing, configuring and deploying a web application bundled as a WAR file f
* Adding Jars to the container classpath for Datasource and other resources.
* Modifying the container configuration to provide JNDI resources.
The result is that the customizations and configurations blend into both the container and the WAR file.
The result is that the customizations and configurations blend into both the container and the WAR file.
If either the container or the base WAR file is upgraded to a new version, it can be a very difficult and error prone task to identify all the changes that have been made and to reapply them to a new version.
[[overlay-overlays]]
==== Overlays
To solve the problems highlighted above, Jetty 7.4 introduces WAR overlays (a concept borrowed from the Maven WAR plugin).
An overlay is basically just another WAR file, whose contents merge on top of the original WAR so that filed can be added or replaced.
To solve the problems highlighted above, Jetty introduced WAR overlays (a concept borrowed from the Maven WAR plugin).
An overlay is basically just another WAR file, whose contents merge on top of the original WAR so that filed can be added or replaced.
Jetty overlays also allow fragments of `web.xml` to be mixed in, which means the configuration can be modified without replacing it.
[[overlay-jtrac]]
==== JTrac Overlay Example
The JTrac issue tracking web application is a good example of a typical web application, as it uses the usual suspects of libs: spring, hibernate, dom4j, commons-*, wicket, etc.
The files for this demonstration are available in overlays-demo.tar.gz.
The demonstation can be expanded on top of the jetty distribution; this tutorial expands it to /tmp and installs the components step-by-step:
The JTrac issue tracking web application is a good example of a typical web application, as it uses the usual suspects of libs: spring, hibernate, dom4j, commons-*, wicket, etc.
The files for this demonstration are available in overlays-demo.tar.gz.
The demonstration can be expanded on top of the Jetty distribution; this tutorial expands it to /tmp and installs the components step-by-step:
[source, screen, subs="{sub-order}"]
----
$ cd /tmp
$ wget http://webtide.intalio.com/wp-content/uploads/2011/05/overlays-demo.tar.gz
$ wget http://webtide.com/wp-content/uploads/2011/05/overlays-demo.tar.gz
$ tar xfvz overlays-demo.tar.gz
$ export OVERLAYS=/tmp/overlays
----
@ -72,8 +72,8 @@ $ export OVERLAYS=/tmp/overlays
[[overlay-configure]]
==== Configuring Jetty for Overlays
Overlays support is included in jetty distributions from 7.4.1-SNAPSHOT onwards, which can be downloaded from oss.sonatype.org or Maven Central and unpack into a directory.
The `start.ini` file needs edited so that it includes the overlay option and configuration file.
Overlays support is included in jetty distributions from 7.4.1-SNAPSHOT onwards, which can be downloaded from oss.sonatype.org or Maven Central and unpack into a directory.
The `start.ini` file needs edited so that it includes the overlay option and configuration file.
The resulting file should look like:
[source, plain, subs="{sub-order}"]
@ -84,7 +84,7 @@ etc/jetty-deploy.xml
etc/jetty-overlay.xml
----
The mechanics of this are in etc/jetty-deploy.xml, which installs the `OverlayedAppProvider` into the `DeploymentManager`.
The mechanics of this are in etc/jetty-deploy.xml, which installs the `OverlayedAppProvider` into the `DeploymentManager`.
Jetty can then be started normally:
[source, screen, subs="{sub-order}"]
@ -96,7 +96,7 @@ Jetty is now listening on port 8080, but with no webapp deployed.
____
[IMPORTANT]
You should conduct the rest of the tutorial in another window with the JETTY_HOME environment set to the jetty distribution directory.
You should conduct the rest of the tutorial in another window with the JETTY_HOME environmental variable set to the Jetty distribution directory.
____
[[overlay-install]]
@ -155,7 +155,7 @@ templates/jtracTemplate=jtrac-2.1.0
----
name of the template directory (or WAR)::
Uses the ‘=’ character in jtracTemplate=jtrac-2.1.0 to separate the name of the template from the name of the WAR file in webapps that it applies to.
Uses the ‘=’ character in jtracTemplate=jtrac-2.1.0 to separate the name of the template from the name of the WAR file in webapps that it applies to.
If = is a problem, use -- instead.
WEB-INF/classes/jtrac-init.properties::
Replaces the JTrac properties file with an empty file, as the properties it contains are configured elsewhere.
@ -175,7 +175,7 @@ WEB-INF/overlay.xml::
----
WEB-INF/template.xml::
A Jetty XML formatted IoC file that injects/configures the resource cache and classloader that all instances of the template share.
A Jetty XML formatted IoC file that injects/configures the resource cache and classloader that all instances of the template share.
It runs only once per load of the template:
[source, xml, subs="{sub-order}"]
@ -194,7 +194,7 @@ WEB-INF/template.xml::
WEB-INF/web-overlay.xml::
A `web.xml` fragment that Jetty overlays on top of the `web.xml` from the base WAR file; it can set init parameters and add/modify filters and
servlets.
servlets.
In this example it sets the application home and springs `webAppRootKey`:
[source, xml, subs="{sub-order}"]
@ -218,7 +218,7 @@ WEB-INF/web-overlay.xml::
Notice the parameterization of values such as `${overlays.instance.classifier}`, as this allows the configuration to be in the template, and not customized for each instance.
Without the Overlay Deployer, all of the above would still need to have configure , but rather than being in a single clear structure the configuration elements would have been either in the server's common directory, the server's `webdefaults.xml` (aka `server.xml`), or baked into the WAR file of each application instance using copied/modified files from the original.
Without the Overlay Deployer, all of the above would still need to have configure , but rather than being in a single clear structure the configuration elements would have been either in the server's common directory, the server's `webdefaults.xml` (aka `server.xml`), or baked into the WAR file of each application instance using copied/modified files from the original.
The Overlay Deployer allows all these changes to be made in one structure; moreover it allows for the parameterization of some of the configuration, which facilitates easy multi-tenant deployment.
==== Installing an Instance Overlay
@ -232,7 +232,7 @@ $ mv /tmp/overlays/instances/jtracTemplate\=red $JETTY_HOME/overlays/instances/
$ mv /tmp/overlays/instances/jtracTemplate\=blue $JETTY_HOME/overlays/instances/
----
As each instance moves into place, the Jetty server window reacts and deploys the instance.
As each instance moves into place, the Jetty server window reacts and deploys the instance.
Within each instance, there is the structure:
[source, plain, subs="{sub-order}"]
@ -246,7 +246,7 @@ instances/jtracTemplate=red/
----
WEB-INF/overlay.xml::
A Jetty XML format IoC file that injects/configures the context for the instance.
A Jetty XML format IoC file that injects/configures the context for the instance.
In this case it sets up a virtual host for the instance:
[source, xml, subs="{sub-order}"]
@ -279,12 +279,12 @@ The default username/password for JTrac is admin/admin.
* A virtual host set in the instance overlay.xml distinguishes the instances.
* All instances share static content from the base WAR and template.
Specifically there is a shared `ResourceCache` so only a single instance of each static content is loaded into memory.
* All instances share the classloader at the base WAR and template level, so that only a single instance of common classes is loaded into memory.
* All instances share the classloader at the base WAR and template level, so that only a single instance of common classes is loaded into memory.
Classes with non shared statics can be configured to load in the instances classloader.
* Jetty hot deploys all overlays and tracks dependencies.
** If an XML changes in an instance, Jetty redeploys it.
** If an XML changes in a template, then Jetty redeploys all instances using it.
** If a WAR file changes, then Jetty redeploys all templates and all instances dependent on it.
* New versions can be easily deployed.
* New versions can be easily deployed.
For example, when JTrac-2.2.0.war becomes available, it can be placed into `overlays/webapps` and then rename `jtracTemplate\=jtrac-2.1.0` to `jtracTemplate\=jtrac-2.2.0`.
* There is a fuller version of this demo in overlays-demo-jndi.tar.gz, that uses JNDI (needs `options=jndi`, annotations and `jetty-plus.xml` in `start.ini`) and shows how additional JARs can be added in the overlays.

4
jetty-documentation/src/main/asciidoc/configuring/deploying/static-content-deployment.adoc
View File

@ -17,8 +17,8 @@
[[static-content-deployment]]
=== Configuring Static Content Deployment
To serve purely static content, the Jetty Deployment Descriptor XML concepts and the internal `ResourceHandler` can be used.
Create a file called `scratch.xml` in the `${jetty.home}/webapps` directory and paste the following file contents in it.
To serve purely static content, the Jetty Deployment Descriptor XML concepts and the internal `ResourceHandler` can be used.
Create a file called `scratch.xml` in the `${jetty.base}/webapps` directory and paste the following file contents in it.
[source, xml, subs="{sub-order}"]
----

1
jetty-documentation/src/main/asciidoc/configuring/part.adoc
View File

@ -13,6 +13,7 @@
//
// You may elect to redistribute this code under either of these licenses.
// ========================================================================
[[jetty-config-guide]]
= Jetty Configuration Guide

1
jetty-documentation/src/main/asciidoc/development/part.adoc
View File

@ -13,6 +13,7 @@
//
// You may elect to redistribute this code under either of these licenses.
// ========================================================================
[[jetty-dev-guide]]
= Jetty Development Guide

23
jetty-documentation/src/main/asciidoc/quick-start/introduction/what-is-jetty.adoc
View File

@ -19,10 +19,27 @@
Jetty is an open-source project providing an HTTP server, HTTP client, and javax.servlet container.
This guide is in two parts.
This guide is broken up in to five parts:
* The first part emphasizes beginning to use Jetty. It provides information about downloading Jetty, changing things like the port Jetty runs on, adjusting logging levels, and configuring many of the most common servlet container features such as JNDI, JMX, and session management.
* The second part describes advanced uses of Jetty, providing in depth coverage of specific features like our highly scalable async client, proxy servlet configuration, the Jetty Maven plugin, and using Jetty as an embedded server. The advanced section includes tutorials, howtos, videos, and reference materials.
* The link:#quick-start[first section] emphasizes beginning to use Jetty.
It provides information about what Jetty is and where you can download it, and where to find Jetty in repositories like Central Maven.
It also provides a Quick Start guide on how to get Jetty up and running as well as an overview of how and what to configure in Jetty.
* The link:#jetty-config-guide[second section] of the guide deals with configuring Jetty at a more granular level.
It explains how to use Jetty to deploy web applications, configure contexts and connects, and how to implement SSL and other security measures.
* Administration of Jetty is the focus of the link:#jetty-admin-guide[third section] of the guide.
From server startup to session management, logging, HTTP/2 support and Jetty optimization, these chapters will help administrators get the most out of their Jetty server instances.
This section also covers configuring many of the most common servlet container features such as JNDI and JMX.
* Aimed at advanced users of Jetty, the link:#jetty-dev-guide[fourth section] of the guide focuses on Jetty development.
A large portion of this section is focused on using Jetty as an embedded server in existing applications.
It contains several examples and how-to guides for making the most out of the Jetty framework.
This section also includes a guide on using the Jetty Maven plugin as well as information on debugging Jetty.
* The link:#jetty-ref-guide[final section] of the guide is a reference section.
Included there are guides on Jetty architecture and Jetty XML syntax, alternate distributions of Jetty and even troubleshooting of common issues.
There is also a chapter on getting involved in the Jetty community including information on how to contribute code and how to find help.
Feedback is always welcome!
Additionally, if you are interested in how to contribute to the open source project there is a link:#community[section on that as well!]

1
jetty-documentation/src/main/asciidoc/quick-start/part.adoc
View File

@ -13,6 +13,7 @@
//
// You may elect to redistribute this code under either of these licenses.
// ========================================================================
[[quick-start]]
= Getting Started With Jetty

1
jetty-documentation/src/main/asciidoc/reference/part.adoc
View File

@ -13,6 +13,7 @@
//
// You may elect to redistribute this code under either of these licenses.
// ========================================================================
[[jetty-ref-guide]]
= Jetty Reference Guide

20
jetty-io/src/main/java/org/eclipse/jetty/io/ByteArrayEndPoint.java
View File

@ -339,9 +339,10 @@ public class ByteArrayEndPoint extends AbstractEndPoint
try(Locker.Lock lock = _locker.lock())
{
if (BufferUtil.isEmpty(_out) && isOpen() && !isOutputShutdown())
while (BufferUtil.isEmpty(_out) && !isOutputShutdown())
{
_hasOutput.await(time,unit);
}
b=_out;
_out=BufferUtil.allocate(b.capacity());
}
@ -531,5 +532,20 @@ public class ByteArrayEndPoint extends AbstractEndPoint
_growOutput=growOutput;
}
/* ------------------------------------------------------------ */
@Override
public String toString()
{
int q;
ByteBuffer b;
String o;
try(Locker.Lock lock = _locker.lock())
{
q=_inQ.size();
b=_inQ.peek();
o=BufferUtil.toDetailString(_out);
}
return String.format("%s[q=%d,q[0]=%s,o=%s]",super.toString(),q,b,o);
}
}

19
jetty-server/src/main/java/org/eclipse/jetty/server/HttpInput.java
View File

@ -668,11 +668,24 @@ public class HttpInput extends ServletInputStream implements Runnable
@Override
public String toString()
{
return String.format("%s@%x[c=%d,s=%s]",
State state;
long consumed;
int q;
Content content;
synchronized (_inputQ)
{
state=_state;
consumed=_contentConsumed;
q=_inputQ.size();
content=_inputQ.peekFirst();
}
return String.format("%s@%x[c=%d,q=%d,[0]=%s,s=%s]",
getClass().getSimpleName(),
hashCode(),
_contentConsumed,
_state);
consumed,
q,
content,
state);
}
public static class PoisonPillContent extends Content

11
jetty-server/src/main/java/org/eclipse/jetty/server/LocalConnector.java
View File

@ -96,6 +96,7 @@ public class LocalConnector extends AbstractConnector
* @throws Exception if the requests fail
* @deprecated Use {@link #getResponse(String)}
*/
@Deprecated
public String getResponses(String requests) throws Exception
{
return getResponses(requests, 5, TimeUnit.SECONDS);
@ -115,6 +116,7 @@ public class LocalConnector extends AbstractConnector
* @throws Exception if the requests fail
* @deprecated Use {@link #getResponse(String, boolean, long, TimeUnit)}
*/
@Deprecated
public String getResponses(String requests,long idleFor,TimeUnit units) throws Exception
{
ByteBuffer result = getResponses(BufferUtil.toBuffer(requests,StandardCharsets.UTF_8),idleFor,units);
@ -133,6 +135,7 @@ public class LocalConnector extends AbstractConnector
* @throws Exception if the requests fail
* @deprecated Use {@link #getResponse(ByteBuffer)}
*/
@Deprecated
public ByteBuffer getResponses(ByteBuffer requestsBuffer) throws Exception
{
return getResponses(requestsBuffer, 5, TimeUnit.SECONDS);
@ -151,6 +154,7 @@ public class LocalConnector extends AbstractConnector
* @throws Exception if the requests fail
* @deprecated Use {@link #getResponse(ByteBuffer, boolean, long, TimeUnit)}
*/
@Deprecated
public ByteBuffer getResponses(ByteBuffer requestsBuffer,long idleFor,TimeUnit units) throws Exception
{
if (LOG.isDebugEnabled())
@ -186,6 +190,13 @@ public class LocalConnector extends AbstractConnector
return endp;
}
public LocalEndPoint connect()
{
LocalEndPoint endp = new LocalEndPoint();
_connects.add(endp);
return endp;
}
@Override
protected void accept(int acceptorID) throws IOException, InterruptedException
{

11
jetty-server/src/test/java/org/eclipse/jetty/server/DumpHandler.java
View File

@ -71,6 +71,16 @@ public class DumpHandler extends AbstractHandler
if (!isStarted())
return;
if (Boolean.valueOf(request.getParameter("flush")))
response.flushBuffer();
if (Boolean.valueOf(request.getParameter("empty")))
{
baseRequest.setHandled(true);
response.setStatus(200);
return;
}
StringBuilder read = null;
if (request.getParameter("read")!=null)
{
@ -214,6 +224,7 @@ public class DumpHandler extends AbstractHandler
}
catch(IOException e)
{
e.printStackTrace();
writer.write(e.toString());
}
}

11
jetty-server/src/test/java/org/eclipse/jetty/server/LocalAsyncContextTest.java
View File

@ -63,6 +63,11 @@ public class LocalAsyncContextTest
_server.setHandler(session);
_server.start();
reset();
}
public void reset()
{
_completed0.set(null);
_completed1.set(null);
}
@ -181,9 +186,8 @@ public class LocalAsyncContextTest
_handler.setCompleteAfter(100);
response = process("wibble");
check(response, "COMPLETED");
_handler.setRead(6);
_handler.setResumeAfter(0);
_handler.setCompleteAfter(-1);
response = process("wibble");
@ -192,6 +196,7 @@ public class LocalAsyncContextTest
_handler.setResumeAfter(100);
_handler.setCompleteAfter(-1);
response = process("wibble");
check(response, "DISPATCHED");
_handler.setResumeAfter(-1);
@ -203,6 +208,7 @@ public class LocalAsyncContextTest
_handler.setCompleteAfter(100);
response = process("wibble");
check(response, "COMPLETED");
}
@Test
@ -238,6 +244,7 @@ public class LocalAsyncContextTest
private synchronized String process(String content) throws Exception
{
reset();
String request = "GET / HTTP/1.1\r\n" +
"Host: localhost\r\n" +
"Connection: close\r\n";

184
jetty-server/src/test/java/org/eclipse/jetty/server/LocalConnectorTest.java
View File

@ -19,6 +19,8 @@
package org.eclipse.jetty.server;
import static org.hamcrest.Matchers.containsString;
import static org.hamcrest.Matchers.not;
import static org.hamcrest.Matchers.nullValue;
import static org.junit.Assert.assertThat;
import static org.junit.Assert.assertTrue;
@ -27,6 +29,7 @@ import java.util.concurrent.CountDownLatch;
import java.util.concurrent.TimeUnit;
import org.eclipse.jetty.io.Connection;
import org.eclipse.jetty.server.LocalConnector.LocalEndPoint;
import org.eclipse.jetty.util.BufferUtil;
import org.junit.After;
import org.junit.Before;
@ -105,22 +108,195 @@ public class LocalConnectorTest
@Test
public void testOneResponse_10_keep_alive() throws Exception
{
String response=_connector.getResponse("GET /R1 HTTP/1.0\r\n" +
String response=_connector.getResponse(
"GET /R1 HTTP/1.0\r\n" +
"Connection: keep-alive\r\n" +
"\r\n");
assertThat(response,containsString("HTTP/1.1 200 OK"));
assertThat(response,containsString("pathInfo=/R1"));
}
@Test
public void testOneResponse_10_keep_alive_empty() throws Exception
{
String response=_connector.getResponse(
"GET /R1?empty=true HTTP/1.0\r\n" +
"Connection: keep-alive\r\n" +
"\r\n");
assertThat(response,containsString("HTTP/1.1 200 OK"));
assertThat(response,not(containsString("pathInfo=/R1")));
}
@Test
public void testOneResponse_11() throws Exception
{
String response=_connector.getResponse("GET /R1 HTTP/1.1\r\n" +
String response=_connector.getResponse(
"GET /R1 HTTP/1.1\r\n" +
"Host: localhost\r\n" +
"\r\n");
assertThat(response,containsString("HTTP/1.1 200 OK"));
assertThat(response,containsString("pathInfo=/R1"));
}
@Test
public void testOneResponse_11_close() throws Exception
{
String response=_connector.getResponse(
"GET /R1 HTTP/1.1\r\n" +
"Host: localhost\r\n" +
"Connection: close\r\n" +
"\r\n");
assertThat(response,containsString("HTTP/1.1 200 OK"));
assertThat(response,containsString("pathInfo=/R1"));
}
@Test
public void testOneResponse_11_empty() throws Exception
{
String response=_connector.getResponse(
"GET /R1?empty=true HTTP/1.1\r\n" +
"Host: localhost\r\n" +
"Connection: close\r\n" +
"\r\n");
assertThat(response,containsString("HTTP/1.1 200 OK"));
assertThat(response,not(containsString("pathInfo=/R1")));
}
@Test
public void testOneResponse_11_chunked() throws Exception
{
String response=_connector.getResponse(
"GET /R1?flush=true HTTP/1.1\r\n" +
"Host: localhost\r\n" +
"\r\n");
assertThat(response,containsString("HTTP/1.1 200 OK"));
assertThat(response,containsString("pathInfo=/R1"));
assertThat(response,containsString("\r\n0\r\n"));
}
@Test
public void testThreeResponsePipeline_11() throws Exception
{
LocalEndPoint endp = _connector.connect();
endp.addInput(
"GET /R1 HTTP/1.1\r\n" +
"Host: localhost\r\n" +
"\r\n"+
"GET /R2 HTTP/1.1\r\n" +
"Host: localhost\r\n" +
"\r\n"+
"GET /R3 HTTP/1.1\r\n" +
"Host: localhost\r\n" +
"\r\n"
);
String response=endp.getResponse();
assertThat(response,containsString("HTTP/1.1 200 OK"));
assertThat(response,containsString("pathInfo=/R1"));
response=endp.getResponse();
assertThat(response,containsString("HTTP/1.1 200 OK"));
assertThat(response,containsString("pathInfo=/R2"));
response=endp.getResponse();
assertThat(response,containsString("HTTP/1.1 200 OK"));
assertThat(response,containsString("pathInfo=/R3"));
}
@Test
public void testThreeResponse_11() throws Exception
{
LocalEndPoint endp = _connector.connect();
endp.addInput(
"GET /R1 HTTP/1.1\r\n" +
"Host: localhost\r\n" +
"\r\n");
String response=endp.getResponse();
assertThat(response,containsString("HTTP/1.1 200 OK"));
assertThat(response,containsString("pathInfo=/R1"));
endp.addInput(
"GET /R2 HTTP/1.1\r\n" +
"Host: localhost\r\n" +
"\r\n");
response=endp.getResponse();
assertThat(response,containsString("HTTP/1.1 200 OK"));
assertThat(response,containsString("pathInfo=/R2"));
endp.addInput(
"GET /R3 HTTP/1.1\r\n" +
"Host: localhost\r\n" +
"\r\n"
);
response=endp.getResponse();
assertThat(response,containsString("HTTP/1.1 200 OK"));
assertThat(response,containsString("pathInfo=/R3"));
}
@Test
public void testThreeResponseClosed_11() throws Exception
{
LocalEndPoint endp = _connector.connect();
endp.addInput(
"GET /R1 HTTP/1.1\r\n" +
"Host: localhost\r\n" +
"\r\n"+
"GET /R2 HTTP/1.1\r\n" +
"Connection: close\r\n" +
"Host: localhost\r\n" +
"\r\n"+
"GET /R3 HTTP/1.1\r\n" +
"Host: localhost\r\n" +
"\r\n"
);
String response=endp.getResponse();
assertThat(response,containsString("HTTP/1.1 200 OK"));
assertThat(response,containsString("pathInfo=/R1"));
response=endp.getResponse();
assertThat(response,containsString("HTTP/1.1 200 OK"));
assertThat(response,containsString("pathInfo=/R2"));
response=endp.getResponse();
assertThat(response,nullValue());
}
@Test
public void testExpectContinuesAvailable() throws Exception
{
LocalEndPoint endp = _connector.connect();
endp.addInput(
"GET /R1 HTTP/1.1\r\n" +
"Host: localhost\r\n" +
"Content-Type: text/plain; charset=UTF-8\r\n" +
"Expect: 100-Continue\r\n" +
"Content-Length: 10\r\n" +
"\r\n"+
"01234567890\r\n");
String response = endp.getResponse();
assertThat(response,containsString("HTTP/1.1 200 OK"));
assertThat(response,containsString("pathInfo=/R1"));
assertThat(response,containsString("0123456789"));
}
@Test
public void testExpectContinues() throws Exception
{
LocalEndPoint endp = _connector.executeRequest(
"GET /R1 HTTP/1.1\r\n" +
"Host: localhost\r\n" +
"Content-Type: text/plain; charset=UTF-8\r\n" +
"Expect: 100-Continue\r\n" +
"Content-Length: 10\r\n" +
"\r\n");
String response = endp.getResponse();
assertThat(response,containsString("HTTP/1.1 100 Continue"));
endp.addInput("01234567890\r\n");
response = endp.getResponse();
assertThat(response,containsString("HTTP/1.1 200 OK"));
assertThat(response,containsString("pathInfo=/R1"));
assertThat(response,containsString("0123456789"));
}
@Test
public void testStopStart() throws Exception
@ -213,11 +389,11 @@ public class LocalConnectorTest
@Test
public void testGETandGET() throws Exception
{
String response=_connector.getResponses("GET /R1 HTTP/1.0\r\n\r\n");
String response=_connector.getResponse("GET /R1 HTTP/1.0\r\n\r\n");
assertThat(response,containsString("HTTP/1.1 200 OK"));
assertThat(response,containsString("pathInfo=/R1"));
response=_connector.getResponses("GET /R2 HTTP/1.0\r\n\r\n");
response=_connector.getResponse("GET /R2 HTTP/1.0\r\n\r\n");
assertThat(response,containsString("HTTP/1.1 200 OK"));
assertThat(response,containsString("pathInfo=/R2"));
}