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
The Jetty Maven plugin is useful for rapid development and testing. You can add it to any webapp project that is structured according to the usual Maven defaults. The plugin can then periodically scan your project for changes and automatically redeploy the webapp if any are found. This makes the development cycle more productive by eliminating the build and deploy steps: you use your IDE to make changes to the project, and the running web container automatically picks them up, allowing you to test them straight away.
You need to use Maven 3 and Java 1.7 for this plugin.
jetty-maven-plugin to your
Then, from the same directory as your root
This starts Jetty and serves up your project on http://localhost:8080/.
Jetty continues to run until you stop it. While it runs, it periodically scans for changes to your project files, so if you save changes and recompile your class files, Jetty redeploys your webapp, and you can instantly test the changes you just made.
You can terminate the plugin with a
ctrl-c in the
terminal window where it is running.
The Jetty Maven plugin has a number of distinct Maven goals.
Arguably the most useful is the
run goal that we saw in the
Quick Start section which runs Jetty on your unassembled webapp. There are
other goals which help you accomplish different tasks. For example, you
might need to run your webapp in a forked instance of Jetty, rather than
within the process running Maven; or you may need finer grained control
over the maven lifecycle stage in which you wish to deploy your webapp.
There are different goals to accomplish these tasks, as well as several
To see a list of all goals supported by the Jetty Maven plugin, do:
To see the detailed list of parameters that can be configured for a particular goal, in addition to its description, do:
mvn jetty:help -Ddetail=true -Dgoal= goal-name
These configuration elements set up the Jetty environment in which your webapp executes. They are common to most goals:
Optional. If not specified, Jetty will create a ServerConnector
instance listening on port 8080. You can change this default port
number by using the system property
jetty.port on the
command line, for example,
jetty:run. Alternatively, you can use this configuration
element to set up the information for the ServerConnector. The
following are the valid configuration sub-elements:
The port number for the connector to listen on. By default it is 8080.
The particular interface for the connector to listen on. By default, all interfaces.
The name of the connector, which is useful for configuring contexts to respond only on particular connectors.
Maximum idle time for a connection.
The socket linger time.
You could instead configure the connectors in a standard jetty xml config file and put its
location into the
jettyXml parameter. Note that since
jetty-9.0 it is no longer possible to configure a https connector directly in the
pom.xml: you need to use jetty
xml config files to do it.
Optional. A comma separated list of locations of
jetty xml files
to apply in addition to any plugin configuration parameters. You
might use it if you have other webapps, handlers, specific types of
connectors etc., to deploy, or if you have other Jetty objects that
you cannot configure from the plugin.
The pause in seconds between sweeps of the webapp to check for changes and automatically hot redeploy if any are detected. By default this is 0, which disables hot deployment scanning. A number greater than 0 enables it.
Default value is "automatic", used in conjunction with a
automatic hot redeploy when changes are detected. Set to "manual"
instead to trigger scanning by typing a linefeed in the console
running the plugin. This might be useful when you are doing a series
of changes that you want to ignore until you're done. In that use,
Optional. A list of
implementations. Note that there is no default realm. If you use a
realm in your
web.xml you can specify a
corresponding realm here. You could instead configure the login
services in a jetty xml file and add its location to the
Optional. An implementation of the
request log interface. An implementation that respects the NCSA
format is available as
org.eclipse.jetty.server.NCSARequestLog. There are three
other ways to configure the RequestLog:
In a jetty xml config file, as specified in the
In a context xml config file, as specified in the
See Configuring Request
Logs for more information.
Optional. Used in conjunction with stopPort for stopping jetty. Useful when used in conjunction with the stop or run-forked goals.
Optional.Allows you to configure System properties for the execution of the plugin. For more information, see Setting System Properties.
Optional. A file containing System properties to set for the
execution of the plugin. By default, settings that you make here
do not override any system
properties already set on the command line, by the JVM, or in the
systemProperties. Read Setting System Properties for how to
Default is false. If true, the execution of the plugin exits.
Same as setting the SystemProperty
-Djetty.skip on the
command line. This is most useful when configuring Jetty for
execution during integration testing and you want to skip the
Default value is
false. If true, the dependencies
<scope>provided</scope> are placed
onto the container classpath. Be aware that
this is NOT the webapp classpath, as "provided" indicates that these
dependencies would normally be expected to be provided by the
container. You should very rarely ever need to use this. Instead,
you should copy the provided dependencies as explicit dependencies
Optional. A list of jetty plugin goal names that will cause the plugin to print an informative message and exit. Useful if you want to prevent users from executing goals that you know cannot work with your project.
In order to configure a https connector, you need to use jetty xml configuration files. This example uses files copied directly from the jetty distribution etc/ directory, although you can of course make up your own xml file or files. We will use the following files:
Sets up various characteristics of the
instance for the plugin to use. Importantly, it sets up the
element that we can refer to in subsequent xml files that
configure the connectors. Here's the relevant section:
Set up ssl which will be used by the https connector. Here's
jetty-ssl.xml file from the
Set up the https connector using the HttpConfiguration from
jetty.xml and the ssl configuration
Now you need to let the plugin know to apply the files above:
Just like with an installed distribution of Jetty, the ordering of the xml files is significant.
You can also use jetty xml files to configure a http connector for
the plugin to use. Here we use the same
jetty-http.xml file from the Jetty
Now we add it to the list of configs for the plugin to apply:
Alternatively, you can use the httpConnector configuration element inside the pom instead as described above.
These configuration parameters apply to your webapp. They are common to almost all goals.
Represents an extension to the class
You can use any of the setter methods on this object to configure
your webapp. Here are a few of the most useful ones:
The context path for your webapp. By default, this is
The path to the
web.xml file for
The path to a
that will be applied to your webapp before the
web.xml. If you don't supply one, Jetty
uses a default file baked into the
The path to a
web.xml file that
Jetty applies after reading your
web.xml. You can use this to replace or add
The path to a dir that Jetty can use to expand or copy
jars and jsp compiles when your webapp is running. The default
The path from which Jetty serves static resources.
Use instead of
baseResource if you
have multiple dirs from which you want to serve static
content. This is an array of dir names.
Defaults to "true". Controls whether any overlaid wars are added before or after the original base resource(s) of the webapp. See the section on overlaid wars for more information.
The path to a context xml file that is applied to your webapp
run goal runs on a webapp that does not have to be
built into a WAR. Instead, Jetty deploys the webapp from its sources. It
looks for the constituent parts of a webapp in the Maven default project
locations, although you can override these in the plugin configuration.
For example, by default it looks for:
The plugin automatically ensures the classes are rebuilt and up-to-date before deployment. If you change the source of a class and your IDE automatically compiles it in the background, the plugin picks up the changed class.
You do not need to assemble the webapp into a WAR, saving time during the development cycle. Once invoked, you can configure the plugin to run continuously, scanning for changes in the project and automatically performing a hot redeploy when necessary. Any changes you make are immediately reflected in the running instance of Jetty, letting you quickly jump from coding to testing, rather than going through the cycle of: code, compile, reassemble, redeploy, test.
Here is a small example, which turns on scanning for changes every ten seconds, and sets the webapp context path to "/test":
In addition to the
element that is common to most goals, the
jetty:run goal supports:
Location of your compiled classes for the webapp. You should
rarely need to set this parameter. Instead, you should set
build outputDirectory in your
Location of the compiled test classes for your webapp. By
default this is
If true, the classes from
and dependencies of scope "test" are placed first on the
classpath. By default this is false.
By default, this is set to
/Users/jesse/docsync/jetty-documentation/src/main/webapp. If your static
sources are in a different location, set this parameter
Optional. Location of a
file, which allows you to make JNDI bindings that satisfy
resource-ref linkages in the
that are scoped only to the webapp and not shared with other
webapps that you might be deploying at the same time (for example,
by using a
Optional. A list of files and directories to periodically scan in addition to those the plugin automatically scans.
Optional. If you have a long list of extra files you want
scanned, it is more convenient to use pattern matching expressions
to specify them instead of enumerating them with the
consisting of a directory, and including and/or excluding
parameters to specify the file matching patterns.
Here's an example:
If, for whatever reason, you cannot run on an unassembled webapp,
run-exploded work on
This goal first packages your webapp as a WAR file and then deploys
it to Jetty. If you set a non-zero
pom.xml and the WAR file; if either
changes, it redeploys the war.
The run-exploded goal first assembles your webapp into an exploded
WAR file and then deploys it to Jetty. If you set a non-zero
scanInterval, Jetty watches your
WEB-INF/lib, WEB-INF/ classes and
WEB-INF/web.xml for changes and redeploys when
This is basically the same as
without assembling the WAR of the current module. Unlike
run-war, the phase in which this plugin executes is not bound
to the "package" phase. For example, you might want to start Jetty on the
"test-compile" phase and stop Jetty on the "test-phase".
This goal allows you to start the webapp in a new JVM, optionally passing arguments to that new JVM.
NOTE: unfortunately, unlike most of the other goals, this one does
NOT support a webApp parameter to
configure the webapp. Therefore, if your webapp requires a lot of
configuration, it will be difficult to switch between eg
The available configuration parameters are:
The locations of jetty xml configuration files used to configure the container in the new JVM.
Optional. The location of a context xml file to configure the webapp in the new JVM.
Optional. The context path for the webapp in the new JVM.
Overrides a setting inside a
Optional. The location of the static resources for your
webapp. Defaults to
Set name="baseResource" setting inside a
Optional. An array of directories containing static content
that form the resource base for your webapp, in conjunction with
webAppSourceDirectory. See also
Defaults to "true". Controls whether the
resourceBases are first on the list of resources that
form the base resource for the webapp.
The location of the
Set name="descriptor" inside a
Temporary directory to use for the webapp. Defaults to
The location of the compiled classes for the webapp.
The location of the compiled test classes for the webapp.
–Defaults to "false". If true, the test classes and
placed on the webapp's classpath.
Defaults to "false". If true, the dependencies of scope "provided" are placed on the jetty container's classpath.
Mandatory. A port number for jetty to listen on to receive a stop command to cause it to shutdown. If configured, the stopKey is used to authenticate an incoming stop command.
Mandatory. A string value that has to be sent to the
stopPort to authenticate the stop command.
Optional. Defaults to false. If true, the execution of this plugin is skipped.
Optional. A string representing arbitrary arguments to pass to the forked JVM.
To deploy your unassembled web app to Jetty running in a new JVM:
Jetty continues to execute until you either:
cntrl-c in the terminal window to stop the
plugin, which also stops the forked JVM.
Use jetty:stop to stop the forked JVM, which also stops the plugin.
If you want to set a custom port, you need to specify it in a
jetty.xml file rather than setting the connector
and port tags. You can specify the location of the
jetty.xml using the
This goal is for use with an execution binding in your
pom.xml. It is similar to the
goal, however it does NOT first execute the build up until the
"test-compile" phase to ensure that all necessary classes and files of the
webapp have been generated. This is most useful when you want to control
the start and stop of Jetty via execution bindings in your
For example, you can configure the plugin to start your webapp at
the beginning of your unit tests and stop at the end. To do this, you need
to set up a couple of
execution scenarios for the Jetty
plugin and use the
configuration option to force Jetty to execute only while Maven is
running, instead of running indefinitely. You use the
Maven build phases to trigger the execution and termination of
Of course, you can use this goal from the command line (
jetty:start), however you need to be sure that all generated
classes and files for your webapp are already present first.
The stop goal stops a running instance of jetty. To use it, you need
to configure the plugin with a special port number and key. That same port
number and key will also be used by the
A port number for jetty to listen on to receive a stop command to cause it to shutdown.
A string value sent to the
stopPort to validate
the stop command.
The maximum time in seconds that the plugin will wait for confirmation that jetty has stopped. If false or not specified, the plugin does not wait for confirmation but exits after issuing the stop command. This parameter is available only since jetty-9.5.
Here's a configuration example:
Then, while Jetty is running (in another window), type:
stopPort must be free on the machine you are
running on. If this is not the case, you get an "Address already in use"
error message after the "Started SelectedChannelConnector ..."
If your webapp depends on other war files, thejetty:run and jetty:run-forked goals are able to merge resources from all of them. It can do so based on the settings of the maven-war-plugin, or if your project does not use the maven-war-plugin to handle the overlays, it can fall back to a simple algorithm to determine the ordering of resources.
The maven-war-plugin has a rich set of capabilities for merging resources. The jetty:run and jetty:run-forked goals are able to interpret most of them and apply them during execution of your unassembled webapp. This is probably best seen by looking at a concrete example.
Suppose your webapp depends on the following wars:
They are configured for the maven-war-plugin:
Then executing jetty:run would yield the following
ordering of resources:
com.acme.X.war : com.acme.Y.war:
/Users/jesse/docsync/jetty-documentation/src/main/webapp. Note that the current
project's resources are placed last in the ordering due to the empty
<overlay/> element in the maven-war-plugin. You can either use
that, or specify the
<baseAppFirst>false</baseAppFirst> parameter to
Moreover, due to the
exclusions specified above, a
request for the resource
bar.jsp would only be satisfied
com.acme.Y.war. Similarly as
excluded, a request for it would result in a 404 error.
The algorithm is fairly simple, is based on the ordering of
declaration of the dependent wars, and does not support exclusions. The
<baseAppFirst> (see the
section on Configuring Your
Webapp for more information) can be used to control whether your
webapp's resources are placed first or last on the resource path at
For example, suppose our webapp depends on these two wars:
Suppose the webapps contain:
Then our webapp has available these additional resources:
You can configure LoginServices in the plugin. Here's an example of setting up the HashLoginService for a webapp:
If you have external resources that you want to incorporate in the execution of a webapp, but which are not assembled into WARs, you can't use the overlaid wars method described above, but you can tell Jetty the directories in which these external resources are located. At runtime, when Jetty receives a request for a resource, it searches all the locations to retrieve the resource. It's a lot like the overlaid war situation, but without the war. Here's a configuration example:
You can use either a
jetty.xml file to
configure extra (pre-compiled) webapps that you want to deploy, or you can
<contextHandlers> configuration element to do
so. If you want to deploy webapp A, and webapps B and C in the same Jetty
Putting the configuration in webapp A's
Alternatively, add a
jetty.xml file to webapp
A. Copy the
jetty.xml file from the jetty
distribution, and then add WebAppContexts for the other 2 webapps:
Then configure the location of this
file into webapp A's jetty plugin:
For either of these solutions, the other webapps must already have been built, and they are not automatically monitored for changes. You can refer either to the packed WAR file of the pre-built webapps or to their expanded equivalents.
You can specify property name/value pairs that Jetty sets as System properties for the execution of the plugin. This feature is useful to tidy up the command line and save a lot of typing.
However, sometimes it is not possible to use this feature to set System properties - sometimes the software component using the System property is already initialized by the time that maven runs (in which case you will need to provide the System property on the command line), or by the time that jetty runs. In the latter case, you can use the maven properties plugin to define the system properties instead. Here's an example that configures the logback logging system as the jetty logger:
Note that if a System property is already set (for example, from the command line or by the JVM itself), then by default these configured properties DO NOT override them (see below for use of the <force> parameter).
Here's an example of how to specify System properties in the POM:
To change the default behaviour so that these system properties
override those on the command line, use the <
You can also specify your System properties in a file. System
properties you specify in this way DO NOT override System properties
that set on the command line, by the JVM, or directly in the POM
Suppose we have a file called
contains the following:
This can be configured on the plugin like so:
You can instead specify the file by setting the System property
jetty.systemPropertiesFile on the command