Using Selective Properties (aka Partial Fetch)

Often is an issue when working with retrieving resources and their properties is getting the desired information efficiently. By definition of the CM 1.0 specification, when requesting a change request resource without any parameters to refine the list of properties you should retrieve ALL properties that resource has. Take for example this simple request:

GET http://example.com/bugs/2314
Accept: application/x-oslc-cm-change-request+xml

This will result in the change request identified by the URL to be retrieved:

<oslc_cm:ChangeRequest 
  rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" 
  dc="http://purl.org/dc/terms/" 
  oslc_cm="http://open-services.net/xmlns/cm/1.0/"
  xmlns="http://myserver/xmlns"
  about="http://example.com/bugs/2314">

  <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 resource="http://example.com/users/aadams" />
  <dc:modified> 2008-09-16T08:42:11.265Z </dc:modified>
  <owner resource="http://example.com/users/john">
  <priority>High</priority>
  <severity>High</severity>
  <status>Working</status>
</oslc_cm:ChangeRequest>

This is useful when a consumer doesn't know which properties to request but can provide more information than is needed (both that the provider needs to generate and the consumer needs to process). To limit the amount of properties returned, the concept of selective properties can be used. If the consumer is only interested in the owner and the status, the request could be formulated such as:

GET http://example.com/bugs/2314?oslc_cm.properties=owner,status
Accept: application/x-oslc-cm-change-request+xml

Resulting in:

<oslc_cm:ChangeRequest 
  dc="http://purl.org/dc/terms/"
  oslc_cm="http://open-services.net/xmlns/cm/1.0/"
  xmlns="http://myserver/xmlns"
  about="http://example.com/bugs/2314">

  <owner resource="http://example.com/users/john" />
  <status>Working</status>
</oslc_cm:ChangeRequest>

Perhaps we are interested in the owner's name and email address, we can expand the owner entry and select only those properties to be returned such as:

GET http://example.com/bugs/2314?oslc_cm.properties=owner{fullname,email},status
Accept: application/x-oslc-cm-change-request+xml

Resulting in:

<oslc_cm:ChangeRequest 
  rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" 
  dc="http://purl.org/dc/terms/"
  oslc_cm="http://open-services.net/xmlns/cm/1.0/"
  xmlns="http://myserver/xmlns"
  about="http://example.com/bugs/2314">

  <owner>
    <User rdf:about="http://example.com/users/john">
      <fullname>John Doe</fullname>
      <email>jdoe@myco</email>
    </User>
  <status>Working</status>
</oslc_cm:ChangeRequest>

This technique is used in CM 1.0 not only for selective retrieval of properties on a change request resource, it is used for partial updates of resources as well as controlling the content on query responses.