定义扩展特征【用户示例】-平芜编程栈

摘要

本文讨论CAAFmExtDefineExtensions用例。该用例详细说明了在特征目录中定义扩展特征所涉及的各个步骤。其前提条件是理解基本的特征建模器概念¹、扩展特征²、特征启动项³以及创建启动项目录⁴。

通过此用例您将学到什么

在CAAFmExtDefineExtensions用例中，用户将学习定义扩展特征并进一步生成特征目录的步骤。关键学习点包括：

理解包含扩展特征定义的OSM文件的重要性。
学习使用CATfctEditorAssistant工具来生成特征目录。

CAAFmExtDefineExtensions用例

CAAFmExtDefineExtensions是CAAFeatureModelerExt.edu框架中的一个用例，用于展示FeatureModelerExt框架的功能。

CAAFmExtDefineExtensions的功能是什么？

CAAFmExtDefineExtensions的目标是演示如何创建扩展特征。该用例将定义两个新的特征目录，每个目录包含一组不同的扩展特征。
下图展示了第一个特征目录的内容：该用例创建的目录包含扩展特征的定义。
目录CAAOsmExt1Catalog包含了两个扩展特征的定义，分别是CAAOsmHistoricalNovel（历史小说）和CAAOsmBiographicalNovel（传记小说），如图所示：

图 1: CAAOsmExt1Catalog.CATfct目录

CAAOsmHistoricalNovel的特征是一个字符串类型的属性Epoch（时代），代表小说所基于的历史时期。
CAAOsmBiographicalNovel扩展特征继承自CAAOsmHistoricalNovel。它具有两个属性：

Epoch（字符串类型）：从父特征继承的属性。
Domain（字符串类型）：由扩展特征显式添加的属性。代表传记所基于的领域。

第二个特征目录CAAOsmExt2Catalog的内容如下所示。

图 2: CAAOsmExt2Catalog.CATfct目录

CAAOsmChildrensNovel（儿童小说）是一个扩展特征，其扩展属性是整数类型的AgeGroup（年龄组）。

如何启动CAAFmExtDefineExtensions

要启动CAAFmExtDefineExtensions，首先需要设置运行时环境。具体步骤详见用例《创建启动项目录》⁴。

$ mkrun -c cmd $cdyour_workspace_root $# 确保运行时视图（包括连接目录）中不存在之前的特征目录文件$rmOS_directory/resources/graphic/CAAOsmExt1Catalog.CATfct

我们使用命令mkrun -c cmd启动一个已设置mkrun环境的子控制台（cmd是Windows控制台命令解释器，Unix上的等效命令是sh）。

接着切换到工作空间目录并删除我们接下来打算创建、但可能已存在于工作空间运行时视图或连接目录中的所有特征目录（CATfct）文件。在本例中我们运行rm命令删除CAAOsmExt1Catalog.CATfct。

$# 创建空特征目录$ CATfctEditorAssistant -create-new-catalog -catalog-name CAAOsmExt1Catalog.CATfct -with-client-id CAAOsmClientId1 -into-directory$PWD/OS_directory/resources/graphic

接下来我们启动CAA安装RTV⁵中可用的CATfctEditorAssistant可执行文件。我们首先在-into-directory标志指定的地址中创建一个新的空特征目录。
<font color="red">clientID（客户端ID）是生成新目录过程的关键输入</font>。此后只有在验证了输入的客户端ID后，客户端才被授权访问特征目录。

$# 将空特征目录描述为一个OSM文件。$ CATfctEditorAssistant -describe-as-osm -catalog-name CAAOsmExt1Catalog.CATfct -with-client-id CAAOsmClientId1 -as CAAOsmExt1Catalog.osm -into-directory$PWD

在更新流程特征目录添加数据之前，将特征目录转换到一个OSM文件中。

$# 使用InputData osm文件升级空特征目录。请注意升级后的特征目录将输出到指定地址中$ CATfctEditorAssistant -update-catalog CAAOsmExt1Catalog.CATfct -with-client-id CAAOsmClientId1 -with-osm$PWD-into-directory$PWD

继续使用更新后的OSM文件作为输入来升级特征目录。上一步输出的OSM文件已更新了所有扩展特征。升级后的目录（CAAOsmExt1Catalog.CATfct）则在您通过-into-directory标识指定的目录中生成。
只有成功验证了输入的客户端ID，目录的升级才会返回SUCCESS。

$# 删除空的特征目录和osm文件$rmOS_directory/resources/graphic/CAAOsmExt1Catalog.CATfct $rm$PWD/CAAOsmExt1Catalog.osm $# 将更新后的目录移动到运行时视图中$mv$PWD/CAAOsmExt1Catalog.CATfct OS_directory/resources/graphic/CAAOsmExt1Catalog.CATfct

最后我们删除不再相关的空OSM和空特征目录文件。

注意：
CATfctEditorAssistant以下列不同的方式处理目录参数：

输入时目录参数会被剥离其目录路径，然后在运行时视图中查找。在您的工作空间级别就是（目录文件必须放在以下地址否则生成OSM文件失败）workspace_root/OS_directory/resources/graphic。
输出时目录被写入到目录参数指定的位置。

在工作空间中存储目录的位置是framework/CNext/resources/graphic。在此地址（位于工作空间文件夹内）中找到的任何特征目录，都会由mkrtv命令自动复制到运行时视图workspace_root/OS_directory/resources/graphic。

上述过程将创建扩展特征目录CAAOsmExt1Catalog.CATfct。要创建扩展特征目录CAAOsmExt2Catalog.CATfct，请重复相同的过程，只需将CAAOsmClientId1、CAAOsmExt1Catalog.osm和CAAOsmExt1Catalog.CATfct分别替换为CAAOsmClientId2、CAAOsmExt2Catalog.osm和CAAOsmExt2Catalog.CATfct。

在哪里可以找到CAAFmExtDefineExtensions的OSM文件

对应两个扩展特征目录的两个OSM文件都位于CAAFeatureModelerExt.edu框架的InputData目录中：InstallRootFolder/CAAFeatureModelerExt.edu/InputData其中InstallRootFolder⁵是您API安装的根文件夹。

分步说明

此用例中创建了两个扩展特征目录。CAAFmExtDefineExtensions 包含3个逻辑步骤：

定义启动项（1）
定义启动项（2）
生成特征目录

定义启动项（1）

每个扩展特征目录都有一个关联的OSM文件。OSM文件中定义了扩展特征。
与CAAOsmExt1Catalog关联的CAAOsmExt1Catalog.osm文件内容如下所示。
它定义了CAAOsmHistoricalNovel和CAAOsmBiographicalNovel扩展特征。

document `CAAOsmExt1Catalog.CATfct` { container RootCont #root { feature CAAOsmHistoricalNovel #startup #extension { #creation::parameter=metadata_NovelExtn string Epoch Epoch="Middle Ages" } feature CAAOsmBiographicalNovel CAAOsmHistoricalNovel #startup #extension { string Domain Domain="Music" } } ...

您首先可能注意到的是#extension标签，它指定该启动项是一个扩展启动项，而不是常规启动项。另一点是启动项可以派生自另一个启动项，如此例中CAAOsmBiographicalNovel继承自 CAAOsmHistoricalNovel。此外CAAOsmHistoricalNovel特征关联了一个字符串类型的属性Epoch，其默认值设置为Middle Ages。而CAAOsmBiographicalNovel特征关联了一个字符串类型的属性Domain，其默认值设置为Music。然后请注意CAAOsmHistoricalNovel的元数据声明（#creation::parameter）。继承自CAAOsmHistoricalNovel的CAAOsmBiographicalNovel继承了相同的元数据：

metadata metadata_NovelExtn { `ContType` = "CAAFmExtApplication1" `Container` = "CAAFmExtApplication1" `Extends` = ["CAAOsmNovel"] `IsLocal` = true } } // OSM 结束 ...

因此CAAOsmHistoricalNovel和CAAOsmBiographicalNovel可以成为CAAOsmNovel特征的本地扩展特征，在应用容器CAAFmExtApplication1内实例化。

注意：
元数据必须包含这4行（ContType/Container/Extends/IsLocal）
当您创建/升级osm文件时，可以省略``。

定义启动项（2）

与CAAOsmExt2Catalog关联的CAAOsmExt2Catalog.osm文件内容如下所示。它定义了CAAOsmChildrensNovel扩展。

document `CAAOsmExt1Catalog.CATfct` { container RootCont #root { feature CAAOsmChildrensNovel #startup #extension { #creation::parameter=metadata_ChildrensNovelExtn int AgeGroup AgeGroup=12 } } }

CAAOsmChildrensNovel被定义为一个扩展特征，其特征是一个整数类型的属性AgeGroup，默认值设置为12。
由#creation::parameter=刻面声明的元数据如下：

metadata metadata_ChildrensNovelExtn { `ContType` = "CAAFmExtApplication2" `Container` = "CAAFmExtApplication2" `Extends` = ["CAAOsmNovel"] `IsLocal` = true } } // OSM 结束 ...