Cognos ReportNet SDK 开发参考手册.doc

Cognos ReportNet SDK 开发参考手册Cognos ReportNet SDK 开发参考手册目 录1Cognos Report SDK 简介101.1总述101.2Cognos ReportNet SDK的工业标准111.3定义111.4参考资料132开发环境说明及样例测试152.1服务端环境准备152.2客户端开发环境样例测试152.3客户端开发环境准备153模块功能及样例说明163.1ReportNet 连接163.1.1程序说明163.1.2参考样例163.2登录到ReportNet163.2.1程序说明163.2.2参考样例173.3运行报表183.3.1程序说明183.3.2参考样例243.4运行带提示信息的报表253.4.1程序说明253.4.2参考样例273.5删除报表273.5.1程序说明273.5.2参考样例283.6修改报表283.6.1程序说明283.6.2参考样例313.7定义报表计划任务323.7.1程序说明323.7.2参考样例354Cognos Report SDK API 清单354.1com.cognos.developer.schemas.bibus._2364.1.1总览364.1.2CognosReportNetPortType444.1.3CognosReportNetService504.1.4_package504.1.5AccessEnum514.1.6Account524.1.7AddOptions554.1.8AncestorInfo564.1.9AncestorInfoArrayProp574.1.10AncestorInfoProp574.1.11AnyTypeMIMEProp584.1.12AnyTypeProp594.1.13AnyURIProp594.1.14AsynchStatusEnum604.1.15AuthoredReport624.1.16Base64BinaryMIMEProp634.1.17BaseClass644.1.18BaseClassArrayProp664.1.19BaseClassProp674.1.20BaseHistory674.1.21BasePowerPlayClass694.1.22BaseProp704.1.23BaseReport704.1.24BatchReportService734.1.25BiBusHeader744.1.26BooleanProp754.1.27BoundRangeParmValueItem764.1.28CAM764.1.29CAMException784.1.30CAMPassport794.1.31CAMProtect794.1.32Capability804.1.33ClassEnum804.1.34ClassEnumProp884.1.35CognosReportNetBindingStub884.1.36CognosReportNetServiceLocator934.1.37Configuration944.1.38ConfigurationData974.1.39ConfigurationDataEnum994.1.40ConfigurationFolder1014.1.41ConflictResolutionEnum1044.1.42Contact1054.1.43Content1074.1.44ContentManagerService1094.1.45ConversationContext1104.1.46CookieVar1114.1.47CopyOptions1124.1.48Credential1124.1.49Currency1134.1.50CurrencyArrayProp1144.1.51CurrencyProp1144.1.52DataSource1154.1.53DataSourceCommandBlock1164.1.54DataSourceCommandBlockProp1174.1.55DataSourceConnection1184.1.56DataSourceNameBinding1194.1.57DataSourceSignon1204.1.58DateTimeProp1204.1.59DecimalProp1214.1.60DeleteOptions1224.1.61DeploymentDetail1224.1.62DeploymentHistory1244.1.63DeploymentOption1244.1.64DeploymentOptionAnyType1254.1.65DeploymentOptionArrayProp1254.1.66DeploymentOptionBoolean1264.1.67DeploymentOptionEnum1274.1.68DeploymentOptionMultilingualString1304.1.69DeploymentOptionPackageInfo1314.1.70DeploymentOptionProp1324.1.71DeploymentOptionResolution1324.1.72DeploymentOptionString1334.1.73DeploymentStatusEnum1334.1.74DeploymentStatusEnumProp1354.1.75Directory1354.1.76Dispatcher1364.1.77DispatcherTransportVar1394.1.78DisplayObject1404.1.79DistributionList1414.1.80EncodingEnum1424.1.81EnvironmentVar1434.1.82EventRecord1444.1.83EventRefProp1454.1.84EventRefPropEnum1454.1.85ExportDeployment1474.1.86ExportDeploymentFolder1474.1.87FaultDetail1484.1.88FaultDetailArrayProp1494.1.89FaultDetailMessage1494.1.90FaultDetailProp1504.1.91FloatProp1514.1.92Folder1514.1.93FormatEnum1524.1.94FormFieldVar1534.1.95Governor1544.1.96GovernorArrayProp1544.1.97GovernorBoolean1554.1.98GovernorEnum1564.1.99GovernorInt1574.1.100GovernorProp1584.1.101Graphic1584.1.102Group1594.1.103Guid1604.1.104GuidProp1614.1.105HdrSession1614.1.106HierarchicalParmValueItem1624.1.107ImportDeployment1634.1.108ImportDeploymentFolder1634.1.109IntProp1644.1.110JobAndScheduleMonitoringService1654.1.111JobDefinition1664.1.112JobHistory1674.1.113JobStepDefinition1684.1.114LanguageProp1694.1.115LoadBalancingModeEnum1694.1.116LoadBalancingModeEnumProp1704.1.117Locale1714.1.118LocaleArrayProp1714.1.119LocaleMapEntry1724.1.120LocaleMapEntryArrayProp1734.1.121LocaleMapEntryProp1734.1.122LocaleProp1744.1.123LogService1754.1.124Message1764.1.125MetadataService1774.1.126Model1774.1.127ModelView1784.1.128MoveOptions1794.1.129MultilingualString1794.1.130MultilingualStringProp1804.1.131MultilingualToken1814.1.132MultilingualTokenProp1814.1.133Namespace1824.1.134NamespaceFolder1834.1.135NavigationPath1834.1.136NavigationPathArrayProp1844.1.137NavigationPathProp1854.1.138NcnameProp1854.1.139Nil1864.1.140NmtokenArrayProp1864.1.141NmtokenProp1874.1.142NonNegativeIntegerProp1874.1.143OrderEnum1884.1.144Output1894.1.145OutputEncapsulationEnum1904.1.146PackageDeploymentInfo1924.1.147Page1924.1.148PageDefinition1934.1.149Parameter1944.1.150ParameterCapabilityEnum1954.1.151ParameterDataTypeEnum1964.1.152ParameterValue1994.1.153ParameterValueArrayProp1994.1.154ParameterValueProp2004.1.155ParmValueItem2014.1.156ParmValueItemArrayProp2014.1.157ParmValueItemProp2024.1.158Permission2024.1.159Policy2034.1.160PolicyArrayProp2044.1.161PolicyProp2044.1.162PositiveIntegerProp2054.1.163PowerPlayCube2064.1.164PowerPlayDataBlock2064.1.165PowerPlayDataBlockArrayProp2074.1.166PowerPlayDataBlockEnum2074.1.167PowerPlayDataBlockProp2084.1.168PowerPlayDataEnum2094.1.169PowerPlayOption2104.1.170PowerPlayOptionArrayProp2104.1.171PowerPlayOptionBoolean2114.1.172PowerPlayOptionData2124.1.173PowerPlayOptionEnum2124.1.174PowerPlayOptionOutputFormat2134.1.175PowerPlayOptionProp2144.1.176PowerPlayOutputFormatEnum2144.1.177PowerPlayReport2154.1.178PresentationService2164.1.179Printer2164.1.180PromptInfo2184.1.181PromptOption2184.1.182PropEnum2194.1.183Provider2394.1.184Query2404.1.185QueryEventsOptions2404.1.186QueryMultipleOptions2424.1.187QueryMultipleResult2424.1.188QueryOptions2434.1.189QueryReply2444.1.190QueryReportOptions2454.1.191QueryReportResult2464.1.192QueryRequest2464.1.193RefProp2474.1.194Report2484.1.195ReportHistory2494.1.196ReportSaveAsEnum2494.1.197ReportService2504.1.198ReportServiceRequest2514.1.199ReportServiceResponse2524.1.200ReportServiceSecondaryRequest2544.1.201ReportSpecification2554.1.202ReportVersion2554.1.203ReportView2574.1.204RetentionRule2574.1.205RetentionRuleArrayProp2584.1.206RetentionRuleProp2594.1.207Role2594.1.208Root2604.1.209RunningStateEnum2614.1.210RunningStateEnumProp2624.1.211RunOption2624.1.212RunOptionAnyURI2634.1.213RunOptionArrayProp2634.1.214RunOptionBoolean2644.1.215RunOptionDateTime2654.1.216RunOptionEncoding2654.1.217RunOptionEnum2664.1.218RunOptionInt2704.1.219RunOptionLanguageArray2704.1.220RunOptionMultilingualString2714.1.221RunOptionNMTOKEN2714.1.222RunOptionOutputEncapsulation2724.1.223RunOptionProp2734.1.224RunOptionSaveAs2734.1.225RunOptionString2744.1.226RunOptionStringArray2754.1.227RunTimeState2754.1.228Schedule2764.1.229SchemaInfo2804.1.230SecuredFeature2814.1.231SecuredFunction2814.1.232Session2824.1.233SetCookieVar2834.1.234SeverityEnum2844.1.235Shortcut2854.1.236SimpleParmValueItem2864.1.237Sort2864.1.238SpecificationFormatEnum2874.1.239SQL2884.1.240StringArrayProp2894.1.241StringProp2894.1.242SystemService2904.1.243TimeZone2914.1.244TimeZoneArrayProp2914.1.245TimeZoneProp2924.1.246TokenArrayProp2924.1.247TokenProp2934.1.248Tracking2944.1.249UiClass2954.1.250UnboundedEndRangeParmValueItem2964.1.251UnboundedStartRangeParmValueItem2974.1.252UpdateActionEnum2974.1.253UpdateOptions2984.1.254URL2994.1.255UserCapabilityEnum3004.1.256UserCapabilityEnumArrayProp3014.1.257UserCapabilityEnumProp3024.1.258UserPreferenceVar3034.1.259ValidateResult3034.1.260VersionControlNumber3044.1.261XmlEncodedXML3054.2com.cognos.developer.schemas.bibus._2.holders3064.2.1DeploymentOptionArrayHolder3064.2.2DeploymentOptionHolder3061 Cognos Report SDK 简介1.1 总述Cognos ReportNet SDK 为ReportNet 各项服务和组件提供了一个平台独立的接口。你可以使用SDK来创建报表、管理和发布，安全和门户集成等，来满足你的个性化，本地化需求，实现和现有软件的良好结合。你可以利用Cognos ReportNet SDK 提供的BI Bus API （通用于任何程序开发语言）非常轻松的实现和你现有的应用程序或者是门户系统集成。你利用Cognos ReportNet SDK可以只开发一个简单的任务，也可以用开发整个报表创建流程：包括建模、建立报表、定义任务，和发布报表。下面的表格对比了Cognos ReportNet UI 中和SDK的功能：目标和文档程序接口使用UI修改模型或者重新发布脚本工具FrameWork Manager修改没有发布的模型BI Bus APIFrameWork Manager在发布的Package中找到可用的查询项BI Bus APICognos Connection性能管理BI Bus APICognos Connection 和 Server Administration管理和实现安全BI Bus APICognos Connection 和 Server Administration在HTML页面中使用超连接来运行、查看、编辑报表URL interfaceCognos Report ViewerQuery StudioCogons Report Studio在内容管理中使用对象BI Bus APICognos ConnectionCognos Query Studio管理各种报表BI Bus APICognos Connection管理各种服务BI Bus APICognos ConnectionServer Administration修改报表BI Bus API report specification(XML文件)Cognos Report Studio修改ReportNet功能URL interfaceCognos ConnectionCognos Report StudioQuery Studio1.2 Cognos ReportNet SDK的工业标准Cognos ReportNet 的Web框架是基于下列工业标准：l Web Services Description Language （WSDL）l 利用XML和HTTP的Simple Object Access Protocol （SOAP）1.3 定义1) access permission（访问权限）：定义一个组或者是用户能够读取，更改和限制使用的资源，这些资源包括报表、文件夹等。2) BI BUS：是ReportNet 的API。它使用了SOAP和其他的一些标准协议来实现消息的编码、传输、和安全。可以使用任何的工具，很方便就能使BI BUS集成到网络门户，应用程序等。3) Content Manager（内容管理）：ReportNet 提供的一个服务，是报表存储的应用程序，包括了应用程序的安全定义，数据、模型、报表的配置和报表的输出。发布模型，查看、存储报表，Cognos namespace和任务的管理都需要用到Content Manager。4) content store（内容数据库）：包含着所有的Cognos ReportNet需要操作的数据，例如：l 报表定义，模型、包的发布l 数据源的连接信息l Cognos自身的namespace和用户定义的namespacel 报表的任务运行和定时触发但是不包含模型设计和日志。ReportNet Service指定Content Manager使用content store。5) conversation（数据交流）：指客户机与系统的服务组件的信息传递，例如利用网络浏览器和ReportNet Server进行request/response数据交换。6) credentials（信任认可）：指使用用户名和密码认证的ReportNet 用户信息。你可以把你的信任任何给别的人用，这样他就能使用你的被服务器认可的资源。credentials是由ReportNet 的一个组件创建的，也被存储在content store中。7) data source（数据源）：是对一个物理数据库连接集合的命名。Framework Manager建模的时候需要这个经过定义的数据源名称。ReportNet Server使用这个来访问物理数据库。8) data source connection（数据源连接）：定义了数据源的类型，例如某种特定的数据库，任何的数据库验证信息，一个数据源可以定义多个数据源连接。9) deployment（部署）：指把ReportNet 应用实例（报表、模型等）复制成ReportNet另外一个实例的过程。举个例子：你可以在一个测试的环境下创建报表然后把它部署到正式的实用环境中。当你部署了一个实例后，你可以导出，移动，导入。10) hierarchy（层次）：用某种衡量标准定义的级别次序。在Framework Manager中，你可以对查询项定义层次。11) local（本地化）：代码定义集合l 对浏览器或者是报表显示的文本使用的用户本地语言。l 包括很多设置：时区、日期、钱币格式化等 在ReportNet中你可以为产品界面定义一个本地化（叫做产品本地化），和对报表数据定义一个本地化（内容本地化）。本地化会存储用户习惯的本地化设置的。12) model（模型）：对来自一个或者多个数据库的数据结构进行的业务化表述。模型描述了数据对象、结构，组织形式，和其中的关联、安全。模型在Framework Manager中创建和维护时，叫做设计模型。设计模型或者是设计模型的子集会被发布为ReportNet Server一个包，供用户创建和运行报表。13) namespace（命名空间）：从安全角度说，它是由授权程序设置的用户帐号和用户组的集合；从XML角度说，命名空间唯一确定了一个元素的类型和属性，XML的命名空间是URI定义的；在Framework Manager中，命名空间可以唯一指定查询项、查询主题等，你可以把不同的数据库分开导入到不同的命名空间中，避免重名。14) package（包）：指模型、报表的容器。建模者在Framework Manager中创建包，然后把包发布到ReportNet Server上。15) passport（认证信息）：指用户的授权信息。ReportNet 为用户每次登录创建一个passport。passport会在会话结束时，或者是用户登出时，或者是用户长时间没有任何动作时清除。passport是credentials的一个引用而已，不是credentials本身。16) project（项目）：指模型、包和相关信息的集合。可以用于管理或者共享模型信息，可以在Framework Manager中创建项目。17) prompt（提示）：带参数运行的报表会告诉用户提供一些参数值，然后等待用户输入参数后再运行。18) query（查询）：对从数据库提取数据的一种描述。查询可以定义了哪些列、哪些查询项需要被包含或者是显示在结果集中，和对提取的数据做哪些可显示的操作。查询是用规范的程序语言来描述的，如：SQL语言，ReportNet XML 定义。在ReportNet Server中，你可以使用Query Studio和Report Studio工具来创建和执行查询。19) report specification（报表定义）：指用XML定义查询项，提示，编排格式，报表风格。你可以使用Cognos Query Studio 和Report Studio或者是自己手工编写XML来创建report spectification。20) role（角色）：指用户登录时选择的用户组，用户改变用户组时，会改变他们的授权数据。21) session（会话）：指授权用户登录到ReportNet的停留时间。22) Simple Object Access Protocol（SOAP，简单对象访问协议）：指通过HTTP和XML交换结构化数据的标准协议，为在不同的操作系统中运行的程序提供了一种交换数据的方式。一个SOAP消息包含了信封和消息内容，信封包含了怎样解析内容的信息。23) URL：指在www上面的文档和其它资源的全球地址。地址的一部分指明了使用那种协议，第二部分指定了IP地址或者时域名。24) Web services：Web services 是指几个相互交换信息的程序。它使用标准的国际协议在不同的系统中建立连接，例如XML，SOAP，UDDI等。25) Web Services Description Language（WSDL，网络服务描述语言）：指定义基于XML的网络服务。WSDL提供了一种简单的办法，让服务提供者来描述他们系统需求的基本格式，而不管使用什么协议。使用WSDL，程序可以知道Web services 访问界面，服务所需参数和服务将返回的类型。ReportNet 使用WSDL为应用程序开发者描述了XML格式的可用APIs，包括这些APIs会用到的参数，和返回的数据结构。26) XML：使用标记或者是标签来描述数据结构的语言。XML标准是W3C组织和相关的HTML、SGML定义的。不像HTML，XML是可以随意扩展的，而不是有限的、预先知道的。1.4 参考资料1. 2. 3. 2 开发环境说明及样例测试2.1 服务端环境准备服务器端：（1） 安装和配置Cognos Report。（2） 浏览器访问http:/localhost/crn/cgi-bin/cognos.cgi，出现ReportNet欢迎页面。（3） 通过Connect Manager配置默认的cognos权限认证方式。（4） 创建用户，并加入用户组。（5） 发布的包和数据模型。（6） 创建报表样例。（7） 数据库已经连接正常，样例报表可以运行。2.2 客户端开发环境样例测试客户端：（1） 浏览器访问http:/servername/crn/cgi-bin/cognos.cgi，出现ReportNet欢迎页面。（2） 可以使用用户登录，并能进行所有的操作，例如：创建报表，修改报表，运行报表等。（3） 安装Cognos ReportNet SDK。（4） 修改Cognos ReportNet SDK安装目录/sdk/java/下的build-samples.bat中的JAVA_HOME，CRN_HOME设置，然后编译。（5） 修改Cognos ReportNet SDK安装目录/sdk/java/下的run-sdktester.bat 中的JAVA_HOME，CRN_HOME设置，然后运行测试。2.3 客户端开发环境准备（1） 调试Java 开发环境，能够编译运行Java程序。（2） 在程序开发时包含一下jar包（可以在Cognos ReportNet SDK安装目录/sdk/java/lib/下找到）l Axis.jarl axisReportNetClient.jarl commons-discovery.jarl commons-logging.jarl jaxrpc.jarl saaj.jarl xercesImpl.jarl xml-apis.jarl wsdl4j.jarl dom4j.jarl xalan.jar3 模块功能及样例说明假设Cognos ReportNet SDK安装目录为：D:cognoscrnsdkjavaCommon。3.1 ReportNet 连接3.1.1 程序说明 如果需要创建报表，就需要先建立连接，并获得ReportNet Server的认可。Java 主要代码如下： / （1）定义连接的URLpublic static String CM_URL = http:/servername/crn/cgi-bin/cognos.cgi; / （2）获取本地服务.String endPoint = CM_URL;service = new CognosReportNetServiceLocator();try/ （3）建立连接 oCrn = service.getCognosReportNetPort(new .URL(endPoint); / . catch expected exceptions after this point3.1.2 参考样例 详细代码请参考D:cognoscrnsdkjavaCommonCRNConnect.java3.2 登录到ReportNet3.2.1 程序说明如果需要使用ReportNet，用户就必须成功的登录。在登录过程中，你必须提供你的认可，例如userID，password，还有所需的namespace。当然这些过程都是假设你的ReportNet 安全设置已经配置好。否则，你只能使用匿名用户登录了，当然这样你的权限就会受到限制。要登录为一个用户，你必须有相应的权限和能力来使用ReportNet和ReportNet SDK。如果你配置了多个命名空间，你可以尝试登录这些命名空间。但是，你使用BI BUS APIs方法时，每次只能用一个用户登录一个命名空间，因为所有的命名空间都共享同一个用户的认证权限，程序不允许用户登录同一个命名空间多次。在ReportNet中验证用户权限需要使用logon(credentials,roles)和logoff() BI BUS API方法。logon(credentials,roles)可以告诉系统你想作什么？你是谁？你能允许作些什么？这个方法需要你提供credentials，roles可以为空。当你没有提供roles参数时，你登录后，将会拥有你的所有角色权限。Java 主要代码如下：public String quickLogon(CognosReportNetPortType oCrn,String namespace,String uid,String pwd)throws ExceptionStringBuffer credentialXML = new StringBuffer();credentialXML.append();credentialXML.append();credentialXML.append(namespace);credentialXML.append();credentialXML.append();credentialXML.append(uid);credentialXML.append();credentialXML.append();credentialXML.append(pwd);credentialXML.append();credentialXML.append();String encodedCredentials = credentialXML.toString();credentialString = encodedCredentials;oCrn.logon(encodedCredentials, new String );return (Logon successful as + uid);3.2.2 参考样例详细代码请参考D:cognoscrnsdkjava Security Logon.java3.3 运行报表3.3.1 程序说明 在登陆后，你可以在一个发布的模型上创建或者运行报表。要运行报表，你需要提供一个搜索路径。搜索路径告诉ReportNet Server在content store中哪个地方去找到报表。方法：你可以使用下面的BI Bus API的方法运行报表。l execute(obj,parameters,options)l execute(spec,parameters,options)l executeAt(startTime,obj,parameters,options)注意：在样例中都使用的是execute(obj,parameters,options)方法。使用上面这个方法，你必须有下面几个权限：l 对这个对象有执行权l 有这个对象父对象的所有权限l 这个包的所有权限l 有这个data source链接所有权限l 有这个data source链接（在你单例使用的情况下）所有权限l 有读、执行metadata的权限Java 主要代码如下：public String executeReport(String reportSearchPath,CRNConnect connect,int reportType,ParameterValue pv,Calendar execTime)CSHandlers csHandler = new CSHandlers();String shortReportName = csHandler.getReportName(reportSearchPath);String reportString = null;RunOption execReportRunOptions = new RunOption6;RunOptionBoolean saveOutputRunOption = new RunOptionBoolean();RunOptionStringArray outputFormat = new RunOptionStringArray();RunOptionInt primaryWaitTimer = new RunOptionInt();RunOptionInt secondWaitTimer = new RunOptionInt();RunOptionBoolean promptFlag = new RunOptionBoolean();RunOptionInt rows = new RunOptionInt();ReportServiceResponse rsr = null;String reportFormat = null;String textOutput = null; / text output returned from CRNbyte binaryOutput = null;String reportSavePath = connect.getDefaultSavePath();reportFormat = setFormatByType(reportType);reportString = setFilenameByType(reportSavePath, reportType);/ 在这里定义是否需要保存输出if (execTime != null)String parentPath =csHandler.getParentPath(connect.getOCrn(), reportSearchPath);MultilingualToken nameTokens = new MultilingualToken2;nameTokens0 = new MultilingualToken();nameTokens0.setLocale(en-us);nameTokens0.setValue(shortReportName + view);RunOptionSaveAs roSaveAs = new RunOptionSaveAs();roSaveAs.setName(RunOptionEnum.saveAs);roSaveAs.setObjectClass(ReportSaveAsEnum.reportView);roSaveAs.setObjectName(nameTokens);roSaveAs.setParentSearchPath(parentPath);execReportRunOptions0 = roSaveAs;saveOutputRunOption.setValue(true);elsesaveOutputRun