Maven Jetty Plugin 配置指南(翻译)

Jetty 版本信息

 

     Jetty7 - 此插件更名为jetty-maven-plugin，以便更符合maven2的协定。为了在Web应用做快速应用开发做准备，详见多Web应用源目录。

  为了在Jetty里运行一个Web应用，你如果按照Maven默认的做法构造(resources文件存放,${basedir}/src/main/webapp下Classes文件存放在${project.build.outputDirectory}下，web.xml的配置描述${basedir}/src/main/webapp/WEB-INF/web.xml)，你不需要配置任何其它东西。

 只需输入：mvn jetty:run

    这将在端口为8080的Jetty服务器上启动你的项目。Jetty将持续运行，直到插件是明确停止，例如，按下<ctrl-c>，您也可以使用mvn jetty:stop命令。

   委托这个插件运行Web应用是非常方便的，因为它可以配置成能定期扫描Web应用的任何改变和自动部署Web应用。这就可以消除开发周期中编译和部署的步骤从而更加富有成效。你使用的IDE时对项目做的任何改变，都将直接自动导入到当前运行的web容器里，使您可以立即对其进行测试，立竿见影。

   如果不管出于什么原因，你总不能运行一个未组合过的web应用吧，在下文讨论中提到这个插件同样也支持jetty:run-war和jetty:run-exploded命令。

    关于其他命令的更多信息请查阅Jetty文档中的mvn jetty:run page、mvn jetty:run-exploded page、mvn jetty:run-war page。

自动执行插件

   有时候，例如在做集成测试时，你当然希望在测试开始时自动运行你的项目，测试完成时停止，而不只是手动的在命令行执行mvn jetty:run吧。

   要做到这一点，你需要为jetty 插件创建几个<execution>脚本，并使用<daemon>true</daemon>配置选项来预防Jetty无限期运行，迫使它只在执行Maven时才运行。

  像下面pom.xml片段中描述的pre-integration-test和post-integration-test 就是用来触发执行和关闭Jetty：

<plugin>

        <groupId>org.mortbay.jetty</groupId>

        <artifactId>maven-jetty-plugin</artifactId>

        <version>6.1.10</version>

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

 

         注意：Maven默认都是通过org.apache.maven.plugins的groupId来查找插件的，即使这个groupId跟上面要表达的内容完全不同。为了更明确的指向这个groupId是我们需要的插件，唯一的办法就是在settings.xml也做如下设置：

       <profile>

                 ...

                                       <pluginGroups>

                                         <pluginGroup>org.mortbay.jetty</pluginGroup>

                                       </pluginGroups>

</profile>

 

如何通过命令行停止插件

  委托Jetty插件无限期运行的目标包括run、run-war和run-exploded。你可以在视窗控制终端（如DOS窗口）使用<ctrl-c>关闭它，或者在另一个视窗控制终端使用stop目标关闭。如果你希望能使用mvn jetty:stop 执行关闭命令，则需要你在插件中配置一个特殊的端口和控制键。下面是一个例子配置：

<plugin>

        <groupId>org.mortbay.jetty</groupId>

        <artifactId>maven-jetty-plugin</artifactId>

        <version>6.1.10</version>

        <configuration>

          <stopPort>9966</stopPort>

          <stopKey>foo</stopKey>

        </configuration>

</plugin>

开始：

mvn jetty:start

关闭：

mvn jetty:stop

如何配置插件

配置公共的run, run-war 和 run-exploded 目标

  不管你执行哪一个Jetty目标，下述的配置参数都是可用的。一般来说它们分为应用于Web容器的配置和应用于具体web应用的配置：

容器级配置

           Connectors 可选.一组org.mortbay.jetty.Connector对象，包含jetty的端口监听。如果你不指定任何一个NIO的org.mortbay.jetty.nio.SelectChannelConnector，将默认配置一个8080端口。当然，你可以在命令行使用系统参数jetty.port 改变默认端口。例如"mvn -Djetty.port=9999 jetty:run"。另外，您也可以指定许多您想要的连接。  
         jettyConfig 可选。除插件配置参数外，你也可以指定一个jetty.xml文件的路径。当你有其他的web应用和操作需要部署时，或者一些你无法在插件中配置的jetty对象,你就可以使用到它,。

             scanIntervalSeconds 可选[秒]。在很短的时间间隔内在扫描web应用检查是否有改变，如果发觉有任何改变则自动热部署。默认为0，表示禁用热部署检查。任何一个大于0的数字都将表示启用。

              systemPropertie 可选。它们允许你在设置一个插件的执行操作时配置系统属性.更多的信息请查阅Setting System Properties.

              userRealms 可选。一组org.mortbay.jetty.security.UserRealm实现。请注意，它没有一个默认的Realm。如果你在你的web.xml应用了一个Realm,你需要在这里指定一个对应的Rleam。

              requestLog 可选。一个org.mortbay.jetty.RequestLog请求日志接口的实现。比如org.mortbay.jetty.NCSARequestLog就是一个作为NCSA格式的实现。

[译注：（美国）国家超级计算技术应用中心 (NCSA) 公用格式是常用的标准日志格式]

 

“手动重载”

从Jetty 6.2.0pre0版本起，添加了一个新的可用组件，用于控制web应用的重新部署。

配置参数：<reload>[manual|automatic]</reload>

当你设置成手动模式后，web应用不会自动的扫描和重部署。相反，用户可以控制的Web应用时，通过键入”回车换行键”重载。当设置成自动模式时，将根据scanIntervalSeconds参数的设置不定时的扫描和自动重部署。你也能通过在命令行使用系统参数
-Djetty.reload 配置选择重载的模式。

比如："mvn -Djetty.reload=manual jetty:run" 将强制手动重载，不管pom.xml文件里如何配置。同理: "mvn -Djetty.reload=automatic -Djetty.scanIntervalSeconds=10 jetty:run" 每隔十秒中后台将重载一次，而不管pom.xml文件里如何配置。

 

Web应用级配置

             contextPath 可选。这个contex地址指向你的webapp.默认情况下，它被设置成该项目的pom.xml的<artifactId>。当然你也可以设置一个你喜欢的从而覆盖它。

             tmpDir 可选。它作为web应用的临时目录。它默认设置在{${basedir}/target}下，但是你也可在这里改变它的路径。

             overrideWebXml 可选. 它是一个应用于web应用的web.xml的备用web.xml文件.这个文件可以存放在任何地方.你可以根据不同的环境中(如测试、开发等等)利用它增加或修改一个web.xml配置.

             webDefaultXml 可选. webdefault.xml文件用来代替webapp默认提供给jetty的文件.

从6.1.6rc0发行版开始，一个替代的更灵活的方式是配置web应用时使用webAppConfig元素代替上面列出的那些单独的参数。使用webAppConfig元素，你能有效的调用org.mortbay.jetty.webapp.WebAppContext类中任何setter方法。下面显示的列子将展示这个元素跟它上面的例子比较是如何配置同样的特性的(当然它们还有更多的特性能让你设置)：

<project>

 ...

 <plugins>

    ...

      <plugin>

        <groupId>org.mortbay.jetty</groupId>

        <artifactId>maven-jetty-plugin</artifactId>

        <configuration>

          <scanIntervalSeconds>10</scanIntervalSeconds>

          <!—web应用的配置 -->

          <contextPath>/biggerstrongerbetterfaster</contextPath>

          <tmpDir>target/not/necessary</tmpDir>

          <webDefaultXml>src/main/resources/webdefault.xml</webDefaultXml>

          <overrideWebXml>src/main/resources/override-web.xml</overrideWebXml>

          <!—从jetty6.1.6rc0起, 你能用webAppConfig 元素代替

          <webAppConfig>

            <contextPath>/test</contextPath>

            <tempDirectory>${project.build.directory}/work</tempDirectory>

            <defaultsDescriptor>src/main/resources/webdefault.xml</defaultsDescriptor>

            <overrideDescriptor>src/main/resources/override-web.xml</overrideDescriptor>

          </webAppConfig>

          -->

          <!—容器的配置 -->

          <jettyConfig>/my/special/jetty.xml</jettyConfig>

         <connectors>

            <connector implementation="org.mortbay.jetty.nio.SelectChannelConnector">

              <port>9090</port>

              <maxIdleTime>60000</maxIdleTime>

            </connector>

          </connectors>

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

jetty:run的配置

  run目标允许你把你未打包的web应用部署到Jetty.它包含在你的pom.xml文件的一部分元素里。下面额外的配置参数都是可用到的：

  classesDirectory 这是你的web应用编译的classes存放的路径。你很少需要设置这个参数，其实可以在你的pom.xml用<build><outputDirectory>替代它。

webAppSourceDirectory 默认设置在${basedir}/src/main/webapp下。如果你的源文件夹结构跟左边不同，就可以设置这个参数。
  webXml  默认设置在${maven.war.webxml}或者${basedir}/src/main/webapp/WEB-INF/web.xml，无论哪个文件都不是空的。如果觉得前两者都不合适，就设置它。

          jettyEnvXml 可选。它指向一个jetty-env.xml文件的路径。允许你创建JNDI绑定并满足web.xml中<env-entry>、<resource-env-ref>和<resource-ref>元素中的条件。当然这个文件的使用范围仅仅在你的当前应用和其他应用同时部署时它并没有共享的情况下。(例如使用一个jettyConfig文件)    

          scanTargets 可选。周期性的扫描除了插件自动扫描外的文件和文件夹列表。

          scanTargetPatterns 可选。如果你想扫描有一长串的额外文件，通过使用模式匹配表达式制定它们更加方便，它可以用来替代 <scanTargets>参数的枚举展示。这个参数包含一组<scanTargetPattern>。每一个都是由一个<directory>和<includes>[或者<excludes>]参数来指定文件的匹配模式。

下面的示例设置了所有这些参数：

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

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

  你也可以查看jetty:run parameter reference。

配置jetty:run-war

  这个目标将首先把你的web应用打包成一个war文件，再发布到Jetty。如果你设置扫描间隔为非零，Jetty将观察你的pom.xml和war文件。如果有任何变化，它都将重新打包并部署war。

  配置参数的详细描述如下：

          webApp 打包后war的路径。默认为${project.build.directory}/${project.build.finalName}.war。如果目标存储空间不足，设置它到你的自定义路径下。

详细设置如下：

<project>

 ...

 <plugins>

    ...

      <plugin>

        <groupId>org.mortbay.jetty</groupId>

        <artifactId>maven-jetty-plugin</artifactId>

        <configuration>

          <webApp>${basedir}/target/mycustom.war</webApp>

        </configuration>

      </plugin>

 </plugins>

</project>           

你也可以查看jetty:run-war parameter reference.

配置jetty:run-exploded

  这个目标首先装配你的web应用到exploded-war文件，再发布到Jetty。如果你设置扫描间隔为非零，Jetty将观察你的pom.xml, WEB-INF/lib, WEB-INF/classes和WEB-INF/web.xml的改变。如果有必要，它都将重新打包并部署war。

配置参数的详细描述如下：

             webApp exploded-war的路径。默认在${project.build.directory}/${project.build.finalName}，但是能通过设置这个参数，从而覆盖它。

详细设置如下：

<project>

 ...

 <plugins>

    ...

      <plugin>

        <groupId>org.mortbay.jetty</groupId>

        <artifactId>maven-jetty-plugin</artifactId>

        <configuration>

          <webApp>${basedir}/target/myfunkywebapp</webApp>

        </configuration>

      </plugin>

 </plugins>

</project>

你也可以查看jetty:run-exploded parameter reference.

设置系统属性

  你可以为插件的执行操作按name/value成对的方式指定系统属性。

  请注意，如果发现有系统属性已经设置过(例如从命令行或者JVM本身)，则这些配置的属性不会覆盖它们。

  这个特性在整理命令行和保存一系列的键盘键入操作时是很有用的。

  譬如，你通常会需要产生Commons logging:

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

 

  使用了systemProperty配置的命令行可以再次更简短的运行mvn jetty:run，看下面的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>

注意：你可以按<name>或者<key>的方式指定<systemProperty>的名称，使用哪个按你的喜好吧。

日志

  Jetty本身并没有依赖一个特定的日志框架，它使用一个内置的日志记录器来输出标准错误。不管怎样，允许了Jetty和其他日志方法集成，如果在类路径中发现了一个SLF4J日志的实现，它的使用将优先于Jetty内置的日志记录器。

 其实Jetty的JSP引擎已经包含了一个日志依赖。如果你使用JSP 2.0(即你运行的Java虚拟机[JVM]版本<1.5)，这个JSP引擎依赖于commons-logging。默认的commons-logging日志记录器在记录信息为INFO及以上级别[DEBUG,WARN,ERROR]时，将提供插件使用的jcl04-over-slf4j和simple-slf4j的实现。

 您可以忽略这一点，按照下列步骤提供自己的commons-logging：

1. 使用插件中<dependencies>增加一个commons-logging和一个commons-logging的实现到插件类路径(如log4j)。请注意，如果您想把Jetty 容器的日志也将发送到这个记录器，你还应该加上slf4j-jcl这个用于桥接的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.用-Dslf4j=false系统属性运行插件：

    mvn -Dslf4j=false jetty:run

     注意：如果你使用的是log4j，你将需要告诉log4j你配置文件的位置。譬如：

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

  

   如果您使用的是JSP2.1 （即你运行的Java虚拟机[JVM]版本>=1.5 ），那太好了，因为这个JSP已经没有什么特别的日志依赖。