集成 IBM 元数据存储库，第 1 部: APIs for accessing Rational Asset Manager
通过将您的应用程序与 IBM® Rational® Asset Manager 集成，学习如何支持基于资产的开发。本文主要介绍用于检索和修改基于存储库资产的各种 API 的功能，其中包括使用 Web service 和 HTTP API 进行常见存储库操作的示例代码。
元数据存储库是业务解决方案一个很重要的部分。本系列文章向您展示如何将您的应用程序和存储库集成、存储库间如何共享资产、如何发现和挖掘新 资产、以及如何使用一个业务术语表从各种资源中分离元数据。第 1 部分关注如何通过将您的应用程序和 Rational Asset Manager（以下称为 Asset Manager）集成来支持基于资产的开发。后续文章涉及 Tivoli® Application Dependency Discovery Manager、WebSphere® Service Registry and Repository 和 WebSphere Business Glossary。
基于资产的开发（Asset-based development，ABD）是应对软件生产和运输的成本和效率方面不断增长的挑战的一个至关重要的机制。Asset Manager 是一个协作软件开发的资产管理解决方案。支持创建、描述和管理基于可重用资产规范（Reusable Asset Specification，RAS）的资产，RAS 是一个源自 Object Management Group (OMG) 的行业标准。Asset Manager 也提供资产搜索、更改跟踪和生命周期管理，这将促进所有类型的软件开发资产的重用。本文讨论如何使用 Web 服务和 HTTP API 来将 Asset Manager 集成到跨平台应用程序。使用这些 API 时 ABD 可用于各种软件开发环境：
- 创建和修改一个资产
- 访问一个资产的运行时元数据
- 访问 ABD 流程需要的系统元数据
- 与资产管理流程交互
在本文底部的 下载部分 获取本文样例代码。
现代的信息越来越庞大且复杂。商机出现时，客户想要使他们的投资最大化；而解决方案的提供商想要重用以前的产品，在节省传递成本的同时提高质量。ABD 通过重用以前的解决方案（所谓的资产）来解决复发和新出现的问题，使双方受益。这能减少资金投入、时间和劳动的重复。
ABD 流程包含四个关键阶段：资产识别、资产生产、资产管理和资产消耗。被认为是潜在资产的解决方案向前移入到了生产。资产生产的结果在存储库中作为资产存储和 管理，并且被客户重用。客户也可以提供反馈给资产生产和管理阶段，这有助于 ABD 流程成为一个自我完善的循环。
IBM 为资产生产、消耗和管理提供一套构建 ABD 流程的产品，包括 Rational Software Architect、Rational Clear Case/Clear Quest 和 Asset Manager。
在套件中，Asset Manager 是资产管理解决方案，在 ABD 流程中处于中心地位。除了资产管理之外，还提供一个协作机制用于资产重用，一个本体系统（ontology system）用于更好地进行资产分类，以及一个管理流程用于资产生命周期。应用程序需要同 Asset Manager 交互来加入 ABD 流程。
Asset Manager 提供两种类型的用户接口（UI）。一个是本地的基于 Web 的 UI，另一个是嵌入基于 Eclipse 的开发工具（例如，Rational Software Architect 或 WebSphere Business Modeler）的 Asset Manager Rich Client 插件。插件提供与 Asset Manager 的无缝集成。然而一个真正的开发环境通常包含用于不同平台的多种开发和管理工具，而且用户对这些工具的操作风格和 UI 可能已经很熟悉了。目前，如果您使用的工具不是基于 Eclipse 的，您必须使用 Asset Manager 的 Web 接口同 ABD Process 交互。
Asset Manager 也提供 API 将 Asset Manager 集成到其他应用程序。其中一个就是基于 Java 的二进制 API（在 参考资料 的 Asset Manager InfoCenter 中获取关于集成的 API 和指南的详细信息）。然而，该 API 是一个特定于平台的实现，而其他非 Java 平台（例如 Microsoft® .NET Framework）不能从该 API 中获益。另一个是一个 Web 服务和 HTTP API，但是相对比较复杂。
本文讨论如何结合使用标准 Web 服务调用和 HTTP 请求来将 Asset Manager 集成到应用程序。尽管解决方案被证实是 Java 的，但是也能应用于其他平台。
Asset Manager 内容模型含有两类数据：资产数据（与某一资产实例相关的数据）和系统元数据（资产实例之间共享的数据）。图 2 说明了 Asset Manager 内容模型。
资产数据包含基本资产信息，一个资产清单、已扩展元数据和资产内容（图 3)。
基本资产信息包含：
- 资产 ID 和资产版本，这是唯一识别资产的
- 资产最后一次更改的日期
- 资产的管理状态
- 资产的名称和简要说明
资产清单是核心元数据；遵循 RAS ，包含以下部分：
- 分类部分 — 一组描述符用于对资产进行分类，以及资产相关背景的描述。
- 解决方案部分 — 构件集合的索引，描述资产中构件的层次结构。
- 使用部分 — 安装、定制和使用资产的规则。
- 相关资产部分 — 该资产与其他资产的关系。
已扩展元数据是被 Asset Manager 定义的，用来提高使用体验和方便用户重用。这些元数据包括：
- User Tags — 关于该资产用户定义的描述性信息，是附加在资产清单的分类部分的。
- Change History — 一个资产修改的日志，能被用于资产版本和管理状态跟踪。
- Usage Metrics — 一些用户对资产评价的统计信息，是一种常见的资产度量方法。度量体系对于提高资产重用是很有用的。
资产内容是解决方案的实现。它包含在目录层次结构中组织的一组构件。层次结构与资产清单中的解决方案部分是一致的。
系统元数据是 Asset Manager 中所有资产实例共享的必要公共元数据。它包含资产类型、类别模式和相关类型。它也是操作资产时重要的信息。
Asset Manager 提供两个 API：Web 服务和 HTTP。Web 服务 API 可以访问系统元数据和资产清单，但是不能创建和更新资产清单和内容。HTTP API 可以检索、创建和更新资产内容，但是不能操作资产的已扩展数据和系统元数据。一个成功的 ABD 集成必须结合两个 API 的功能。
首先，您必须连接 API，两个 API 都使用 HTTP Basic Authentication 进行识别用户。因此请求被发送之前，确保在 HTTP 头部的用户名和密码是设置正确的。
HTTP API 使用 HTTP GET 请求来检索资产内容，使用 HTTP POST 请求来创建和更新资产内容。HTTP API 的端点是：
https://<host>:<port>/com.ibm.ram.repository.web.ws.was/RAMSecure/ RAMAssetAccess.jsp?assetID=<id>&version=<version> |
意识到这是一个 HTTP 连接 — 对于一个成功的请求您必须确保诸如密钥存储和信任存储等安全连接参数被正确设置。
为了连接 Web 服务 API，进行以下操作：
- 下载 Asset Manager Web 服务的 Web Services Definition Language (WSDL) 文件（参见 参考资料 中的 Asset Manager InfoCenter）。
- 使用一个代码生成器，例如 WSDL2Java，来生成远程服务存根。
- 执行一个 Web 服务请求到以下地址：
http://<host>:<port>/com.ibm.ram.repository.web.ws.was/RAMSecure/services/RAM1
连接完成后，您就可以通过使用在 WSDL 中定义的操作来访问 Web 服务。在其他的平台上，例如 .NET 或 C++，您可以使用类似的技术来连接 HTTP 和 Web 服务 API。
这有两种格式可以访问一个资产清单。您可以通过 HTTP 接口检索整个清单 XML 文件连同资产内容，或者您也可以以一种面向对象的方式使用 Web 服务接口定义的方法。
HTTP API 提供更低级别的信息和对清单的完全控制，但是为了正确理解和修改清单，您必须熟悉 RAS，这种风格的一个优势是您可以访问资产内容和资产清单。这是非常有用的，因为对于创建和修改一个资产它们都是必须的。
要以这种风格访问，首先，您必须使用资产 ID 和资产版本作为参数发送一个 HTTP GET 请求。返回的响应是一个 ZIP 流，含有资产清单和资产内容。您可以将其保存到本地磁盘或使用标准 ZIP 工具来处理它。一个资产 ZIP 文件结构的样例如图 4 所示。
一个资产 ZIP 文件包含资产清单文件（manifest.rmd）和构件。清单文件描述解决方案分类、使用和相关资产。图 5 显示了一个样例清单文件。
您可以使用标准 ZIP 和 XML 处理技术根据 RAS 来操作资产内容及其清单，这给您完全的资产控制，但是同时也意味着较少的直觉和更大的风险。例如，为了向资产添加一个分类术语，您必须在相应的 descriptorGroup 元素下添加一个 nodeDescriptor 元素，然而如果 descriptorGroup 不存在，您必须同时添加 descriptorGroup 和 nodeDescriptor 元素。（见 访问系统元数据 获取如何通过添加一个新 descriptorGroup 元素来检索所需信息。）为了向资产添加一个构件，您首先必须在 ZIP 文件中的正确位置添加该构件，然后向资产清单相应的解决方案部分添加一个构件实体元素。所有这些在核心资产文件上的修改必须遵从 RAS。
一个资产被创建或修改之后，您可以使用 HTTPS POST 请求向 Asset Manager 存储库提交新资产。HTTP POST 参数在 Asset Manager InfoCenter（见 参考资料 ）中予以说明。
清单 1 说明了如何使用 HTTP 接口来访问一个资产。
String http_location =
"https://9.125.62.227:9080/com.ibm.ram.repository.web.ws.was/RAMSecure/
RAMAssetAccess.jsp?assetID={C986918C-8E01-4039-6D94-D56E0B6E57A6}&version=0.9";
try {
// use the https get to get the asset content
InputStream is = HTTPHelper.getHTTPSContent(oneAssetHTTPLocation,
username, password);
ZipInputStream zis = new ZipInputStream(is);
ZipEntry zipEntry;
int len = 0;
String name = null;
byte[] buffer = new byte[512];
while ((zipEntry = zis.getNextEntry()) != null) {
ByteArrayOutputStream out = new ByteArrayOutputStream();
name = zipEntry.getName();
while ((len = zis.read(buffer, 0, buffer.length)) != -1) {
out.write(buffer, 0, len);
}
out.flush();
entryMap.put(name, out.toByteArray());
out.close();
}
} catch (IOException e) {
// TODO Auto-generated catch block
e.printStackTrace();
}
byte[] mainfest = entryMap.get("manifest.rmd");
|
Web 服务接口对资产客户是友好的。它以一种面向对象的方式提供访问资产清单的对象和方法，并提供对资产已扩展元数据的完全控制。
连接到 Web 服务接口之后，您可以在 Asset Manager 中的资产上执行一个搜索，然后使用资产 ID 和版本来获取资产的元数据对象。元数据对象包含关于数据清单的必要信息。您可以调用 getManifest 方法来获取清单文件，与您在之前 manifest.rmd 文件中所用的方式一样，或者您可以调用关于资产元数据对象的方法来获取资产清单的对应部分。例如，您可以在资产清单中调用 getRelationships 方法来获取 relatedAsset 部分，调用 getArtifactsRoot 获取构件层次结构的根，然后递归调用 getChildren 方法来获取整体构件层次结构。
一些已扩展元数据，诸如用户标记和修改历史，也可以通过 Web 服务 API 检索和修改，更多 Asset Manager Web 服务 API 的信息，请参考 参考资料 。
清单 2 说明了如何使用 Web 服务 API。
try {
//Get the asset metadata object
AssetSO asset = ramWebService.getAsset(assetID, assetVersion, true,
true, true, true, true, true, true, true, true, "zh_CN");
//Get the category schema list related to this asset object
CategorySchema[] categoryschemas=asset.getCategorySchemas();
for(int i=0;i<categoryschemas.length;i++){
CategorySchema oneCategorySchema=categoryschemas[i];
//OO Style Access: get the categories related to this asset
Category[] categories=oneCategorySchema.getCategories();
// Recursively retrieve the sub categories
for(int j=0;i<categories.length;j++){
Category oneSubCategory=categories[j];
SubCategory[] subCategories=oneSubCategory.getSubCategories();
// ......
}
}
|
一些常见的系统元数据（例如资产类型、类别模式和关系类型）在 Asset Manager 存储库中被多个资产共享。在操作资产清单时该元数据是必须的。例如，您可能需要检索系统分离层次结构来更好地理解清单文件的分类部分，或在您想要向资产中 添加一个新分类时，您可能需要了解所有分类术语。这一部分介绍如何访问两类系统元数据：类别模式和关系。
Asset Manager 分类系统包含一组类别模式，每个类别模式含有一组相关术语。在类别模式中每个术语有一个独一无二的标识符，并且该标识符需要理解资产清单文件中的分类部分。
首先，您需要知道在系统中有多少个类别模式。为了获取所有类别模式对象的列表，使用 getCategorySchemas 方法，如下所示：
CategorySchemaSO[] categories = ramWebService.getCategorySchemas(null, true); |
这有两个访问一个类别模式的方法。一个获得全部类别模式完整的 XML 描述，另一个是使用 Asset Manager Web 服务 API 的递归格式。为了检索一个类别模式的全部 XML 内容，首先，获取类别模式的 URL ，然后在模式 UI 上执行一个 HTTP GET。一个类别模式的样例如图 6 所示。
类别模式包含一个分类实体的层次结构，每个实体是一个特定的元素，有两个属性：@xmi:id 和 @name。@xmi:id 是惟一的，并能识别在类别模式中使用哪些分类实体来对资产清单中的资产进行分类。
检索实体模式的另一种方法是通过递归调用 getSubCategories 方法来遍历类别模式。当用户从顶层查看类别层次结构时，这种风格对他们来说更为直观。
资产之间的关系在组织资产中也起着重要的作用。您可以通过资产清单检索一个资产的已有关系。然而，当您想要向资产中添加一个新关系，或者在创 建一个资产的同时添加和删除一个新关系时，您需要列出 Asset Manager 服务器中所有可用的关系类型。这些任务也可使用 Web 服务 API 来完成。清单 3 展示了如何列出 Asset Manager 中的所有关系类型。
清单 3. 在一个 Asset Manager 存储库中列出所有关系类型
RelationshipType[] types = ramWebService.getAllAssetRelationTypes();
for(int i=0;i<types.length;i++){
RelationshipType oneType=types[i];
String displayName=oneType.getDisplayName();
String reverseRealtionShipName= oneType.getReverseName();
String name= oneType.getName();
}
|
删除一个关系类型时要特别注意：删除一个已有的关系类型可能会导致资产清单的 relatedAsset 缺失。
Asset Manager 有一个默认的资产生命周期定义。当资产被提交时，它可以进行审核和批准为公众使用，一个旧版资产不再适用时，它可能被停止使用并存档。默认资产生命周期如图 7 所示。
Asset Manager 不允许自定义资产生命周期。然而，在真实开发环境，用户有自己的生命周期定义，并为资产审查流程。该生命周期不能完全与 Asset Manager 的默认生命周期保持一致。为了填补这一空缺，应用一个外部驱动的生命周期机制。首先，您可以定义自己生命周期和转换规则，然后将定制生命周期的状态映射到 Asset Manager 中的默认资产生命周期。最后，当资产的外部状态达到一个预定义传输点时，您可以在 Asset Manager 中使用一个外部触发器来传输一个资产状态。
清单 4 说明如何用一个外部触发器来管理一个资产生命周期。
清单 4. 列出 Asset Manager 存储库中的关系类型
// Get the asset metadata object
AssetSO asset = ramWebService.getAsset(assetID, assetVersion, true,
true, true, true, true, true, true, true, true, "zh_CN");
String currentState = asset.getState().getName();
String newState = "Approved";
if (someConditionSatisfied == true) {
String[] message = ramWebService.changeAssetState(assetID,
assetVersion, newState, true);
if (message == null) {
System.out.println("State Change Success");
} else {
System.out.println("State Change Failed");
}
}
|
基于资产的研发是开发一个面向服务架构（SOA）解决方案的最佳选择。本文提议一个解决方案，可以通过集成 Asset Manager 使异构应用程序轻松地加入 ABD 流程。ABD 加速和促进模块和组件在业务和 IT 领域的重用。
| 样例代码 | RAM71AccessSampleCode.zip | 216KB | HTTP |
原文：http://www.ibm.com/developerworks/cn/websphere/library/techarticles/0905_cfengli/0905_cfengli.html?ca=drs-