CmCollectionNeeds < Main

This wiki is locked. Future workgroup activity and specification development must take place at our new wiki. For more information, see this blog post about the new governance model and this post about changes to the website.

TWiki>

Main Web>CmHome>CmCollectionNeeds (07 Apr 2010, SteveSpeicher)

Purpose

A temporary page to collect data needed to define and align needs for formats for collection of resources.

Purpose
Related Work
Definitions
Scenarios
Experience with @collref
things to investigate
Early Draft Proposals

Related Work

Collection of Change Requests CM 1.0

Multi-valued properties and resource links CM 1.0

Change Request CM 2.0

CmXmlFormat

MetricsCollectionsInRDFXML

Definitions

Change Request resource - A request for change to an application or product. Typically a product request for enhancement or a report for a resolution of a product defect.

Resource collection - An ordered or unordered set of resources, typically generated as the result of performing a query or search.

Multi-valued properties - A resource property that can exist more than once in a resource definition. In XML schema terms, maxOccurs > 1.

Scenarios

Scenarios used to help solidify the requirements for the proposed solution. The requests and responses are loosely defined to illustrate the needs

Query for Change Requests (references)

Request

GET /search?oslc.query=oslc:searchTerms="bugs"
Accept: application/atom+xml

Response

ATOM (referenced content)

Query for Change Requests (inlined)

Request

GET /search?oslc.query=oslc:searchTerms="bugs"&oslc.properties=oslc_cm:relatedChangeRequests
Accept: application/atom+xml

Response

ATOM (inlined content)

Request multi-valued property on Change Request

Request

GET /bugs/1?oslc.properties="relatedChangeRequest"
Accept: application/x-oslc-cm-change-request+xml

Response

<oslc_cm:ChangeRequest rdf:about="http://myhost/bugs/1">
  <oslc_cm:relatedChangeRequest rdf:resource="http://myhost/bugs/2" />
  <oslc_cm:relatedChangeRequest rdf:resource="http://myhost/bugs/3" />
  <oslc_cm:relatedChangeRequest rdf:resource="http://myhost/bugs/4" />
<;/oslc_cm:ChangeRequest>

Remove a multi-valued property from a Change Request

Request

GET as above and then

PUT /bugs/1?oslc.properties="relatedChangeRequest"
Content:
<oslc_cm:ChangeRequest rdf:about="http://myhost/bugs/1">
 <oslc_cm:relatedChangeRequest rdf:resource="http://myhost/bugs/2" />
 <oslc_cm:relatedChangeRequest rdf:resource="http://myhost/bugs/4" />
</oslc_cm:ChangeRequest>

Add another multi-valued property to a Change Request

Request

GET as above and then

PUT /bugs/1?oslc.properties="relatedChangeRequest"
Content:
<oslc_cm:ChangeRequest rdf:about="http://myhost/bugs/1">
 <oslc_cm:relatedChangeRequest rdf:resource="http://myhost/bugs/2" />
 <oslc_cm:relatedChangeRequest rdf:resource="http://myhost/bugs/4" />
 <oslc_cm:relatedChangeRequest rdf:resource="http://myhost/bugs/5" /> 
</oslc_cm:ChangeRequest>

Get a Change Request with many multi-valued properties

Request

GET /bugs/2
Accept: application/x-oslc-cm-change-request+xml

Response A bit exaggerated but possible example.

<oslc_cm:ChangeRequest rdf:about="">
  <dc:title> Provide import </dc:title>
  <dc:identifier> 2314 </dc:identifier>
  <dc:type> http://myserver/mycmapp/types/Enhancement </dc:type>
  <dc:description>
    Implement the system's import capabilities.
  </dc:description>
  <dc:subject> import, blocker </dc:subject>
  <dc:creator rdf:resource="http://myserver/mycmapp/users/joe" />
  <dc:modified> 2008-09-16T08:42:11.265Z </dc:modified>
  <dc:name>Enh2314: Provide import</dc:name>
  <dc:created> 2008-07-04T11:00:00.000Z </dc:created>
  <oslc_cm:doneDate> </oslc_cm:doneDate>  <!-- Done/Completion date -->
  <oslc_cm:project rdf:resource="http://myserver/mycmapp/projects/proj1" />
  <oslc_cm:component rdf:resource="http://myserver/mycmapp/projects/proj1/comps/comp1" />
  <oslc_cm:status> InProgress </oslc_cm:status>
  <oslc_cm:owner rdf:resource="http://myserver/mycmapp/users/bob" />
  <oslc_cm:priority> High </oslc_cm:priority>
  <oslc_cm:severity> Blocker </oslc_cm:severity>

  <oslc_cm:relatedChangeRequest rdf:resource="http://myhost/bugs/1" />
  ...
  <oslc_cm:relatedChangeRequest rdf:resource="http://myhost/bugs/100" />
  <oslc_cm:affectedTestCase rdf:resource="http://myhost/testcases/1" />
  ...
  <oslc_cm:affectedTestCase rdf:resource="http://myhost/testcases/100" />
  <oslc_cm:changeSets rdf:resource="http://myhost/changesets/1" />
  ...
  <oslc_cm:changeSets rdf:resource="http://myhost/changesets/100" />
  <oslc_cm:implements rdf:resource="http://myhost/reqs/1" />
  ...
  <oslc_cm:implements rdf:resource="http://myhost/reqs/100" />
</oslc_cm:ChangeRequest>

Experience with @collref

RTC and CQ have used to provide some optimization and works well. Things the work well:

Optimized retrieval of change request resource when there are many multi-valued properites for things like change sets, test cases, builds, related CRs, etc
Can still request inlined content by requesting property explicitly. GET /bugs/1?oslc.properties="builds{*}"
Provides a URL (value of @collref) as a simple place to POST to add an entry to a list (or another property value)

Drawbacks:

Removing an entry: Still have to PUT the entire collection minus one to be removed
Need to have proper pagination support and minimal format definition (XML)

things to investigate

Whether RTC can delete links
Concerns with scaling still valid Need to model intermediate link resources vs. multi-value properties
Possible approach is to give each entry its own URL so it can be removed. This enables delete when entry URL is given. How to handle creating/adding new entries?
Look into approaches with proppatch or similar approach ATOM Syndication Format is expensive to generate for some CM providers due to its required attributes.
Entry with rdf:parseType="Collection"

Early Draft Proposals

Provide an alternative to a truly flat structure by having an alternative way of providing scalable collections. Simple multi-valued properties will still utilize a flat structure (repeating elements) instead of providing the following proposed level of indirection that is intended for multi-valued link properties.

Fetch: The scalable collections provide an indirect access to the entire set of values by providing a URL where a GET can be performed to retrieve the collection of property values. A service provider may chose to limit the number of entries returned and provide information in the results so additional values can be retrieved. Service providers may also accept filters or pagination parameters to refine the amount returned in the collection.

Add: This URL can also be used to add additional entries to this collection, in other words, assign another value to a multi-valued property.

Remove: A service provider may provide a URL with each multi-valued property to uniquely identify a property-value pair. A consumer can perform a DELETE on this entry URL to remove it from the collection/list.

To illustrate this approach, we'll take some examples: