Question

This part of the Jetty tutorial covers basic administration and configuration of Jetty.

First, we need to have set the basic Jetty environment variables. The environment variables are set in the system-wide /etc/environment > file or user's .profile or .bashrc (for Bash shell) files.

$ echo $JETTY_HOME
/home/janbodnar/bin/jetty
$ echo $JETTY_BASE
/home/janbodnar/prog/jetty/my-base

We can now refer to Jetty home and Jetty base using these two variables in our commands.

Jetty base

Jetty base is our customised Jetty environment, where we place our own configuration files, logs, and where we have the deployment directory. The deployment directory's default name is webapps .

To create a Jetty base, we create a new directory and enable necessary modules with the start.jar command. Jetty is then started from this directory. Alternatively, we specify jetty.base property as a command line option.

$ cd $JETTY_BASE
$ java -jar $JETTY_HOME/start.jar

These two commands start Jetty from the Jetty base directory. Jetty automatically loads configuration files located in the directory—the start.ini file, and optionally, files located in resources , modules , and etc subdirectories.

$ java -jar $JETTY_HOME/start.jar jetty.base=$JETTY_BASE

If we are not located in the Jetty base directory, we can enable Jetty base environment by specifying the jetty.base command line option.

The start.jar command

The start.jar tool, located in Jetty home, is used to start Jetty, provide information, and perform some configuration settings.

$ java -jar $JETTY_HOME/start.jar --help

The --help option prints the current list of command line options and some basic usage help.

$ ls -l $JETTY_BASE
total 0
$ cd $JETTY_BASE
$ java -jar $JETTY_HOME/start.jar --add-to-start=deploy,http
INFO: deploy      initialised in ${jetty.base}/start.ini (appended)
MKDIR: ${jetty.base}/webapps
INFO: webapp      initialised transitively
INFO: servlet     initialised transitively
INFO: security    initialised transitively
INFO: server      initialised transitively
INFO: http      initialised in ${jetty.base}/start.ini (appended)
INFO: server      initialised transitively
$ ls
start.ini  webapps

Jetty is a highly modular system. The --add-to-start option enables Jetty modules by appending them to the ${jetty.base}/start.ini file. The command enabled the deploy and HTTP modules, and also modules on which they depend. The command also created the start.ini file and the webapps deployment directory. The start.ini file is loaded by Jetty at startup time.

$ 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]
...

Here we see a partial output of the --list-modules option. It lists all available Jetty modules—active and inactive.

$ 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

The --list-config option lists configuration settings including Java and Jetty environments, JVM arguments, properties, Server classpath, and XML configuration files. The partial output shows active XML configuration files loaded by Jetty.

The deployment directory

The deployment directory is a directory where we deploy our WAR files. The default name of the directory is webapps. The directory is located in Jetty home and Jetty base directories.

...
<Set name="monitoredDirName"><Property name="jetty.base" default="." />/
<Property name="jetty.deploy.monitoredDirName" default="webapps"/></Set>
...

The default deployment directory's name is specified in the $JETTY_HOME/etc/jetty-deploy.xml file.

$ java -jar $JETTY_HOME/start.jar jetty.deploy.monitoredDirName=webapps2

We can set the property value on the command line.

$ cat start.ini 
#
# Initialize module deploy
#
--module=deploy
## DeployManager configuration
# Monitored Directory name (relative to jetty.base)
jetty.deploy.monitoredDirName=webapps3

Another possibility is to set the deployment directory name inside the start.ini file's deploy module section.

$ cat myjetty.properties 
jetty.deploy.monitoredDirName=webapps4
$ java -jar $JETTY_HOME/start.jar myjetty.properties 

The deployment directory can be set in a properties file, which is passed to the start.jar tool.

We have shown four places where the deployment directory can be set. If there is a conflict, the value is taken from the option with the highest order. The order is the following: ( a ) the Java property file; ( b ) the command line option; ( c ) the Jetty base start.ini file; and ( d ) the jetty-deploy.xml file located in Java home's etc directory.

Jetty XML files

Jetty can be configured with XML configuration files. The jetty.xml is a default Jetty configuration file. It configures the server class, the ThreadPool, the connectors, the handler structure, the deployment manager, the login service, and the request log. The jetty-web.xml is a Jetty configuration file that can be bundled with a specific web application. The jetty-env.xml is an optional Jetty configuration file that arranges JNDI resources for an individual web application. The webdefault.xml configuration file is applied to a web application before its own web.xml file. It is used to save a web application from having to define a lot of house-keeping and container-specific elements in their own web.xml files. The override-web.xml is a web application configuration file that is applied after the application's own web.xml file.

Application context

A context path is a part of a URL path that is used to select the web application to which an incoming request is routed. The context path can be set with a method call (in embedded Jetty), derived from the name of the WAR file, specified in the deployer XML file or in the jetty-web.xml . The next example will use the jetty-web.xml file to set the application's context path. The file is located inside the WEB-INF directory.

$ tree
.
├── build.xml
└── src
  ├── com
  │   └── zetcode
  └── web
    ├── index.html
    └── WEB-INF
      └── jetty-web.xml

5 directories, 3 files

We list the directory structure of the project.

index.html

<!DOCTYPE html>
<html> 
<body>

Simple page.

</body> 
</html>

This is a simple HTML file.

jetty-web.xml

<?xml version="1.0"  encoding="ISO-8859-1"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" 
  "http://www.eclipse.org/jetty/configure.dtd">
 
<Configure class="org.eclipse.jetty.webapp.WebAppContext">
  <Set name="contextPath">/myapp</Set>  
  <Get class="org.eclipse.jetty.util.log.Log" name="rootLogger">
  <Call name="warn"><Arg>Web application is deployed</Arg></Call>
  </Get>  
</Configure>

In the jetty-web.xml file, we set the context to /myapp . We also log a message upon deployment.

build.xml

<?xml version="1.0" encoding="UTF-8"?>

<project name="AppContext" default="archive">
  
  <property name="name" value="appcontext"/>
  <property environment="env"/>
  <property name="src.dir" value="src"/>
  <property name="web.dir" value="${src.dir}/web"/>
  <property name="dist.dir" location="dist"/>
  <property name="deploy.path" location="${env.JETTY_BASE}/webapps"/>
  
  <target name="init">
    <mkdir dir="${dist.dir}"/>
  </target>   
  
  <target name="archive">
    <war destfile="${dist.dir}/${name}.war" needxmlfile="false">
      <fileset dir="${web.dir}"/>
    </war>
    <echo>Archive created</echo>
  </target> 
  
  <target name="clean" depends="init">
    <delete dir="${dist.dir}"/>
    <echo>Cleaning completed</echo>
  </target>  
  
  <target name="deploy" depends="archive">
    <copy file="${dist.dir}/${name}.war" overwrite="true" 
      todir="${deploy.path}"/>
    <echo>Archive deployed</echo>
  </target>  
  
</project>

This is Ant build file.

<property environment="env"/>

The environment atttribute sets the prefix to use OS environment variables.

<property name="deploy.path" location="${env.JETTY_BASE}/webapps"/>

We use the JETTY_BASE environment variable to define the deployment path.

$ curl localhost:8080/myapp/
<!DOCTYPE html>
<html> 
<body>
Simple page.
</body> 
</html>

We connect to the web application using the selected context path. If we have not specified the context file explicitly, it would be derived from the WAR file name, which is given in the third line of the build.xml file.

Deployment descriptor

Deployment descriptors are XML files used to deploy web applications. The name of the XML file must match the name of the WAR file. If both WAR file and XML file are present in the deployment directory, the XML file is used for the deployment.

We use the previous example code.

appcontext.xml

<?xml version="1.0"  encoding="ISO-8859-1"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" 
  "http://www.eclipse.org/jetty/configure_9_0.dtd">

<Configure class="org.eclipse.jetty.webapp.WebAppContext">
  <Set name="contextPath">/myapp2</Set>
  <Set name="war">/home/janbodnar/prog/jetty/appcontext/dist/appcontext.war</Set>
</Configure>

Inside the deployment descriptor, we set the context path and specify the WAR file using an absolute location path.

jetty-web.xml

<?xml version="1.0"  encoding="ISO-8859-1"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" 
  "http://www.eclipse.org/jetty/configure.dtd">
 
<Configure class="org.eclipse.jetty.webapp.WebAppContext">
<!--   <Set name="contextPath">/myapp</Set>   -->
  <Get class="org.eclipse.jetty.util.log.Log" name="rootLogger">
  <Call name="warn"><Arg>Web application is deployed</Arg></Call>
  </Get>  
</Configure>

The jetty-web.xml is called after all other configuration has been applied to the web application. Therefore, we comment the line specifying the context path.

$ curl localhost:8080/myapp2/
<!DOCTYPE html>
<html> 
<body>
Simple page.
</body> 
</html>

The modified context path works.

In this chapter, we have showed some basic administration of the Jetty server.