Contents[hide]
IntroductionJetty 7 and Jetty 8 are now EOL (End of Life)
All development and stable releases are being performed with Jetty 9.
The information on this page refers to the plugin versions for Jetty 7 and above. If you're using the plugin with Jetty 6, see the Jetty 6 Maven Plugin guide at codehaus. It is now called the jetty-maven-plugin. In previous versions it was the maven-jetty-plugin.
This documentation ONLY refers to using the jetty-maven-plugin with Jetty 7.x or Jetty 8.x.
For Jetty 9.x an onward, this wiki has been replaced with a docbook documentation, found at http://www./jetty/documentation/current/jetty-maven-plugin.htmlFeatureQuick Start: Get Up and RunningFirst, 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. Stopping the PluginYou can terminate the plugin with a <ctrl-c> in the terminal window where it is running. Running and DeployingThe 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: Configuring the Jetty ContainerThese configuration elements set up the Jetty environment in which your webapp executes.
Configuring Your WebAppThese configuration parameters apply to your webapp. They should apply to all goals, except for run-forked and stop:
jetty:run : Running an unassembled webappThe 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> Configuring additional parametersIn 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. jetty:run-war : Running an assembled webapp as a warThis 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. Configuring 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> jetty:run-exploded : Running an assembled webapp as an expanded WARThe 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. Configuring the exploded war
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> jetty:deploy-war : Running a pre-assembled warThis 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>
jetty:run-forked : Running an unassembled webapp in a separate jvmThis 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:
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.
jetty:start : Starting jetty without first executing the build up to "test-compile" phaseThis 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 <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. MoreExcluded GoalsSometimes, 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>
Manual ReloadSometimes 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:
Stopping the plugin from Another Terminal WindowIf 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 Using mvn jetty:help for More Helpmvn 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. Skipping execution of jettySimilarly 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).
Configuring Security SettingsYou 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>
Configuring ConnectorsYou 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> Using Overlayed WARsIf 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>
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) Multiple webapp root directoriesIf 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> Using GZip Compression and Other Jetty ExtensionsYou 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> Setting the groupId
Maven by default looks for plugins with a groupId of org.apache.maven.plugins, even if the groupId is declared differently as above. In order to instruct Maven to look for the plugin in the groupId as defined, set a plugin group in a profile in settings.xml like so: <profile> ... <pluginGroups> <pluginGroup>org.mortbay.jetty</pluginGroup> </pluginGroups> </profile>
Running more than one webappYou 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>
<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. Setting System PropertiesAs 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> In the PomNote 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>
<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> In a FileYou 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> |
|