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
)
(raw view)
---++ Purpose A temporary page to collect data needed to define and align needs for formats for collection of resources. %TOC% ---++ Related Work [[http://open-services.net/bin/view/Main/CmRestApiV1#Get_a_collection_of_change_reque][Collection of Change Requests CM 1.0]] [[http://open-services.net/bin/view/Main/CmRestApiV1#Managing_multi_valued_properties][Multi-valued properties and resource links CM 1.0]] [[http://open-services.net/bin/view/Main/CmResourceDefinitionsV2#XML_Representation_of_the_Change][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* <verbatim>GET /search?oslc.query=oslc:searchTerms="bugs" Accept: application/atom+xml </verbatim> *Response* ATOM (referenced content) ---+++ Query for Change Requests (inlined) *Request* <verbatim>GET /search?oslc.query=oslc:searchTerms="bugs"&oslc.properties=oslc_cm:relatedChangeRequests Accept: application/atom+xml </verbatim> *Response* ATOM (inlined content) ---+++ Request multi-valued property on Change Request *Request* <verbatim>GET /bugs/1?oslc.properties="relatedChangeRequest" Accept: application/x-oslc-cm-change-request+xml </verbatim> *Response* <verbatim><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> </verbatim> ---+++ Remove a multi-valued property from a Change Request *Request* GET as above and then <verbatim>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> </verbatim> ---+++ Add another multi-valued property to a Change Request *Request* GET as above and then <verbatim>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> </verbatim> ---+++ Get a Change Request with many multi-valued properties *Request* <verbatim>GET /bugs/2 Accept: application/x-oslc-cm-change-request+xml </verbatim> *Response* A bit exaggerated but possible example. <verbatim><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> </verbatim> ---++ 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: ---+++ Get a Change Request with some multi-valued properties (tags) *Request* <verbatim>GET /bugs/1?oslc.properties=dc:subject Accept: application/x-oslc-cm-change-request+xml </verbatim> *Response* A simplified example <verbatim><oslc_cm:ChangeRequest rdf:about="http://myhost/bugs/1"> <dc:subject>blocker</dc:subject> <dc:subject>m4candidate</dc:subject> <dc:subject>newandnoteworthy</dc:subject> </oslc_cm:ChangeRequest> </verbatim> ---+++ Get a Change Request with many multi-valued link properties (referenced) *Request* <verbatim>GET /bugs/1 Accept: application/x-oslc-cm-change-request+xml </verbatim> *Response* A simplified example <verbatim><oslc_cm:ChangeRequest rdf:about="http://myhost/bugs/1"> <dc:title> Provide import </dc:title> <dc:identifier> 2314 </dc:identifier> <dc:type> http://myserver/mycmapp/types/Enhancement </dc:type> <oslc_cm:relatedChangeRequest rdf:resource="http://myhost/bugs/1/related" /> </oslc_cm:ChangeRequest> </verbatim> ---+++ Get a Change Request with many multi-valued link properties (inlined) *Request* <verbatim>GET /bugs/1?oslc.properties="dc:title,oslc_cm:relatedChangeRequests{*}" Accept: application/x-oslc-cm-change-request+xml </verbatim> *Response* A simplified example <verbatim><?xml version="1.0" encoding="UTF-8"?> <oslc_cm:ChangeRequest xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:dc="http://purl.org/dc/terms/" xmlns:oslc_cm="http://open-services.net/xmlns/cm/1.0/" rdf:about="http://myhost/bugs/1"> <dc:title> Provide import </dc:title> <oslc_cm:relatedChangeRequests> <oslc_cm:ChangeRequests rdf:about="http://myhost/bugs/1/related"> <oslc_cm:relatedChangeRequest rdf:resource="http://myhost/bugs/2" /> <oslc_cm:relatedChangeRequest rdf:resource="http://myhost/bugs/4" /> </oslc_cm:ChangeRequests> </oslc_cm:relatedChangeRequests> </oslc_cm:ChangeRequest> </verbatim> ---+++ Get a Change Request with many multi-valued properties (inlined, pagination) *Request* <verbatim>GET /bugs/1?oslc.properties="dc:title,oslc_cm:relatedChangeRequests{*}" Accept: application/x-oslc-cm-change-request+xml </verbatim> *Response* A simplified example <verbatim><?xml version="1.0" encoding="UTF-8"?> <oslc_cm:ChangeRequest xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:dc="http://purl.org/dc/terms/" xmlns:oslc_cm="http://open-services.net/xmlns/cm/1.0/" rdf:about="http://myhost/bugs/1"> <dc:title> Provide import </dc:title> <oslc_cm:relatedChangeRequest > <oslc_cm:ChangeRequests rdf:about="http://myhost/bugs/1/related" > <oslc_cm:relatedChangeRequest rdf:resource="http://myhost/bugs/2" /> <oslc_cm:relatedChangeRequest rdf:resource="http://myhost/bugs/4" /> <oslc_cm:nextPage>http://myhost/bugs/1/related?startIdx=3</oslc_cm:nextPage> </oslc_cm:ChangeRequests> </oslc_cm:relatedChangeRequest> </oslc_cm:ChangeRequest> </verbatim> ---+++ Get the collection of a multi-valued property GET on collection resource *Request* <verbatim>GET http://myhost/bugs/1/related Accept: application/x-oslc-cm-change-request+xml </verbatim> *Response* A simplified example <verbatim><oslc_cm:ChangeRequests rdf:about="http://myhost/bugs/1/related"> <oslc_cm:relatedChangeRequest rdf:resource="http://myhost/bugs/2" /> <oslc_cm:relatedChangeRequest rdf:resource="http://myhost/bugs/4" /> </oslc_cm:ChangeRequests> </verbatim> ---+++ Get a single property value of a multi-valued property GET on entry (@rdf:resource) *Request* <verbatim>GET http://myhost/bugs/2 Accept: application/x-oslc-cm-change-request+xml </verbatim> *Response* <verbatim><oslc_cm:ChangeRequest rdf:about="http://myhost/bugs/2"> <dc:title> Title for bug 2 </dc:title> </oslc_cm:ChangeRequest> </verbatim> ---+++ Add another value to a multi-valued property See OSLCCorePartialUpdateDRAFT POST to @rdf:resource/about of relatedChangeRequests <verbatim>POST http://myhost/bugs/1/related Content-type: application/x-oslc-cm-change-request+xml Content: <oslc_cm:relatedChangeRequest rdf:resource="http://myhost/bugs/6"/> </verbatim> *Response* <verbatim> 201 (Created) Location: http://myhost/bugs/1/related?oslc.where=rdf:resource="http://myhost/bugs/6" </verbatim> ---+++ Remove a value from a multi-valued property *Request* <verbatim> DELETE http://myhost/bugs/1/related?oslc.where=rdf:resource="http://myhost/bugs/6" </verbatim> *Response* <verbatim> 200 (Ok) </verbatim> *NOTE* Would it be wrong to just do a DELETE on query URI? HTTP says that DELETE deletes a resource represented by the Request-URI. According to HTTP definition of a resource, this seems to be in line. *NOTE* Need to clarify what happens if URL matches more that one property-value pair. *TODO* Investigate the commands through PATCH approach, though this POST/DELETE seems to be enough ---+++ Update a value from a multi-valued property Delete old value, add new value. See above.
E
dit
|
A
ttach
|
P
rint version
|
H
istory
: r12
<
r11
<
r10
<
r9
<
r8
|
B
acklinks
|
V
iew topic
|
Ra
w
edit
|
M
ore topic actions
Topic revision: r12 - 07 Apr 2010 - 14:22:30 -
SteveSpeicher
Main
Main Web
Create New Topic
Index
Search
Changes
Notifications
RSS Feed
Statistics
Preferences
Webs
Main
Sandbox
TWiki
Български
Cesky
Dansk
Deutsch
English
Español
Français
Italiano
日本語
Nederlands
Polski
Português
Русский
Svenska
简体中文
簡體中文
Copyright � by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Contributions are governed by our
Terms of Use
Ideas, requests, problems regarding this site?
Send feedback