一种maven改造快速支持servlet3.1web工程的方法

原文地址:http://shmilyaw-hotmail-com.iteye.com/blog/2221134

问题的引出

    平时在工作中大量的开发都依赖于工具maven，而且这个工具总的来说功能还是非常强大的。由于在最近的一些web开发中要用到最新的servlet3.1以及最新的web container tomcat 8，于是想利用maven原生的archetype类型来构建项目。可惜尝试使用默认的类型之后发现它并不提供最新版本的支持。而如果要将原来的工程改造成支持servlet 3.1 web工程的话，还是很麻烦。于是想找个好点的办法，能够尽量高效的生成这样的工程。

    为了完整的记录和对比两种方法，这里主要列举了一种是针对原有maven web-app工程进行改造的方法，还有一种是利用一个自定义的maven archetype工程进行改造的方法。

 

原有方法

      假如我们需要创建一个maven web工程，一种方法是使用IDE里自带的功能来创建一个，然后一步步的配置，还要一个方法就是使用maven命令行。比如我们输入如下的命令：

 

 mvn archetype:generate -DgroupId=com.yunzero -DartifactId=MavenDefaultProject -DarchetypeArtifactId=maven-archetype-webapp -DinteractiveMode=false

    这个时候，我们将生成一个名字为MavenDefaultProject的web工程。上述命令的输出如下：

 

 [INFO] Scanning for projects...
 [INFO]
 [INFO] ------------------------------------------------------------------------
 [INFO] Building Maven Stub Project (No POM) 1
 [INFO] ------------------------------------------------------------------------
 [INFO]
 [INFO] >>> maven-archetype-plugin:2.2:generate (default-cli) > generate-sources @ standalone-pom >>>
 [INFO]
 [INFO] <<< maven-archetype-plugin:2.2:generate (default-cli) < generate-sources @ standalone-pom <<<
 [INFO]
 [INFO] --- maven-archetype-plugin:2.2:generate (default-cli) @ standalone-pom ---
 [INFO] Generating project in Batch mode
 [INFO] ----------------------------------------------------------------------------
 [INFO] Using following parameters for creating project from Old (1.x) Archetype: maven-archetype-webapp:1.0
 [INFO] ----------------------------------------------------------------------------
 [INFO] Parameter: basedir, Value: /home/frank/programcode/maven
 [INFO] Parameter: package, Value: com.yunzero
 [INFO] Parameter: groupId, Value: com.yunzero
 [INFO] Parameter: artifactId, Value: MavenDefaultProject
 [INFO] Parameter: packageName, Value: com.yunzero
 [INFO] Parameter: version, Value: 1.0-SNAPSHOT
 [INFO] project created from Old (1.x) Archetype in dir: /home/frank/programcode/maven/MavenDefaultProject
 [INFO] ------------------------------------------------------------------------
 [INFO] BUILD SUCCESS
 [INFO] ------------------------------------------------------------------------
 [INFO] Total time: 15.339 s
 [INFO] Finished at: 2015-06-21T21:12:47+08:00
 [INFO] Final Memory: 15M/303M

    而这个时候如果我们用IDE工具比如ecilpse直接去导入的话，还是不能成功的，因为我们还需要做一步转换。执行命令： 

 

 mvn eclipse:eclipse

    这个时候再使用eclipse导入到工程中，我们将看到一个如下的工程结构：

 

    我们再来看对应的pom.xml文件内容：

 

 <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
   <modelVersion>4.0.0modelVersion>
   <groupId>com.yunzerogroupId>
   <artifactId>MavenDefaultProjectartifactId>
   <packaging>warpackaging>
   <version>1.0-SNAPSHOTversion>
   <name>MavenDefaultProject Maven Webappname>
   <url>http://maven.apache.orgurl>
   <dependencies>
     <dependency>
       <groupId>junitgroupId>
       <artifactId>junitartifactId>
       <version>3.8.1version>
       <scope>testscope>
     dependency>
   dependencies>
   <build>
     <finalName>MavenDefaultProjectfinalName>
   build>
 project>

     从文件里可以看到，它和我们期望的工程还是有一些差别的。比如说，我们希望指定的工程里有对servlet 3.1的依赖。可是这里没有，另外，也没有指定我们期望的java执行版本。还要一个问题就是，我们希望它们像一些默认的工程一样，给我们生成一个java代码的包以及测试代码包还要对应配置文件的resources目录。

    所以，要改造成一个期望的工程，我们就需要一步一步的来改造这些项。

 

将目标工程改造成maven工程

    首先选择该工程，点击右键，选择Config->Convert to Maven Project。这个时候，我们将看到工程才真正成为一个maven工程。不过这个时候系统会有一个如下的错误：

 

    解决这个问题很简单，在pom.xml里添加对servlet的依赖：

 

 <dependency>
         <groupId>javax.servletgroupId>
         <artifactId>javax.servlet-apiartifactId>
         <version>3.1.0version>
         <scope>providedscope>
     dependency>

    如果这个时候，我们编译和运行工程，将看到一个正常运行的结果：

    可惜这个工程仅仅默认支持servlet 2.3。我们可以打开src/main/webapp/WEB-INF/web.xml文件，它的内容如下：

 

  "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
  "http://java.sun.com/dtd/web-app_2_3.dtd" >

 <web-app>
   <display-name>Archetype Created Web Applicationdisplay-name>
 web-app>

   如果要升级到servlet 3.1，这里必然是一个需要修改的地方。另外，如果我们去查看工程的Facets：

 

   很明显，这里显示的也是2.3, java版本支持是1.5。

 

升级

    现在如果我们直接在刚才project Facets里去修改的话，发现这部分的修改都无法保存。很无奈，这个时候，我们需要做一些人工的修改。在该工程所在目录下面，有一个.settings的目录，它是一个隐藏目录，其主要包含的内容如下：

 

 

    我们打开里面的文件org.eclipse.wst.common.project.facet.core.xml，发现它的内容如下：

 

 xml version="1.0" encoding="UTF-8"?>
 <faceted-project>
   <fixed facet="wst.jsdt.web"/>
   <installed facet="java" version="1.5"/>
   <installed facet="jst.web" version="2.3"/>
   <installed facet="wst.jsdt.web" version="1.0"/>
 faceted-project>

   很显然，它里面的内容正好就是我们需要设定的内容，我们将jst.web部分的version内容设置为3.1，而java的version内容设置为1.8。这个时候刷新工程，将看到如下的变化。

 

   改了这么多了，居然还有不少问题，再一个个的改过来。首先在pom.xml里添加如下部分来设定支持的java版本：

 <build>
     <finalName>MavenDefaultProjectfinalName>
     <plugins>
         <plugin>
             <groupId>org.apache.maven.pluginsgroupId>
             <artifactId>maven-compiler-pluginartifactId>
             <version>3.1version>
             <configuration>
                 <source>1.8source>
                 <target>1.8target>
             configuration>
         plugin>
     plugins>
   build>

  修改完之后更新一下工程，将发现关于java compiler的问题已经解决了。现在，需要修改的下一个文件就是web.xml，将它的内容修改为如下：

 

 xml version="1.0" encoding="UTF-8"?>
 <web-app xmlns="http://xmlns.jcp.org/xml/ns/javaee"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/javaee
                              http://xmlns.jcp.org/xml/ns/javaee/web-app_3_1.xsd"
          version="3.1">

   <display-name>Archetype Created Web Applicationdisplay-name>

 web-app>

    之所以这个文件的修改能够解决前面那个问题是因为从servlet 3以来所有的web.xml文件的定义支持的命名空间由原来的dtd格式改为xmlns的样式了。这个时候，我们再尝试运行这个工程，发现它能够正常的运行了，而且支持的版本个已经是servlet 3.1了。

    现在还要一个小的问题就是，如果我们需要添加代码的话，在IDE里通过添加source folder到src/main下面是不行的，还需要手工到工程所在目录下面创建目录，然后刷新工程。

    最终，通过这种方式修改了很多文件和配置，才生成一个我们期望的工程模板。老实说，就为了弄一个这样的工程模板，居然要费这么大的劲，实在是太不值得了。那么有没有更加高效的方法呢？

 

资源的引入

    带着这个问题，在网上搜索了一会儿之后，发现了一个已经有人实现了的工程模板。目前这个工程已经支持servlet 3.0了。它的思路是定义一个类似于maven web-app的archetype，这样每次我们使用它们的时候，这些配置和文件就已经生成好了。

    这个servlet 3的模板生成方法及使用描述如下链接： http://maciejwalkowiak.github.io/servlet3-maven-archetype/

    工程的源代码在github上：https://github.com/maciejwalkowiak/servlet3-maven-archetype.git

    它的使用在链接里，这里就不再赘述了。因为这个工程是一个maven archetype工程。而maven archetype从本质上来说是什么呢？它相当于是一个针对某种类型工程提供的模板，比如对quickstart类型的工程定义为普通工程类库，然后提供对应的java, test目录，然后提供默认的单元测试库引用junit等等。那么按照这个思路，我们这个工程模板里应该有servlet 3.1 api、junit的库引用，以及对应的web.xml配置文件和对应的源代码结构，包括src/main/java, src/main/resources, src/test/java, src/test/resources。于是，我们所要做的事情就是对这个工程的改造。

 

改造

    在改造前，我们先看看原来这个工程的结构：

 

     这个工程里我们实际上需要修改的在archetype-resources里面。在这个目录下的pom.xml文件就是我们最后生成的工程里的pom.xml文件，它原来的内容如下：

 

 xml version="1.0" encoding="UTF-8"?>
 <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
     <modelVersion>4.0.0modelVersion>
     <groupId>${groupId}groupId>
     <artifactId>${artifactId}artifactId>
     <packaging>warpackaging>
     <version>${version}version>
     <name>Servlet 3 Web Applicationname>
     <url>http://maven.apache.orgurl>

     <properties>
         <project.build.sourceEncoding>UTF-8project.build.sourceEncoding>
         <java-version>1.6java-version>
     properties>

     <dependencies>

         <dependency>
             <groupId>javax.servletgroupId>
             <artifactId>javax.servlet-apiartifactId>
             <version>3.0.1version>
             <scope>providedscope>
         dependency>


         <dependency>
             <groupId>junitgroupId>
             <artifactId>junitartifactId>
             <version>4.8.2version>
             <scope>testscope>
         dependency>
     dependencies>
     <build>
         <finalName>${project.artifactId}-${project.version}finalName>
         <plugins>
             <plugin>
                 <groupId>org.apache.maven.pluginsgroupId>
                 <artifactId>maven-compiler-pluginartifactId>
                 <version>2.3.2version>
                 <configuration>
                     <source>${java-version}source>
                     <target>${java-version}target>
                 configuration>
             plugin>

             <plugin>
                 <groupId>org.apache.tomcat.mavengroupId>
                 <artifactId>tomcat7-maven-pluginartifactId>
                 <version>2.0version>
             plugin>

             <plugin>
                 <groupId>org.apache.maven.pluginsgroupId>
                 <artifactId>maven-war-pluginartifactId>
                 <version>2.3version>
                 <configuration>
                     <failOnMissingWebXml>falsefailOnMissingWebXml>
                 configuration>
             plugin>
         plugins>
     build>
 project>

    这里的内容比较多，无非就是定义了支持的java版本，依赖的servlet api, junit版本等等。里面的plugin tomcat7-maven-plugin因为目前没有最新官方对tomcat8的支持，可以暂时去掉。我们针对支持的版本等信息也做一个修改，这样修改后的pom.xml文件如下：

 

 xml version="1.0" encoding="UTF-8"?>
 <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
     <modelVersion>4.0.0modelVersion>
     <groupId>${groupId}groupId>
     <artifactId>${artifactId}artifactId>
     <packaging>warpackaging>
     <version>${version}version>
     <name>Servlet 3 Web Applicationname>
     <url>http://maven.apache.orgurl>

     <properties>
         <project.build.sourceEncoding>UTF-8project.build.sourceEncoding>
         <java-version>1.8java-version>
     properties>

     <dependencies>

         <dependency>
             <groupId>javax.servletgroupId>
             <artifactId>javax.servlet-apiartifactId>
             <version>3.1.0version>
             <scope>providedscope>
         dependency>


         <dependency>
             <groupId>junitgroupId>
             <artifactId>junitartifactId>
             <version>4.11version>
             <scope>testscope>
         dependency>
     dependencies>
     <build>
         <finalName>${project.artifactId}-${project.version}finalName>
         <plugins>
             <plugin>
                 <groupId>org.apache.maven.pluginsgroupId>
                 <artifactId>maven-compiler-pluginartifactId>
                 <version>3.1version>
                 <configuration>
                     <source>${java-version}source>
                     <target>${java-version}target>
                 configuration>
             plugin>

             <plugin>
                 <groupId>org.apache.maven.pluginsgroupId>
                 <artifactId>maven-war-pluginartifactId>
                 <version>2.4version>
                 <configuration>
                     <warSourceDirectory>src/main/webappwarSourceDirectory>
                     <failOnMissingWebXml>falsefailOnMissingWebXml>
                 configuration>
             plugin>
         plugins>
     build>
 project>

   剩下来需要修改的就是我们添加对应的文件和目录结构。修改之后的目录结构如下：

   详细的改动比较可以参考后面的附件。现在我们再按照文中描述的过程将该工程打包：

 

 mvn clean install

   我们再来创建一个利用这个新archetype的工程：

 

 mvn archetype:generate -DarchetypeGroupId=pl.maciejwalkowiak -DarchetypeArtifactId=servlet3-webapp-archetype -DarchetypeVersion=1.0.1 -DgroupId=com.yunzero -DartifactId=MavenDefaultProject -DinteractiveMode=false

 

   我们将执行完之后创建的工程转化为eclipse工程：

 

 mvn eclipse:eclipse

    然后再用eclipse导入进来：

 

 

    这个时候，我们如果再运行工程，会发现正常的输出页面。这样，整个工程的改造就完成了。

 

总结

    maven的archetype其实就是一个工程结构模板，如果我们需要定制一个需要的模板的话，可以自己按照固定的格式来添加需要的文件和目录。这里包括有pom.xml文件，里面的依赖关系等。通过这么一个小的改动就可以让我们快速的创建一个支持servlet 3.1的web工程了。在maven提供最新的支持servlet 3.1的archetype之前，这也算是一种临时的办法吧。其实看透了它的本质后，自己做一个也可以，不一定非要等到官方出来不可，万一人家就是不出来，逗你呢？

 

参考材料

http://maciejwalkowiak.github.io/servlet3-maven-archetype