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.
To embed a Jetty server, the following steps are typical.
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.
Writing Handlers
To produce a response to a request, Jetty requires a Handler to be set on the server. A handler may:
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:
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.