Snapshots With Resource Rewriting

Snapshots With Resource Rewriting

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 resource snapshots are created by rewriting the links in each affected resource. A variant of this proposal has been suggested, providing more service provider assistance in determining dependent resource links across multiple service providers, but suffering from complexity and implementation difficulties.

There are two concepts: a camera capability for finding or making immutable snapshots, copies, or versions of resources, 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 arbitrary resources to be members of a baseline, including non-OSLC and non-RDF resources.

The Camera Capability

An OSLC service provider MAY provide a camera capability, to form or discover immutable snapshots, copies, or versions of its resources. This capability is indicated by the presence of a camera property on the service provider resource, giving the URI of the camera, as well as information about the camera’s features.

Additional property on oslc:ServiceProvider resource:

The oslc:Camera resource has the following properties:

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 URI, with the POST data containing the URI of the resources for which a snapshot is requested. The result is the URI of an immutable resource. If the POST request was given only a single resource to snapshot, the result might be a new version or copy of that resource, or it might be the original resource made immutable. If multiple resources were passed to the snapshot request, the result would be a container resource with the snapshot resources linked using the camera’s oslc:snapshotMember property, or using rdfs:member if no oslc:snapshotMember property was defined.
2. Each resource in the set returned from a snapshot request has the same properties as the original resource except for member links as described below, and the optional addition of the oslc:readOnly state predicate set to true.
3. When a snapshot of a resource is taken, a snapshot MUST also be taken of all resources that are from the same service provider as the initial resource and that are the object of any of the camera’s oslc:dependentMember properties; in the immutable resource returned from the snapshot request, the dependent member properties MUST point to the (possibly newly created) immutable member resource snapshots.
4. The resources returned from a snapshot request, including any dependent member resources SHOULD be immutable; a PUT on any of these resources SHOULD fail.

Finding Existing Snapshots

From Steve:

Does there need to be a way for a client to discover the snapshots that exist? For example, does a client always need to create/get a snapshot or can it pick from existing ones? If we feel there is a need for discovery of existing snapshots, then we could add snapshots as a property of the camera - the camera remembers what snapshots it has taken. A client can then find all snapshots with a GET on the camera URI. The snapshots for a given resource could be found if we added an oslc:snapshotOf property to a snapshot.

An alternative design could be using a collection pattern for creating and finding snapshots of each individual resource, like this: * Create a snapshot using POST uri?oslc.snapshot * Get all snapshots associated with resource with GET uri?oslc.snapshot

However, this approach does not provide information on the existence of the camera capability or its properties.

OSLC Baseline Resource

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

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 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 SHOULD support the partial update protocol.
3. The members added to a baseline do not have to be all from the same service, service provider, or OSLC domain - they can in fact be non-OSLC or non-RDF resources.
4. A Baseline resource has rdfs:member links to one or more other resources that are members of the baseline. Any resource can be a member of a baseline, but since completed baselines should be immutable, clients SHOULD add as members only immutable resources, or mutable resources from the same service provider as the Baseline resource itself. One way to get immutable resources for Baselining is using the snapshot capability described earlier.
5. An OSLC baseline service MUST provide a Baseline creation factory, and SHOULD provide a query capability that includes Baselines.
6. A baseline service provider MUST implement the camera capability. Once a baseline construction has been completed, clients SHOULD get the URI of an immutable snapshot of this Baseline resource using the camera. This will also get immutable versions of members resources from the same service provider; as noted earlier, resources from other providers should already be immutable versions.

Making the contributing service providers rather than a baseline service from a different service provider responsible for creating versions or snapshots is a key characteristic of this proposal. Note that that it is possible for a client to “front-end” a service provider that doesn’t currently support snapshots to add the capability, so this approach does not preclude integrating service providers that don’t support snapshots or immutability, it just says that the baseline service does not provide this function.

Baseline membership traversal

The proposals above use the property rdfs:member for the immediate members of a baseline, and provider-specific properties for snapshot members and dependent resources.

When forming a baseline, a client can snapshot one or more resources, and then either add just the immediate snapshot results to a baseline, or add the immediate snapshot results and all their dependent members, recursively.

When examining the contents of a baseline, a client can look at the immediate members. From those immediate members, a client could find the service provider of any OSLC member resources with the oslc:serviceProvider property, inspect the oslc:camera property to find the dependent member property names, and recurse down finding dependent members. However, there is no guarantee that this procedure would find the complete set of baseline members intended by the clients that were involved in constructing the snapshots and baselines. For example, since the oslc:serviceProvider property is optional, the algorithm would not work for resources missing that property. Attempting to work around this issue by having clients add all dependent resources directly to the baseline does not seem to scale well as baselines are composed into even larger baselines across teams, components, products, and product lines.

Comments

Added my comments as document attachment

Nick: Steve, I think all your comments were either addressed in the previous meeting, or incorporated into this updated proposal.

– Main/SteveSpeicher - 06 Apr 2011

Nick, regarding #6 above:

An OSLC baseline service MUST provide a Baseline creation factory, and SHOULD provide a Baseline query capability. To be compliant with the Indexer Profile, the service MUST provide a Baseline query capability.

Unless I’m misunderstanding the intent, I’m not sure I agree with the last requirement (‘To be compliant with the Indexer Profile, the service MUST provide a Baseline query capability.’).

Or rather I don’t believe it to be a mandatory requirement.

The snapshot resources, or the baseline resources themselves are ultimately resources that (if the service provider wants them to be - in other words they decide that they should be published resources) will already be exposed by a service provider implementing the indexing profile requirement that at least one Query Capability be exposed with a defined oslc:usage value (e.g. oslc:usage = “http://open-services.net/ns/core/log#resources”)

I see that it may be useful for indices to be able to store data that excludes snapshotted resources (current version only) as well as to be able to store only snapshotted resources (be they from multiple baselines or just one) and so having Query Capabilities available that return relevant resource subsets for baselines would often be useful, I just don’t know if it should be mandatory in the context of the indexing profile.

– Main/BenjaminWilliams - 06 Apr 2011

Nick: That sentence was intended to mean “If the provider intends to be compliant with the Indexer Profile, the service MUST provide a query base that includes Baseline resources.” Since the change log proposal itself covers this requirement, it is redundant to state it here, so I have removed it.

dcterms:name is still in the list of properties but it doesn’t exist, use oslc:shortTitle or rdfs:label or something else instead.

– Main/SteveSpeicher - 13 Apr 2011

Nick: lost that edit - now fixed!