[106901] Maven 工程中使用 Velocity Tools View 3.0

本文是在某高校为学生授课后整理的笔记，同道中人可以任意传播，唯独期望在 CxDN 上全文照抄时，注明原文出处

1、配置 Maven

Apache Maven 下载地址: http://maven.apache.org/download.cgi ( 本文撰写时最新版本为 3.5.3 )。

下载好 Apache Maven 后，将 Apache Maven 解压( 本文假设将 Maven 解压到 C:/applications 目录 )。

进入 Apache Maven 主目录 ( C:/applications/apache-maven-3.5.3 ) 目录下的 conf 目录中，

随后 将 conf 目录下的 settings.xml 文件复制一份，并重命名为 settings_bak.xml ，

再用EditPlus等文本编辑软件修改 settings.xml ，修改本地仓库位置( 这里约定为 C:/repository 目录 ):

<!-- localRepository
 | The path to the local repository maven will use to store artifacts.
 |
 | Default: ${user.home}/.m2/repository
<localRepository>/path/to/local/repo</localRepository>
-->
<localRepository>C:/repository</localRepository>

然后在 <mirrors> 和 </mirrors> 之间插入以下内容:

<!-- 由阿里云提供的Maven中央仓库镜像 -->
<mirror>
    <id>nexus-aliyun</id>
    <name>Nexus aliyun</name>
    <url>http://maven.aliyun.com/nexus/content/groups/public/</url>
    <mirrorOf>*</mirrorOf>
</mirror> 

<!-- 由 Apache 提供的仓库 -->
<mirror>
    <id>apache-repo</id>  
    <name>apache Repository</name>  
    <url>https://repository.apache.org/content/groups/public/</url> 
    <mirrorOf>apache-repo</mirrorOf> <!-- 注意，这里必须写 apache-repo -->
</mirror> 

注意，apache Repository 的 mirrorOf 必须写 apache-repo ，否则将导致无法从 apache Repository 下载  velocity-tools-view ( 3.0-SNAPSHOT ) 。

2、创建 Maven 工程

这里使用 IntelliJ IDEA 创建 Maven 工程。

首先启动 IntelliJ IDEA ，在下图所示区域中点击 "Create New Project" :

在 "New Project" 窗口的左侧点击 "Maven" 后，勾选 "Create from archetype"，再选中 "org.apache.maven.archetypes:maven-archetype-webapp"，如下图示:

上图中点击右下角 "Next" 进入下一步，并在新开启的界面中输入 GroupId 和 ArtifactId ，如图:

输入GroupId 和 ArtifactId后，点击 "Next" 进入下一步(如下图所示)。

点击上图中红色箭头所指向的按钮，在新弹出的 "Select Maven Home Directory" 对话框中选择 Maven 主目录( 之前约定位置是 C:/applications/apache-maven-3.5.3 )，随后点击 "OK" 按钮确定。

选择 Maven 主目录后的界面如下图所示(红线上方是选择的 Maven 主目录，下方是正在使用的 Maven 版本):

随后在上图中，勾选 红色箭头指向的 复选框，再点击蓝色箭头指向的 按钮 弹出 "Select User Settings File" 对话框，并在其中选择Maven配置文件(根据之前约定，应该是  C:/applications/apache-maven-3.5.3/conf/settings.xml )，选择完成后点击 "OK" 按钮确定。

因为之前在 Maven 中指定过本地仓库的位置(之前约定的是 C:/repository )，所以在选择Maven的配置文件之后，"Local repository" 被自动更换为 Maven 中指定的本地仓库位置。(如下图所示)

以上配置完成后，点击 "Next" 按钮进入下一步操作(如下图所示)。在下一步的界面中，可以看到之前的 ArtifactId 即为 Project name，同时 Project location 的后缀也是 ArtifactId .

(建议: 将所有的 IDEA 工程放到同一个目录中，比如我的所有IDEA工程都放在 C:/IdeaProjects 中 )

最后，点击 "Finish" 按钮即可创建一个 Maven 工程(Web工程) 。 新创建的工程结构如下图所示:

如果是第一次使用IDEA创建 Maven 工程，可能会有一个漫长的等待过程(IDEA要下载maven插件)。

3、配置仓库

完全创建好 Maven 工程后，IDEA会直接打开当前工程的 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.0</modelVersion>
  <groupId>org.malajava</groupId>
  <artifactId>hello</artifactId>
  <packaging>war</packaging>
  <version>1.0-SNAPSHOT</version>
  <name>hello Maven Webapp</name>
  <url>http://maven.apache.org</url>
  <dependencies>
    <dependency>
      <groupId>junit</groupId>
      <artifactId>junit</artifactId>
      <version>3.8.1</version>
      <scope>test</scope>
    </dependency>
  </dependencies>
  <build>
    <finalName>hello</finalName>
  </build>
</project>

随后，在 build 内部添加 maven 插件:

<build>

   <finalName>hello</finalName>

    <plugins>

      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-compiler-plugin</artifactId>
        <version>3.1</version>
        <configuration>
          <source>1.8</source>
          <target>1.8</target>
          <compilerVersion>1.8</compilerVersion>
          <encoding>UTF-8</encoding>
        </configuration>
      </plugin>

      <plugin>
        <groupId>org.eclipse.jetty</groupId>
        <artifactId>jetty-maven-plugin</artifactId>
        <version>9.4.8.v20171121</version>
        <configuration>
          <httpConnector>
            <port>8080</port> <!-- 这里指定 jetty 服务的端口号 -->
          </httpConnector>
          <useTestClasspath>true</useTestClasspath>
          <webAppConfig>
            <contextPath>/</contextPath> <!-- 这里指定在浏览器访问时，当前Web应用的根路径 -->
          </webAppConfig>
        </configuration>
      </plugin>

    </plugins>

</build>

因为 Apache Tomcat 提供的 maven 插件仅仅支持到 Tomcat 7.x ，而 Tomcat 7.x 不支持 Servlet 3.1 新特性，所以这里选择了插件更新较快的 jetty 做 Servlet 容器。

最后在 pom.xml 文件末尾追加以下内容:

  <repositories>
    <repository>
      <id>nexus-aliyun</id>
      <name>Nexus aliyun</name>
      <url>http://maven.aliyun.com/nexus/content/groups/public/</url>
      <releases>
        <enabled>true</enabled>
      </releases>
      <snapshots>
        <enabled>true</enabled>
      </snapshots>
    </repository>
    <repository>
      <id>apache-repo</id>
      <name>apache Repository</name>
      <url>https://repository.apache.org/content/groups/public/</url>
      <releases>
        <enabled>true</enabled>
      </releases>
      <snapshots>
        <enabled>true</enabled>
      </snapshots>
    </repository>
  </repositories>

4、添加依赖

在 pom.xml 的 dependencies 中添加 servlet-api 和 velocity-tools-view 依赖:

  <dependencies>

    <dependency>
      <groupId>junit</groupId>
      <artifactId>junit</artifactId>
      <version>3.8.1</version>
      <scope>test</scope>
    </dependency>

    <dependency>
      <groupId>javax.servlet</groupId>
      <artifactId>javax.servlet-api</artifactId>
      <version>3.1.0</version>
      <scope>provided</scope>
    </dependency>


    <dependency>
      <groupId>org.apache.velocity</groupId>
      <artifactId>velocity-tools-view</artifactId>
      <version>3.0-SNAPSHOT</version>
    </dependency>

  </dependencies>

以上依赖中，junit 为 IDEA 创建 Maven 工程时默认添加，如果并不使用单元测试可以将该依赖删除。

5、部署 VelocityViewServlet

由 IDEA 创建的 Maven 工程中，src/main/webapp 是 Web 主目录，其中的 WEB-INF/web.xml 所使用的 Servlet 版本太低(默认是2.3)，因此建议使用以下内容替换原来的 WEB-INF/web.xml 中的内容。

<?xml version="1.0" encoding="UTF-8"?>

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

    <servlet>
        <servlet-name>VelocityViewServlet</servlet-name>
        <servlet-class>org.apache.velocity.tools.view.VelocityViewServlet</servlet-class>
    </servlet>

    <servlet-mapping>
        <servlet-name>VelocityViewServlet</servlet-name>
        <url-pattern>*.vm</url-pattern>
    </servlet-mapping>

</web-app>

同时，在修改后的 WEB-INF/web.xml 中，已经部署了 VelocityViewServlet 。

注意，这里的url-pattern仅匹配以vm为后缀的路径，因此将来创建的Velocity模版文件应该以vm为后缀。

6、创建 HelloServlet

对于 IDEA 新创建的 Maven 工程来说，其 src/main 目录下是没有 java 目录的，因此需要在 main 目录下创建名称为 java 的目录( 在 main 目录点击右键后，选择 "New" --> "Directory" --> 输入名称后确定即可 )。

在 src/main 目录下创建 java 目录后，它并不是一个可以存放 Java 源代码的目录，需要标记一下。

因此，右键点击新创建的 java 目录，选择 "Mark Directory As" 后再点击 "Sources Root" 即可(如下图)。

随后，在 java 目录上点击右键，选择 "New" --> "Package" ，输入包名后点击 "OK" 确定(如下图)。

接下来在 org.malajava.servlet 包上点击右键，选择 "New" --> "Java Class" ，创建名称为 HelloServlet 的类，其中内容如下:

package org.malajava.servlet;


import javax.servlet.ServletException;
import javax.servlet.annotation.WebServlet;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import java.io.IOException;

@WebServlet("/hello/velocity")
public class HelloServlet extends HttpServlet {

    @Override
    protected void service( HttpServletRequest request, HttpServletResponse response )
            throws ServletException, IOException {

        request.setAttribute( "username" , "malajava" );

        String path = "/WEB-INF/templates/hello.vm" ;

        request.getRequestDispatcher( path ).forward(request,response);

    }

}

在 HelloServlet 重写的 service 方法中，只做了两件事:

• 向 request 对象中添加 名称是 username 的属性，取值为 malajava
• 将请求转发到 /WEB-INF/templates/hello.vm ( 这里的 hello.vm 就是 Velocity 模版文件 ) 

特别说明:

• 如非特殊需要，没有必要非得重写 javax.servlet.http.HttpServlet 类的 doGet 和 doPost 方法，只需要重写 HttpServlet 类的 service( HttpServletRequest , HttpServletResponse ) 方法即可。
• 重写 service( HttpServletRequest , HttpServletResponse ) 方法后，不论 GET 请求还是 POST 请求又或者是其它方式的请求，都将交给该方法处理。
• HttpServlet 类的 service( HttpServletRequest , HttpServletResponse ) 方法主要负责解析客户端的请求方式，根据不同的请求方式调用不同的方法，比如客户端使用GET方式发起请求，就调用 doGet 方法。

7、创建 Velocity 模板

为了不让用户直接访问模板文件，我们将模版文件统一放在 WEB-INF 内部的 templates 目录中。
(注意，这个操作并不是必须的，你可以根据你的爱好和需要进行存放)

先在 WEB-INF 中创建 templates 目录，然后在 WEB-INF/templates 目录下创建 hello.html 。

最后，在 hello.html 文件上点击右键，选择 "Refactor" --> "Rename" 将该文件重命名为 hello.vm 。

重命名后，直接双击打开 hello.vm ，IDEA 会直接调用其 Velocity 编辑器来编辑 hello.vm 文件。

同时在 WEB-INF/templates/hello.vm 文件中添加:

<h1>Hello , $!{username} !</h1>

这里，${username} 是 Velocity 中的正式引用，$!{username} 属于静默引用，其中的 username 是 HelloServlet 中向 request 中添加的属性的名称。

( 有关 Velocity 的引用、变量、循环等内容，这里不做介绍 )

最终的 hello.vm 内容如下:

<!DOCTYPE html>

<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Hello</title>
</head>
<body>

    <h1>Hello , $!{username}</h1>

</body>
</html>

8、启动 jetty 服务器

在 IDEA 右侧的侧边栏，点击 "Maven Projects" 展开 "Maven Projects" 视图，展开当前工程下的 Plugins 后，再展开 jetty ，然后选中 jetty:run 后点击右键，选择 " Run 'hello [jetty:run]' " 即可启动 jetty :

启动成功后，在控制台中输出日志如下:

9、访问 HelloServlet

在开发 HelloServlet 时，我们在 HelloServlet 类上添加了 @WebServlet( "/hello/velocity" )，

因此打开浏览器后，直接输入 http://localhost:8080/hello/velocity 即可访问 HelloServlet ，如图:

其中，malajava 是从 request 对象的属性中获取到的值。

10、解决中文字符乱码问题

为了解决中文乱码问题，我们准备开发一个字符编码过滤器。

1)、创建 org.malajava.filter 包

在 src/main/java 目录上 点击右键，选择 "New" --> "Package" ，创建 org.malajava.filter 包

2)、创建 CharacterEncodingFilter 的类

右键点击 org.malajava.filter 包，选择 "New" --> "Java Class" ，创建 CharacterEncodingFilter 类。

CharacterEncodingFilter 类的具体内容如下:

package org.malajava.filter;

import javax.servlet.*;
import javax.servlet.annotation.WebFilter;
import java.io.IOException;


public class CharacterEncodingFilter implements Filter {

    @Override
    public void init(FilterConfig filterConfig) throws ServletException {
    }

    @Override
    public void doFilter(ServletRequest request, ServletResponse response, FilterChain filterChain) throws IOException, ServletException {
        request.setCharacterEncoding( "UTF-8" );
        response.setCharacterEncoding( "UTF-8" );
        filterChain.doFilter( request , response );
    }

    @Override
    public void destroy() {
    }

}

3)、部署 CharacterEncodingFilter

从 Servlet 3.0 开始，支持在 javax.servlet.Filter 实现类上添加 @WebFilter 来部署相应的过滤器。

我们为了将 CharacterEncodingFilter 当作工具类来使用，并追求最大程度的灵活性，依然选择在 web.xml 中部署 CharacterEncodingFilter 。

部署 CharacterEncodingFilter 后的 web.xml 如下:

<?xml version="1.0" encoding="UTF-8"?>

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

    <!-- 字符编码过滤器 -->
    <filter>
        <filter-name>CharacterEncodingFilter</filter-name>
        <filter-class>org.malajava.filter.CharacterEncodingFilter</filter-class>
    </filter>

    <filter-mapping>
        <filter-name>CharacterEncodingFilter</filter-name>
        <url-pattern>/*</url-pattern>
    </filter-mapping>

    <!-- 指定 Velocity 模版处理器 ( 由一个Servlet来处理 ) -->
    <servlet>
        <servlet-name>VelocityViewServlet</servlet-name>
        <servlet-class>org.apache.velocity.tools.view.VelocityViewServlet</servlet-class>
    </servlet>

    <servlet-mapping>
        <servlet-name>VelocityViewServlet</servlet-name>
        <url-pattern>*.vm</url-pattern>
    </servlet-mapping>


</web-app>

至此，即使是在 HelloServlet 中向 request 中添加中文属性值，到了 hello.vm 页面上也会正常显示。

在 HelloServlet 中向 request 添加中文属性值:

    protected void service( HttpServletRequest request, HttpServletResponse response )
            throws ServletException, IOException {

        request.setAttribute( "username" , "张三丰" );

        String path = "/WEB-INF/templates/hello.vm" ;

        request.getRequestDispatcher( path ).forward(request,response);

    }

访问 /hello/velocity 后在 hello.vm 中的显示结果:

本文在 macOS 下完成，为照顾大部分同学，抓图部分有修改 ( 路径改为 Windows 风格 ) 。

有鉴于时间和精力有限，本文中难免错误和疏漏，不当之处，敬请指正。

转载于:https://my.oschina.net/malajava/blog/1633684