 ------
 Maven2 Jetty Plugin: Configuration Guide
 ------
 Jan Bartel
 <janb@mortbay.com>
 ------
 July 6 2006


=====
W\ A\ R\ N\ I\ N\ G !
  Previously this plugin was invoked with <<<mvn jetty6:run>>>. This has changed to <<<mvn jetty:run>>> (we dropped the "6").

  Please update your poms to use:

+--------+
      <plugin> 
        <groupId>org.mortbay.jetty</groupId> 
        <artifactId>maven-jetty-plugin</artifactId>
      </plugin>
+--------+

  If you do not update your pom, "mvn jetty6:run" will continue to work, but there will be no further snapshots or releases of it as of 6 July 2006.

=====


Jetty Plugin Configuration Guide

  In order to run Jetty on a webapp project which is structured according to the usual Maven defaults (resources in <<<${basedir}/src/main/webapp>>>, classes in <<<${project.build.outputDirectory}>>> and the <<<web.xml>>> descriptor at <<<${basedir}/src/main/webapp/WEB-INF/web.xml>>>), you don't need to configure anything. 

  Simply type: 

+--------+
  mvn jetty:run
+--------+

  This will start Jetty running on port 8080 and serving your project.  Jetty will continue to run until the plugin is explicitly stopped, for example, by a <<<\<cntrl-c\>>>>.

  It is extremely convenient to leave the plugin running because it can be configured to periodically scan for changes and automatically redeploy the webapp. This makes the development cycle much 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.
  
  If, for whatever reason, you cannot run on an unassembled webapp, the plugin supports the <<<jetty:run-war>>> and <<<jetty:run-exploded>>> goals which are discussed below.

  For more information, see the {{{http://docs.codehaus.org/display/JETTY/Jetty+User+Guides}Jetty User Guides}} and the {{{http://docs.codehaus.org/display/JETTY/FAQ}FAQ}}.

Configuration Common to All Goals

 Regardless of which jetty goal you execute, the following configuration parameters are common to all:

  * <<connectors>> Optional. A list of <<<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. Alternatively, you can specify as many connectors as you like.


  * <<contextPath>> Optional. The context path for your webapp. By default, this is set to the <<<artifactId>>> from the project's pom.xml. You can override it and set it to anything you like here.

  * <<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>>.


  * <<tmpDir>> Optional. The temporary directory to use for the webapp. This is set to <<<${basedir}/target>>> by default but can be changed here.

  * <<webDefaultXml>> Optional. A webdefault.xml file to use instead of the supplied jetty default for the webapp.

  * <<overrideWebXml>> Optional. A web.xml file which will be applied AFTER the webapp's web.xml. This file can be stored anywhere. It is used to add or modify the configuration of a web.xml for different environments eg test, production etc. 

  * <<userRealms>> Optional. A list of <<<UserRealm>>> objects. 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.mortbay.jetty.RequestLog>>> request log interface. An implementation that respects the NCSA format is available as <<<org.mortbay.jetty.NCSARequestLog>>>.


  Let's take a look at an example of how we set these common properties (see also <<Setting System Properties>>):

+--------+
<project>
  ...
  <plugins>
    ...
      <plugin>
        <groupId>org.mortbay.jetty</groupId>
        <artifactId>maven-jetty-plugin</artifactId>
        <configuration>
          <contextPath>/biggerstrongerbetterfaster</contextPath>
          <connectors>
            <connector implementation="org.mortbay.jetty.nio.SelectChannelConnector">
              <port>9090</port>
              <maxIdleTime>60000</maxIdleTime>
            </connector>
          </connectors>
          <jettyConfig>/my/special/jetty.xml</jettyConfig>
          <scanIntervalSeconds>10</scanIntervalSeconds>
          <tmpDir>target/not/necessary</tmpDir>
          <webDefaultXml>src/main/resources/webdefault.xml</webDefaultXml>
          <overrideWebXml>src/main/resources/override-web.xml</overrideWebXml>
          <userRealms>
            <userRealm implementation="org.mortbay.jetty.security.HashUserRealm">
              <name>Test Realm</name>
              <config>etc/realm.properties</config>
            </userRealm>
          </userRealms>
          <requestLog implementation="org.mortbay.jetty.NCSARequestLog">
            <filename>target/yyyy_mm_dd.request.log</filename>
            <retainDays>90</retainDays>
            <append>true</append>
            <extended>false</extended>
            <logTimeZone>GMT</logTimeZone>
          </requestLog>
        </configuration>
      </plugin>
  </plugins>
</project>
+--------+


Configuration for the jetty:run Goal

 The <<<run>>> goal allows you to deploy your unassembled webapp to jetty, based on the locations of its constituent parts in your pom.xml. The following extra configuration parameters are available:

  * <<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>>>.

  * <<webAppSourceDirectory>> By default, this is set to <<<${basedir}/src/main/webapp>>>. If your static sources are in a different location, set this parameter accordingly.

  * <<webXml>> By default, this is set to either the variable <<<${maven.war.webxml}>>> or <<<${basedir}/src/main/webapp/WEB-INF/web.xml>>>, whichever is not null. If neither of these are appropriate, set this parameter.

  * <<jettyEnvXml>> This is an optional parameter. 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>> A list of files and directories to also periodically scan in addition to those automatically scanned by the plugin. Optional.

 Here's an example of setting these parameters:

+--------+
<project>
  ...
  <plugins>
    ...
      <plugin>
        <groupId>org.mortbay.jetty</groupId>
        <artifactId>maven-jetty-plugin</artifactId>
        <configuration>
          <webAppSourceDirectory>${basedir}/src/staticfiles</webAppSourceDirectory> 
          <webXml>${basedir}/src/over/here/web.xml</webXml>
          <jettyEnvXml>${basedir}/src/over/here/jetty-env.xml</jettyEnvXml>
          <classesDirectory>${basedir}/somewhere/else</classesDirectory>
          <scanTargets>
            <scanTarget>src/mydir</scanTarget>
            <scanTarget>src/myfile.txt</scanTarget>
          </scanTargets>
        </configuration>
      </plugin>
  </plugins>
</project>
+--------+




Configuration for the jetty:run-war Goal

 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.

 The configuration parameters specific to this goal are:

 * <<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>maven-jetty-plugin</artifactId>
        <configuration>
          <webApp>${basedir}/target/mycustom.war</webApp> 
        </configuration>
      </plugin>
  </plugins>
</project>
+--------+



Configuration for the jetty:run-exploded Goal

 This 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.

 The configuration parameters specific to this goal are:

 * <<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>
+--------+




Setting System Properties

  You may specify property name/value pairs that will be set as {System} properties for the execution of the plugin. Note that if a System property is found that is already set (eg 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. For example, to set up Commons logging you would usually need to type:


+---------+
  mvn -Dorg.apache.commons.logging.Log=org.apache.commons.logging.impl.SimpleLog jetty:run
+---------+

  Using the <<<systemProperty>>> configuration the command line can again be shorted to <<<mvn jetty:run>>> by placing the following in the pom.xml:

+---------+
<project>
  ...
  <plugins>
    ...
      <plugin>
        <groupId>org.mortbay.jetty</groupId>
        <artifactId>maven-jetty-plugin</artifactId>
        <configuration>
         ...
         <systemProperties>
            <systemProperty>
              <name>org.apache.commons.logging.Log</name>
               <value>org.apache.commons.logging.impl.SimpleLog</value>
            </systemProperty>
            ...
         </systemProperties>
        </configuration>
      </plugin>
  </plugins>
</project>
+---------+
 <<Note:>> You can use either \<name\> or \<key\> to specify the name of a \<systemProperty\>. Use whichever you prefer.


Logging

 Jetty itself has no dependencies on a particular logging framework, using a built-in logger which outputs to stderr. However, to allow jetty to integrate with other logging mechanisms, if an {{{http://www.slf4j.org}SLF4J}} log implementation is detected in the classpath, it will use it in preference to the built-in logger. 

 The JSP engine used by jetty does however have logging dependencies. If you are using JSP 2.0 (ie you are running in a JVM version \< 1.5), the JSP engine depends on commons-logging. A default commons-logging logger will be provided by the plugin using a combination of the {{{http://www.slf4j.org/manual.html#gradual}jcl04-over-slf4j}} and the {{{http://www.slf4j.org/api/org/slf4j/impl/SimpleLogger.html}simple-slf4j}} implementation, which logs all messages INFO level and above.  You can override this and provide your own commons-logging delegated logger by following these steps:


  [[1]] Use plugin \<dependencies\> add commons-logging and a commons-logging impl such as log4j onto the plugin classpath. Note that if you want the Jetty container log to also be routed to this log, you should also add the {{{http://www.slf4j.org/manual.html#gradual}slf4j-jcl}} bridge jar: 

+---------+
      <plugin>
        <groupId>org.mortbay.jetty</groupId>
        <artifactId>maven-jetty-plugin</artifactId>
        <version>6.0-SNAPSHOT</version>
        <configuration>
          <scanIntervalSeconds>5</scanIntervalSeconds>
        </configuration>
       <dependencies>
        <dependency>
          <groupId>commons-logging</groupId>
          <artifactId>commons-logging</artifactId>
          <version>1.1</version>
          <type>jar</type>
        </dependency>
        <dependency>
          <groupId>org.slf4j</groupId>
          <artifactId>slf4j-jcl</artifactId>
          <version>1.0.1</version>
          <type>jar</type>
        </dependency>
        <dependency>
          <groupId>log4j</groupId>
          <artifactId>log4j</artifactId>
          <version>1.2.13</version>
          <type>jar</type>
        </dependency>
       </dependencies>
      </plugin>
+---------+

  [[2]] Run the plugin with the system property <<<-Dslf4j=false>>> : 

+---------+
 mvn -Dslf4j=false jetty:run
+---------+

 NOTE: if you are using log4j you will need to tell the log4j discovery mechanism where your configuration properties file is. For example:

+---------+
mvn -Dslf4j=false -Dlog4j.configuration=file:./target/classes/log4j.properties jetty:run
+---------+


 If you are using JSP2.1 (ie you are running in a JVM \>= 1.5), then the JSP engine has no particular logging dependencies.

