Introduction to Jetty

This is an introductory Jetty tutorial. The purpose of this tutorial is to get you started with Jetty. The tutorial has been created and tested on Linux. This tutorial covers Jetty version 9.

About Jetty

Jetty is an open source project providing an HTTP server, an HTTP client, and a Java servlet container. The project is a part of the Eclipse Foundation. Jetty is a mature project, which started in 1995. Jetty can be easily embedded in devices, tools, frameworks, application servers, and clusters.

Jetty also supports additional Java technologies including:

Installing Jetty

In this tutorial we work on a local computer. Detailed instructions to install Jetty on a remote server are provided in a separate chapter. First, we download Jetty from the Eclipse's download page to a directory of our choice.

$ tar xzvf jetty-distribution-9.2.2.v20140723.tar.gz 

We unpack the compressed file.

$ mv jetty-distribution-9.2.2.v20140723/ jetty-9.2.2/
$ cd jetty-9.2.2/

We rename the directory and move into it.

$ export JETTY_HOME=/home/janbodnar/bin/jetty-9.2.2

A Jetty home environment variable is created.

$ ls -F
bin/        lib/                        modules/     resources/  start.jar
demo-base/  license-eplv10-aslv20.html  notice.html  start.d/    VERSION.txt
etc/        logs/                       README.TXT   start.ini   webapps/

We list the contents of the directory. The bin directory contains utility scripts to help run Jetty on Unix systems. The lib directory contains all JAR files necessary to run Jetty. The modules directory has module definitions where a module is a configuration file that includes all the libraries, dependencies, XML and template INI files for a Jetty feature. The resources directory contains additional resources for the classpath. The start.jar is used to invoke Jetty.

The demo-base directory contains demo applications distributed with Jetty. The start.d directory contains INI files that contain arguments that are added to the command line. (For instance, the port number of the HTTP module on which Jetty listens.) The etc is a directory for Jetty XML configuration files. The logs is a directory for logs. The start.ini file contains arguments that are added during command line execution. Finally, the webapps directory contains web applications that run under the default configuration of Jetty. It is where we deploy our web archives.

Running Jetty

To run the Jetty server, we use the start.jar file.

$ pwd
/home/janbodnar/bin/jetty
$ java -jar start.jar 

We are inside the Jetty home directory. We run the server passing the start.jar file to the java command. The start.jar builds a classpath and executes a main java class with a classloader built from that classpath. It reads the contents of the start.ini file and the INI files found in the start.d directory. By default the start.jar mechanism is configured to start the Jetty server, but it can be configured to start any Java main class.

We can now navigate a browser at this server at http://localhost:8080.

$ curl localhost:8080
<HTML>
<HEAD>
<TITLE>Error 404 - Not Found</TITLE>
<BODY>
<H2>Error 404 - Not Found.</H2>
No context on this server matched or handled this request.
...

We use a command line tool curl to do the HTTP request. The server returns a 404 error—there is no application in the webapps directory yet. (Earlier versions included some demo applications in the webapps directory.) In order to start some demo applications, we relocate to the demo-base directory and start the server with the following command:

$ java -jar ../start.jar

Navigating the browser to the localhost at port 8080 shows a Jetty welcome page with several examples. The demo-base is an example of a Jetty base, which we cover later.

Shutting down Jetty

The Jetty server can be stopped by pressing Ctrl+C at the shell prompt or by killing its process.

It is possible to stop Jetty with the start.jar. Stopping this way must be enabled first.

$ java -jar start.jar STOP.PORT=8090 STOP.KEY=mypasswd 

When we start Jetty, we provide a password and a port number on which Jetty listens to stop command.

$ java -jar start.jar STOP.PORT=8090 STOP.KEY=mypasswd --stop

We append the --stop option to shut down the Jetty server.

Jetty home & base

Starting with Jetty 9.1, it is possible to maintain a separation between the binary installation of the standalone Jetty called Jetty home, and the customizations for a specific environment called Jetty base. Jetty home is the location for the Jetty distribution binaries, default XML configurations, and default module definitions. Jetty base is the location for configurations and customizations to the Jetty distribution.

$ mkdir my-base
$ cd my-base/

We create a my-base directory which will be our Jetty base.

$ export JETTY_BASE=/home/janbodnar/prog/jetty/my-base

A JETTY_BASE environment variable is created. Jetty determines the Jetty home and Jetty base locations either from environment variables or from properties.

Three important items of a Jetty base are the start.d configuration directory, the start.ini configuration file and the webapps directory. We use the start.jar to enable necessary modules of Jetty. The --add-to-start option enables a module by appending lines to the ${jetty.base}/start.ini file. The --add-to-startd enables a module via creation of a module-specific INI file in the ${jetty.base}/start.d/ directory.

$ java -jar $JETTY_HOME/start.jar --add-to-start=deploy

The start.ini file is created and the deploy module is added to it. Also the webapps directory is created.

$ java -jar $JETTY_HOME/start.jar --add-to-startd=http

The http module configuration named http.ini is created in the start.d directory.

$ tree
.
├── start.d
│   └── http.ini
├── start.ini
└── webapps

2 directories, 2 files

At this moment we have this content in our Jetty base directory. Actually, we have enabled more than two modules—modules may have dependent modules and these were enabled as well. For instance, by enabling the http module we have activated the server module as well.

$ java -jar $JETTY_HOME/start.jar --list-modules
...
Jetty Active Module Tree:
-------------------------
 + Module: server [enabled]
   + Module: http [enabled]
   + Module: security [enabled]
   + Module: servlet [enabled]
     + Module: webapp [enabled]
       + Module: deploy [enabled]

The --list-modules option list all modules, both active and inactive. At the end of the output we have a tree of active modules. So we have now five active modules. The http module enabled the server module and the deploy module activated the webapp module which in turn activated the servlet and security modules.

$ cat start.d/http.ini 
#
# Initialize module http
#
--module=http
## HTTP Connector Configuration
# HTTP port to listen on
jetty.port=8080
# HTTP idle timeout in milliseconds
http.timeout=30000
# HTTP Socket.soLingerTime in seconds. (-1 to disable)
# http.soLingerTime=-1

These are the contents of the http.ini file located in the start.d directory. There is a Jetty port configuration option. We change it to 8081.

$ pwd
/home/janbodnar/prog/jetty/my-base
$ java -jar $JETTY_HOME/start.jar

It is recommended to sit in the Jetty base directory and to start the server by referencing the start.jar remotely.

Jetty listening on port 8081
Figure: Jetty listening on port 8081

The server is running, but we have not deployed any web application and therefore the server returns the 404 error message.

First web application

We create and deploy our first web application with Jetty. The application will display a simple JSP page. We create a Jetty base from scratch to enable running JSP pages.

$ cd $JETTY_BASE
$ java -jar $JETTY_HOME/start.jar --add-to-start=http,deploy,jsp,jstl,annotations

These modules are needed for web application having JSP pages.

$ java -jar $JETTY_HOME/start.jar

The server is started.

Now we are going to create a simple web application.

$ cd ..
$ mkdir first
$ cd first
$ mkdir -p src/web/WEB-INF
$ touch src/web/index.jsp
$ touch build.xml

We create a welcome index.jsp page and the ANT build.xml file.

index.jsp
<!DOCTYPE html>
<html> 
<body>
<p>
   Today's date: <%= (new java.util.Date()).toLocaleString()%>
</p>
</body> 
</html>

The index.jsp page prints the current date in the localized form.

build.xml
<?xml version="1.0"?>

<project name="First" default="archive">
    
    <property name="name" value="first"/>
    <property name="dist.dir" location="dist"/>
    <property name="web.dir" location="src/web"/>
    <property name="jetty.base" location="/home/janbodnar/prog/jetty/my-base"/>
    <property name="deploy.path" location="${jetty.base}/webapps"/>
      
    <target name="init">
        <mkdir dir="${dist.dir}"/>
    </target>    
       
    <target name="archive" depends="init">
        <war destfile="${dist.dir}/${name}.war" needxmlfile="false">
            <fileset dir="${web.dir}"/>
        </war>
        <echo>Archive created</echo>
    </target> 
    
    <target name="deploy" depends="archive">
        <copy file="${dist.dir}/${name}.war" overwrite="true" 
              todir="${deploy.path}"/>
        <echo>Archive deployed</echo>
    </target>        
    
    <target name="clean" depends="init">
        <delete dir="${dist.dir}"/>
        <echo>Cleaning completed</echo>
    </target>  
    
</project>

This Ant build file has targets to create a build directory and distribution directory and to clean (delete) them. It creates a web archive (a WAR file) containing a single index.jsp file. The deploy target deploys the WAR file to the webapps directory of the Jetty base.

$ ant deploy
Buildfile: /home/janbodnar/prog/jetty/first/build.xml
init:
archive:
     [echo] Archive created
deploy:
     [copy] Copying 1 file to /home/janbodnar/prog/jetty/my-base/webapps
     [echo] Archive deployed
BUILD SUCCESSFUL
Total time: 0 seconds

We run Ant with the deploy task. A web archive is created and deployed.

$ curl localhost:8080/first/
<!DOCTYPE html>
<html> 
<body>
<p>
   Today's date: Sep 16, 2014 10:43:45 AM
</p>
</body> 
</html>

The web application's context is detemined from the name of the archive file: first.war. The application successfully returns the current date.

We have enabled a JSP module for our Jetty base but we have not explicitly configured the usage of JSP pages. (For instance in the web.xml file.) A default configuration is included by enabling the deploy module.

$ java -jar $JETTY_HOME/start.jar --list-config
...
Jetty Active XMLs:
------------------
 ${jetty.home}/etc/jetty.xml
 ${jetty.home}/etc/jetty-http.xml
 ${jetty.home}/etc/jetty-deploy.xml
 ${jetty.home}/etc/jetty-plus.xml
 ${jetty.home}/etc/jetty-annotations.xml

The --list-config option lists the configuration that will be used to start Jetty. At the end of the output, we have XML files that are loaded by the server. For each module an XML file is loaded. The jetty-deploy.xml is one of them.

<Set name="defaultsDescriptor"><Property name="jetty.home" 
    default="." />/etc/webdefault.xml</Set>

The jetty-deploy.xml has this line that loads the webdefault.xml configuration file, which contains the configuration of JSP pages.

<servlet id="jsp">
  <servlet-name>jsp</servlet-name>
  <servlet-class>org.apache.jasper.servlet.JspServlet</servlet-class>
...
</servlet>

This is an excerpt from the webdefault.xml file configuring the support of JSP pages.

Sources

Jetty's official reference guide was used to create this tutorial.

This chapter was an introduction to Jetty.