HttpListener --> HttpServer --> HandlerContext --> HttpHandlerA simple example of this to have single SocketListener listening for normal HTTP requests and a ResourceHandler serving static content:
SocketListener --> HttpServer --> HandlerContext --> ResourceHandler port: 80 "/" "./docroot"HTTP Listeners
Multiple listeners may be used to listen on different ports or specific IP addresses. This is most frequently used for SSL or multi-hosting:
SocketListener -+> HttpServer --> HandlerContext --> ResourceHandler port: 80 | "/" "./docroot" JSSEListener -+ port: 443 | SocketListener -+ host: 1.2.3.4 port: 80Listeners are configured via set methods. Listeners can be created by using the HttpServer as a factory to create a standard type of listener:
HttpServer server = new HttpServer(); HttpListener listener = server.addListener(new InetAddrPort("myhost",8080));However, in order to provide detailed configuration, it is more common to create the listener directly and then add it to the HttpServer:
HttpServer server = new HttpServer(); SocketListener listener = new SocketListener(); listener.setHost("myhost"); listener.setPort(8080); listener.setMinThreads(5); listener.setMaxThreads(250); server.addListener(listener);Note that HttpListeners are responsible for allocating threads to requests, so most implementations are extensions of the org.mortbay.util.ThreadedServer or org.mortbay.util.ThreadPool. Thus attributes such as min/max threads, min/max idle times etc are set via the listeners API. As usual, the configurations above can also be express in XML:
<Call name="addListener"> <Arg> <New class="org.mortbay.http.SocketListener"> <Set name="Port">8080</Set> <Set name="MinThreads">5</Set> <Set name="MaxThreads">255</Set> </New> </Arg> </Call>
Handler Contexts
A org.mortbay.http.HandlerContext is a collection of
org.mortbay.http.HttpHandler implementations, which are tried in turn until a request is handled. Typically a context might have a security, servlet and resource handler:
SocketListener --> HttpServer --> HandlerContext +-> SecurityHandler port: 80 "/" | +-> ServletHandler | +-> ResourceHandlerHttpHandlers within a HandlerContext share the following attributes:
SocketListener --> HttpServer +-> HandlerContext --> HttpHandler(s) port: 80 | path: /contextpath1/* +-> HandlerContext --> HttpHandler(s) path: /contextpath2/*Or virtual hosts:
SocketListener --> HttpServer +-> HandlerContext --> HttpHandler(s) port: 80 | host: www.acme.com | path: / +-> HandlerContext --> HttpHandler(s) host: www.myacme.org path: /If multiple contexts are to be served from the same port, but on different IP addresses, then each context may be given its own HttpServer:
SocketListener --> HttpServer --> HandlerContext --> HttpHandler(s) host: www.acme.com path: / port: 80 SocketListener --> HttpServer --> HandlerContext --> HttpHandler(s) host: www.myacme.org path: / port: 80The HttpServer is used as a factory to create HandlerContext instances for a specific context path:
HandlerContext context = server.addContext("/context/*"); context.setResourceBase("./docroot/");Or for a specific virtual host and context path:
HandlerContext context = server.addContext("myhost","/context/*"); context.setResourceBase("./docroot/");A handler context may be registered with multiple virtual hosts, but only a single context path:
HandlerContext context = server.addContext("myhost1","/context/*"); context.setResourceBase("./docroot/"); server.addContext("myhost2",context);Virtual hosts may have several aliases registered:
HandlerContext context = server.addContext("myhost","/context/*"); server.addHostAlias("myhost","myhost.com"); server.addHostAlias("myhost","www.myhost.com"); server.addHostAlias("myhost","1.2.3.4");Each call to
addContext()
will create new HandlerContext instance. Multiple contexts can exist for the
same contextPath and they are tried in the order they were added until the request is handled. If you wish to avoid
the possibility of creating multiple contexts, the getContext
can be used to get an existing context or
to create one if one does not exist:
HandlerContext context = server.getContext("myhost","/context/*"); context.setResourceBase("./docroot/");Derivations of HttpServer may implement the
newHandlerContext()
method to change the factory method for creating new Contexts. This is used by the org.mortbay.jetty.Server class to return
HandlerContext derivations that have conveniance methods for configuring servlets.
The org.mortbay.jetty.servlet.WebApplicationContext class is a specialization of HandlerContext that configures the handlers by looking at the standard web application files and layout.
HTTP Handlers
The org.mortbay.http.HttpHandler interface represents Jetty's core unit of content generation or manipulation. Implementations of this interface can be used to modify or handle requests. Typically handlers are arranged in a list, and a request presented to each handler in turn until the one indicates that the request has been handled. This allows handlers to:
HttpHandlers are tried within a context in the order they were added to the HandlerContext. The following code creates a context that checks authentication, then tries a servlet mapping before finally trying static content:
HandlerContext context = server.addContext("/"); context.add(new SecurityHandler()); context.add(new ServletHandler()); context.add(new ResourceHandler()); context.add(new NotFoundHandler());
Resource Handler
The org.mortbay.http.handler.ResourceHandler implementation of HttpHandler is used to server static content from a base directory or URL. Its features include:
HandlerContext context = server.addContext("myhost","/context/*"); context.setResourceBase("./docroot/"); context.add(new ResourceHandler());As this is a frequent configuration option, a conveniance setServingResources method is provided that creates the ResourceHandler:
HandlerContext context = server.addContext("myhost","/context/*"); context.setResourceBase("./docroot/"); context.setServingResources(true);To configure the ResourceHandler in detail, it is best to construct it directly and add it to the context:
ResourceHandler handler = new ResourceHandler(); handler.setDirAllowed(true); handler.setPutAllowed(false); handler.setDelAllowed(false); handler.setAcceptRanges(true); handler.addIndexFile("index.html"); handler.setMaxCachedFiles(200); handler.setMaxCachedFileSize(32000); context.addHandler(handler);The same configuration can be done in XML:
<Call name="addHandler"> <Arg> <New class="org.mortbay.http.handler.ResourceHandler"> <Set name="dirAllowed">true</Set> <Set name="putAllowed">false</Set> <Set name="delAllowed">false</Set> <Set name="acceptRanges">true</Set> <Call name="addIndexFile"><Arg>index.html</Arg></Call> <Set name="maxCachedFiles">200</Set> <Set name="maxCachedFileSize">32000</Set> </New> </Arg> </Call>Back Index Exit Next