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

Updates to Intro, Chapter 5 and ResourceHandler example for #687. 

Signed-off-by: WalkerWatch <ctwalker@gmail.com>
This commit is contained in:
WalkerWatch 2016-07-07 16:34:58 -04:00
parent 172ee4266c
commit db9a8dc962
13 changed files with 90 additions and 54 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)].
____

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