HistoryViewLinks to this page 2012 September 6 | 03:49 pm

This is one proposal for creating baselines in OSLC. For an overall description of the baseline scope and scenarios, and links to other proposals, see Baselines In Oslc.

This proposal defines a baselining capability where a service provider creates a snapshot of one or more resources by capturing the state of those resources. Compared to the other OSLC baseline proposals, it has the advantage of simplicity, but has a disadvantage in that the client has to determine the set of resources and service providers involved, rather than the providers themselves determining the dependencies.

There are two primary concepts: a camera capability for finding or making immutable snapshots, copies, or versions of resources or their states, and a Baseline resource that holds links to members of a baseline. The camera capability manipulates resources from a single OSLC provider; the baseline capability allows links to snapshots from multiple service providers.

The proposal also introduces the concept of a base resource URI: this is a URI that encompasses all possible states or versions of some resource. From the combination of a base resource URI together with sufficient context, a provider MUST return the appropriate state or version of that resource. If no context, or insufficient context, is provided, a provider MAY treat this as an error, or MAY return some representation of the base resource itself.

The Camera Capability

A server MAY provide a camera capability, to form or discover immutable snapshots, copies, or versions of its resources or their states. This capability is described by a Camera resource; the Camera resource is a factory through which new snapshots may be constructed, and providing information about snapshots previously made.

The oslc:Camera resource has the following properties, consistent with those of an OSLC Core Specification Resource Creation Factory:

Prefixed Name Occurs Read-only Value-type Representation Range Description
dcterms:title exactly-one True XMLLiteral n/a n/a Title string that could be used for display, possibly “Camera” in English
oslc:creation exactly-one True Resource Reference n/a Same as the oslc:snapshots property below: to create a new snapshot via the factory, post it to this URI
oslc:snapshots exactly-one True Resource Reference n/a Creation factory and resource base: to create a new snapshot, post an oslc:Snapshot resource to this URI, or GET this URI to see the set of existing snapshots
oslc:resourceShape exactly-one True Resource Reference oslc:ResourceShape The resource shape for the oslc:Snapshot resource
oslc:resourceType zero-or-many True Resource Reference n/a The oslc:Snapshot resource type URI
oslc:usage one-or-many True Resource Resource n/a An identifier URI for the camera: one occurrence of this property MUST have the value http://open-services.net/ns/core#camera

oslc:Snapshot Resource

The oslc:Snapshot resource has the following properties:

Prefixed Name Occurs Read-only Value-type Representation Range Description
dcterms:created zero-or-one True DateTime n/a n/a Timestamp of resource creation (reference: Dublin Core)
dcterms:creator zero-or-many True Resource either any Creator or creators of resource (reference: Dublin Core). It is likely that the target resource is a foaf:Person but that is not necessarily the case.
dcterms:description zero-or-one False XMLLiteral n/a n/a Descriptive text (reference: Dublin Core) about resource represented as rich text in XHTML content; this SHOULD include only content that is valid and suitable inside an XHTML <div> element. This is intended to be a a human-readable description of the baseline.
dcterms:identifier zero-or-one True String n/a n/a An internal identifier, usually assigned by the service provider. If this property exists, its value SHOULD be unique amongst all currently existing baseline resources from this service provider. The string is not necessarily intended to be conveniently readable to humans.
dcterms:modified zero-or-one True DateTime n/a n/a Timestamp of the latest resource modification (reference: Dublin Core)
dcterms:title exactly-one False XMLLiteral n/a n/a Title string that could be used for display
rdfs:member zero-or-many False Resource Reference Any A resource that is part of this snapshot. Note that this URI might or might not be the same as the URI of the resource given at the time the snapshot was requested: the original URI might be that of a base resource, encompassing all versions of that resource, while this rdfs:member URI might be that same base resource URI or might be a version-specific URI. Clients SHOULD assume that the snapshot member URI is that of the base resource, and therefore SHOULD always use one of the mechanisms described in Using a Snapshot to retrieve the state of the given member in a snapshot. Note also that a snapshot can have more members than those originally requested, since the service provider MAY add additional dependent resources.

Camera Usage and Results

  1. A consumer requests an immutable snapshot of one or more resources belonging to a single service provider by a POST to the camera creation factory, following the normal OSLC conventions, with the rdfs:member properties in the POSTed snapshot resource containing the URIs of the resources for which a snapshot is requested. The result is the URI of an immutable oslc:Snapshot resource.
  2. The snapshot request MAY fail, perhaps because one or more of the resources for which a snapshot was requested cannot be the subject of such a request. In this case, the provider SHOULD return sufficient information about the cause of the failure that a user can correct the situation.
  3. If the request is successful, the resulting oslc:Snapshot resource has as members at least the set of resources in the original POST request.
  4. A service provider MAY add to the snapshot additional dependent resources from the same service provider.
  5. The specification for an OSLC domain MAY provide additional clarification and requirements determining the dependent members of a snapshot.
  6. A service provider SHOULD provide a query capability that includes snapshots.

Using a Snapshot

An OSLC service that implements the camera service MUST support retrieval of a resource in the context of specified snapshot; the result of such a request MUST be a representation materially the same as the state of the requested resource as it was at the time the snapshot was taken. For example, read-only properties such as the time of last access may be different.

A snapshot is identified using the URI of the snapshot itself, or using the URI of a baseline containing a snapshot. When given a baseline, the service provider finds the member snapshot created by that same service provider; it is an error if there is no such snapshot, or if there is more than one. A snapshot provider MUST support passing the snapshot or baseline context to a resource request in each of the following ways:

  • Appending oslc.snapshotMember query string and the URI (or base resource URI) of the requested resource to the URI of a snapshot or baseline;
  • Passing the URI of a snapshot or baseline in the X-Oscl-Snapshot http header;
  • Passing the URI of a snapshot or baseline in an X-Oscl-Snapshot cookie.

OSLC domain specifications MAY define additional or extended mechanisms for communicating baseline and snapshot context. In some domains the combination of a base resource URI and a baseline or snapshot URI might not be sufficient to identify a unique resource state - for example, in SCM, a configuration might contain two different versions of the same base resource in different paths within that configuration, as when a dependent library was rebuilt to fix a last-minute defect, but only selected portions of the complete configuration were updated to use that new library version to reduce the risk associated with making last-minute changes. In this case, it might be convenient to allow a URI to be constructed combining in some manner the snapshot context, the base resource identity, and the relative path to that resource within the SCM snapshot.

oslc.snapshotMember ::= "oslc.snapshotMember=" uri_ref_esc

Examples:

GET http://example2.com/oslc/baseline/1234?oslc.snapshotMember=http://example1.com/oslc/someresource

GET http://example2.com/oslc/baseline/1234/scmSnapshot1?oslc.snapshotMember=http://examplescm.com/oslc/configuration1/path/to/someresource

GET /oslc/someresource
Host: http://example1.com
X-Oscl-Snapshot: http://example2.com/oslc/baseline/1234

GET http://example1.com/oslc/someresource
Cookie: X-Oscl-Snapshot=http://example2.com/oslc/baseline/1234

OSLC Baseline Resource

This baseline resource is adapted from the OSLC SCM baseline, for a more general usage across OSLC:

Prefixed Name Occurs Read-only Value-type Representation Range Description
Dublin Core properties
dcterms:created zero-or-one True DateTime n/a n/a Timestamp of resource creation (reference: Dublin Core)
dcterms:creator zero-or-many True Resource either any Creator or creators of resource (reference: Dublin Core). It is likely that the target resource is a foaf:Person but that is not necessarily the case.
dcterms:description zero-or-one False XMLLiteral n/a n/a Descriptive text (reference: Dublin Core) about resource represented as rich text in XHTML content; this SHOULD include only content that is valid and suitable inside an XHTML <div> element. This is intended to be a a human-readable description of the baseline.
dcterms:identifier zero-or-one True String n/a n/a An internal identifier, usually assigned by the service provider. If this property exists, its value SHOULD be unique amongst all currently existing baseline resources from this service provider. The string is not necessarily intended to be conveniently readable to humans.
dcterms:modified zero-or-one True DateTime n/a n/a Timestamp of the latest resource modification (reference: Dublin Core)
dcterms:shortTitle zero-or-one False String n/a n/a A short name that is often used for an abbreviated identifier and used for presentation to end-users.
dcterms:subject zero-or-many False String n/a n/a Tag or keyword for a resource. Each occurrence of a dcterms:subject property denotes an additional tag for the resource.
dcterms:title zero-or-one False XMLLiteral n/a n/a Title (reference: Dublin Core) of the resource represented as rich text in XHTML content; this SHOULD include only content that is valid inside an XHTML <span> element. This is intended to be a human readable name or synopsis of the baseline.
Other common properties
oslc:instanceShape zero-or-one True Resource reference oslc:ResourceShape Resource Shape that specifies allowed and required fields.
oslc:serviceProvider zero-or-one True Resource reference oslc:ServiceProvider A link to the resource’s OSLC Service Provider.
rdf:type one-or-many True Resource reference n/a The resource type URI
Baseline-specific properties
rdfs:member zero-or-many False Resource reference oslc:Snapshot A snapshot resource that is a member of this baseline.

Baseline Creation and Usage

  1. Clients create a Baseline resource by creating a HTTP POST request with the initial set of baseline properties to the baseline creation factory URI.
  2. Clients may add oslc:Snapshot resources as members of a Baseline resource when that baseline is initially created using POST, or while it is under construction using PUT updates. Service providers MAY support a partial update protocol.
  3. The snapshots added to a baseline do not have to be all from the same service, service provider, or OSLC domain.
  4. An OSLC baseline service MUST provide a Baseline creation factory, and SHOULD provide a query capability that includes Baselines.
  5. A baseline service provider MAY also implement the camera capability. In such a service provider, baselines may be composed from snapshots of other baselines and other snapshots.

Note that that it is possible for a client to “front-end” documents or service providers that do not currently support snapshots to add thise capability. For example, simple Word or Excel documents can be added to baselines by creating a wrapper to copy the required documents or resources, create an oslc:Snapshot resource linking to those now-static copies, and add this new snapshot to an oslc:Baseline. It would also be possible to define and create a new service providing this wrapping capability.

Baseline membership traversal

Clients can navigate from baselines to their oslc:Snapshot members. This specification does not define the link structure within those snapshots: some providers might add as snapshot members all the resources in the snapshot, or just direct members, with other snapshotted members linked to those direct members. An OSLC domain specification MAY provide additional details about snapshot membership.

Best Practices for Linking

A link between OSLC resources MAY be in the form of a URI qualified by the baseline or snapshot context. While such version-specific links might be appropriate in some cases, in general they should be avoided as they reduce flexibility. For example, if a test case is linked directly to a requirement in the context of a given baseline, it is forever linked only to that specific state of the target requirement. It might be more appropriate to create the link between the test case and the base resource URI for the requirement, and to express the baseline context using the http header or cookie techniques. This allows the link to be remain valid for subsequent baselines of the test cases and requirements.


Comments

From Ian Green: This proposal leaves somewhat unconstrained the relationship between a resource and an immutable snapshot of that resource. The mention of “base URI” seems to suggest that the rdfs:member URIs of a snapshot might have something in common with the URIs of the things they are snapshots of, but the spec does not require this, nor provide a mechanism for the user to derive one from the other. Should a client be able to determine that a resource and one of its snapshots are so related?

Also from Ian: The proposal allows for the creation of snapshots of baselines, and hence the composition of baselines of baselines. Is this extra complexity necessary?

From Martin Nally: I think the “Baseline membership traversal” paragraph is too complex. I think we should go one of two ways 1) make the snapshot totally opaque – you can’t get a list of its members 2) make it list all its members in a flat list.

Main/NickCrossley - 20 Jul 2011

Should the snapshot creation process use long-running operation techniques, such as returning a status resource that the client must poll until completion, whereupon the URI of the snapshot resource becomes available?

Main/NickCrossley - 04 Aug 2011

Are we comfortable with the proposed terminology? The term ‘snapshot’ as used here might correspond to existing ‘baseline’ artifacts in current tools.

Main/NickCrossley - 04 Aug 2011