Difference between revisions of "Jetty/Feature/Jetty Maven Plugin"

Revision as of 09:30, 13 April 2010

Introduction

The Jetty Maven plugin is useful for rapid development and testing. It can be added to any webapp project which 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 will automatically pick them up, allowing you to test them straight away.

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.

NOTE: It is now called the jetty-maven-plugin. In previous versions it was the maven-jetty-plugin.

Feature

Quick Start

Get up and running

First, 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 will start Jetty and serve up your project on http://localhost:8080/.

Jetty will continue to run until you stop it. While it runs, it will periodically scan for changes to your project files, so if you save changes and recompile your class files, Jetty will redeploy your webapp, and you can instantly test the changes you just made.

Stop the plugin from the same terminal window

You can terminate the plugin with a <ctrl-c> in the terminal window where it is running.

Running and Deploying

The jetty-maven-plugin has six 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 may 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's the configuration elements that are common to all goals:

Container Configuration

These configuration elements set up the jetty environment in which your web app executes.

• <connectors> Optional A list of org.mortbay.jetty.Connector objects, which are the port listeners for jetty. If you don't specify any, an NIO org.mortbay.jetty.nio.SelectChannelConnector will be configured on port 8080. You can change this default port number by using the system property jetty.port on the command line. Eg "mvn -Djetty.port=9999 jetty:run". Alternatively, you can specify as many connectors as you like.

• <jettyConfig> Optional The location of a jetty.xml file that will be applied in addition to any plugin configuration parameters. You might use it if you have other webapps, handlers etc to be deployed, or you have other jetty objects that cannot be configured from the plugin.

• <scanIntervalSeconds> Optional 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.

• <systemProperties> Optional These allow you to configure System properties that will be set for the execution of the plugin. More information can be found on them at Setting System Properties.

• <systemPropertiesFile> Optional This is a file containing System properties that will be set for the execution of the plugin. They will not override any system properties that have been set on the command line, by the JVM, or in the POM via systemProperties. Available from Jetty 6.1.15rc4

• <loginServices> Optional A list of org.mortbay.jetty.security.UserRealm implementations. Note that there is no default realm. If you use a realm in your web.xml you can specify a corresponding realm here.

• <requestLog> Optional An implementation of the org.eclipse.jetty.server.RequestLog request log interface. An implementation that respects the NCSA format is available as org.eclipse.jetty.server.NCSARequestLog.

Web App Configuration

These configuration parameters apply to your web app.

• <webAppConfig> this represents an extension to the class org.mortbay.jetty.webapp.WebAppContext. Any of the setter methods on this object can be used to configure your webapp. Here are a few of the most useful ones:
  • <contextPath> The context path for your webapp. By default, this is set to the /${project.artifactId} from the project's pom.xml.
  • <descriptor> The path to the web.xml file for your webapp.
  • <defaultsDescriptor> The path to a webdefault.xml file that will be applied to your webapp before the web.xml. If none is supplied, jetty uses a default one baked into the jetty-webapp.jar.
  • <overrideDescriptor> The path to a web.xml file that will be applied after your web.xml is read. You can use this to replace or add configuration.
  • <tempDirectory> The path to a dir that jetty can use to expand or copy jars and jsp compiles when your webapp is running. The default is ${project.build.outputDirectory}/tmp

• <webAppXml> This is the path to a context xml file that is applied to your webapp AFTER the <webAppConfig> element. This is optional.

Run an unassembled webapp with mvn jetty:run

The run goal runs on a webapp that does not have to be built into a war. Instead, jetty will deploy 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. So, for example, by default it will look for:

• resources in ${basedir}/src/main/webapp
• classes in ${project.build.outputDirectory}
• web.xml in ${basedir}/src/main/webapp/WEB-INF/

The plugin will automatically ensure 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 will pick up the changed class.

The webapp does not need to be assembled into a WAR, saving time during the development cycle. Once invoked, the plugin can be configured to run continuously, scanning for changes in the project and automatically performing a hot redeploy when necessary. Any changes you make will be immediately reflected in the running instance of Jetty, letting you quickly jump from coding to testing, rather going through the cycle of: code, compile, reassemble, redeploy, test.

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>
    <webAppConfig>
      <contextPath>/test</contextPath>
    </webAppConfig>
  </configuration>
</plugin>

Configuration

In addition to the <webAppConfig> element which is common to all goals, the jetty:run goal supports:

• <classesDirectory> This is the location of your compiled classes for the webapp. You should rarely need to set this parameter. Instead, you should set <build><outputDirectory> in your pom.xml.
• <testClassesDirectory> Location of the compiled test classes for your webapp. By default this is ${project.build.testOutputDirectory}.
• <useTestClasspath> If true, the classes from <testClassesDirectory> and dependencies of scope "test" are placed first on the classpath. By default this is false.
• <webAppSourceDirectory> By default, this is set to ${basedir}/src/main/webapp. If your static sources are in a different location, set this parameter accordingly.
• <jettyEnvXml> Optional it is the location of a jetty-env.xml file, which allows you to make JNDI bindings that will satisfy <env-entry>, <resource-env-ref> and <resource-ref> linkages in the web.xml that are scoped only to the webapp and not shared with other webapps that you may be deploying at the same time (eg by using a jettyConfig file).
• <scanTargets> Optional A list of files and directories to also periodically scan in addition to those automatically scanned by the plugin.
• <scanTargetPatterns> 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 <scanTargets> parameter. This parameter is a list of <scanTargetPattern>s, each consisting of a <directory> and <includes> and/or <excludes> parameters to specify the file matching patterns.

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.

Run an assembled webapp as a WAR with mvn jetty:run-war

This goal will first package your webapp as a war file and then deploy it to Jetty. If you set a non-zero scanInterval Jetty will watch your pom.xml and the war file and if either changes, it will redeploy the war.

Configuration

• <webApp> The location of the built war file. This defaults to ${project.build.directory}/${project.build.finalName}.war. If this is not sufficient, set it to your custom location.

Here's how you would set it:

<project>
  ...
  <plugins>
    ...
      <plugin>
        <groupId>org.mortbay.jetty</groupId>
        <artifactId>jetty-maven-plugin</artifactId>
        <configuration>
          <webApp>${basedir}/target/mycustom.war</webApp>
        </configuration>
      </plugin>
  </plugins>
</project>

Run an assembled webapp as an exploded WAR with mvn jetty:run-exploded

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 will watch your pom.xml, WEB-INF/lib, WEB-INF/classes and WEB-INF/web.xml for changes and redeploy when necessary.

Configuration

• <webApp> The location of the exploded war. This defaults to ${project.build.directory}/${project.build.finalName} but can be overridden by setting this parameter.

Here's how you would set it:

<project>
  ...
  <plugins>
    ...
      <plugin>
        <groupId>org.mortbay.jetty</groupId>
        <artifactId>maven-jetty-plugin</artifactId>
        <configuration>
          <webApp>${basedir}/target/myfunkywebapp</webApp>
        </configuration>
      </plugin>
  </plugins>
</project>

Run a pre-assembled WAR with mvn jetty:deploy-war

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 will not be 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>
          <webApp>${basedir}/target/mycustom.war</webApp>
        </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>

More

Stop the plugin from another terminal window with mvn jetty:stop

You can terminate the plugin from another terminal window by executing the stop goal. If you wish to be able to use mvn jetty:stop then you need to configure the plugin with a special port number and key that you also supply on the stop command:

<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 will get an "Address already in use" error message after the "Started SelectedChannelConnector ..." message.

Get more help with mvn jetty:help

mvn jetty:help prints out the list of goals for the jetty-maven-plugin, with a description of each goal.

mvn jetty:help -Ddetail=true -Dgoal=<goal-name> will print out a list of the settable properties for that goal, in addition to its description, which is useful to get quick information about a goal.

Automatic plugin execution during unit testing with mvn jetty:run

One useful feature of the plugin is its automatic plugin execution. You can automatically have your webapp started at the beginning of the tests, and stopped at the end rather than manually executing mvn jetty:run on the command line.

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 only execute while Maven is running, instead of running indefinitely.

The pre-integration-test and post-integration-test Maven build phases can be used 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>run</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>

Security

LoginServices (this was known as UserRealms in jetty-6) can be configured directly 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>

Connectors

A list of org.eclipse.jetty.server.Connector objects can be configured for the plugin. If you don't specify any, an NIO org.eclipse.jetty.server.nio.SelectChannelConnector will be configured on port 8080. You can change this default port number by using the system property jetty.port on the command line. Eg "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>
    <webAppConfig>
      <contextPath>/test</contextPath>
    </webAppConfig>
    <connectors>
       <connector implementation="org.eclipse.jetty.server.nio.SelectChannelConnector">
          <port>9090</port>
          <maxIdleTime>60000</maxIdleTime>
       </connector>
     </connectors>
  </configuration>
</plugin>

Overlayed wars

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 2 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)

GZip compression and other jetty extensions

Must be explicitly enabled 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>

Notes

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>