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 选择平台的版本。如果选择了较新版本，则会根据需要决定是否会执行版本的自动迁移。

  • 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。

Marketplace 标签页

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

addons market small

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

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

addon details

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

使用坐标安装扩展

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

addon by coords

Installed 标签页

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

addons installed

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

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

Updates 标签页

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

addons updates

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

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

addon update notification

5.1.4. 模块管理

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

项目树的 Modules 部分显示项目中当前使用的模块。创建新项目时，默认包含 global 、 core 和 web。对于每个模块，Studio 也显示位于此模块中的配置文件。

5.1.5. 管理数据存储

主数据存储

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

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

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

数据存储属性

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

  • 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 和 Password - 数据库连接凭证。

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

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

add store settings

附加数据存储

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

additional stores

右键单击附加数据存储，会弹出右键菜单：

  • Delete Data Store - 从项目中移除该附加数据存储

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

  • Generate Model…​ - 从选中的附加数据存储生成数据模型

创建或编辑附加数据存储时，会显示 Data Store 对话框，其带有以下字段：

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

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

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

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

数据库初始化和更新脚本

主数据存储 可以使用 数据库初始化和更新脚本 ，这些脚本显示在数据存储之下：

db scripts

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

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

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

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

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

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

new update script

5.1.6. 部署设置

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 任务。