从 IBM Rational DOORS 访问 OSLC 服务

本文解释了其他应用程序如何从 IBM Rational DOORS 访问 OSLC Requirements Management V2 Services,介绍了用于创建、更新、查询需求的服务的基本内容,以及 IBM Rational DOORS 提供的 Delegated UI,所有内容均基于 OSLC RM V2 规范。本文假设读者对 OSLC 有基本了解。

Sudarshan Rao, 咨询软件工程师, IBM

http://www.ibm.com/developerworks/i/p-srao60.jpgSudarshan Rao 从事 Rational 客户机支持已有超过 9 年的时间,主要侧重于 Rational DOORS 和其他需求管理应用程序。



2014 年 2 月 13 日

概述

IBM® Rational® DOORS® 是一款需求管理软件,旨在为复杂的嵌入式系统开发提供帮助。Rational DOORS V9.3 实现了 OSLC Requirements Management V1,并且从 V9.4 标准开始实现了 OSLC Requirements Management V2 接口。本文参考了 DOORS V9.4 的内容。

备注:
要使用这些服务,必须安装和配置 IBM Rational DOORS Web Access,这是 DOORS 的 Web 接口。

任何使用 HTTP 的应用程序都可以轻松地使用 DOORS 提供的服务。根据 OSLC RM V2 规范,DOORS 提供的服务可以分为以下几类:

Delegated User Interfaces
提供一种机制,在使用的应用程序中显示 DOORS Web Access 用户界面,以便创建或选择需求。
 
Query Capability
为工件容器提供一个基本的 URI,以便可以在工件容器上运行查询。
 
资源操作
提供了一种机制,在使用 GET、PUT 或 DELETE 的给定资源上执行基本操作。
 
Creation Factory
提供一个基本的 URI,以便使用 POST 创建需求。
 

所有这些功能都可以通过一组 URI 进行访问。后面的小节将介绍如何发现这些 URI,以及如何使用这些服务。除了 rootservices 文档之外,所有服务和资源都通过 OAuth 提供保护。rootservices 文档是执行发现的起点。DOORS 同时支持 OAuth 1.0 和 OAuth 1.0a。本文并未详细介绍 OAuth,但是结尾部分的注意事项小节中提到了一些基本要点。为了解释每一项功能,我使用 RESTClient(为 Mozilla Firefox 提供的插件)演示了如何使用这些服务。

发现服务

Rootservices 文档是 DOORS 提供的发现服务的起始点。该文档可以通过以下 URI 进行访问:
http://<dwaServer>:<port>/dwa/public/rootservices

对上面的 URI 执行一个 GET 操作将会返回一个 Resource Description Framework (RDF)/XML 格式的文档,其中列出了应用程序根级别的服务以及其他配置信息,如与 OAuth 有关的 URI。清单 1 显示了一个 DOORS 返回的样例 rootservices 文档:

清单 1. 清单 1. Rootservices 文档
<rdf:Description rdf:about="https://doors9501.com:8443/dwa/public/rootservices">
<jd:registration 
rdf:resource="https://doors9501.com:8443/dwa/public/registration"/>
<jfs:oauthDomain>https://doors9501.com:8443/dwa</jfs:oauthDomain>
<jfs:oauthUserAuthorizationUrl 
rdf:resource="https://doors9501.com:8443/dwa/oauth-authorize-token"/>
<dc:title>RM on DOORS9501</dc:title>
<jfs:oauthAccessTokenUrl 
rdf:resource="https://doors9501.com:8443/dwa/oauth-access-token"/>
<trs:trackedResourceSet rdf:resource="https://doors9501.com:8443/dwa/rm/trs"/>
<jfs:oauthRequestConsumerKeyUrl 
rdf:resource="https://doors9501.com:8443/dwa/oauth/request-consumer-key"/>
<oslc_rm:rmServiceProviders
rdf:resource="https://doors9501.com:8443/dwa/rm/discovery/catalog"/>
<jfs:oauthRealmName>DWA</jfs:oauthRealmName>
<jfs:oauthRequestTokenUrl 
rdf:resource="https://doors9501.com:8443/dwa/oauth-request-token"/>
<jd:oslcCatalogs>
<oslc:ServiceProviderCatalog 
rdf:about="https://doors9501.com:8443/dwa/rm/discovery/catalog">
<oslc:domain rdf:resource="http://open-services.net/ns/rm#"/>
</oslc:ServiceProviderCatalog>
</jd:oslcCatalogs>
</rdf:Description>

备注:
对大部分 URL 都使用 Mozilla Firefox 插件 RESTClient 执行 GET、PUT、POST 操作。所使用的报头没有明确指明,Content-Type 被设置为 “application/rdf+xml”,“oslc-core-version” 被设置为 “2.0”。

如清单 1 所示,JFS 名称空间中的代码行主要是与使用 OAuth 访问受保护资源/服务有关的配置内容。本文最后一个小节将解释如何通过 OAuth 实现访问。

发现 DOORS 提供的 OSLC 服务所必需的 URI 是 Service Provider Catalog (ServiceProviderCatalog),可在 oslc 名称空间中找到。Service Provider URI 是一组允许访问实际资源的服务集合。

图 1. 图 1. 发现服务链的图形说明
发现链接链

从比较的角度来看,Service Provider Catalog 可以被看作是一个 Project / Folder,而 Service Provider 可以被看作一个 Module / View。

Service Provider Catalog,Service Provider 和服务

Service Provider Catalog 是一个 Service Provider 列表或多个 Service Provider Catalog。Service Provider 可以看作是进入工具中的工件的实际入口,当前使用的应用程序可通过它执行进一步操作,比如创建/更新/链接等等。这些为了实现进一步操作而提供的功能被称为服务

图 2. 图 2. OSLC Core Specification V2 中的图形说明,描述了 DOORS 中的实现。
OSLC Service provider 表示

Service Provider CatalogService Provider 框上方的图标表示对 Rational DOORS 中分层项目的映射。

DOORS 中的需求总是包含在 Formal Module 中,因此充当了一个基本的工件容器。Formal Module 因此可以充当服务提供者,为进行访问的应用程序提供了与所含数据进行交互的能力。在 OSLC 术语中,我们将这种工件容器称为 Requirement Collection。因此,Formal Module 中的视图也可以充当不同的服务提供者。这将允许进行访问的应用程序根据视图定义访问特定的需求集合。

清单 2 摘取自 Service Provider Catalog,显示了 Service Provider 是如何定义的。oslc:serviceProvider 指定的 URL 允许您访问 Service Provider

清单 2. 清单 2. Service Provider Catalog 中对 Service Provider 的引用
<oslc:serviceProvider 
rdf:resource="https://doors9501.com:8443/dwa/rm/discovery/service/urn:rational:ers-
515ad1367be43903:1-515ad1367be43903-M-00000080"/>
<oslc:serviceProvider 
rdf:resource="https://doors9501.com:8443/dwa/rm/discovery/service/urn:rational:ers-
515ad1367be43903:1-515ad1367be43903-M-00000080/view:00000004"/>

反过来,Formal Module 总是包含在 Project 或 Folder 中,这又允许对 DOORS 中的数据进行划分。因此,Project 和 Folder 可以充当 Service Provider Catalogs,为当前运行的应用程序提供请求特定上下文中的工件的能力。Rootservices 文档包含初始目录,列出了 DOORS 数据库根目录下每个 Project / Folder 的 Service Provider Catalog。

现在我们了解了从 rootservices 文档发现 Service Provider。让我们看一看 DOORS 实际提供了哪些服务。根据 OSLC RM V2 Specifications 的定义,DOORS 提供了三种服务

  • Delegated User Interfaces (UIs)
  • Query Capability
  • Creation Factory

我们将通过下面的小节详细了解每一种服务及其功能。


Delegated UIs

Delegated UI 对话提供了一种机制,可以在所访问的应用程序的上下文中,通过一个与提供应用程序完美贴合的 Web 界面创建或选择工件。例如,如果您希望在您的应用程序中提供一个选项,以便在 DOORS 中创建一个工件,那么 Creation Dialog URI 可以帮助您实现这一点。调用 Creation Dialog URI 将显示一个 DOORS Web Access UI,它将允许创建工件。图 3 显示了样例 Creation UI 流。

图 3. 图 3. 使用 Creation UI
Creation UI 工作流

注意事项 1:
图 3 中的屏幕截图来自 DOORS 版本 9.4.0.1。delegated UI 在最新版本中出现了一些变化,每个屏幕的上方都会显示用户友好消息,表示期望执行的操作。

注意事项 2:
每个 Service Provider 中提供的 Delegated UI Service 允许用户选择 DOORS 中的任意工件,而不仅限于该 Service Provider 的上下文。这种行为将修改为特定于 Service Provider 提供的上下文。

DOORS 提供了两种类型的 Delegated UI:

  • Creation UI
  • Selection UI

Creation UI 允许创建工件。用户能够在 Formal Module 中选择分层位置,在其中创建工件。当用户选中一个位置(即一个对象)后,Create 按钮可以让您选择在所选对象之后(After)或下方(Below)创建工件,如图 3 所示。做出选择后,用户可以为 Object Heading、Object Text 和 Object Short Text 提供值。创建完工件后,用户将被提示输入 Label 值,即该工件的 OSLC Title*。完成工件创建后,工件/对象的 URL 将被返回到进行访问的应用程序。该 URI 可用来在进行访问的应用程序中创建一个链接/引用。

特殊服务提供者

有一个 Service Provider 位于 DOORS 数据库的根级别。它在两方面不同于其他服务提供者。

  • 它提供对数据库中任意位置的工件的访问。
  • 可以仅为 Delegated UI 提供服务。

关于如何访问服务提供者的样例用法,请参考 CLM Applications。将 Rational DOORS 配置为朋友(friend)后,该服务器将在建立关联时指定。

Selection UI 可对工件进行选择。该 UI 的常见用法是将提供的应用程序和使用的应用程序中的工件连接起来。选择工件后将返回该工件在 DOORS 中的 UI,可用于在使用的应用程序中创建链接/引用。

在提供应用程序中,可以创建一个连接到正使用的应用程序中的工件的链接(DOORS),方法是对 URI 发出一个 GET 请求,向获取的 RDF 内容添加链接信息,然后对资源 URI 发出 PUT 操作。这个过程通常称为 Backlink creation。我们将在 Updating Artifacts 小节详细介绍这一点。

除非由用户提供,否则 OSLC Title 默认为 Object Heading 的前 50 个字符;如果 Object Heading 没有值,那么 OSLC Title 将是 Object Text 的前 50 个字符。

清单 3 摘自 Service Provider 文档,展示了 Delegated UI 的详细信息。<oslc:CreationDialog> 识别提供 Creation UI 详细信息的节点。在该节点中,<oslc:dialog rdf:resource> 引用了将在该 UI 中使用的 URL。类似地,<oslc:CreationDialog> 识别提供 Selection UI 详细信息的节点。注意这里有两个 Selection UI,一个用于选择 Requirement,另一个用于选择 Requirement Collection。

清单 3. 清单 3. Service Provider 文档中的 Delegated UI 定义
<oslc:service>
<oslc:Service>
<oslc:domain rdf:resource="http://open-services.net/ns/rm#"/>
<oslc:selectionDialog>
<oslc:Dialog>
<dcterms:title rdf:parseType="Literal">
Select requirement from User Requirements Document</dcterms:title>
<oslc:label>User Requirements Document</oslc:label>
<oslc:dialog rdf:resource="https://doors9501.com:8443/dwa/rm/calm/v2/
selectRequirement/urn:rational:ers-515ad1367be43903:1-515ad1367be43903-M-000000a2"/>
<oslc:hintWidth>600px</oslc:hintWidth>
<oslc:hintHeight>500px</oslc:hintHeight>
<oslc:usage rdf:resource="http://open-services.net/ns/core#default"/>
<oslc:resourceType rdf:resource="http://open-services.net/ns/rm#Requirement"/>
</oslc:Dialog>
</oslc:selectionDialog>
<oslc:creationDialog>
<oslc:Dialog>
<dcterms:title rdf:parseType="Literal">
Create requirement in User Requirements Document</dcterms:title>
<oslc:label>User Requirements Document</oslc:label>
<oslc:dialog rdf:resource="https://doors9501.com:8443/dwa/rm/calm/v2/
createRequirement/urn:rational:ers-515ad1367be43903:1-515ad1367be43903-M-000000a2"/>
<oslc:hintWidth>600px</oslc:hintWidth>
<oslc:hintHeight>500px</oslc:hintHeight>
<oslc:usage rdf:resource="http://open-services.net/ns/core#default"/>
<oslc:resourceType rdf:resource="http://open-services.net/ns/rm#Requirement"/>
</oslc:Dialog>
</oslc:creationDialog>
<oslc:selectionDialog>
<oslc:Dialog>
<dcterms:title rdf:parseType="Literal">
Select requirement collection from User Requirements Document
</dcterms:title>
<oslc:label>User Requirements Document</oslc:label>
<oslc:dialog rdf:resource="https://doors9501.com:8443/dwa/rm/calm/v2/
selectRequirementCollection/urn:rational:ers-515ad1367be43903:1-
515ad1367be43903-M-000000a2"/>
<oslc:hintWidth>600px</oslc:hintWidth>
<oslc:hintHeight>500px</oslc:hintHeight>
<oslc:usage rdf:resource="http://open-services.net/ns/core#default"/>
<oslc:resourceType rdf:resource="http://open-services.net/ns/
rm#RequirementCollection"/>
</oslc:Dialog>
</oslc:selectionDialog>

查询功能

DOORS 提供的查询功能可以使得使用应用程序获得满足特定条件的工件列表。这里的条件是指 Formal Module 中各种属性的值需要满足一个或多个条件。这些属性可以看作是对象属性,但是又不仅限于属性。它还可以表示对象的状态(无论是否软删除)、与其他工件的链接等等。

指定查询参数的语法需符合 OSLC Core Specifications V2。DOORS 支持使用 oslc.select、oslc.where、oslc.orderBy、oslc.searchTerms。上面的链接详细介绍了如何使用这些参数。

查询范围由 Service Provider 的上下文确定。每个 Service Provider 为查询提供一个基础 URI,标记为 oslc:queryBase。这个基本 URI 必须 与一个或多个查询参数一起使用,比如 oslc.where / oslc.select / oslc.searchTerms / oslc.orderBy。生成的 RDF 响应将包含满足条件的对象的 URI 以及对象的 Title。

构建查询

要构建一个查询,需要使用以下信息:

  • Query Base URL
  • Resource Shape URL – 属性定义,这是创建查询的基础
  • 查询的语法

Query Base URL 可以在 Service Provider 文档中找到,标记为 <oslc:queryBase>,位于 <oslc:queryCapability> 节点内。这构成了用于发送查询的 URL 的第一部分。第二部分将包含查询参数。

在深入了解查询参数之前,我们需要知道可以对工件的哪些属性进行查询。这在 Resource Shape 中进行了定义。Query Capability 定义中包含了到 Resource Shape 的 URI。清单 4 截取自 Service Provider 文档,显示了 Query Capability 节点。

清单 4. 清单 4. Service Provider 文档中有关 queryCapability 的片段
<oslc:queryCapability>
<oslc:QueryCapability>
<dcterms:title 
rdf:parseType="Literal">Query in User Requirements Document</dcterms:title>
<oslc:label>User Requirements Document</oslc:label>
<oslc:queryBase rdf:resource="https://doors9501.com:8443/dwa/rm/oslc/
query/urn:rational:ers-515ad1367be43903:1-515ad1367be43903-M-000000a2"/>
<oslc:resourceShape rdf:resource="https://doors9501.com:8443/dwa/rm/
oslc/shape/requirement/urn:rational:ers-515ad1367be43903:1-
515ad1367be43903-M-000000a2"/>
<oslc:resourceType rdf:resource="http://open-services.net/ns/rm#Requirement"/>
<oslc:usage rdf:resource="http://open-services.net/ns/core#default"/>
</oslc:QueryCapability>
</oslc:queryCapability>

对 Resource Shape 执行 GET 操作将返回该容器(Formal Module)中的工件的属性。属性定义将包括一些具体信息,比如属性是否可修改,属性可以接受哪些值。清单 5 是 Formal Module 的 Resource Shape 中的工件的一些属性。

清单 5. 清单 5. ResourceShape 中的样例属性
<oslc:Property>
<oslc:readOnly 
rdf:datatype="http://www.w3.org/2001/XMLSchema#boolean">true</oslc:readOnly>
<dcterms:title rdf:parseType="Literal">Created By</dcterms:title>
<oslc:valueType 
rdf:resource="http://www.w3.org/1999/02/22-rdf-syntax-ns#XMLLiteral"/>
<oslc:occurs rdf:resource="http://open-services.net/ns/core#Exactly-one"/>
<oslc:propertyDefinition 
rdf:resource="https://doors9501.com:8443/dwa/rm/urn:rational::1-515ad1367be43903-
M-000000a2/types/attrDef-4"/>
<oslc:name 
rdf:datatype="http://www.w3.org/2001/XMLSchema#string">attrDef-4</oslc:name>
</oslc:Property>
</oslc:property>
<oslc:property>
<oslc:Property>
<oslc:representation rdf:resource="http://open-service.net/ns/core#Reference"/>
<oslc:readOnly 
rdf:datatype="http://www.w3.org/2001/XMLSchema#boolean">false</oslc:readOnly>
<dcterms:description rdf:parseType="Literal">
Link to a resource, such as a test case, which validates this resource.
</dcterms:description>
<dcterms:title rdf:parseType="Literal">Validated By</dcterms:title>
<oslc:valueType rdf:resource="http://open-services.net/ns/core#Resource"/>
<oslc:occurs rdf:resource="http://open-services.net/ns/core#Zero-or-many"/>
<oslc:propertyDefinition 
rdf:resource="http://open-services.net/ns/rm#validatedBy"/>
<oslc:name 
rdf:datatype="http://www.w3.org/2001/XMLSchema#string">validatedBy</oslc:name>
</oslc:Property>
</oslc:property>
<oslc:Property>
<oslc:readOnly 
rdf:datatype="http://www.w3.org/2001/XMLSchema#boolean">true</oslc:readOnly>
<dcterms:description 
rdf:parseType="Literal">Modified date of the DOORS object</dcterms:description>
<dcterms:title rdf:parseType="Literal">Modified</dcterms:title>
<oslc:valueType rdf:resource="http://www.w3.org/2001/XMLSchema#dateTime"/>
<oslc:occurs rdf:resource="http://open-services.net/ns/core#Exactly-one"/>
<oslc:propertyDefinition rdf:resource=
"http://purl.org/dc/terms/modified"/>
<oslc:name rdf:datatype=
"http://www.w3.org/2001/XMLSchema#string">modified</oslc:name>
</oslc:Property>
</oslc:property>

清单 5 中的第一个属性定义是某个对象的 Last Modifiedy By 属性的定义。
readOnly 标记的值表示这是一个只读(Read Only)属性,而 valueType 则表示值的类型为字符串(String)。

occurs 标记表示属性可以有多个值,其中 One-Or-More 表示属性是一个具有多个值的枚举属性。

上面代码片段中的第二个属性定义是 Link Type – Validated By。这是 Collaboration Link 中的一个,在从 QM 域连接 Test Case 或 Test Plan 等工件时使用的一个链接。

注意,上述代码中的最后一个属性是 Requirement Resource 的一个必选属性。在 OSLC RM Specifications V2 的 Resource Requirement 小节 中可以找到这些必选属性的列表。Rational DOORS 的原生属性可以通过在每个 oslc:property 中使用 dcterms:title 识别。注意,查询语法使用了 oslc:name 而不是 dcterms:title。

查询语法

有关语法的详细信息,敬请参考 OSLC Core Specifications V2 Query Syntax。但是,下面给出了一些简单的解释。

查询 URL 的基本结构:
<queryBase URL>?<query parameters – oslc.select/oslc.where/oslc.orderBy/oslc.searchTerms>

每个查询参数都采用以下格式使用工件属性:
<nameSpace>:<oslcNameOfProperty>

Resource Shape 中的每个参数定义都由 oslc:propertyDefinition 和 oslc:name 构成。前者识别属性的名称空间,后者识别属性的名称。比较操作符,如 =、!=、>、>=、<、<= 都用于定义条件。布尔(Boolean)操作符 “and” 可以与 oslc.select 一同使用。然而,“or” 不受支持。

示例查询:

备注:
下面所有的样例都需要对 URL 编码,附加到 queryBase URL 后面。

  • 简单查询 - 创建者为 John
    ?oslc.where=dcterms:created="John"
  • 复合查询 - 修改日期晚于 2012 年 1 月 31 日且属性 “isReq” 的值不是 “True”(attrDef1002 是将用于 isReq 的名称,该名称是从 queryBase 的实例形状中获得的)。
    ?oslc.where=dcterms:modified>"31 January 2013" and rm_property:attrDef1002=true
  • 使用多个查询参数 - 修改日期晚于 2012 年 1 月 31 日且属性 “isReq” 的值不是 "True”,则选择 Creator, Title and Implemented By 关系。
    ?oslc.where=dcterms:modified>"31 January 2013" and rm_property:attrDef1002=true&
    oslc.select=oslc_rm:implementedBy,dcterms:title,dcterms:creator{*}

注意上述查询中 {*} 的用法。Creator 是一个属性,表示为 foaf,其中用户名是一个嵌入式属性。在构建查询时,嵌入式属性的详细信息可以通过 {} 操作符和通配符查询/获得。


Creation Factory

Creation Factory 能够在没有用户干预的情况下在容器中创建工件。对 Creation Factory URL 执行一个 POST 操作即可创建一个工件。Creation Factory 的定义可以在 Service Provider 文档中找到,标记为 creationFactory。

与 Query Base 功能类似,Creation Factory 功能的定义包含一个 Resource Shape URL。清单 6 是 Service Provider 文档中定义的 Creation Factory 功能的一个片段。

清单 6. 清单 6. Service Provider 文档中有关 Creation Factory 定义的摘要
<oslc:creationFactory>
<oslc:CreationFactory>
<dcterms:title 
rdf:parseType="Literal">Create requirement in User Requirements Doc</dcterms:title>
<oslc:label>User Requirements Doc</oslc:label>
<oslc:creation 
rdf:resource="https://doors9501.com:8443/dwa/rm/rest/requirementFactory/urn:rational:ers-
515ad1367be43903:1-515ad1367be43903-M-000000a2"/>
<oslc:hintWidth>600px</oslc:hintWidth>
<oslc:hintHeight>500px</oslc:hintHeight>
<oslc:usage rdf:resource="http://open-services.net/ns/core#default"/>
<oslc:resourceShape 
rdf:resource="https://doors9501.com:8443/dwa/rm/oslc/shape/requirement/urn:rational:ers-
515ad1367be43903:1-515ad1367be43903-M-000000a2"/>
<oslc:resourceType rdf:resource="http://open-services.net/ns/rm#Requirement"/>
</oslc:CreationFactory>
</oslc:creationFactory>

在创建工件时,使用 Resource Shape URL 作为引用来判断需要提供哪些属性。例如,找出必选属性并确保 POST 正文中包含这些属性。

下面是一个与 Creation Factory 一起使用的样例内容:

Action: POST
URL: https://doors9501.com:8443/dwa/rm/rest/requirementFactory/urn:rational:ers-515ad1367be43903:1-515ad1367be43903-M-000000a2
Header: Content-Type: application/rdf+xml
oslc-core-version: 2.0
Body:

<rdf:RDF
	xmlns:dcterms="http://purl.org/dc/terms/"
	xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
	xmlns:doors="http://jazz.net/doors/xmlns/prod/jazz/doors/2.0/"
	xmlns:oslc="http://open-services.net/ns/core#"
	xmlns:rm_property="https://doors9501.com:8443/dwa/rm/urn:rational::1-
	515ad1367be43903-M-00000080/types/"
	xmlns:oslc_rm="http://open-services.net/ns/rm#"
	xmlns:rm="http://jazz.net/ns/rm#"
>
<oslc_rm:Requirement>
<oslc:resourceShape rdf:about="https://doors9501.com:8443/dwa/rm/oslc/shape/
requirement/urn:rational:ers-515ad1367be43903:1-515ad1367be43903-M-000000a2" />
<rm_property:attrDef-12 rdf:datatype="http://www.w3.org/2001/XMLSchema#string">
Created using OSLC Creation Factory</rm_property:attrDef-12>
<rm_property:attrDef-11 rdf:datatype="http://www.w3.org/2001/XMLSchema#string">
Just some text for Object Text</rm_property:attrDef-11>
</oslc_rm:Requirement>
</rdf:RDF>

成功的 POST 将返回 Status Code 201 – Created。Response Header 之一 Location 将返回 DOORS 中创建的对象的 URL,而响应正文将包含该对象的 RDF 表示。

备注:

  1. 使用 Creation Factory 创建的工件始终是 DOORS 模块中第一个被创建的对象。使用这种方法无法控制工件的位置。
  2. 在 POST 正文中包含 <oslc:resourceShape> 非常重要,否则资源创建将失败。

更新工件

更新操作主要用于在两个应用程序域中的工件之间建立联系,这也是 OSLC 的目标之一。

更新操作通常涉及三个步骤:

  1. 对需要更新的工件执行一个 GET 操作
  2. 根据需要修改响应正文
  3. 对工件执行一个 PUT

如前面小节所示,要执行 GET 操作,可以通过多种方式获得工件 URL。通过使用 Query Capability,可以从响应正文获得 URL;其他方法(Creation/Selection UI,Creation Factory)将在 Response Header 的指定 “位置” 返回工件 URL。

在对正文进行修改之前,使用 Resource Shape 找出可以修改的工件属性。在正文中可以创建(插入)与其他工件的关系。要获得 Requirement 工件可以包含的关系列表,请参见 OSLC RM V2 Specs 的 Resource Requirement 小节中的 “Relationship properties” 表。

要执行 PUT 操作,需要在 If-Match 标题中包含 Etag 值。Etag 可作为 Response Header 的一部分,通过对资源执行前面的 GET 操作获得。

下面是一个样例正文,以及将用于某个 QM 工件的 URL 和 Request Header,可创建一个 Validated By 关系。

操作: PUT
URL: https://doors9501.com:8443/dwa/rm/urn:rational::1-515ad1367be43903-O-49-000000a2
标题:
Content-Type:application/rdf+xml
If-Match:对资源执行 GET 后获得的 Etag 值
正文:

<rdf:RDF
    xmlns:dcterms="http://purl.org/dc/terms/"
    xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
    xmlns:rm_property="https://doors9501.com:8443/dwa/rm/urn:rational::1-
	515ad1367be43903-M-000000a2/types/"
    xmlns:rm="http://jazz.net/ns/rm#"
    xmlns:acp="http://jazz.net/ns/acp#"
    xmlns:oslc="http://open-services.net/ns/core#"
    xmlns:foaf="http://xmlns.com/foaf/0.1/"
    xmlns:oslc_rm="http://open-services.net/ns/rm#">
<oslc_rm:Requirement rdf:about="https://doors9501.com:8443/dwa/rm/urn:rational::1-
515ad1367be43903-O-49-000000a2">
<oslc:instanceShape rdf:resource="https://doors9501.com:8443/dwa/rm/oslc/shape/
requirement/urn:rational::1-515ad1367be43903-M-000000a2"/>
<rm_property:attrDef-12 rdf:datatype="http://www.w3.org/2001/XMLSchema#string">
Created using OSLC Creation Factory</rm_property:attrDef-12>
<rm_property:attrDef-4 rdf:datatype="http://www.w3.org/2001/XMLSchema#string">
Administrator</rm_property:attrDef-4>
<rm_property:attrDef-7 rdf:datatype="http://www.w3.org/2001/XMLSchema#dateTime">
2013-05-01</rm_property:attrDef-7>
<dcterms:created rdf:datatype="http://www.w3.org/2001/XMLSchema#dateTime">
2013-05-01</dcterms:created>
<acp:accessControl rdf:resource="https://doors9501.com:8443/dwa/rm/acp/noaccess"/>
<rm_property:attrDef-5 rdf:datatype="http://www.w3.org/2001/XMLSchema#dateTime">
2013-05-01</rm_property:attrDef-5>
<dcterms:contributor>
<foaf:Person>
<foaf:name>Administrator</foaf:name>
</foaf:Person>
</dcterms:contributor>
<rm_property:attrDef-13 rdf:datatype="http://www.w3.org/2001/XMLSchema#string">
</rm_property:attrDef-13>
<dcterms:title rdf:parseType="Literal">
49: Created using OSLC Creation Factory</dcterms:title>
<oslc:shortTitle rdf:parseType="Literal">
49: Created using OSLC Creation Factory</oslc:shortTitle>
<rm_property:attrDef-9 rdf:datatype="http://www.w3.org/2001/XMLSchema#integer">
49</rm_property:attrDef-9>
<oslc:serviceProvider rdf:resource="https://doors9501.com:8443/dwa/rm/discovery/
service/urn:rational::1-515ad1367be43903-M-000000a2"/>
<rm_property:attrDef-8 rdf:datatype="http://www.w3.org/2001/XMLSchema#dateTime">
2013-05-01T06:10:24Z</rm_property:attrDef-8>
<rm_property:attrDef-6 rdf:datatype="http://www.w3.org/2001/XMLSchema#string">
Administrator</rm_property:attrDef-6>
<rm_property:attrDef-10 
rdf:resource="https://doors9501.com:8443/dwa/rm/urn:rational::1-515ad1367be43903-M-
000000a2/types/attrDef-10#1"/>
<dcterms:description rdf:parseType="Literal"></dcterms:description>
<dcterms:creator>
<foaf:Person>
<foaf:name>Administrator</foaf:name>
</foaf:Person>
</dcterms:creator>
<dcterms:identifier rdf:datatype="http://www.w3.org/2001/XMLSchema#string">
49</dcterms:identifier>
<dcterms:modified rdf:datatype="http://www.w3.org/2001/XMLSchema#dateTime">
2013-05-01T06:10:24Z</dcterms:modified>
<rm_property:attrDef-11 rdf:datatype="http://www.w3.org/2001/XMLSchema#string">
Just some text for Object Text</rm_property:attrDef-11>
<oslc_rm:validatedBy rdf:resource="https://RQMServer.com:9443/qm/oslc_qm/contexts/
_EUB0tIJpEeKjaIQNt_0suA/resources/com.ibm.rqm.planning.VersionedTestCase/
_Jjh4EIJsEeKjaIQNt_0suA"/>
</oslc_rm:Requirement>
</rdf:RDF>

样例用例

让我们考虑这样一个场景:您需要在应用程序工件和 DOORS 工件(Requirement or Requirement Collection)之间创建一种关系。为了简化这个场景,我们将使用 DOORS 在根级别提供的 Selection UI 服务。

下面简单介绍了一些您需要在代码中执行的步骤:

  1. 访问 rootservices 文档
  2. 获得 oAuth 信息和授权
  3. 从 rootservices 获得 Service Provider Catalog URL
  4. 访问 Service Provider Catalog,找到 Service Provider URL
  5. 访问 Service Provider 文档并找到 Selection URI
  6. 访问 Selection URI,它将使用户能够在 Rational DOORS 中选择工件
  7. 完成选择后,工件的 URL 将在名为 “Location” 的响应标题中返回。
  8. 对所选工件的 URL 执行 GET 操作。捕捉响应的 Etag 和正文。
  9. 将应用程序工件的链接插入到您的应用程序中,插入 GET 返回的响应的正文中。按照工件的 resource shape 的定义,使用相应的关系类型。
  10. 对修改后的正文和 If-Match 标题(指定 Etag)执行 PUT 操作

oAuth 注意事项

OAuth 1.0 通常涉及 3 个步骤:

  1. 获取 Request Token
  2. 对 Request Token 进行授权
  3. 将 Request Token 换成 Access Token

在请求令牌前,您应当在 DOORS 中将应用程序注册为 Consumer。可以在 DOORS Database Properties -> Local Keys 中实现这一点。为您的应用程序添加一个条目并记住 Consumer Key 和 Consumer Secret(将在请求令牌时用到)。

以编程方式处理 oAuth

针对 IBM Rational DOORS 以编程方式处理 oauth 的代码样例可以从 Eclipse\Lyo 项目 获得。

Rootservices 文档包含以上提到的所有三个步骤所使用的 URL 的信息。节点 jfs:oauthRequestTokenUrl、jfs:oauthUserAuthorizationUrl、jfs:oauthAccessTokenUrl 分别包含这三个步骤所使用的 URL。

获取 Request Token:
操作: POST
URL: https://<dwaServer>:<dwaPort>/dwa/oauth-request-token
Headers:
oauth_version
oauth_consumer_key
oauth_signature_method = "HMAC-SHA1"
oauth_signature
oauth_timestamp
oauth_nonce

对以上请求的响应类型为 text/html Media Type,它将包含 oauth_token 和 oauth_secret。

对 Request Token 进行授权:
使用下面的 URL 登录到 DWA,对前面步骤中获得的 oauth_token 进行授权:
https://<dwaServer>:<dwaPort>/dwa/oauth-authorize-token?oauth_token=<request_token>

获取 Access Token:
对 Request 令牌进行授权后,使用 jfs:oauthAccessTokenUrl 的 URL 将它与访问令牌交换。
操作: GET
标题:
oauth_version
oauth_consumer_key
oauth_token = <request Token>
oauth_signature_method = "HMAC-SHA1"
oauth_signature
oauth_timestamp
oauth_nonce

请注意,在创建签名之前,oauth_secret 应当始终对 URL 编码。

参考资料

学习

获得产品和技术

讨论

条评论

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=Rational
ArticleID=962674
ArticleTitle=从 IBM Rational DOORS 访问 OSLC 服务
publish-date=02132014