All development and stable releases are being performed with Jetty 9.
This wiki is now officially out of date and all content has been moved to the Jetty Documentation Hub
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.
For Jetty 9.x an onward, this wiki has been replaced with a docbook documentation, found at
http://www.eclipse.org/jetty/documentation/current/jetty-maven-plugin.htmlFirst, add jetty-maven-plugin to your pom.xml definition:
<plugin> <groupId>org.mortbay.jetty</groupId> <artifactId>jetty-maven-plugin</artifactId></plugin>
Then, from the same directory as your root pom.xml, simply type:
mvn jetty:run
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. Each goal is an action you can run to accomplish a specific task, or to work with a particular web application setup. You might need to insert goal-specific configuration to run it properly.
To run the jetty-maven-plugin with a particular goal, use this command:
mvn jetty:goalname
Here are the configuration elements that are common to all goals:
These configuration elements set up the Jetty environment in which your webapp executes.
These configuration parameters apply to your webapp. They should apply to all goals, except for run-forked and stop:
The run goal runs on a webapp that does not have to be built into a WAR. Instead, Jetty deploys the webapp from its constituent 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.
The webapp does not need to be assembled 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":
<plugin> <groupId>org.mortbay.jetty</groupId> <artifactId>jetty-maven-plugin</artifactId> <configuration> <scanIntervalSeconds>10</scanIntervalSeconds> <webApp> <contextPath>/test</contextPath> </webApp> </configuration></plugin>
In addition to the <webApp> element which is common to most goals, the jetty:run goal supports:
Here's an example:
<project> ... <plugins> ... <plugin> <groupId>org.mortbay.jetty</groupId> <artifactId>jetty-maven-plugin</artifactId> <configuration> <webAppSourceDirectory>${basedir}/src/staticfiles</webAppSourceDirectory> <webAppConfig> <contextPath>/</contextPath> <descriptor>${basedir}/src/over/here/web.xml</descriptor> <jettyEnvXml>${basedir}/src/over/here/jetty-env.xml</jettyEnvXml> </webAppConfig> <classesDirectory>${basedir}/somewhere/else</classesDirectory> <scanTargets> <scanTarget>src/mydir</scanTarget> <scanTarget>src/myfile.txt</scanTarget> </scanTargets> <scanTargetPatterns> <scanTargetPattern> <directory>src/other-resources</directory> <includes> <include>**/*.xml</include> <include>**/*.properties</include> </includes> <excludes> <exclude>**/myspecial.xml</exclude> <exclude>**/myspecial.properties</exclude> </excludes> </scanTargetPattern> </scanTargetPatterns> </configuration> </plugin> </plugins></project>
If, for whatever reason, you cannot run on an unassembled webapp, the goals run-war and run-exploded will work on unassembled webapps.
This goal first packages your webapp as a WAR file and then deploys it to Jetty. If you set a non-zero scanInterval Jetty watches your pom.xml and the WAR file; if either changes, it redeploys the war.
Here's how to set it:
<project> ... <plugins> ... <plugin> <groupId>org.mortbay.jetty</groupId> <artifactId>jetty-maven-plugin</artifactId> <configuration> <war>${basedir}/target/mycustom.war</war> </configuration> </plugin> </plugins></project>
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 pom.xml, WEB-INF/lib, WEB-INF/classes and WEB-INF/web.xml for changes and redeploys when necessary.
Here's how to set it:
<project> ... <plugins> ... <plugin> <groupId>org.mortbay.jetty</groupId> <artifactId>maven-jetty-plugin</artifactId> <configuration> <war>${basedir}/target/myfunkywebapp</war> </configuration> </plugin> </plugins></project>
This is basically the same as jetty:run-war, but 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.Here's the configuration for that:
<project> ... <plugins> ... <plugin> <groupId>org.mortbay.jetty</groupId> <artifactId>jetty-maven-plugin</artifactId> <configuration> <war>${basedir}/target/mycustom.war</war> </configuration> <executions> <execution> <id>start-jetty</id> <phase>test-compile</phase> <goals> <goal>deploy-war</goal> </goals> <configuration> <daemon>true</daemon> <reload>manual</reload> </configuration> </execution> <execution> <id>stop-jetty</id> <phase>test</phase> <goals> <goal>stop</goal> </goals> </execution> </executions> </plugin> </plugins></project>
This goal is new in jetty-7.5.2. You can force jetty to start the webapp in a new jvm, optionally passing arguments to the jvm. Unlike the other goals, this one does not share all the same configuration parameters (although a lot of them are the same, so that you can use many of the goals with the same configuration). The configuration options are:
To deploy your unassembled web app to jetty running in a new jvm:
mvn jetty:run-forked
With <waitForChild>true</waitForChild>:
The jetty plugin will continue to execute until either -
or
With <waitForChild>false</waitForChild>:
The jetty plugin will fork the child process and then exit.
NOTE: if you would like to set a custom port, you will need to specify it in a jetty.xml file rather than setting the <connector><port></port></connector> tags. The location of the jetty.xml can be specified using the jettyXml parameter.
This goal is new in jetty-7.6.0. This goal is designed to be used with an execution binding in your pom.xml. It is just like the jetty:run goal, however the difference is that 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 pom.xml.
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 <daemon>true</daemon>
configuration option to force Jetty to execute only while Maven is running, instead of running indefinitely. You use the pre-integration-test
and post-integration-test
Maven build phases to trigger the execution and termination of Jetty:
<plugin> <groupId>org.mortbay.jetty</groupId> <artifactId>jetty-maven-plugin</artifactId> <configuration> <scanIntervalSeconds>10</scanIntervalSeconds> <stopKey>foo</stopKey> <stopPort>9999</stopPort> </configuration> <executions> <execution> <id>start-jetty</id> <phase>pre-integration-test</phase> <goals> <goal>start</goal> </goals> <configuration> <scanIntervalSeconds>0</scanIntervalSeconds> <daemon>true</daemon> </configuration> </execution> <execution> <id>stop-jetty</id> <phase>post-integration-test</phase> <goals> <goal>stop</goal> </goals> </execution> </executions></plugin>
Of course, you can use this goal from the command line (mvn jetty:start), however, you need to be sure that all generated classes and files for your webapp are already present first.
Sometimes, your webapp might simply not be able to work with one of the goals, for example "jetty:run". In this case, use the <excludedGoals> parameter:
<configuration> <excludedGoals>run,run-exploded</excludedGoals></configuration>
Sometimes you may not want jetty to automatically reload and redeploy your webapp when something about it has changed. For example, you may be doing a series of changes and you want to ignore them all until you're done. In that use, use the <reload> parameter:
If you want to use mvn jetty:stop, you need to configure the plugin with a special port number and key that you also supply by executing the stop goal:
Here's a configuration example:
<plugin> <groupId>org.mortbay.jetty</groupId> <artifactId>jetty-maven-plugin</artifactId> <configuration> <stopPort>9966</stopPort> <stopKey>foo</stopKey> </configuration></plugin>
Then, while Jetty is running, type:
mvn jetty:stop
The <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 ..." message.
mvn jetty:help prints the list of goals for the jetty-maven-plugin, with a description of each goal.
mvn jetty:help -Ddetail=true -Dgoal=<goal-name> prints a list of the settable properties for that goal, in addition to its description.
Similarly to the well known system property "mvn.test.skip", you can define the system property "jetty.skip" to prevent jetty running. This is most useful when configuring jetty for execution during integration testing and you want to skip the tests:
mvn -Djetty.skip=true
You can also use the <skip> configuration parameter to skip jetty during certain executions (see above).
You can configure LoginServices (this was known as UserRealms in Jetty 6) in the plugin. Here's an example of setting up the HashLoginService for a webapp:
<plugin> <groupId>org.mortbay.jetty</groupId> <artifactId>jetty-maven-plugin</artifactId> <configuration> <scanIntervalSeconds>10</scanIntervalSeconds> <webAppConfig> <contextPath>/test</contextPath> </webAppConfig> <loginServices> <loginService implementation="org.eclipse.jetty.security.HashLoginService"> <name>Test Realm</name> <config>${basedir}/src/etc/realm.properties</config> </loginService> </loginServices> </configuration></plugin>
You can configure a list of org.eclipse.jetty.server.Connector objects for the plugin. If you don't specify any, an NIO org.eclipse.jetty.server.nio.SelectChannelConnector is configured on port 8080. You can change this default port number by using the system property jetty.port on the command line, for example "mvn -Djetty.port=9999 jetty:run". Alternatively, you can specify as many connectors as you like. Here's an example of configuring a connector on a different port number:
<plugin> <groupId>org.mortbay.jetty</groupId> <artifactId>jetty-maven-plugin</artifactId> <configuration> <scanIntervalSeconds>10</scanIntervalSeconds> <webApp> <contextPath>/test</contextPath> </webApp> <connectors> <connector implementation="org.eclipse.jetty.server.nio.SelectChannelConnector"> <port>9090</port> <maxIdleTime>60000</maxIdleTime> </connector> </connectors> </configuration></plugin>
If your webapp depends on other WAR files, the Jetty Maven plugin is able to merge resources from all of them. The merging is fairly simple and does not support exclusions. The ordering of dependencies is important if you have the same resource defined in multiple files. There is no special configuration for this beyond simply declaring the dependencies.
For example, suppose our webapp depends on these two WARs:
<dependency> <groupId>com.acme</groupId> <artifactId>X</artifactId> <type>war</type></dependency><dependency> <groupId>com.acme</groupId> <artifactId>Y</artifactId> <type>war</type></dependency>
Suppose the webapps contain:
WebAppX: /foo.jsp/bar.jsp/WEB-INF/web.xml WebAppY: /bar.jsp/baz.jsp/WEB-INF/web.xml/WEB-INF/special.xml
Then our webapp will have available these additional resources:
/foo.jsp (X)/bar.jsp (X)/baz.jsp (Y)/WEB-INF/web.xml (X)/WEB-INF/sitemesh.xml (Y)
If you have external resources that you want to incorporate in the execution of your webapp - but they're not assembled into wars so you can't use the Overlaid Wars method described above - then you can simply tell jetty the directories in which these external resources are located. At runtime, when jetty receives a request for a resource, it will look along all the locations to retrieve the resource. It's a lot like the overlaid war situation, without the war. Here's a configuration example:
<configuration> <webApp> <contextPath>/${build.finalName}</contextPath> <baseResource implementation="org.eclipse.jetty.util.resource.ResourceCollection"> <resourcesAsCSV>src/main/webapp,/home/johndoe/path/to/my/other/source,/yet/another/folder</resourcesAsCSV> </baseResource> </webApp></configuration>
You must be explicit enable GZip compression and other Jetty extensions by adding a dependency on jetty-servlets:
<plugin> <groupId>org.mortbay.jetty</groupId> <artifactId>jetty-maven-plugin</artifactId> <version>7.0.1.v20091125</version> <configuration> [...] </configuration> <dependencies> <dependency> <groupId>org.eclipse.jetty</groupId> <artifactId>jetty-servlets</artifactId> <version>7.0.1.v20091125</version> </dependency> </dependencies> </plugin>
<profile> ... <pluginGroups> <pluginGroup>org.mortbay.jetty</pluginGroup> </pluginGroups></profile>
You can use either a jetty.xml file to configure extra (pre-compiled) webapps that you wish to deploy, or you can use the contextHandlers configuration element in the jetty plugin configuration to do so. Say you have a webapp A, and you'd also like to deploy webapps B and C in the same jetty instance.
Putting the configuration in webapp A's pom.xml:
<plugin> <groupId>org.mortbay.jetty</groupId> <artifactId>jetty-maven-plugin</artifactId> <configuration> <scanIntervalSeconds>10</scanIntervalSeconds> <webApp> <contextPath>/test</contextPath> </webApp> <contextHandlers> <contextHandler implementation="org.eclipse.jetty.webapp.WebAppContext"> <war>${basedir}../../B.war</war> <contextPath>/B</contextPath> </contextHandler> <contextHandler implementation="org.eclipse.jetty.webapp.WebAppContext"> <war>${basedir}../../C.war</war> <contextPath>/B</contextPath> </contextHandler> </contextHandlers> </configuration></plugin>
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:
<Ref id="Contexts"> <Call name="addHandler"> <Arg> <New class="org.eclipse.jetty.webapp.WebAppContext"> <Set name="contextPath">/B</Set> <Set name="war">../../B.war</Set> </New> </Arg> </Call> <Call> <Arg> <New class="org.eclipse.jetty.webapp.WebAppContext"> <Set name="contextPath">/C</Set> <Set name="war">../../C.war</Set> </New> </Arg> </Call> </Ref>
Then configure the location of this jetty.xml file into webapp A's jetty plugin:
<plugin> <groupId>org.mortbay.jetty</groupId> <artifactId>jetty-maven-plugin</artifactId> <configuration> <scanIntervalSeconds>10</scanIntervalSeconds> <webApp> <contextPath>/test</contextPath> </webApp> <jettyXml>src/main/etc/jetty.xml</jettyXml> </configuration></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.
As a convenience, you can specify property name/value pairs that Jetty sets as System properties for the execution of the plugin. NOTE however that some system properties MUST be set on the command line to take effect, as by the time maven runs their values have already been established.
NOTE also that configuring logging using this method of setting system properties may not work as the logging system may initialize BEFORE the jetty plugin can set the system properties.
You may find it useful instead to use the properties maven plugin directly in your pom to set system properties which must be evaluated before any jetty code executes. Eg:
<plugin> <groupId>org.codehaus.mojo</groupId> <artifactId>properties-maven-plugin</artifactId> <version>1.0-alpha-2</version> <executions> <execution> <goals> <goal>set-system-properties</goal> </goals> <configuration> <properties> <property> <name>logback.configurationFile</name> <value>${project.baseUri}/resources/logback.xml</value> </property> </properties> </configuration> </execution> </executions></plugin>
Note that if a System property is found that is already set (for example, from the command line or by the JVM itself), then these configured properties DO NOT override them. This feature is useful to tidy up the command line and save a lot of typing. Here's an example:
<plugin> <groupId>org.mortbay.jetty</groupId> <artifactId>jetty-maven-plugin</artifactId> <configuration> <systemProperties> <systemProperty> <name>fooprop</name> <value>222</value> </systemProperty> </systemProperties> <webApp> <contextPath>/test</contextPath> </webApp> </configuration></plugin>
As of jetty-7.6.5, you CAN cause the system properties defined in the pom to override those on the command line, by using the <force> parameter:
<plugin> <groupId>org.mortbay.jetty</groupId> <artifactId>jetty-maven-plugin</artifactId> <configuration> <systemProperties> <force>true</force> <systemProperty> <name>fooprop</name> <value>222</value> </systemProperty> </systemProperties> <webApp> <contextPath>/test</contextPath> </webApp> </configuration></plugin>
You can also specify your System properties in a file. System properties specified in this way do NOT override System properties that have been set on the command line, by the JVM, or directly in the POM via systemProperties.
Here's an example of the file:
fooprop=222
Here's an example of configuring the file for the plugin, although you can instead specify the file by setting the System property (!) jetty.systemPropertiesFile on the command line:
<plugin> <groupId>org.mortbay.jetty</groupId> <artifactId>jetty-maven-plugin</artifactId> <configuration> <systemPropertiesFile>${basedir}/mysys.props</systemPropertiesFile> <webApp> <contextPath>/test</contextPath> </webApp> </configuration></plugin>
联系客服