4.3.4.3. 构建 War

buildWarCubaWarBuilding 类型的任务,会构建一个 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 - 如果设置成 truecontext.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:SingleAppCoreServletListenerSingleAppWebServletListener。通过上下文参数给这两个监听器传递所需要的所有参数。

    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">
    6. <!--Application components-->
    7. <context-param>
    8. <param-name>appComponents</param-name>
    9. <param-value>com.haulmont.cuba</param-value>
    10. </context-param>
    11. <!-- Web Client parameters -->
    12. <context-param>
    13. <description>List of app properties files for Web Client</description>
    14. <param-name>appPropertiesConfigWeb</param-name>
    15. <param-value>
    16. classpath:com/company/sample/web-app.properties
    17. /WEB-INF/local.app.properties
    18. file:${app.home}/local.app.properties
    19. </param-value>
    20. </context-param>
    21. <context-param>
    22. <description>Web resources version for correct caching in browser</description>
    23. <param-name>webResourcesTs</param-name>
    24. <param-value>${webResourcesTs}</param-value>
    25. </context-param>
    26. <!-- Middleware parameters -->
    27. <context-param>
    28. <description>List of app properties files for Middleware</description>
    29. <param-name>appPropertiesConfigCore</param-name>
    30. <param-value>
    31. classpath:com/company/sample/app.properties
    32. /WEB-INF/local.app.properties
    33. file:${app.home}/local.app.properties
    34. </param-value>
    35. </context-param>
    36. <!-- Servlet context listeners that load the application blocks -->
    37. <listener>
    38. <listener-class>
    39. com.vaadin.server.communication.JSR356WebsocketInitializer
    40. </listener-class>
    41. </listener>
    42. <listener>
    43. <listener-class>
    44. com.haulmont.cuba.core.sys.singleapp.SingleAppCoreServletListener
    45. </listener-class>
    46. </listener>
    47. <listener>
    48. <listener-class>
    49. com.haulmont.cuba.web.sys.singleapp.SingleAppWebServletListener
    50. </listener-class>
    51. </listener>
    52. </web-app>

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

单一 WAR 包只包含 coreweb 客户端 模块。如果需要部署 portal 模块,需要用另外的 WAR 包。

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