5.1. 项目

本节介绍可用于管理项目基础设施的编辑器和命令。

5.1.1. 项目属性编辑界面

Project Properties 编辑界面允许对项目进行配置。可以从 CUBA 主菜单中打开它，也可以通过双击项目树的 Project > Properties 项来打开。

基本设置

Main 选项卡显示基本设置。

  • Module prefix 字段显示项目模块的名称前缀。后面加上模块的名称决定了项目攻坚的名称，比如 sales-global 模块装配成 sales-global-0.1.jar 工件。如果要重命名模块，可以修改模块名前缀。例如，使用 wages 模块名前缀的基本 CUBA 项目有 wages-global、wages-core 和 wages-web 模块。

  • Artifact version 字段可以修改项目工件的版本。如果是 final build，可以不勾选 Snapshot，snapshot（快照版本）是可以被同名构建覆盖的版本。

  • Repositories 表格显示当前在项目中使用的仓库。Studio 扫描这些仓库以寻找可用的平台版本。使用该字段旁边的按钮配置对仓库的访问。有关详细信息，请参阅 文档。还可以在 build.gradle 中手动注册包含应用程序组件的其它仓库，并且仓库数量不受限制。

  • Platform version 显示项目中使用的 CUBA 平台版本。Change…​ 链接按钮可以用来升级平台版本，升级时会根据需要自动完成项目迁移。参阅 升级项目 了解更多。

  • Show unstable versions 复选框可以选择显示不稳定的 CUBA 版本，是指带有 BETA 或 SNAPSHOT 的版本。

  • Groovy support 复选框可以在应用程序内启用 Groovy 代码，比如，在界面控制器类中。

  • 如果需要更改应用程序服务的路径，请在 Tomcat path 字段中指定新路径。下一次执行 gradlew deploy 或 gradlew start 会将 Tomcat 安装到该位置。

  • Tomcat ports 分组允许为通过 快速部署 安装在 deploy/tomcat 文件夹中的 Tomcat 应用程序服务分配非标准端口。

  • 需要特别留意 HTTP port 字段，该字段 Tomcat 监听的 HTTP 连接端口，以及 cuba.webPort 、cuba.webAppUrl 、 cuba.restApiUrl 和 cuba.connectionUrlList 应用程序属性。

  • 在 AJP port 字段中，可以设置 AJP 连接器的端口。

  • 在 Shutdown port 字段中，可以设置 Tomcat 监听的 SHUTDOWN 命令端口。

  • 在 Debug port 字段中，可以设置 Tomcat 监听的 Java 调试器连接端口。如果更改了此端口，还应在 IDE 的调试配置中进行同步更改。

  • Available locales 字段允许设置应用程序可用的 本地化语言。单击该字段旁边的按钮打开语言环境编辑界面。位于编辑界面窗口中的 Locale select visible 复选框控制 cuba.localeSelectVisible 应用程序属性的值。 编辑界面还可以为 解析和格式化数据定义新的或覆盖已有的格式化字符串。

5.1.2. 项目依赖

Project Properties 对话框的 Dependencies 部分展示并管理项目的第三方依赖（库）。

dependencies

项目依赖在表格中按照模块分组展示，根据项目中选择模块的不同，一般有三个或更多的模块分组。 如果类库是添加到 global 模块，则在整个项目的范围内全局能用，因为其他的 CUBA 项目模块依赖于 global 模块。

表格中的 Type 列展示依赖的类型：

  • compile - 在编译和运行时使用的库

  • provided - 只在编译生产版本的应用程序时使用，不能包含在运行时的 classpath 中（比如 JDBC 驱动，Servlet API 的实现等。）

  • runtime - 只在运行时使用的库

  • testCompile - 在编译和测试时使用的库

  • testRuntime - 只在运行时测试使用的库

Text 列以 Gradle 依赖字符串的格式展示库的坐标：“group:name:version”。

依赖管理的操作在依赖列表的右侧显示：

  • Add dependency - 添加新的项目依赖。指定 Maven 依赖声明或 Gradle 依赖坐标。对话框会自动验证依赖声明是否正确。

  • Remove dependency - 从项目中移除依赖。

  • Edit dependency - 修改依赖声明的内容。

参阅 Gradle 文档 了解更多关于第三方依赖的内容。

添加新的第三方依赖

添加新的第三方依赖需要以下步骤：

  • 找到需要类库的 Maven 依赖声明或者 Gradle dependency string for the required library.

newdep gradle

newdep maven

  • 复制依赖声明至剪切板

  • 打开 Project Properties 对话框

  • 选择需要添加依赖的模块，或者用 global 模块声明项目全局依赖。

  • 点击 Dependencies 表格右边的 + 按钮打开 Dependency Editor 对话框。剪贴板的依赖声明会自动粘贴到这里。

  • 点击 Dependency Editor 对话框的 OK 按钮，如果有声明验证错误的话，请手动修复。

  • 点击 CUBA Project Properties 对话框的 OK 按钮应用修改。Studio 会在项目的构建脚本添加必须的声明，并刷新项目配置。

  • 现在可以在代码中使用库中的类了。

Tip

Gradle implementation ‘a.b.c’ 依赖类型目前还不支持，请使用 compile ‘a.b.c’ 代替。

添加 JAR 文件依赖

有时您需要添加一个 JAR 文件作为项目的依赖，但是此文件不在任何公共的或内部的 Maven 仓库。此时，需要手动修改 build.gradle 脚本文件。

  • 在项目的根目录创建 lib 文件夹；

  • 将 JAR 文件复制到该文件夹，比如， <my-project>/lib/custom-lib.jar

  • 打开 Gradle 构建脚本：CUBA 项目树 → Build Script → build.gradle；

  • 修改 build.gradle 文件，为 repositories 部分添加 flatDir ：

  1.     repositories {
  2.         maven {
  3.             ...
  4.         }
  5.         flatDir {
  6.             dirs "${project.rootDir}/lib"
  7.         }
  8.      }
  • 修改 build.gradle 的 configure(globalModule) 部分，添加指定的 JAR：
  1. configure(globalModule) {
  2.     ...
  3.     dependencies {
  4.         compile(name: 'custom-lib')
  5.     }
  6. }

  • 刷新 Gradle 项目配置；Gradle 工具窗口 → Reimport All Gradle Projects；

  • 现在可以在代码中使用该库的类。

5.1.3. 管理扩展插件

扩展插件是公共发布的全栈类库，用来对项目进行扩展使用其提供的附加功能。 可以参阅 CUBA 开发者手册 了解更多关于扩展和应用程序组件的知识。

CUBA Add-ons 对话框可以用来管理 CUBA 项目中引入的扩展插件。 可以通过下面的方式打开这个对话框：

  • 在 CUBA 项目树双击 Project → Add-ons

  • 从主菜单项： CUBA → Marketplace…​

该对话框有三个标签页： Marketplace、Installed 和 Updates。

5.1.3.1. 扩展插件市场

Marketplace 标签页展示发布的扩展中那些能与项目兼容的扩展插件。

addons market small

扩展按照类型分组。可以用过滤器查找需要的扩展，比如，”email” 或 “category:Translation”。

点击扩展的标题可以跳转到扩展的详情页，包括概览、兼容性、许可等信息：

addon details

如需安装一个或多个扩展，点击它们的 Install 按钮即可 然后点击 Apply 或 Apply & Close 按钮。 在确认之后，Studio 会对项目的构建脚本和配置文件做必要的修改、下载新的库并刷新 Gradle 项目的配置。

安装商业扩展插件在单独的章节介绍：商业扩展组件安装。

5.1.3.2. 使用坐标安装

扩展的坐标其实就是 Gradle 的依赖字符串，如， “com.mycompany.cuba-addons:myaddon:0.1.5”。 这个字符串可以在 CUBA 平台的网站上发布或者由扩展插件的作者自己发布。 如果该需要使用坐标（或使用 Gradle 依赖字符串）进行安装，点击 Updates 标签页标题右边的 “Install Add-on Manually” 图标：

addon by coords

5.1.3.3. 已安装的扩展插件

Installed 标签页展示已经安装的关联到当前项目的扩展插件。

addons installed

已安装的扩展插件按照两种分类进行分组。 Marketplace Add-Ons 是从 CUBA 市场安装的扩展。 Custom Add-Ons 是由第三方开发、发布在第三方仓库或者 Maven 本地仓库的扩展。

如果要在项目中移除关联的扩展，可以选中相应的扩展点击 Delete，或者右键点击扩展，选择 Uninstall。 然后在弹出框选择 Apply。Studio 会从项目的依赖移除该扩展并更新项目的配置。

5.1.3.4. 升级扩展插件

Studio 会自动检查项目中引入的扩展是否需要升级。 Updates 标签页显示可以升级的扩展的相关信息。

addons updates

如果要升级扩展，点击 Update 按钮，然后点击 Apply 或 Apply & Close 按钮。 Studio 会自动升级依赖、下载需要的类库并更新项目配置。

另外，在打开项目之后，也会在界面的右下角显示可用的升级信息：

addon update notification

5.1.4. 商业扩展组件安装

使用 CUBA 商业扩展组件需要进行订阅。可以在 CUBA 商店 网页购买。另外，如需评估扩展组件，可以新装特定扩展插件的试用版（有效期 30 天）。

下面介绍以下几种场景的安装方式：

5.1.4.1. 安装试用扩展插件

  • 打开 Marketplace 窗口，比如，从主菜单：CUBA → Marketplace。

  • 找到需要的扩展插件，点击旁边的 Install。

    addon try step1

  • 弹出的对话框中点击 Get free trial

  • 如果您还没有登录 CUBA user profile，则点击弹窗中的 Sign In…​

  • 注册或者登入 CUBA 网页

  • 阅读介绍并点击 Install Trial

    addon try step2

  • 点击 Apply。您的项目即能安装插件的试用版。

当试用版结束后，CUBA Studio 会提示您。保持 CUBA user profile 的登录状态，以免错过提醒。

Warning

注意，一旦试用扩展插件过期，您的项目将无法启动。

CUBA User Profile

登录 cuba-platform.com user profile 之后，可以查看试用扩展插件剩余的有效时间。

如果还未登录，可以通过 CUBA Add-Ons 窗口右上角的 Sign In to CUBA 按钮登录：

user profile sign in

将会重定向至浏览器登录。登录之后，IDE 中会收到通知，再次点击上面的按钮能打开一个弹窗，显示您个人信息以及可用的扩展插件试用：

user profile info

5.1.4.2. 安装购买的扩展插件

购买扩展插件后，您会收到 license key。可能与 Studio premium 的 key 一样，也可能是一个单独的 key（如果您没有订阅 Studio 或者是单独购买的扩展插件）。

  • 打开 Marketplace 窗口，比如通过主菜单：CUBA → Marketplace

  • 找到需要的扩展插件，并点击 Install

    addon install step1

  • 在弹窗中输入 license key。

    addon install step2

  • 在 Commercial Add-On Installation 弹窗中点击 Install

  • 点击 Apply 或 Apply & Close 按钮，然后在确认弹窗中点击 Continue

确认之后，Studio 会对项目的构建脚本和配置文件做必要的修改，然后下载新的依赖库并刷新 Gradle 项目配置。

5.1.4.3. 手动安装扩展插件

如果自动安装出现了任何问题，或者需要从命令行配置项目构建环境（比如，持续集成），则可以使用该方式进行手动安装商业扩展插件。

购买扩展插件后会收到一个 license key。用这个 key 配置 premium 仓库凭证。

添加 Premium 仓库

打开 build.gradle 文件，在仓库列表中 最后一行 添加：

  • 如果主仓库是 repo.cuba-platform.com，则添加 https://repo.cuba-platform.com/content/groups/premium

    1. buildscript {
    2.     // ...
    3.     repositories {
    4.         // ...
    5.         maven {
    6.             url 'https://repo.cuba-platform.com/content/groups/premium'
    7.             credentials {
    8.                 username(rootProject.hasProperty('premiumRepoUser') ?
    9.                         rootProject['premiumRepoUser'] : System.getenv('CUBA_PREMIUM_USER'))
    10.                 password(rootProject.hasProperty('premiumRepoPass') ?
    11.                         rootProject['premiumRepoPass'] : System.getenv('CUBA_PREMIUM_PASSWORD'))
    12.             }
    13.         }
    14.     }
    15. }

  • 如果主仓库是 Bintray，则添加 https://cuba-platform.bintray.com/premium

    1. buildscript {
    2.     // ...
    3.     repositories {
    4.         // ...
    5.         maven {
    6.             url 'https://cuba-platform.bintray.com/premium'
    7.             credentials {
    8.                 username(rootProject.hasProperty('bintrayPremiumRepoUser') ?
    9.                         rootProject['bintrayPremiumRepoUser'] : System.getenv('CUBA_PREMIUM_USER'))
    10.                 password(rootProject.hasProperty('premiumRepoPass') ?
    11.                         rootProject['premiumRepoPass'] : System.getenv('CUBA_PREMIUM_PASSWORD'))
    12.             }
    13.         }
    14.     }
    15. }

提供仓库凭证

您的 license key 包含两部分：短横前的部分为仓库用户名，短横后的部分为密码。比如，如果您的 key 是 111111222222-abcdefabcdef，则 111111222222 是用户名，abcdefabcdef 是密码。如果使用的是 Bintray 仓库，用户名后面需要加上 @cuba-platform。

可以使用下面的一种方式为仓库提供凭证：

  • 推荐的方式是在用户主目录（比如，windows 上：C:\users\john\.gradle\gradle.properties；Mac 上：/Users/helen/.gradle/gradle.properties）创建一个 ~/.gradle/gradle.properties 文件。然后添加下列内容：

    1. premiumRepoUser=111111222222
    2. bintrayPremiumRepoUser=111111222222@cuba-platform
    3. premiumRepoPass=abcdefabcdef

  • 或者，通过环境变量 CUBA_PREMIUM_USER 和 CUBA_PREMIUM_PASSWORD 设置。

  • 当在命令行运行 Gradle 任务时（比如持续集成环境中），可以用 -P 前缀将变量传递给 Gradle，示例：

    1. gradlew assemble -PpremiumRepoUser=111111222222 -PpremiumRepoPass=abcdefabcdef
Tip

IDE 中可以通过 CUBA → Advanced → Edit Gradle Properties 菜单打开 ~/.gradle/gradle.properties 进行编辑。

添加组件

  1. 在 build.gradle 文件中的 dependencies 部分按照下面例子的格式指定组件的坐标：

    1. com.haulmont.addon.<addon-name>:<addon-name>-global:<addon-version>

    示例：

    1. dependencies {
    2.     //...
    3.     appComponent('com.haulmont.addon.maps:maps-global:1.3.0')
    4. }

  2. 在 core、web（以及 portal，如果有的话）模块的 web.xml 文件的 appComponents 上下文中添加扩展插件的标识符，示例：

    1. <context-param>
    2.     <param-name>appComponents</param-name>
    3.     <param-value>com.haulmont.cuba com.haulmont.addon.maps</param-value>
    4. </context-param>

  3. 如果是从命令行运行 Gradle，执行 gradlew assemble 后，扩展插件即能安装。

5.1.5. 模块管理

Studio 允许创建、编辑和删除项目的可选模块： core 、 gui 、 web 、 web-toolkit 、 portal 和 front。可以使用 CUBA > Advanced > Manage Modules 主菜单或从项目树的 Project 项的右键菜单中执行此操作。

manage modules from tree

当您创建一个新项目，默认包含 global、core 和 web 模块。

自动模块管理

注意，在某些情况下，Studio 会自动为您的项目添加模块。

比如，Studio 检测到项目中有两个或多个定义 widgetsets（带有客户端侧 Vaadin 代码的组件） 的扩展插件时，会自动添加 web-toolkit 模块。此时，项目中有 web-toolkit 模块才能构建完整的 widgetsets，包含 CUBA 和所有扩展插件使用正确 Vaadin 版本编译的 UI 组件客户端侧代码。

auto web toolkit notification

5.1.6. 管理数据存储

5.1.6.1. 主数据存储

主数据存储指定连接至 CUBA 应用程序使用的主数据库的信息。该数据存储包含系统实体，是 CUBA 项目不可缺少的存储。

Main Data Store Properties 窗口展示主数据存储的配置。 可以通过以下方式打开该窗口：

  • 在 CUBA 项目树双击 Project → Data Stores → Main Data Store。

  • 从主菜单点击： CUBA → Main Data Store Settings…​。

5.1.6.2. 数据存储属性

下列属性可以为主数据存储和附加数据存储配置：

  • Define JDBC DataSource in - 决定使用哪个组件创建数据库连接池（需要项目基于 CUBA 7.2+）。可选值为：Application 和 JNDI。

    • Application - 通过 CUBA 平台使用 HikariCP 库创建和管理连接池。推荐使用该模式。

    • JNDI - 通过应用程序服务器创建连接池并放入 JNDI。CUBA 应用程序使用 JNDI 名称从 JNDI registry 获取数据源。

  • Database type - 数据库服务的类型 。Studio 开箱支持 PostgreSQL、Microsoft SQL Server、Oracle、MySQL、MariaDB、Amazon RedShift 以及 HSQLDB。如果需要，也可以集成其他数据库，参阅 本章节 了解细节。

  • Database URL - 指定主机、端口以及数据库名称。

  • Connection params - 指定其他连接参数。连接参数的格式依赖所选的数据库。字符串需要在数据库名称和参数之间包含一个分隔符。 比如，指定一个 Microsoft SQL Server 2008+ 实例名称，在该字段使用下列字符串：

    1. ;instanceName=myinstance

    可以使用 Connection params 字段旁边的 “铅笔” 按钮方便的输入连接参数。此时，Studio 会使用数据库特定的分隔符将参数组成连接串。

  • Custom database URL - 指定一个自定义的数据库连接 URL。这里需要提供 Host 和 Database 名称，单独用于创建数据库。

  • Database user and Password - 数据库连接凭证。

  • Integrated Security - 当连接至 Microsoft SQL Server 2012+ 数据库时，启用相应的验证选项。

如果是 HSQLDB，Studio 本身会提供数据库服务，并将数据文件保存在 build/hsqldb 文件夹。

add store settings

5.1.6.3. 用环境变量做连接参数

一些数据库连接参数可以通过环境变量指定。这样开发团队可以避免在版本控制软件中存储这些参数。支持下列参数：

  • database host,

  • database port,

  • database name,

  • user,

  • password.

数据存储需要设置 Define JDBC DataSource In 为 Application。

比如，定义环境变量：

  1. PG_DB_HOST=127.0.0.1
  2. PG_DB_NAME=salespg
  3. PG_DB_USER=admin
  4. PG_DB_PASSWORD=admin

重启 IDE 重新获取环境变量。然后修改 core 模块 app.properties 文件内的数据库连接配置：

  1. cuba.dataSourceProvider=application
  2. cuba.dataSource.username=${PG_DB_USER}
  3. cuba.dataSource.password=${PG_DB_PASSWORD}
  4. cuba.dataSource.dbName=${PG_DB_NAME}
  5. cuba.dataSource.host=${PG_DB_HOST}
  6. cuba.dataSource.port=

Studio 对该功能的支持：

  • Data Store Properties 对话框能正确检测并显示配置值。

  • Create database、Update database、Generate database scripts 和 Generate Model 操作能从环境变量取值。

  • 调试用的 Tomcat 能从环境变量取值。

检测到的配置值在 Data Store Settings 窗口以只读的形式展示，如需改动，则需要手动修改 app.properties 文件。

db conn env props

5.1.6.4. 附加数据存储

You can add additional data stores to the project in order to store data in separate database, or to allow CUBA application reading data produced by another system.

如需在项目中创建附加数据存储，在 CUBA 项目树右键点击 Data Stores，选择 New → Additional Data Store。 项目中注册的附加数据存储作为 Data Stores 部分的子项展示：

additional stores

当创建或编辑数据存储时，会弹出 Data Store 对话框，有如下字段：

  • Data store name - 数据存储的名称。只能包含字母和下划线，并且不能与项目名称相同。

  • Data store type - 数据存储的类型：RdbmsStore 或 Custom，参阅 文档 了解细节。

  • DataSource JNDI name - Studio 基于数据存储的名称自动设置。

  • 对于 RdbmsStore，需要指定下面描述的附加的属性。

  • DB schema management - 选择 Studio 管理数据库和跟踪实体变化的模式。

DB Schema 管理模式

与主数据存储不同，CUBA 应用程序和 Studio 对于附加数据存储的使用，有几种使用模式。

  1. 3rd-party database - 第三方数据库。在这个场景中，为 CUBA 应用程序接入一个由其他系统产生的数据库，目的是从数据存储级别做系统集成。此时，数据结构和数据格式都由外部系统完全控制，CUBA 不应当尝试修改或 drop 任何已有的表。不需要重新创建对应实体，而很大程度上可以通过 Studio 的生成模型功能导入。

  2. Shared database - 共享数据库。 在这个场景中，也是由于系统集成，为 CUBA 应用程序接入了已存在的数据库。但不一样的是，这里数据库的目的是在多个应用程序之间共享，CUBA 可以创建其自己的表，也可以修改已经存在的表。应用程序操作数据库的边界可以通过数据库角色权限控制。可以用实体设计器创建实体也可以通过生成模型功能导入。Studio 可以更新数据库 schema，但是不能重新创建数据库。

  3. Owned database - 独享数据库。在这个场景中，数据库是计划完全由 CUBA 应用程序控制。Studio 可以重新创建数据库，因为项目的数据库模型有初始化数据库的所有信息。实体通过实体设计器创建。

根据上面介绍的场景，您可以根据需要决定用哪种方式管理数据库结构：

  1. Disabled - Studio 不跟踪该存储的数据库结构变化。这是默认模式，以前版本的 Studio 也是这个行为。如果是接入 第三方 数据库，则推荐使用此模式。

  2. Update Only - Studio 能生成数据库 更新 脚本并能根据数据模型更新数据库。但是，Studio 没法重新创建数据库。这个模式可以用在 共享 数据库场景。

  3. Create and Update - Studio 创建完整的 初始化 和 更新 数据库的脚本，并提供从头创建数据库的能力（使用 Gradle 任务或者 UI 操作）。该模式可用在 独享 数据库场景。

5.1.6.5. 数据存储操作

在 CUBA 项目树右键点击数据存储可以看到菜单：

data store context menu

根据数据存储的类型和数据库 schema 管理模式，菜单内容会有所不同。

  • Delete Data Store - 从项目删除该数据存储，包括所有的配置文件及数据库迁移脚本。

  • Edit Data Store - 打开对话框编辑数据存储设置。

  • Create Database - 重新创建选择的数据存储。可用在主数据存储和 Create and Update 管理模式的附加数据存储。

  • Update Database - 更新选择的数据存储，运行那些还没有运行过的更新脚本。可用在主数据存储和 Update only 或 Create and Update 管理模式的附加数据存储。

  • Generate Database Scripts…​ - 为选中的数据存储生成 DDL 脚本，通过比较数据模型和数据库 schema 实现。可用在主数据存储和 Update only 或 Create and Update 管理模式的附加数据存储。

  • Generate Model…​ - 从选中的数据库 生成数据模型。

5.1.6.6. 数据库初始化和更新脚本

主数据存储 和使用 Create and Update 或 Update Only shema 管理模式的附加数据存储可以使用 数据库初始化和更新脚本 ，这些脚本显示在数据存储之下：

db scripts

  • Init 脚本包含重新创建数据库的 DDL 和 DML 语句，建立数据库以匹配当前的数据模型状态。

  • Update 脚本包含更新数据库的脚本，可以对之前任意状态的数据库进行更新，以匹配当前的数据模型状态。

Studio 会根据数据模型的更改自动维护初始化和更新脚本，阅读 数据库迁移 部分了解更多细节。

如果需要，也可以创建附加的数据库脚本。只需在 CUBA 项目树的 Data Stores → Main Data Store 或 Data Stores → (Name of the additional data store) 部分使用下面的操作：

  • init → 右键菜单 → New → Database init script

  • update → 右键菜单 → New → Database update script

new update script

5.1.6.7. 附加 JDBC 驱动

当生成数据库迁移脚本时，Studio 会连接至数据库，因此需要数据库对应的 JDBC 驱动。Studio 默认包含下列 DBMS 类型的 JDBC 驱动：

  • PostgreSQL

  • HSQLDB

  • Microsoft SQL Server

  • MariaDB

  • MySQL（使用 MariaDB 驱动）

如果是用下列 DBMS 类型，则需要手动下载 JDBC 驱动并添加至 Studio：

  • Oracle

  • Amazon RedShift

  • MySQL（使用适当的驱动）

添加驱动可以通过配置界面操作：主菜单 → CUBA → Settings → Database Proprietary Drivers。

当集成自定义数据库时，需要手动复制驱动至 {USER_HOME}/.haulmont/studio/lib 文件夹（比如，windows：C:\Users\{username}\.haulmont\studio\lib）。此文件夹也可以用来存放已经支持的数据库的其他驱动程序。

手动添加驱动后，别忘了下面的步骤：

  • 重启 IDE。

  • 停止 Gradle daemon（在终端执行 gradlew --stop）。

5.1.7. 部署设置

Studio 中有一些与部署相关的编辑界面，用于对构建部署工件的 Gradle 任务进行设置。可以通过 CUBA > Deployment 主菜单打开这些编辑界面，也可以通过双击项目树中的 Project > Deployment 项来打开。

deployment settings

WAR 设置

WAR Settings 编辑界面允许设置 WAR 文件的构建配置。完成设置后，会在 build.gradle 中创建 buildWar 任务。

  • Build WAR - 如果选中，buildWar 任务会被配置在 build.gradle 中。

  • Include JDBC driver - 是否应将 JDBC 驱动程序包含在 WAR 文件中。

  • Single WAR for Middleware and Web Client - 是否构建将中间件和 Web 客户端应用程序 block 打包到一起的单个 WAR。

  • Custom web.xml path 指定用于单 WAR 的特定 web.xml 文件。单击 Generate 可自动创建此文件。

  • Logback configuration file - logback.xml 配置文件相对于项目根目录的路径。单击 Generate 以自动创建此文件。

  • 对基于 CUBA 版本 7.2 及以上版本的项目：

    • Custom data store configuration - 可以指定 WAR 工件要使用的自定义数据存储配置。

  • 对基于 CUBA 7.1 及以下版本：

    • Include Tomcat’s context.xml - 是否需要再 WAR 文件中包含 context.xml（Tomcat 部署描述文件）。

    • Custom context.xml path - 相对于项目根目录指定 context.xml Tomcat 部署描述文件。如果勾选了 Include Tomcat’s context.xml，则启用该配置。点击 Generate 自动创建该文件。

  • App properties - 要为此部署定义的一组应用程序属性。这些属性会添加到 WAR 内的 /WEB-INF/local.app.properties 文件中。

如果在设置中开启了相应的属性，则会显示 Build WAR 子元素。点击会执行 gradlew buildWar 任务。

Uber JAR 设置

UberJAR Settings 编辑界面允许对 Uber JAR 的构建进行设置。完成设置后，会在 build.gradle 中创建 buildUberJar 任务。

  • Build Uber JAR - 如果选中，buildUberJar 任务会被配置在 build.gradle 中。

  • Single Uber JAR - 如果选中，buildUberJar 任务会将所有应用程序模块打包到一起，创建一个 Uber JAR。

  • Logback configuration file - logback.xml 配置文件相对于项目根目录的路径。单击 Generate 可自动创建此文件。

  • 对基于 CUBA 版本 7.2 及以上版本的项目：

    • Custom data store configuration - 可以指定 UberJAR 工件要使用的自定义数据存储配置。

  • 对基于 CUBA 7.1 及以下版本：

    • Custom Jetty environment file - 嵌入式 Jetty 服务使用的 jetty-env.xml 配置文件路径，相对于项目根目录。单击 Generate 可自动创建此文件。

  • App properties -要为此部署定义的一组应用程序属性。这些属性将被添加到 Uber JAR 内的 /WEB-INF/local.app.properties 文件中。

  • Core port、 Web port、 Portal port 字段允许为相应应用程序块的嵌入式服务设置端口。如果选中 Single Uber JAR，这些字段就不设置了。默认端口值在 文档 中有描述。在运行 JAR 时可以使用 -port 命令行参数设置端口。

如果在设置中开启了相应的属性，则会显示 Build UberJAR 子元素。点击会执行 gradlew buildUberJar 任务。

5.1.8. 配置接口

使用配置接口机制可以很方便的使用应用程序配置参数，通过 Java 接口方法实现，因此能提供对这些属性类型安全的访问。

Studio 在项目树的 Project → Config Interfaces 部分展示项目中所有的配置接口：

config interfaces tree

如需创建新的配置接口，在项目树选中 Config Interfaces ，然后在右键菜单中选择 New → Configuration Interface，然后会弹出 New CUBA Config 对话框：

create config interface

  • Module - 选择配置接口所在模块

  • Class - 接口类名称

  • Package - 接口类包名

  • Source type - 选择属性值保存的位置：

    • DATABASE - 属性值保存在数据库

    • APP - 属性值保存在 app.properties 文件

    • SYSTEM - 属性值从 JVM 的系统参数获取

可以在 开发者手册 相应章节了解更多配置接口的信息。

5.1.9. 日志

CUBA 项目树的 Logging 部分有以下目的：

  • 展示本地 Tomcat 调试服务的日志文件

  • 开发者可以创建并修改项目特定的日志配置。

logging tree

日志文件展示在两个文件夹中，反映它们在文件系统的真实位置。当应用程序部署至生产环境时，也能看到同样的目录结构：

这里展示的 logback.xml 是一个自定义的日志配置文件，位于项目根目录的相对路径 etc/logback.xml 下。CUBA 用这个文件作为本地调试的 Tomcat 服务日志配置。默认也会用同一个文件作为 WAR 配置 和 UberJar 配置 中的日志配置文件。可以创建自定义的日志配置文件，右键点击 CUBA 项目树的 Logging，然后选择 Generate Logback Configuration File…​ ：

create logback xml

可以修改生成的 logback.xml 文件，比如，可以添加自己的 appender 并且根据类别限定日志的输入。参阅 logback 手册 了解更多的日志配置。