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.

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:

Prefixed Name Occurs Value-type Repr. Range Description
oslc:camera zero-or-one Resource Either oslc:SnapshotRequest The camera capability for this service provider. A GET on this resource returns the set of interim snapshot request resources that currently exist; a POST on this resource is a request to perform a snapshot of one or more resources.

The oslc:SnapshotRequest resource has the following properties:

Prefixed Name Occurs Value-type Repr. Range Description
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.
oslc:externals zero-or-many Resource Reference Any The resources in set R3 (see below).

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

Prefixed Name Occurs Value-type Repr. Range Description
oslc:originalResource exactly-one Resource Reference Any The original resource
oslc:immutableResource exactly-one Resource Reference Any A reference to what is or will be an immutable equivalent of the original resource; it is possible that this is the same as the original resource URI.

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:

Prefixed Name Occurs Value-type Representation Range Description
Dublin Core properties
dcterms:created zero-or-one DateTime n/a n/a Timestamp of resource creation (reference: Dublin Core)
dcterms:creator zero-or-many 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 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 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 DateTime n/a n/a Timestamp of the latest resource modification (reference: Dublin Core)
dcterms:shortTitle zero-or-one 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 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 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 Resource reference oslc:ResourceShape Resource Shape that specifies allowed and required fields.
oslc:serviceProvider zero-or-one Resource reference oslc:ServiceProvider A link to the resource's OSLC Service Provider.
oslc:readOnly zero-or-one Boolean n/a n/a A read-only state predicate indicating whether or not the resource is an immutable version or snapshot; if this value is true, the resource SHOULD NOT be modifiable.
rdf:type one-or-many Resource reference n/a The resource type URI
Baseline-specific properties
rdfs:member zero-or-many Resource reference any A resource that is a member of this baseline. Such a resource SHOULD NOT be modifiable.

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.

Topic revision: r1 - 13 Jun 2011 - 17:57:05 - NickCrossley
 
This site is powered by the TWiki collaboration platform 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