Snapshots With Complex Resource Rewriting

This proposal defines a general baselining capability. 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.

Note : this proposal is not recommended; it is over-complex, and is included only as a basis for discussion of where resource rewriting might lead. For an overall description of the baseline scope and scenarios, and links to current proposals, see Baselines In Oslc.

The Camera Capability

An OSLC service provider MAY provide a camera capability, to form or discover immutable snapshots, copies, or versions of its resources. The camera also identifies dependent resources – those that should be part of a snapshot. The camera 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 snapshots currently in progress.

Additional property on oslc:ServiceProvider resource:

The oslc:SnapshotRequest resource has the following properties:

Prefixed Name	Occurs	Value-type	Repr.	Range	Description
oslc:externals	zero-or-many	Resource	Reference	Any	The resources in set R3 (see below).
oslc:resourceMap	one-or-many	Local Resource	Inline	n/a	The map of original URIs to the equivalent immutable URIs, for resources in the sets R1 and R2 (see below). There must be at least one map entry, since there must be at least one original URI in a snapshot request; it is an error to request a snapshot of no resources.

The oslc:resourceMap property is a blank node with the following properties:

Dependent Resources and the Snapshot Procedure

1. In order to form a meaningful snapshot of one resource, it may be necessary to form a snapshot of one or more linked resources at the same time, to ensure semantic consistency of the snapshot. In this specification, we define such linked resources as dependent resources. It is left to each service provider to determine the set of dependent resources.
2. A set of resources R1 from a single service provider S1 may be dependent on zero or more resources R2 from the same service provider, and zero or more resources R3 from other service providers.
3. The set R2 is transitively closed; the service provider S1 is responsible for forming the complete set of dependent resources belonging to S1.
4. The set R3 is not closed, but is the complete set of resources not belonging to S1, but known by S1 to be dependencies of resources in R1 or R2.
5. A consumer wishes to form a snapshot of R1 and all its transitive dependent resources in all service providers.
6. The consumer requests this snapshot process to start by a POST to the camera URI, with the POST data containing the URIs of the resources in the set R1. The result is an interim resource indicating the status of the snapshot request, in the form of a SnapshotRequest resource. This interim resource identifies the original URIs for resources in the set R3, and also identifies (potentially new) URIs for immutable versions or copies of the resources in the sets R1 and R2, in the form of a map from each original URI to its equivalent immutable resource URI. Note that this could be an identity mapping.
7. The consumer examines this response, and for each resource in R3 the consumer identifies the owning service provider. For each of these service providers, the consumer requests snapshot process to start, passing in both the list of the resources from set R3 that belong to this service provider and the current map of original URI to immutable URI. For each response, the client appends any previously unseen URIs in R3 to the set of resources for which snapshots are desired, and the client also appends the resource map in the response to its copy of the map.
8. After getting a snapshot request for each service provider involved, the client has a complete mapping from original URIs to their equivalent immutable versions or copies. The client now POSTs that map to each SnapshotRequest resource. This indicates to each service provider that the snapshot is confirmed, and should be created.
9. As the snapshot is created, the service provider forms the immutable version or copy of each resource in the snapshot sets R1 and R2, with the URI that was determined previously. During this process, the service provider MUST rewrite each resource, changing all references to dependent resources using the map from the original URI to the equivalent immutable resource URI. Note that at this point, that map contains the combined mapping for URIs in all the participating service providers.
10. Each resulting immutable resource MAY also have the oslc:readOnly state predicate set to true.
11. At the end of the snapshot process, the SnapshotRequest resource itself is made immutable, and MAY have the oslc:readOnly state predicate set to true.
12. A PUT or POST to an immutable resource SHOULD fail.
13. Service providers MAY delete SnapshotRequest resources at some time after they are created; if the SnapshotRequest is not immutable then deleting the SnapshotRequest MAY also release the URIs previously allocated for immutable versions or copies of the original resources.

If a client finds a resource in any of the S3 external references for which the service provider is unknown, not an OSLC provider, or a provider that does not offer the camera service, it is up to the client how to proceed. The client could decide to abandon the snapshot process (when doing this the client SHOULD delete all open SnapshotRequest resources), or it could just leave that resource out of the snapshot, or it could arrange to make its own immutable copy of that resource and add the resulting URI to the map.

Finding Existing Snapshots

Recently created snapshots can be found by performing a GET on the camera and examining the SnapshotRequest resources. If we feel there is a need to find all snapshots, the last step above could be modified to allow auto-deletion only for SnapshotRequest resources that were never completed.

The snapshots for a given resource could be found if we added an oslc:snapshotOf property to a snapshot - though this might not make sense for providers that use versions, where a snapshot might be taken by making the existing version immutable, so the oslc:snapshotOf property would either always point to itself (which is not very useful) or to some other version such as the next or last version (neither of which would necessarily be very meaningful).

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 service providers that implement the camera.
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 member and dependent resources from the same service provider, as well as immutable versions of member and dependent resources from other service providers that offer the camera capability. Clients are responsible for finding or creating immutable versions of resources from providers that do not offer the camera capability.

Baseline membership traversal

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

When forming a baseline, a client can snapshot one or more resources, and then either add just the immutable versions of those original resources to a baseline, or add those and the immutable versions of all the dependent resources as well.

When examining the contents of a baseline, a client can see the immediate members of that baseline. If the baseline was created without adding all the dependent members, a client must have provider-specific knowledge about how to navigate through the resource graph to find all dependent resources.