Contact the core Jetty developers at www.webtide.com
private support for your internal/customer projects ... custom extensions and distributions ... versioned snapshots for indefinite support ... scalability guidance for your apps and Ajax/Comet projects ... development services from 1 day to full product delivery

Chapter 16. Embedding

Table of Contents

Embedding Jetty
Jetty HelloWorld
Configuring the Jetty Overlay Deployer

Embedding Jetty

Jetty has a slogan, "Don't deploy your application in Jetty, deploy Jetty in your application." What this means is that as an alternative to bundling your application as a standard WAR to be deployed in Jetty, Jetty is designed to be a software component that can be instantiated and used in a Java program just like any POJO. Put another way, running Jetty in embedded mode means putting an HTTP module into your application, rather than putting your application into an HTTP server.

This tutorial takes you step-by-step from the simplest Jetty server instantiation to running multiple web applications with standards-based deployment descriptors. The source for most of these examples is part of the standard Jetty project.

This tutorial is also available as a Embedding Jetty Webinar recording.

Overview

To embed a Jetty server, the following steps are typical.

  1. Creating the Server

    The following code from SimplestServer.java instantiates and runs the simplest possible Jetty server:

    package org.eclipse.jetty.embedded;
    
    import org.eclipse.jetty.server.Server;
    
    /** The simplest possible Jetty server.
     */
    public class SimplestServer {
    
        public static void main(String[] args) throws Exception {
            Server server = new Server(8080);
            server.start();
            server.join();
        }
    }
    

    This runs an HTTP server on port 8080. It is not a very useful server as it has no handlers and thus returns a 404 error for every request.

  2. Writing Handlers

    To produce a response to a request, Jetty requires a Handler to be set on the server. A handler may:

    • Examine/modify the HTTP request.
    • Generate the complete HTTP response.
    • Call another Handler (see HandlerWrapper).
    • Select one or many Handlers to call (see HandlerCollection).
    Hello World Handler

    The following code based on HelloHandler.java shows a simple hello world handler:

    package org.eclipse.jetty.embedded;
    
    import java.io.IOException;
    import javax.servlet.ServletException;
    import javax.servlet.http.HttpServletRequest;
    import javax.servlet.http.HttpServletResponse;
    import org.eclipse.jetty.server.Request;
    import org.eclipse.jetty.server.handler.AbstractHandler;
    
    public class HelloHandler extends AbstractHandler {
    
        final String _greeting;
    
        final String _body;
    
        public HelloHandler() {
            _greeting = "Hello World";
            _body = null;
        }
    
        public HelloHandler(String greeting) {
            _greeting = greeting;
            _body = null;
        }
    
        public HelloHandler(String greeting, String body) {
            _greeting = greeting;
            _body = body;
        }
    
        public void handle(String target, Request baseRequest, HttpServletRequest request, HttpServletResponse response) throws IOException, ServletException {
            response.setContentType("text/html;charset=utf-8");
            response.setStatus(HttpServletResponse.SC_OK);
            baseRequest.setHandled(true);
            response.getWriter().println("<h1>" + _greeting + "</h1>");
            if (_body != null) response.getWriter().println(_body);
        }
    }
    

    The parameters passed to the handle method are:

    • target - the target of the request, which is either a URI or a name from a named dispatcher.
    • baseRequest - the Jetty mutable request object, which is always unwrapped.
    • request - the immutable request object, which might have been wrapped.
    • response - the response, which might have been wrapped.

    The handler sets the response status, content-type and marks the request as handled before it generates the body of the response using a writer.

    The following code from OneHandler.java shows how a Jetty server can use this handler:

    public static void main(String[] args) throws Exception {
        Server server = new Server(8080);
        server.setHandler(new HelloHandler());
        server.start();
        server.join();
    }

    You now know everything you need to know to write an HTTP server based on Jetty. However, complex request handling is typically built from multiple Handlers. We will look in later sections at how you can combine handlers like aspects. You can see some of the handlers available in Jetty in the org.eclipse.jetty.server.handler package.

See an error or something missing?
Contribute to this documentation at Github!