4.3.4.3. 构建 War

buildWar – CubaWarBuilding 类型的任务，会构建一个 WAR 包，包含所有的应用程序代码和所有的依赖包。需要在 build.gradle 文件的根目录声明。生成的 WAR 包会在项目的 build/distributions 目录。

可以通过 Studio 里的 Deployment > WAR Settings 界面配置这个任务。

任何 CUBA 应用程序包含至少两个 block：中间件（Middleware）和 web 客户端（Web Client）。所以部署程序最自然的方法就是创建两个单独的 WAR 包：中间件一个，web 客户端一个。这样做的话也可以在用户数量增长的时候方便进行扩展。但是单独的包会重复包含一些两边都依赖的包，因此会增加整个程序的大小。还有就是扩展的部署选择也不常用，反而会使得部署流程更加复杂。CubaWarBuilding 任务可以创建这两种类型的 WAR 包：每个 block 一个包，或者包含两个 block 的包，后面这种情况下，应用程序的那些 block 会在一个 web 应用程序里面被不同的类加载器加载。

给中间件和 web 客户端创建不同的 WAR 包

可以采用这样的 task 配置:

  1. task buildWar(type: CubaWarBuilding) {
  2.     appProperties = ['cuba.automaticDatabaseUpdate': 'true']
  3.     singleWar = false
  4. }

任务参数：

  • appName - web 应用程序的名称，默认值是读取 Modules prefix，比如 app。

  • appProperties - 定义应用程序属性键值对。这些属性会以 WAR 包里面的 /WEB-INF/local.app.properties 文件为基础增加。

    appProperties = ['cuba.automaticDatabaseUpdate': 'true'] 会在应用程序第一次启动的时候创建数据库，如果没有现成的数据库，需要设置这个参数。

  • singleWar - 如果要为 blocks 构建单独的 WAR，需要设置这个为 false。

  • includeJdbcDriver - 是否包含项目里当前使用的 JDBC 驱动，默认是 false。

  • includeContextXml - 是否包含项目里当前使用的 Tomcat 的 context.xml 文件，默认值是 false。

  • coreContextXmlPath - 如果 includeContextXml 设置为 true，使用这个参数设置一个配置文件的相对目录用来替换项目 context.xml 文件。

  • hsqlInProcess - 如果设置成 true，context.xml 里面的数据库 URL 会按照 HSQL in-process 模式修改。

  • coreProject - 用来作为 core 模块（Middleware）的 Gradle 项目。如果没定义，则会使用标准的 core 模块。

  • webProject - 用来作为 web 模块（Web Client）的 Gradle 项目。如果没定义，则会使用标准的 web 模块。

  • portalProject - 用来作为 portal 模块（Web Portal）的 Gradle 项目。如果项目包含了 portal 模块，需要设置这个参数，比如，portalProject = project(':app-portal')。

  • coreWebXmlPath, webWebXmlPath, portalWebXmlPath - 用来作为相应模块 web.xml 的文件的相对目录。

    使用自定义 web.xml 文件的例子:

    1. task buildWar(type: CubaWarBuilding) {
    2.     singleWar = false
    3.     // ...
    4.     coreWebXmlPath = 'modules/core/web/WEB-INF/production-web.xml'
    5.     webWebXmlPath = 'modules/web/web/WEB-INF/production-web.xml'
    6. }

  • logbackConfigurationFile - 日志配置文件的相对目录。

    示例:

    1. task buildWar(type: CubaWarBuilding) {
    2.     // ...
    3.     logbackConfigurationFile = 'etc/war-logback.xml'
    4. }

  • useDefaultLogbackConfiguration - 当设置成 true （也是默认值）的时候，这个任务会拷贝标准的 logback.xml 配置文件。

  • frontBuildDir - Front UI 构建生成的目录名称。默认是 build。如需自定义，可以修改这个参数。

创建单一的 WAR 包

需要创建包含中间件和 web 客户端 block 的单一 WAR 包，可以用下面这个配置：

  1. task buildWar(type: CubaWarBuilding) {
  2.     webXmlPath = 'modules/web/web/WEB-INF/single-war-web.xml'
  3. }

除了上面这些参数之外，以下这些参数也可以使用：

  • singleWar - 不设置或者设置成 true。

  • webXmlPath - 用来作为单一 WAR 包 web.xml 的文件相对目录。这个文件定义了两个 servlet 上下文的监听器，用来加载程序 block：SingleAppCoreServletListener 和 SingleAppWebServletListener。通过上下文参数给这两个监听器传递所需要的所有参数。

    single-war-web.xml 示例:

    1. <?xml version="1.0" encoding="UTF-8"?>
    2. <web-app xmlns="http://java.sun.com/xml/ns/javaee"
    3.          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    4.          xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"
    5.          version="3.0">
    7.     <!--Application components-->
    8.     <context-param>
    9.         <param-name>appComponents</param-name>
    10.         <param-value>com.haulmont.cuba</param-value>
    11.     </context-param>
    13.     <!-- Web Client parameters -->
    15.     <context-param>
    16.         <description>List of app properties files for Web Client</description>
    17.         <param-name>appPropertiesConfigWeb</param-name>
    18.         <param-value>
    19.             classpath:com/company/sample/web-app.properties
    20.             /WEB-INF/local.app.properties
    21.             file:${app.home}/local.app.properties
    22.         </param-value>
    23.     </context-param>
    25.     <context-param>
    26.         <description>Web resources version for correct caching in browser</description>
    27.         <param-name>webResourcesTs</param-name>
    28.         <param-value>${webResourcesTs}</param-value>
    29.     </context-param>
    31.     <!-- Middleware parameters -->
    33.     <context-param>
    34.         <description>List of app properties files for Middleware</description>
    35.         <param-name>appPropertiesConfigCore</param-name>
    36.         <param-value>
    37.             classpath:com/company/sample/app.properties
    38.             /WEB-INF/local.app.properties
    39.             file:${app.home}/local.app.properties
    40.         </param-value>
    41.     </context-param>
    43.     <!-- Servlet context listeners that load the application blocks -->
    45.     <listener>
    46.         <listener-class>
    47.             com.vaadin.server.communication.JSR356WebsocketInitializer
    48.         </listener-class>
    49.     </listener>
    50.     <listener>
    51.         <listener-class>
    52.             com.haulmont.cuba.core.sys.singleapp.SingleAppCoreServletListener
    53.         </listener-class>
    54.     </listener>
    55.     <listener>
    56.         <listener-class>
    57.             com.haulmont.cuba.web.sys.singleapp.SingleAppWebServletListener
    58.         </listener-class>
    59.     </listener>
    60. </web-app>

单个 WAR 包部署时所有的 sevlets 和 filters 需要通过编程的方式注册，参考Servlet 和过滤器的注册。

单一 WAR 包只包含 core 和 web 客户端 模块。如果需要部署 portal 模块，需要用另外的 WAR 包。

参考 部署 WAR 至 Jetty 章节详细介绍 WAR 部署的各种情况和步骤。