3.2.9. 应用程序属性

应用程序属性表示不同类型的命名值,它们决定着应用程序配置和功能的各个方面。平台广泛使用应用程序属性,还可以使用它们来配置应用程序的某些特性。

平台应用程序属性可按预期目的进行分类,如下所示:

设置应用程序属性

应用程序属性的值可以设置在数据库属性文件 ,也可以通过 Java 系统属性和操作系统的环境变量设置。如果同样名称的属性在多个地方定义,会按照下面的优先级决定其属性值:

  1. Java 系统属性(最高优先级)

  2. 操作系统环境变量

  3. 属性文件

  4. 数据库(最低优先级)

比如,在属性文件中定义的值会覆盖在数据库中定义的值。

对于操作系统环境变量,框架会先尝试寻找严格匹配的属性名称,如果没找到,则会尝试找名称全大写、点被下划线替代的属性名称。举个例子,环境变量 MYAPP_SOMEPROPERTY 可以赋值给 myapp.someProperty 应用程序属性。如果想禁用这个功能,还是使用严格匹配的话,可以设置 cuba.disableUppercaseEnvironmentProperties 应用程序属性为 true。

某些属性不支持设置在数据库中,原因是:在应用程序代码还无法访问数据库时就需要使用这些属性值。这些属性是上面提到的配置和部署参数。因此,只能在属性文件中或通过 Java 系统属性和操作系统环境变量定义它们。运行时参数始终设置在数据库中(可能被文件或系统属性中的值覆盖)。

通常情况下,应用程序属性用于一个或多个应用程序block。例如cuba.persistenceConfig仅用于中间件,cuba.web.appWindowMode用于 Web 客户端,而cuba.springContextConfig用于所有的 block。这意味着如果你需要为一个属性设置值,就应该在所有使用这个属性的block中进行设置。存储在数据库中的属性可自动用于所有 block,因此可以仅在一个位置设置它们的值(在数据库表中),而不用关心哪个 block 将会使用它们。而且,还有一个标准 UI 界面来管理此类属性:请参考 Administration > Application Properties 。存储在文件中的属性应分别在各 block 的相应文件中设置。

当需要为平台属性设置值时,请在文档中找到相关属性。如果文档声明该属性存储在数据库中,请使用 Administration > Application Properties 界面设置其值。否则,找出哪些 block 使用该属性并在这些 block 的 app.properties 文件中定义它。例如,如果文档声明该属性在所有 block 中使用,并且应用程序由中间件和 Web 客户端组成,则应在 core 模块的 app.properties 文件和 web 模块的 web-app.properties 文件中定义该属性。部署参数也可以在外部的 local.app.properties 文件设置。有关详细信息,请参阅在文件中存储属性

应用程序组件属性

应用程序组件可以通过在app-component.xml文件定义属性来对外暴露这些属性。 如果使用该组件的应用程序没有为这些属性指定值,则从该组件获取这些属性值。如果应用程序使用的多个组件定义了相同的属性,则应用程序中的实际值将从组件依赖关系层次结构从最近的组件中获得。如果多个组件位于依赖层次中的同一级,则该属性值会变得不确定。

累加 Properties

有时,需要从项目中使用的所有应用程序组件中获取属性值的组合。特别是应用程序的行为依赖于多个组件的同一属性的情况,平台需要读取多个组件的同一属性来配置应用程序。

通过在属性值的开头添加加号来使这些属性成为_累加_属性。此符号表示在运行时从应用程序组件组装属性值。例如,cuba.persistenceConfig是一个累加属性。在项目中,指定了一个定义项目数据模型的 persistence.xml 文件。但是由于实际的属性值还包括应用程序所依赖的应用程序组件的 persistence.xml 文件,因此应用程序的完整数据模型还要包括组件中定义的实体。

如果属性省略了 +,则只能从当前项目获取其值。如果不想从组件继承某些配置(例如,在定义菜单结构时),它会很有用。

在运行时获得的累加属性值是由 空格 连接的元素组成。

以编程的方式访问应用程序属性

可以使用以下机制访问代码中的应用程序属性:

  • Configuration 接口。如果将应用程序属性定义为配置接口的带注解方法,则应用程序代码将可对属性进行类型化访问。配置接口允许定义和访问所有存储类型的属性:数据库、文件和系统属性。

  • AppContext类的 getProperty() 方法。如果在文件或 Java 系统属性中设置属性,则可以使用此方法读属性值。该方法有以下弊端:

    • 不支持存储在数据库中的属性。

    • 与调用接口方法不同,必须提供 String 类型的属性名称。

    • 不能获取特定类型的属性值,只能获取 String 类型的属性值。