HTTP Server Tutorial      Back Index Exit Next

The org.mortbay.http.HttpServer class provides a connection between a collection of request listeners and collections of request handlers:
  HttpListener --> HttpServer --> HandlerContext --> HttpHandler
A 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
Implementations of the org.mortbay.http.HttpListener interface are added to a HttpServer and act as sources of requests for the server. org.mortbay.http.SocketListener is the main implementation that listens of a standard TCP/IP port for request, but there are also implementation for SSL, Non blocking IO, testing and others.

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: 80                              
Listeners 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
                                                   |
                                                   +-> ResourceHandler
HttpHandlers within a HandlerContext share the following attributes: Multiple contexts are typically used to server several applications from the same port(s) using URL mappings:
  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: 80                              
The 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:

The handlers provided in the org.mortbay.http.handler package are: Note that a ServletHandler is provided by the org.mortbay.jetty.servlet package and is discussed in detail later in this tutorial.

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:

The root directory or URL for serving static content is the ResourceBase of the HandlerContext. Thus to server static content from the directory "./docroot/":
    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