<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title></title>
</head>
<body>
<br>
<table cellpadding="0" cellspacing="8" border="0" width="20%">
<tbody>
<tr>
<td valign="middle" bgcolor="#ccccff"><small><a href="HttpServer.html">
BACK</a></small></td>
<td valign="middle" bgcolor="#ccccff"><small><a href="index.html">
INDEX</a></small></td>
<td valign="middle" bgcolor="#ccccff"><small><a href="..">
EXIT</a></small></td>
<td valign="middle" bgcolor="#ccccff"><small><a href="logging.html">
NEXT</a></small></td>
</tr>
</tbody>
</table>
<h1>Jetty Server</h1>
<big><big><b><a name="introduction"></a>Introduction</b></big></big><br>
<br>
The <a href="HttpServer.html">HttpServer</a> class provides the core Jetty HTTP
server and HttpHandler extension architecture.
The
<a href="/javadoc/org/mortbay/jetty/package-summary.html">org.mortbay.jetty</a>
and
<a href="/javadoc/org/mortbay/jetty/servlet/package-summary.html">org.mortbay.jetty.servlet</a>
packages extend the basic HttpServer with standard compliant
<a href="http://java.sun.com/servlet">servlets and webapplications</a>. The
key classes in these packages are:<UL>
<LI><a href="/javadoc/org/mortbay/jetty/Server.html">org.mortbay.jetty.Server</a>
extends HttpServer with XML configuration and servlet conveniance methods.<br>
<LI><a href="/javadoc/org/mortbay/jetty/servlet/ServletHandler.html">org.mortbay.jetty.servlet.ServletHandler</a>
A HttpHandler that uses standard servlets to provide dynamic content. Can be
used in a HttpServer or as the basis of a Web Application.
<br>
<LI><a href="/javadoc/org/mortbay/jetty/servlet/ServletHttpContext.html">org.mortbay.jetty.servlet.ServletHttpContext</a>
extends HttpContext with conveniance methods for Servlets..
<br>
<LI><a href="/javadoc/org/mortbay/jetty/servlet/WebApplicationHandler.html">org.mortbay.jetty.servlet.WebApplicationHandler</a>
extends ServletHandler with security and filtering capabilities.
<br>
<LI><a href="/javadoc/org/mortbay/jetty/servlet/WebApplicationContext.html">org.mortbay.jetty.servlet.WebApplicationContext</a>
extends ServletHttpContext with the ability to add and configure a
WebApplicationHandler from a <tt>WEB-INF/web.xml</tt> file from within a
standard web application.
<br>
<LI><a href="/javadoc/org/mortbay/jetty/servlet/Default.html">org.mortbay.jetty.servlet.Default</a>
The default servlet within a webapplication that serves static content.
This servlet replaces ResourceHandler and NotFoundHandler when using webapplications.
<br>
<LI><a href="/javadoc/org/mortbay/jetty/servlet/Invoker.html">org.mortbay.jetty.servlet.Invoker</a>
A servlet for creating dynamic servlet mappings.
<br>
</UL>
<big><big><b><a name="nonwebapps"></a>Using the ServletHandler</b></big></big></p>
If you do not wish to use web applications but you want to deploy servlets, then you need to register at least one context and at least the ServletHandler with the server. You are able to statically configure individual servlets at a specific URL pattern, or use dynamic mapping to extract servlet names from the request URL.
<P>
The ServletHandler can be used with a HttpServer:
<table align=center cellspacing=2 cellpadding=0 border=0 width="90%">
<tbody><tr><td><small><pre>
HttpServer server = new HttpServer();
server.addListener(":8080");
HttpContext context = server.getContext("/");
ServletHandler handler= new ServletHandler();
handler.addServlet("Dump","/dump/*",
"org.mortbay.servlet.Dump");
context.addHandler(handler);
</pre></small>
<b>Code Example: Using ServletHandler in HttpServer</b>
</td></tr></tbody></table><p>
Alternately, the <a href="/javadoc/org/mortbay/jetty/Server.html">org.mortbay.jetty.Server</a>
can be used instead of a HttpServer, so that it's conveniance methods may be
used:
<table align=center cellspacing=2 cellpadding=0 border=0 width="90%">
<tbody><tr><td><small><pre>
Server server = new Server();
server.addListener(":8080");
ServletHttpContext context = (ServletHttpContext)
server.getContext("/");
context.addServlet("Dump","/dump/*",
"org.mortbay.servlet.Dump");
</pre></small>
<b>Code Example: Using ServletHandler in Server</b>
</td></tr></tbody></table><p>
<P>
<big><b><a name="mapping"></a>Using Static Servlet Mappings</b></big></p>
The examples above used defined servlet mappings to map a request URL to a
servlet. Prefix (eg "/dump/*"), suffix (eg. "*.jsp"), exact (eg "/path") or default ("/")
mappings may be used and they are all within the scope of the context
path:
<table align=center cellspacing=2 cellpadding=0 border=0 width="90%">
<tbody><tr><td><small><pre>
Server server = new Server();
server.addListener(":8080");
ServletHttpContext context = (ServletHttpContext)
server.getContext("/context");
context.addServlet("Dump","/dump/*",
"org.mortbay.servlet.Dump");
context.addServlet("Dump","/dump/session",
"org.mortbay.servlet.SessionDump");
context.addServlet("JSP","*.jsp",
"org.apache.jasper.servlet.JspServlet");
context.addServlet("Default","/",
"org.mortbay.jetty.servlet.Default");
</pre></small>
<b>Code Example: Static servlet mappings</b>
</td></tr></tbody></table><p>
Examples of URLs that will be mapped to these servlets are:<ur>
<table border=0>
<tr>
<td><code>/context/dump</code> </td><td>Dump Servlet by prefix</td>
</tr>
<tr>
<td><code>/context/dump/info</code> </td><td>Dump Servlet by prefix</td>
</tr>
<tr>
<td><code>/context/dump/session</code> </td><td>SessionDump Servlet by exact</td>
</tr>
<tr>
<td><code>/context/welcome.jsp</code> </td><td>JSP Servlet by suffix</td>
</tr>
<tr>
<td><code>/context/dump/other.jsp</code> </td><td>Dump Servlet by prefix</td>
</tr>
<tr>
<td><code>/context/anythingelse</code> </td><td>Default Servlet</td>
</tr>
<tr>
<td><code>/anythingelse</code> </td><td>Not this context</td>
</tr>
</table></ul>
<P>
<big><b><a name="dynamic"></a> Using Dynamic Servlets</b></big><br>
Servlets can be discovered dynamically by using the
<a href="/javadoc/org/mortbay/jetty/servlet/Invoker.html">org.mortbay.jetty.servlet.Invoker</a>
servlet. This servlet uses the request URI to determine a servlet class or the name of a
previously registered servlet:
<table align=center cellspacing=2 cellpadding=0 border=0 width="90%">
<tbody><tr><td><small><pre>
Server server = new Server();
server.addListener(":8080");
ServletHttpContext context = (ServletHttpContext)
server.getContext("/context");
context.addServlet("Dump","/dump/*",
"org.mortbay.servlet.Dump");
context.addServlet("Invoker","/servlet/*",
"org.mortbay.jetty.servlet.Invoker");
</pre></small>
<b>Code Example: Dynamic servlet mappings</b>
</td></tr></tbody></table><p>
Examples of URLs that will be mapped to these servlets are:<ur>
<table border=0>
<tr>
<td><code>/servlet/Dump</code> </td><td>Dump Servlet by name</td>
</tr>
<tr>
<td><code>/servlet/com.acme.MyServlet/info</code> </td><td>Servlet by
dynamic class</td>
</tr>
<tr>
<td><code>/servlet/com.mortbay.servlet.Dump</code> </td><td>Dump Servlet
by class or ERROR</td>
</tr>
</table></ul><p>
By default, the Invoker will only load servlets from the context classloader,
so the last URL above will result in an error. The Invoker can be configured
to allow any servlet to be run, but this can be a secuirty issue.
<p>
<big><big><b><a name="webapps"></a>Deploying Web Applications</b></big></big><br>
<p>
The <a href="http://java.sun.com/products/servlet/download.html">
Servlet Specification</a> details a standard layout for web applications.
If your content is packaged according to these
specifications, then simply call the <tt>addWebApplication(...)</tt>methods
on the <a href="/javadoc/org/mortbay/jetty/Server.html">
org.mortbay.jetty.Server</a> instance, specifying at minimum a context
path, the directory or <tt>war</tt> file of your application.
Jetty is then able to discover and configure all the required handlers
including security, static content and servlets.
</p>
<p>
The <tt>addWebApplication(...)</tt>methods transparently create and return an
instance of
<a href="/javadoc/org/mortbay/jetty/servlet/WebApplicationContext.html">
WebApplicationContext</a> which contains a
<a href="/javadoc/org/mortbay/jetty/servlet/WebApplicationHandler.html">
WebApplicationHandler</a>.
<P>
The WebApplicationHandler extends ServletHandler and as well as servlets, it
provides standard security and filters. Normally it is configured by
the <tt>webdefault.xml</tt> file to contain
<a href="/javadoc/org/mortbay/jetty/servlet/Invoker.html">
Invoker</a>,
<a href="/javadoc/org/apahe/jasper/servlet/JspServlet.html">
JSP</a> and
<a href="/javadoc/org/mortbay/jetty/servlet/Default.html">
Default</a> servlets.
<A href=/javadoc/servlet/http/Filter.html>Filters</A>,
<A href=/javadoc/servlet/http/HttpServlet.html>Servlets</A> and
other mechanisms are configured from the <tt>WEB-INF/web.xml</tt> file
within the web application.
<p>This example configures a web application located in the directory <tt>
./webapps/myapp/</tt> at the context path <tt>/</tt> for a virtual
host <tt> myhost</tt>:
<table align=center cellspacing=2 cellpadding=0 border=0 width="90%">
<tbody>
<tr>
<td>
<small>
<pre>
server.addWebApplication("myhost","/","./webapps/myapp/");
</pre>
</small>
<b>Code Example: Configuring a web application</b>
</td>
</tr>
</tbody>
</table>
<P>
The arguments to the <tt>addWebApplication</tt> method are:
<ul>
<li>An (optional) virtual host name for the context </li>
<li>A <a href="/jetty/faq?s=500-Servlets&t=Path Mapping">context path</a>
</li>
<li>The location of the web application, which may be a
directory structure or a <tt>war</tt> file, given as a URL, war filename
or a directory name.</li>
</ul>
The <tt>addWebApplication</tt> method is overloaded to accommodate
the parameters marked as (optional).<br>
<br>
<br>
<table border=1><TR><TD><I>Note: If you run Jetty within <A HREF="http://sourceforge.net/projects/jboss/">JBoss</A>, then you should <B>NOT</B> use the addWebApplication API (or XML), as this bypasses the
JBoss classloaders. Use the JBoss deployment mechanisms instead and only use the Jetty
configuration for listeners and logs.</I></TD></TR></TABLE><BR><BR>
<big><b>Multiple Web Applications</b></big>
<br>
<br>
To make things even easier, if you have multiple web apps to deploy, you can accomplish this with a single method call:
<br>
<table align=center cellspacing=2 cellpadding=0 border=0 width="90%">
<tbody>
<tr>
<td>
<tt>
<pre>
server.addWebApplications ("myhost","./webapps/");
</pre>
</tt>
<b>Code Example: Configuring multiple web apps</b>
</td>
</tr>
</tbody>
</table>
<br>
<br>
Given the code above, Jetty would look in the directory <tt>"./webapps/"</tt> for all <tt>war</tt> files and subdirectories, and configure itself with each web application specified therein. For example, assuming the directory <tt>webapps</tt> contained the <tt>war</tt> files <tt>webapps/root.war, webapps/customer.war and webapps/admin.war</tt>, then Jetty would create the contexts <tt>"/"</tt>, <tt>"/customer/*"</tt> and <tt>"/admin/*"</tt> mapped to the respective war files. NOTE the special mapping of <tt>war</tt> files (or directories) named <tt>root</tt> to the context <tt>"/"</tt>.
<br>
<br>
In order to actually deploy the web application, it is also necessary
to configure a port listener. The full code example to deploy the web application
in the code snippet is:<br>
<br>
<table align=center cellspacing=2 cellpadding=0 border=0 width="90%">
<tbody>
<tr>
<td>
<small>
<pre>
Server server = new Server();
SocketListener listener = new SocketListener();
listener.setPort(8080);
server.addListener(listener );
server.addWebApplication("myhost","./webapps/myapp/");
server.start();
</pre>
</small>
<b>Code Example: Deploying a web application</b>
</td>
</tr>
</tbody>
</table>
<br>
<br>
<big><b>Using XML</b></big>
<br>
<br>
The same web application can be deployed instead via an XML configuration
file instead of calls to the API. The name of the file is passed to Jetty
as an argument on the command line (see the section on <a href="GettingStarted.html#manual">
Jetty demonstrations</a> for instructions). The following excerpt deploys
the same web application as given in the code example above:
<table align=center cellspacing=2 cellpadding=0 border=0 width="90%">
<tbody>
<tr>
<td>
<small>
<pre>
<Configure class="org.mortbay.jetty.Server">
<Call name="addListener">
<Arg>
<New class="org.mortbay.http.SocketListener">
<Set name="Port">
<SystemProperty name="jetty.port"
default="8080"/>
</Set>
</New>
</Arg>
</Call>
<Call name="addWebApplication">
<Arg>/</Arg>
<Arg><SystemProperty name="jetty.home"
default="."/>/webapps/myapp
</Arg>
</Call>
</Configure>
</pre>
</small>
<b>XML Example: Deploying a web application</b>
</td>
</tr>
</tbody>
</table>
<br>
<br>
An explanation of the Jetty XML syntax can be found in the section on
<a href="XmlConfiguration.html">
Jetty XML Configuration</a>.<br>
<br>
<br>
<br>
<big><b><a name="security"></a>Web Application Configuration</b></big><br><br>
When a WebApplicationContext is started, up to three configuration files are applied
as follows:
<ol>
<li><tt>webdefault.xml</tt> This file must be in standard web.xml format and typically contains all the default settings for all webapplicatios. By default the <tt>org/mortbay/jetty/servlet/webdefault.xml</tt> file is used as a resource from the jetty jar and it configures the JspServlet and default session timeouts. The default xml file may be changed for a particular context by calling <tt>setDefaultsDescriptor(String)</tt><br> </li>
<li><tt>web.xml</tt> The standard web application configuration file and is found in
the <tt>WEB-INF</tt> directory of the webapplicaton.<br> </li>
<li><tt>web-jetty.xml</tt> This file must be in <tt>org.mortbay.xml.XmlConfiguration</tt> format and if found in the <tt>WEB-INF</tt>directory of a web application, it is applied to the <tt>WebApplicationContext</tt> instance. It is typically used to change non standard configuration.<BR>
<table align=center cellspacing=2 cellpadding=0 border=0 width="90%">
<tbody>
<tr>
<td>
<small>
<pre>
<Configure class="org.mortbay.jetty.servlet.WebApplicationContext">
<Set name="statsOn" type="boolean">false</Set>
</Configure>
</pre>
</small>
<b>XML Example: A web-jetty.xml file</b>
</td>
</tr>
</tbody>
</table>
<I>Note: the name </I><tt>jetty-web.xml</tt><I> is also accepted for this file.</I><br> </li>
</ol>
<br>
<br>
<big><b><a name="security"></a>Web Application Security </b></big><br>
<br>
Jetty makes the following interpretations for the configuration of security
constraints within a web.xml file:
<UL>
<LI> Methods PUT, DELETE and GET are disabled unless explicitly enabled.
<LI> If multiple security-constraints are defined, the most specific applies to a
request.
<LI> A security-constraint an empty auth-constraint forbids all access by any
user:
<blockquote>
<small><PRE>
<security-constraint>
<web-resource-collection>
<web-resource-name>Forbidden</web-resource-name>
<url-pattern>/auth/noaccess/*</url-pattern>
</web-resource-collection>
<auth-constraint/>
</security-constraint>
</PRE></small>
</blockquote>
<LI> A security constraint with an auth constraint with a role of "*" gives access
to all authenticated users:
<blockquote>
<small><PRE>
<security-constraint>
<web-resource-collection>
<web-resource-name>Any User</web-resource-name>
<url-pattern>/auth/*</url-pattern>
</web-resource-collection>
<auth-constraint>
<role-name>*</role-name>
</auth-constraint>
</security-constraint>
</PRE></small>
</blockquote>
<LI>A security-constraint with no auth-constraint and no data contrain gives access
to any request:
<blockquote>
<small><PRE>
<security-constraint>
<web-resource-collection>
<web-resource-name>Relax</web-resource-name>
<url-pattern>/auth/relax/*</url-pattern>
</web-resource-collection>
</security-constraint>
</PRE></small>
</blockquote>
<LI> On platforms without the / file separator or when the system parameter
org.mortbay.util.FileResource.checkAliases is true, then the FileResouce class
compares the absolutePath and canonicalPath and treats the resource as not found
if they do not match. THIS means that win32 platforms need to exactly match
the case of drive letters and filenames.
<LI> Dynamic servlets by default, can only be loaded from the context classpath.
Use ServletHandler.setServeDynamicSystemServlets to control this behaivour.
</UL>
<BR><big><b>Security Recommendation</b></big><br>
<br>
It is strongly recommended that secure WebApplications take following
approach. All access should be denied by default with
<blockquote>
<small><PRE>
<security-constraint>
<web-resource-collection>
<web-resource-name>Default</web-resource-name>
<url-pattern>/</url-pattern>
</web-resource-collection>
<auth-constraint/>
</security-constraint>
</PRE></small>
</blockquote>
Specific access should then be granted with constraints like:
<blockquote>
<small><PRE>
<security-constraint>
<web-resource-collection>
<url-pattern>/public/*</url-pattern>
<url-pattern>/images/*</url-pattern>
<http-method>GET</http-method>
<http-method>HEAD</http-method>
</web-resource-collection>
<web-resource-collection>
<url-pattern>/servlet/*</url-pattern>
<http-method>GET</http-method>
<http-method>HEAD</http-method>
<http-method>POST</http-method>
</web-resource-collection>
<auth-constraint>
<role-name>*</role-name>
</auth-constraint>
</security-constraint>
</PRE></small>
</blockquote>
<BR><big><b>Session Security</b></big><br>
<br>
Jetty uses the standard java.util.Random class to generate session IDs. This
may be insufficient for high security sites. The SessionManager instance can
be initialized with a more secure random number generator, such as java.security.SecureRandom
The Jetty configuration XML to do this to a webapplication is:
<blockquote>
<small><PRE>
<Call name="addWebApplication">
<Arg>/myapp/*</Arg>
<Arg><SystemProperty name="jetty.home"
default="."/>/demo/webapps/myapp</Arg>
<Call name="getServletHandler">
<Set name="sessionManager">
<New class="org.mortbay.jetty.servlet.HashSessionManager">
<Arg><New class="java.security.SecureRandom"/></Arg>
</New>
</Set>
</Call>
</Call>
</PRE></small>
</blockquote>
Note: initialising the SecureRandom object is a one-off time consuming
operation which may cause the initial request to take much longer.
<table cellpadding="0" cellspacing="8" border="0" width="20%">
<tbody>
<tr>
<td valign="middle" bgcolor="#ccccff"><small><a href="HttpServer.html">
BACK</a></small></td>
<td valign="middle" bgcolor="#ccccff"><small><a href="index.html">
INDEX</a></small></td>
<td valign="middle" bgcolor="#ccccff"><small><a href="..">
EXIT</a></small></td>
<td valign="middle" bgcolor="#ccccff"><small><a href="logging.html">
NEXT</a></small></td>
</tr>
</tbody>
</table>
</body>
</html>
