IBM Cognos 最佳实践: IBM Cognos 8 SDK 方法

文档性质:技巧或技术;产品:IBM Cognos 8;关注领域:开发

免费下载:IBM® Cognos® Express V9.5 或者 Cognos® 8 Business Intelligence Developer Edition V8.4 试用版
下载更多的 IBM 软件试用版,并加入 IBM 软件下载与技术交流群组,参与在线交流。

简介

概述

事实上,IBM Cognos 8 Connection 提供的大多数功能都可以通过 IBM Cognos 8 SDK 重新创建。

从 8.4.1 版本开始,IBM Cognos 8 SDK 文档包含超过 2900 个 PDF 页。除文档外,SDK 还附带了许多代码样例以及大量与 IBM Cognos 8 SDK 有关的 Technotes 和 SupportLink 文章。对于刚开始接触 IBM Cognos 8 SDK 的人来说,这样巨大的信息量会令人感到无从选择,并且很难从中找到合适的起点。

本文档的目的就是提供一些对于几乎所有 IBM Cognos 8 SDK 应用程序来说都非常基本的知识点。掌握了这些基础知识后,就可以在庞大的 IBM Cognos 8 SDK 文档中更加游刃有余地浏览和寻找所需的内容,并快速理解所提供的大量有用的样例代码片段。

本文档将大量引用 IBM Cognos 8 SDK 文档,除非在进行解释时需要用到,否则不会重复产品文档中的内容。

本文将涉及如下所示的主题:

  • 内容存储结构和搜索路径
  • 枚举集
  • 类和属性
  • IBM Cognos 8 服务
  • 登录和退出
  • 查询内容库
  • 运行一个简单的报告
  • 异步通信简介

以下是本文未涵盖的一些主题,读者将了解到使用 IBM Cognos 8 SDK 可以实现的其他一些功能。

  • 在内容库中添加、删除和修改对象
  • 运行需要提示的复杂报告
  • 调度报告并运行任务
  • IBM Cognos 8 服务、Content Manager 服务和 Report 服务

在 IBM Cognos 8 SDK 文档集合中,有许多关于开发 Framework Manager 元数据模型和开发 Custom Authentication Providers 的手册。这些内容涉及到更精深的知识,因此本文将不对此多做介绍。

要使用 IBM Cognos 8 SDK 创建应用程序,不要求具备报告创建或数据建模经验。然而,了解有关报告创建和建模的基本知识可能会有所帮助。这些基础知识可以从 IBM Cognos 8 附带的样例和产品文档或 IBM Cognos Education 提供的正式培训课程获得。有关 IBM Cognos Education 培训课程的更多信息,请访问 http://www.ibm.com/software/data/education/cognos.html

先决条件

读者在阅读本文时需要具备以下条件:

  • Java、C# 或 VB.NET 方面的编程经验
  • 已安装并配置了 IBM Cognos 8 BI 的单机版
  • 已在安装了 IBM Cognos 8 BI 的计算机上安装了 SDK
  • 已安装并部署了一些 IBM Cognos 8 BI 样例包和数据
  • 理解 IBM Cognos Connection 提供的功能。

文档范围

本文所述概念适用于 IBM Cognos 8 SDK 的所有版本。


准备好合适的工具

在开始之前,强烈建议读者针对首选编程语言安装一个集成开发环境(IDE)。IDE 提供了许多有用的功能,但是最有用的功能是上下文感知帮助、构建和调试工具、实时语法检查以及代码着色等。

如果要用 Java 编写 IBM Cognos 8 SDK 应用程序,那么使用最广泛的是 Eclipse IDE,它可以从 http://www.eclipse.org 免费下载。

如果使用 C# 或 VB.NET 编写 IBM Cognos 8 SDK 应用程序,Microsoft 的 Visual Studio 是最常用的 IDE,并且同样具有免费的开源版本。

如果使用 Visual Basic 6 (VB6) 作为开发语言,强烈建议慎重选择 IDE,推荐使用 VB.NET。Microsoft 在 2008 年 4 月宣布不再支持 VB6,此外,随着 IBM Cognos 8 BI 版本 8.4 的发布,IBM Cognos 8 SDK 也不再支持 VB6。

确定了首选编程语言后,重要的就是阅读 IBM Cognos 8 SDK 入门指南中 IBM Cognos 8 Toolkits 标题下的相关内容。


关于 IBM Cognos 8 Web 服务

IBM Cognos 8 采用基于 Web 服务的架构构建,而 IBM Cognos 8 SDK 在这些 Web 服务的基础上实现。在实践中,不需要细究 IBM Cognos 8 Web 服务的具体细节。它们的表现完全符合产品宣传的描述。如果希望了解这些 web 服务的实际工作情况,有很多工具可以帮助查看 SOAP 消息。


部署一个独立 IBM Cognos 8 安装

开始使用 IBM Cognos 8 SDK 时,建议在开发的初始阶段构建一个独立的沙盒或开发系统,这样可以确保其他 IBM Cognos 8 安装不会因此受到影响。

在独立 IBM Cognos 8 安装中,建议不要限制对内容库中的所有对象的访问。这样在学习内核内容时就不需要考虑访问权限的问题。这并不意味着访问权限不重要,而是说可以逐步了解它们的应用和含义。

对内容库设置不受限的访问很简单:在 Cognos 名称空间的内置 System Administrators 角色中将个别的帐户或组对象指定为成员。后面将会介绍到,以用户的身份通过与交互用户相同的方式登录,IBM Cognos 8 SDK 应用程序就可以获得访问。如果该用户是内置的 System Administrators 角色的一名成员,那么 IBM Cognos 8 SDK 应用程序就能够访问内容库中的所有对象。

单个服务器上的默认安装将允许匿名访问,并为 Cognos 名称空间的 Everyone 组授予内置 System Administrators 角色的权限。IBM Cognos 8 SDK 应用程序不需要登录,因为它将被视为匿名用户。

如果不能或不愿意采用匿名访问,那么从 security 名称空间中添加一个用户,该名称空间是在安装过程中设置的,将该用户添加到 System Administrators 角色中。IBM Cognos 8 SDK 应用程序将需要使用该用户帐户进行身份验证并登录到 IBM Cognos 8。


样例部署和数据

在使用 IBM Cognos 8 SDK 之前,建议安装一些 IBM Cognos 8 BI 样例部署和数据。这将创立一个独立的报告环境,并为 IBM Cognos 8 SDK 应用程序开发提供以下好处。

  • 使用具有不同样式和复杂程度的样例报告填充内容库
  • 可以在 IBM Cognos 8 SDK 文档中获得参考
  • 可由大多数 SDK 代码样例使用
  • 是一个 “众所周知” 的报告环境,许多人都很熟悉
  • 支持在 IBM Cognos Support 内轻松地复制报告环境,可请求援助

同时建议通过 IBM Cognos Connection 执行一些样例报告,从而理解在运行和管理报告时可能发生的情况。与通过 IBM Cognos Connection 运行和管理报告有关的功能都可以通过 IBM Cognos 8 SDK 获得。


内容存储结构和搜索路径

由 IBM Cognos 8 SDK 处理的对象都包含在内容库中,内容库的结构类似于文件夹结构。要访问这些对象,需要熟悉内容库的基本结构。可以在 IBM Cognos 8 SDK 开发人员指南中了解内容库的结构。

  • 对于 IBM Cognos 8 BI 版本 8.1、8.2 和 8.3,参见内容管理 一章中的 内容库结构
  • 对于 IBM Cognos 8 BI 版本 8.4,参见附录 C – 初始内容库设置

内容库的结构定义了搜索路径。搜索路径对于 IBM Cognos 8 SDK 应用程序开发非常重要,因为它用于指定要对哪些内容库对象进行检索。IBM Cognos 8 SDK 开发人员指南中的搜索路径语法 附录中提供了有关搜索路径的详细信息,包括如何使用 IBM Cognos Connection 获得特定对象的搜索路径。该部分提供了一个简单的表,包含各种搜索路径示例。从本文中,需要特别留意 "~"、"/"(单斜杠)、"//"(双斜杠)和 "//*" (双斜杠加星号)的含义。

  • "~"(一个波浪字符)是一个搜索路径快捷方式,表示 IBM Cognos 8 SDK 应用程序用于身份验证的用户的帐户对象。本文后面将详细介绍有关登录到 IBM Cognos 8 SDK 应用程序的内容。
  • 搜索路径中的 "/"(单斜杠)表示从当前位置 “返回指定类型的直接子节点”。
  • 搜索路径中的 "//"(双斜杠)表示从当前位置 “返回指定类型的所有内容”。
  • 搜索路径中的 "//*"(双斜杠加星号)表示从当前位置 “返回任意类型的所有内容”。

搜索路径类似于 XPath 语句。如果不熟悉 XPath 的话,可以查看基本概念,从 http://www.w3schools.com/xpath 可以获得一个基本教程。使用 IBM Cognos 8 SDK 不需要成为 XPath 专家,但是值得注意的是,使用 XPath 解析和处理任何 XML 文档可以极大地简化开发,因为它可以减少应用程序所需的代码。

在 IBM Cognos 8 SDK 开发人员指南中,“类” 一章中包含标题为内容管理器包含关系 的小节。该小节非常有用并可以作为快速参考指南,帮助确定对象在内容库结构中的位置以及对象的搜索路径。

除了用于开发 Cognos 8 SDK 应用程序外,搜索引擎还可用于其他非 SDK 用途,例如:

  • 通过 URL 运行报告,独立于 Cognos Connection
  • 当突然出现大量报告时参考用户帐户和目录清单

在 Cognos 8 的内容库结构中,共有 7 个顶级文件夹。它们分别为:

  • adminFolder
  • capability
  • configuration
  • content
  • directory
  • portal
  • transientStateFolder

最广泛使用的 Cognos 8 SDK 应用程序顶级文件夹为 contentdirectory。特别是以下子文件夹最为常用:

  • /content/package 包含针对特定包创建的所有报告和报告视图。
  • /directory/namespace 将包含外部安全信息,例如特定用户名称的用户、组和角色。需要注意的是内置的 Cognos 名称空间,其中包含的信息并不是外部安全提供商中存储的数据。它代表特定于内容库的相关数据。

/directory/namespace(包括名称空间)下的内容库对象的搜索路径不同于内容库结构中的其他部分。这些对象的搜索路径将以 "CAMID" 开头,它代表 Cognos Access Manager ID 的缩写。CAMID 是一个完整搜索路径,方式与 "~" 相同。CAMID 是一种内部表示,IBM Cognos 8 SDK 应用程序不应当依赖于构成 CAMID 的单个组件。不能保证不同的产品发行版具有相同的 CAMID 内容或格式。


枚举集

在 IBM Cognos 8 SDK 上下文中,枚举集可以被视为一组只读常量。作为单独的实体,枚举集并未包含太多的值。它们唯一的作用就是充当标识符,与实际的内容无关。枚举集中的值通常用于提供方法输入,但是有些情况下,它们还可用于判断输出的类型。

枚举集中的实体采用以下形式指定:

  • enumSetName.enumMemberName

例如,

  • 要指定 propEnum 枚举集中的 defaultName 成员,使用 propEnum.defaultName
  • 要指定 classEnum 枚举集中的 account 成员,使用 classEnum.account

IBM Cognos 8 SDK(版本 8.2 提供了 80 多个,版本 8.4 中提供了 110 多个)提供了许多枚举集,但是暂时只需要了解其中的 7 个枚举集。它们分别是:

  • 通用
    • classEnum
  • 查询内容库
    • propEnum
  • 运行报告
    • runOptionEnum
    • outputEncapsulationEnum
    • outputFormatEnum
    • asynchReplyStatusEnum
    • asynchDetailReportStatusEnum

枚举集的完整列表可以在 IBM Cognos 8 SDK 开发人员指南中的枚举集 一章中找到。在下一小节中,将看到 classEnumpropEnum 还可用于识别组成 Cognos 8 SDK 的众多类的用途。


所有类

IBM Cognos 8 SDK 提供了数百个类。IBM Cognos 8 SDK 开发人员指南中的 一章中列出并描述了每一种类。

IBM Cognos 8 类列表可以分为两个不同的部分:

  • 表示内容库对象的类
  • 实现内容库对象的属性的类

表示内容库对象的类

表示内容库对象的类是 IBM Cognos 8 SDK 应用程序最关心的类。这些类就是在内容库结构中看到类。它们在 classEnum 枚举集中也进行了定义。

除了 classEnum 中列出的类外,还有一些类专门用于定义其他类的常见属性。这些类被称为抽象类。IBM Cognos 8 SDK 提供了若干个抽象类,但是本文主要涉及到以下几个类

  • baseClass – 定义适用于 classEnum 中的所有类以及下面列出的类的属性。
  • uiClass – 定义可以通过 IBM Cognos Connection 处理的属性。classEnum 中列出的许多类都继承该类。
  • baseReport – 继承自 uiClass。包含与运行和管理报告有关的类。
  • authoredReport. – 继承自 baseReport。包含特定于某个报告的属性。report specification 是该类的一个属性。

对象 两个词可以互换使用。在本文档中, 一词用于定义,而对象 一词用于表示该定义的一个具体实例。例如,报告对象 一词指 report 类的实际的内容库对象。对象 可以通过搜索路径访问。

实现内容库对象的属性的类

IBM Cognos 8 SDK 开发人员指南的 一章中的其他类用于实现内容库对象的属性。事实上,所有 IBM Cognos 8 SDK 属性均被实现为类。对于 IBM Cognos 8 SDK,不存在 “简单” 或 “原生” 数据类型,如 intstringboolean。相反,这些数据类型通过使用类实现。例如:

  • booleanProp 类表示一个原生的 boolean 数据类型
  • intProp 类表示一个原生的 int 数据类型
  • stringProp 类表示一个原生的 string 数据类型

表示属性的类可以在 propEnum 枚举集中找到。在版本 8.2 中,有超过 300 个类表示属性,在版本 8.4 中,则有超过 400 个这样的类。


IBM Cognos 8 服务

IBM Cognos 8 服务是连接 IBM Cognos 8 服务器的 SDK 应用程序接口。在不同的版本中,共有 15-20 个服务可用于 IBM Cognos 8 SDK 应用程序。

每个 IBM Cognos 8 服务都针对特定的功能。例如,ContentManagerService 用于访问和操作内容库,ReportService 包含的功能确保报告正常运行,而 JobService 则负责运行任务。

在内部,IBM Cognos 8 服务可能调用另一个 IBM Cognos 8 服务来执行一部分任务。例如,如果一个任务包含要运行的报告,JobService 将调用 ReportService 运行报告。

每个 IBM Cognos 8 服务都具有相关的方法,每个方法都属于方法集的一部分。多个服务可以包含相同的方法。例如,ReportService 和 JobService 都包含 run() 方法。ReportService 将运行报告,而 JobService 将运行任务。

本文档的其他部分将重点介绍以下两个类:

  • ContentManagerService
  • ReportService

这两个服务是典型 IBM Cognos 8 安装中应用最广泛的两个服务,SDK 应用程序使用它们登录和退出,对内容库发出查询并运行报告。了解了这两个类后,使用 JobService 等其他类就会变得十分的简单。

对于每一个 IBM Cognos 8 服务的详细信息,每一个服务使用的方法以及有关创建和连接到 IBM Cognos 8 服务的代码样例,参见 Cognos 8 SDK 开发人员指南中的服务一章。

注意:在 IBM Cognos 8 SDK 版本 8.1 和 8.2 中,有一个名为 CognosReportNetService 的服务。该服务用于确保针对 IBM Cognos ReportNet 编写的 SDK 应用程序的兼容性。从版本 8.1 开始弃用 CognosReportNetService,并在版本 8.3 开始正式移除该服务。


登录和退出

当 IBM Cognos 8 SDK 应用程序创建表示 IBM Cognos 8 服务的对象时,在创建对象的过程中,服务将被自动连接到指定 URL 指向的 IBM Cognos 8 服务。创建和连接 IBM Cognos 8 服务的过程是相同的,与具体使用的服务无关。

除非设置为允许匿名访问,否则当 IBM Cognos 8 SDK 应用程序被连接到 IBM Cognos 8 服务器时,应用程序不具备隐含的权限或访问权。IBM Cognos 8 SDK 应用程序需要像交互用户那样进行登录。如果允许匿名访问,IBM Cognos 8 SDK 应用程序将被授予与 Cognos 名称空间的匿名用户相同的权利和权限。例如,如果不允许匿名访问,并且 IBM Cognos 8 SDK 应用程序没有登录,那么当应用程序尝试执行查询内容库或运行报告等操作时,将发生一个异常。

所有登录和退出都是通过 ContentManagerService 的 logon() 和 logoff() 方法执行的。其他 IBM Cognos 8 服务都不能执行登录和退出操作。

登录

ContentManagerService 的 logon() 方法有两个参数:credentialsroles

credentials 参数是一个编码的 XML 字符串,其格式可参考 IBM Cognos 8 SDK 开发人员指南 一章下的 credentials 类中。基本的 credentials 参数的 XML 类似如下所示,

<credential>
<namespace>
namespace ID as specified in Cognos Configuration
</namespace>
<username>
username contained in namespace
</username>
<password>
password for username
</password>
</credential>

roles 参数用于指定在 Cognos 名称空间中到 role 对象的搜索路径。这些 role 对象的权限将被应用到凭证中指定的用户。如果不需要任何额外的角色,那么该参数将为一个空数组,而不是 null。

在服务之间共享 CAM Passport

如果登录成功,ContentManagerService 将成为经过验证的服务,在 BIBusHeader 中将向 IBM Cognos 8 SDK 应用程序发送回一条名为 CAM Passport 的字符串。当 IBM Cognos 8 SDK 应用程序创建一个对象以表示 IBM Cognos 8 服务时,该对象将包含一个名为 BIBusHeader 的属性。BIBusHeader 表示用于与 IBM Cognos 8 服务器通信的 SOAP 头部。在 BIBusHeader 内,一个名为 CAM 的属性包含另一个名为 CAMPassport 的属性。logon() 方法返回的 CAM Passport 被存储到 CAMPassport 属性中。

CAM Passport 为什么很重要?在 IBM Cognos 8 SDK 应用程序中,CAM Passport 不会自动传播到应用程序内可能使用的其他服务。由于 ContentManagerService 是唯一可以执行登录和退出的服务,因此需要能够向 SDK 应用程序可能需要的其他服务(如 ReportService)分配 CAM Passport 的能力。这种分配很简单,只需要将 ContentManagerService 的 BIBusHeader 复制到其他服务的 BIBusHeader,从而使该服务成为经过验证的服务。

IBM Cognos 8 SDK 附带安装的样例包含有代码,演示了如何连接到 IBM Cognos 8 服务、如何使用 ContentManagerService 登录,如何从 ContentManagerService 将 BIBusHeader 复制到另一个服务。

Java 样例

Java 样例文件展示了如何登录和共享一个 CAM Passport,它们分别为:

<install_location>/sdk/java/Common/CRNConnect.java
<install_location>/sdk/java/Security/Logon.java

要连接到 IBM Cognos 8 服务,在 CRNConnect.java 中可以看到其中一个 connectToCognosServer 方法。这是一种工具方法,将把许多 IBM Cognos 8 服务连接到同一个 URL。

一旦成功连接 IBM Cognos 8 服务后,Logon.java 文件中的方法 quickLogon() 显示了如何构建 XML 凭证并调用 ContentManagerService 的 logon() 方法。

要复制 BIBusHeader,使用 CRNConnect.java 中的 getReportService() 方法。详细查看 CRNConnect.java 将发现表单 get____Service() 的多个方法,其中 "____" 填写 IBM Cognos 8 服务名。从 ContentManagerService 中将 BIBusHeader 复制到另一个 IBM Cognos 8 服务的过程是相同的,与具体的服务无关。

C# 样例

C# 样例文件展示了如何登录和共享 CAM Passport,它们为

<install_location>/sdk/csharp/SamplesCommon/SamplesConnect.cs
<install_location>/sdk/csharp/SamplesCommon/SamplesLogon.cs

正如 SamplesConnect.cs 中看到的一样,要连接到 IBM Cognos 8 服务,所需做的就是设置 IBM Cognos 8 服务对象的 Url 属性。

连接 Cognos 8 服务后,方法 specificUserLogon() 将展示如何构建 XML 凭证并调用 ContentManagerService 的 logon() 方法。

要从 ContentManagerService 将 BIBusHeader 复制到另一个服务,只需要使用 SamplesConnect.cs 末端实现的 get 方法中的 "=" 运算符。

退出

IBM Cognos 8 SDK 应用程序使用 ContentManagerService 的 logoff() 方法执行退出。logoff() 方法不包含参数。

logoff() 方法得到调用时,IBM Cognos 8 服务器将使 CAM passport 变为无效。这意味着任何其他由 SDK 应用程序创建并经过验证的 IBM Cognos 8 服务将自动退出。已保存的 BIBusHeader 随后使用 CAM Passport 时都会返回一个错误。

如果 IBM Cognos 8 SDK 应用程序不会显式退出,会话将保持激活状态,直到超时为止。所有已登录的 SDK 应用程序在完成处理后都应当退出。


查询内容库

有时,典型的 IBM Cognos 8 SDK 应用程序需要查看一个或多个内容库对象。这是通过使用 ContentManagerService 实现的。如前所述,可以检索到的内容库对象为 classEnum 枚举集中列出的对象,并通过搜索路径指定。

ContentManagerService.query () 方法

ContentManagerService 的 query(searchPath, properties, sortBy, options) 方法用于从内容库检索对象。由于可以返回多个内容库对象,因此 query() 方法将返回一个内容库对象的数组。

query() 方法包含以下参数:

  • searchPath 是一个字符串,包含内容库对象的搜索路径。
  • properties 是从 propEnum 枚举集获得的值数组,用于表示将随内容库对象返回的属性。
  • sortBy 是一个 sort 对象数组,用于确定如何对返回的数组排序。本文不会讨论该参数,但要注意,即使不会使用到该参数,仍然要提供一个空的 sort 对象。
  • options 是一个 queryOptions 对象,提供了多种数据处理选项。本文不会讨论该参数,但是即使不会用到该参数,仍然需要提供一个空的 queryOptions 对象。

在许多样例代码片段中,将看到以下 query() 方法:

query(searchPath, properties, new Sort[] {}, new QueryOptions())

注意,sortByoptions 参数不为 null。它们是对象的空实例。如果提供了 null 值,将出现一个错误(异常)。

从本质上讲,查询就是从内容库检索对象。IBM Cognos 8 SDK 应用程序的大多数代码用于处理检索得到的内容库对象的属性。

如何返回内容库对象

query(searchPath, properties, sortBy, options) 方法的返回类型是一个 baseClass 对象数组。然而,这并不代表数组实际持有 baseClass 对象,该数组实际上以类的形式持有内容库对象。返回 baseClass 对象数组的原因是编程语言(Java、C#、VB.NET)要求数组的所有成员为相同的类,而唯一适用于所有内容库对象的类是 baseClass。要访问以类的形式存储在数组中的内容库对象,对象必须转换为它自己的类。在大多数情况下,返回的内容库对象的实际的类是已知的,因此可以直接进行转换。

如果返回的类是未知的,可能需要判断对象的类,从而执行正确的转换。例如,searchPath 要求返回特定的 folder 对象下的所有内容库对象,它可以返回 reportreportViewfolderURL 对象。要判断返回的对象的类,可以采用两种方法。

第一种方法是使用特定于语言的操作符,它将对对象执行比较操作。在 Java 中,使用 instanceof 操作符,在 C# 中则使用 is 操作符,而在 VB.NET 中使用 TypeOfIs

第二种方法是将 baseClass 对象的 objectClass 属性的值与 ClassEnum 中的成员进行比较。例如:

if (baseClassObj.getObjectClass().getValue()== ClassEnum.Report)
{
<code to process a Report object>
}

if (baseClassObj.getObjectClass().getValue()== ClassEnum.ReportView)
{
<code to process a ReportView object>
}

if (baseClassObj.getObjectClass().getValue()== ClassEnum.Account)
{
<code to process an Account object>
}

运行一个简单的报告

本节将主要介绍使用 Report Studio 创建和保存报告。但是需要注意的是,这里的概念也可以应用于使用 Query Studio 创建和保存的报告。这两者之间存在一些细微的差别。

  • Report Studio 保存内容库中的 report 对象。
  • Query Studio 保存内容库中的 query 对象。
  • reportquery 对象具有相同的属性集。

在讨论 IBM Cognos 8 和报告时,会经常用到 report specification 一词(通常缩写为 report spec)。报告规范就是一个 XML 文档,可由 IBM Cognos 8 转换并生成一个报告。该 XML 文档脱离 IBM Cognos 8 后将没有任何意义。报告规范包含大量的信息,并且可能会非常复杂。有关报告规范的细节超出了本文的讨论范围,但是可以在 IBM Cognos 8 SDK 开发人员指南的使用报告规范报告规范参考 几章中找到相关内容。

在 IBM Cognos 8 SDK 应用程序上下文以外,报告和报告规范这两个词有时可以互换。然而,对于 IBM Cognos 8 SDK,这种用法是不正确的。报告是指一个内容库对象,是枚举集 classEnum 中的一个成员。报告规范是一个属性,是 propEnum 枚举集的成员。因此可以猜想得到,报告规范是报告类的一个属性。

IBM Cognos 8 SDK 开发人员指南的报告运行 一节中包含与运行报告有关的信息。

ReportService.run () 方法

要使用 IBM Cognos 8 SDK 运行报告,将使用 ReportService 的 run(objectPath, parameterValues, options) 方法。该方法将执行此前作为报告的一部分或 reportView 对象保存到内容库中的 XML 报告规范。objectPath 参数是 reportreportView 对象的搜索路径。该方法将在用户在 IBM Cognos Connection 中单击 reportreportView 对象时用到。

runSpecification(specification, parameterValues, options) 方法将运行 XML 报告规范(通过 specification 参数传递)。该方法特别适合于实时创建报告规范并且报告规范没有被保存到内容库的情形。该方法将由 Report Studio 和 Query Studio 调用以运行报告。

run()runSpecification() 方法的 parameterValuesoptions 参数是相同的。这些参数必须是真正的对象,不管它们是否被使用。null 值(或空值)将生成一个错误(异常)。

parameterValues 是一个 ParameterValue 对象数组。数组中的每一项都映射到报告中包含的一个提示。提示/参数之间的映射非常复杂,因此本文不予讨论。

options 是一个 option 对象数组。应当注意,option 对象本身是一个抽象对象,只用于定义其他对象将继承的属性。运行报告所使用的选项包含在枚举集 runOptionEnum 中。

最常用的选项包括:

  • outputFormat – 指定生成的输出的类型。有效输出类型在 outputFormatEnum 枚举集中指定。
  • outputEncapsulation – 指定输出的保存位置。有效的输出封装在 outputEncapsulationEnum 枚举集中指定。
  • prompt – 指定是否生成提示页面以满足未解析的报告参数。本文不会讨论有关处理提示页面和从 SDK 应用程序提交提示值的内容。
  • primaryWaitThreshold – 初始时间,单位为秒,指 asynchronous conversion 开始前等待报告完成的时间。下一小节将讨论异步通信的内容。
  • secondaryWaitThreshold – 指异步通信的过程中,状态检查之间的时间间隔,单位为秒。
  • saveOutput – 指定是否将报告输出保存到内容库

正如所预料的一样,run() 方法将等待报告完成运行,但是需要指出,它不会一直等待下去。运行选项 primaryWaitThresholdrun() 方法中指定了最长的等待时间。默认值为 7 秒。如果报告输出在这个时间段之后仍未就绪,run() 方法将完成,IBM Cognos 8 SDK 应用程序将继续进行处理。可能需要 run() 方法后的其他代码块处理长期运行的报告。异步通信 小节将继续讨论这些内容。

处于完整性考虑,还提供了 EventManagementService 的 runAt(startTime, objectPath, parameterValues, options) 方法。该方法的行为与 run(objectPath, parameterValues, options) 方法相同,不同之处在于报告运行时间是在 startTime 参数中指定的,输出被保存在内容库。runAt() 方法未在文中进行介绍。

异步通信

报告具有动态特性,有许多外部因素可以决定报告的性能和表现形式。这些因素包括检索的数据量、报告所需的格式化量,以及保持通信套接字处于激活状态。所有这些因素还会受到访问环境的用户的数量的影响,以及环境中使用的硬件的负载程度。由于存在太多不可预知的变化因素,因此很难预测任何给定报告的具体运行时间。此外,一些产品特性也会使报告创建变得更复杂,比如交互式报告和提示功能。要在这样一个复杂的环境下运行报告,IBM Cognos 8 SDK 应用程序需要采用异步通信。

第一次使用 IBM Cognos 8 SDK 时,异步通信可能要比其他主题更令人困惑,然而,对于产品级别的应用程序,需要对异步通信有一个透彻的了解。还需要注意,异步通信不适用于运行中的报告。它适用于所有其他实现 run() 方法的 IBM Cognos 8 服务。

大量利用异步通信的应用程序的一个例子就是 Cognos Viewer。一个更形象的异步通信的组成部分就是旋转的沙漏,在输出等待期间、提示页面呈现期间、提交提示值以及在 HTML 报告中进行翻页时都会用到。

IBM Cognos 8 SDK 开发人员指南的运行任务 一章的理解异步通信小节中介绍了有关异步通信的详细内容。本节将使用一个典型的异步通信来运行报告。

即使是不包含提示的简单报告也需要较长的时间来完成运行。当报告中包含大量数据时,运行时间会更长。如前所述,primaryWaitThreshold 用于确定 run() 方法等待报告输出的时间。如果时间超时且报告输出仍未就绪,那么 IBM Cognos 8 SDK 应用程序必须等待并与 Cognos 8 服务器同步,直到输出就绪。这个过程中将同时使用 ReportService 的 wait() 方法。IBM Cognos 8 SDK 应用程序将一直使用 wait() 方法,直到报告输出就绪或 secondaryWaitThreshold 运行选项中指定的时间超时。secondaryWaitThreshold 的默认值为 30 秒。IBM Cognos 8 SDK 应用程序通常将循环使用 wait() 方法,直到报告输出就绪。

IBM Cognos 8 SDK 开发人员指南中指出,可以将等待的时间阈值指定为 0。这意味着不会出现异步通信,IBM Cognos 8 SDK 应用程序将一直等待下去,直到返回报告数据或出现错误。对于产品级应用程序来说,在难以确定具体时间的情况下保持等待通常被看作是一种不好的实践。这是一种被动式方法,并且很难(如果不是不可能的话)对错误作出反应。此外,应用程序通常需要额外的代码来管理对时间敏感的资源,比如通信套接字。了解并使用异步通信来主动地管理报告处理要比前述方法好得多。出于学习的目的,可以将等待阈值设置为 0 或一个很高的值,但是对于在生产环境中运行的 IBM Cognos 8 SDK 应用程序,强烈反对使用这样的设置。所有等待阈值必须设置为以秒为单位。

如何返回报告内容

run() 方法和 wait() 方法都返回 asynchReply 对象。根据异步通信的状态,一个 asynchReply 对象可以有多个用途。

如果报告尚未完成,asynchReply 对象主要用作异步通信中的状态跟踪器,并由 wait() 方法进行更新。

如果报告已完成,asynchReply 对象的 details 属性将包含一个 asynchDetailReportOutput 对象。根据运行选项的不同,asynchDetailReportOutput 对象将包含实际的报告输出,或包含报告输出在内容库中的存储位置的搜索路径。

运行选项 saveOutput、outputFormat 和 outputEncapsulation 主要负责报告输出的存储以及 Cognos 8 SDK 应用程序如何访问输出。

如果运行选项 saveOutput 为真,则:

  • 运行选项 outputEncapuslation 被忽略。
  • 可以指定一个或多个输出格式。
  • 报告输出将作为 reportVersion 对象的一部分存储在内容库中。
  • reportVersion 对象将以时间戳命名,并将成为运行的 report 对象的子对象。
  • reportVersion 对象将包含一个或多个 output 子对象。将为 outputFormat 运行选项中指定的每个输出格式创建一个 output 对象。
  • output 对象列表通过 asynchDetailReportOutputgetOutputObjects() 方法返回。

注意,runSpecification() 方法不能包含保存的输出,因为在内容库中不存在相对应的 report 对象,该对象可以包含用于存放已保存的输出的 reportVersion 对象。

如果运行选项 saveOutput 为假,那么

  • 如果指定了多个输出格式,那么将生成一个错误(异常)并且不会运行报告。
  • 根据运行选项 outputEncapsulation 的值,报告输出可能会被保存。
    • OutputEncapsulationEnum.none
      • 报告输出将在 asynchDetailReportOutput 对象中返回,并可以通过 getOutputPages() 方法访问。
    • OutputEncapsulationEnum.URL
      • asynchDetailReportOutput 对象的 getOutputPages() 方法将获得指向报告输出的 URL。
      • 此外,asynchDetailReportOutput 对象的 getOutputObjects() 方法将包含保存对象输出的临时内容库对象的完整搜索路径。
    • OutputEncapsulationEnum.URLQueryString
      • asynchDetailReportOutput 对象的 getOutputPages() 方法仅包含 URL 的查询字符串。URL 查询字符串可以是以 "?" 开头的任何内容,通常在 URL 的路径部分可以看到。
      • 此外,asynchDetailReportOutput 对象的 getOutputObjects() 方法将包含保存对象输出的临时内容库对象的完整搜索路径。
    • OutputEncapsulationEnum.HTML
      • HTML 输出可通过 asynchDetailReportOutput 对象的 getOutputPages() 方法访问。如果输出格式为 HTML,那么将返回实际的报告输出。如果输出格式不是 HTML,那么将返回引用报告输出的 HTML 页面。

从该列表中可以看到,指定除 "none" 以外的任何 outputEncapsulation 值都将导致报告输出被保存到临时内容库对象中。如果正在运行的报告非常大,那么保存的报告输出将导致 IBM Cognos 8 SDK 应用程序用光内存,因为它需要一次性检索全部的报告输出。如果报告输出被放在内容库中,那么可以查询内容库对象并以较小的块检索输出。


更多信息

许多技术笔记都提供了样例代码,演示了如何使用 IBM Cognos 8 SDK 执行各种不同的任务。

要访问这些技术笔记,请访问 IBM Cognos 的支持门户:

IBM Cognos 的支持门户

并在页面左侧的 Search support 字段中输入 "SDK sample"。


结束语

本文介绍的信息为您提供了有关 IBM Cognos 8 SDK 的基本知识。通过掌握这些基础知识,在浏览海量 IBM Cognos 8 SDK 文档集合并利用其他 IBM Cognos 8 服务构建健壮应用程序时就会更加游刃有余。

参考资料

学习

获得产品和技术

讨论

  • 参与 developerWorks 博客 并加入 developerWorks 中文社区,developerWorks 社区是一个面向全球 IT 专业人员,可以提供博客、书签、wiki、群组、联系、共享和协作等社区功能的专业社交网络社区。

条评论

developerWorks: 登录

标有星(*)号的字段是必填字段。


需要一个 IBM ID?
忘记 IBM ID?


忘记密码?
更改您的密码

单击提交则表示您同意developerWorks 的条款和条件。 查看条款和条件

 


在您首次登录 developerWorks 时,会为您创建一份个人概要。您的个人概要中的信息(您的姓名、国家/地区,以及公司名称)是公开显示的,而且会随着您发布的任何内容一起显示,除非您选择隐藏您的公司名称。您可以随时更新您的 IBM 帐户。

所有提交的信息确保安全。

选择您的昵称



当您初次登录到 developerWorks 时,将会为您创建一份概要信息,您需要指定一个昵称。您的昵称将和您在 developerWorks 发布的内容显示在一起。

昵称长度在 3 至 31 个字符之间。 您的昵称在 developerWorks 社区中必须是唯一的,并且出于隐私保护的原因,不能是您的电子邮件地址。

标有星(*)号的字段是必填字段。

(昵称长度在 3 至 31 个字符之间)

单击提交则表示您同意developerWorks 的条款和条件。 查看条款和条件.

 


所有提交的信息确保安全。


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=10
Zone=Information Management
ArticleID=676807
ArticleTitle=IBM Cognos 最佳实践: IBM Cognos 8 SDK 方法
publish-date=07222011