OSLC Changelog Specification Proposal

STATUS: proposed specification text under discussion, has not yet reach convergence stage

Overview

Clients that wish to work with a set of resources (for example, the complete set of resources owned by some service) need, at a minimum, a way to get an enumeration of the set's resource URIs. If, however, this set is large, a service is unlikely to be able to provide such an enumeration quickly enough that it can be used by a client to regularly keep up with a changing resource-set over time. Even worse, if the enumeration is huge, the set may even be somewhat stale by the time the client receives it. To handle this situation, a mechanism for keeping up with ongoing changes to a resource-set is needed.

This specification defines a "change log" protocol/capability for monitoring incremental changes to a set of resources. An implementation of this capability is referred to as a "Changelog provider". A Changelog provider MUST provide a URI that contains a log of resource changes as described below.

Changelog Contents

An HTTP GET on a change log URI returns a list of changes organized in inverse chronological order, most recent first. The following example illustrates the contents of a change log:

@prefix oslc_log: <http://open-services.net/ns/core/log#> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .

<https://.../myChangeLog> 
  a oslc_log:ChangeLog ; 
  oslc_log:changes (
    [ a oslc_log:Creation ;
      oslc_log:changed <https://.../WorkItem/23> ;
      oslc_log:at "103"^^xsd:integer
    ]
    [ a oslc_log:Modification ;
      oslc_log:changed <https://.../WorkItem/22> ;
      oslc_log:at "102"^^xsd:integer
    ]
    [ a oslc_log:Deletion ;
      oslc_log:changed <https://.../WorkItem/21> ;
      oslc_log:at "101"^^xsd:integer
    ]) .

As shown, a change log provides a set of change entries in a single-valued RDF collection-type property called oslc_log:changes. An RDF collection, i.e., a linked list (reference: RDF Collections), is used in the change log to ensure that the entries retain their correct (inverse chronological) order. Each entry in the list identifies a changed resource, a type of change (Creation, Modification, or Deletion), and the relative time of the change. Note that the actual time of change is not included. Only a sequence number, representing the "sequence in time" of each change, is provided.

The first entry in the change log, i.e., "103" in this example, is the most recent change. As changes continue to occur, a Changelog provider MUST add new entries to the front of the list. The sequence number (i.e., oslc_log:at) of newer entries MUST be greater than previous ones. The sequence numbers MAY be consecutive numbers but need not be.

Changelog Scope (Published Resources)

The scope of resources reported by the change log is referred to as the Changelog provider's "published resources". A Changelog provider SHOULD provide an enumeration of its corresponding published resources. If it does, it MAY also provide the sequence number (e.g., oslc_log:at value) corresponding to the point in the change log from which a client can begin incremental monitoring in order to remain synchronized with ongoing changes to the returned resource-set. One or more OSLC queryBase (or queryBase-like) URIs MAY be used to enumerate the published resources. For example:

@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
@prefix oslc_log: <http://open-services.net/ns/core/log#> .

<https://.../myPublishedResources> 
  oslc_log:at "101"^^xsd:integer ;
  rdfs:member <https://.../WorkItem/1"/> ;
  rdfs:member <https://.../WorkItem/2"/> ;
  rdfs:member <https://.../WorkItem/3"/> ;
  ...
  rdfs:member <https://.../WorkItem/199"/>;
  rdfs:member <https://.../WorkItem/200"/> .

In this case, OSLC paging (reference: Resource Paging) will likely also be needed/used. If a Changelog provider uses “unstable paging” for queryBase results, it MUST provide a guarantee that resources will not be skipped. An unstable paged result may return a combination of older and newer states of the result, but it will never skip resources that were in both.

A change log MUST contain all change events for the set of published resources, as well as creation events for new resources that would have been included in the published resources enumeration, had they existed at the time. A change entry for a published resource MUST be added to the log if that resource has been deleted, or if a GET on that resource would return a set of RDF triples that is different in number, subjects, predicates, objects, or reified statements, from the set returned by a previous GET. A change entry for a resource MAY be given even if the RDF triple set has not been so altered because, for example, it changed twice sufficiently quickly that the provider only put a single entry in the change log, or because the updated property values are the same as they were, and the provider does not compare original to updated values.

Changelog Segmentation

The change log in the previous example consisted of a single oslc_log:ChangeLog resource. Typically, however, the change log will be very large, requiring multiple segments:

@prefix oslc_log: <http://open-services.net/ns/core/log#> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .

<https://.../myChangeLog>
  a oslc_log:ChangeLog ; 
  oslc_log:changes ( ... ) ;
  oslc_log:priorChangeLog <https://.../myChangeLog/1> .

As shown, the oslc_log:priorChangeLog reference is used in this case to locate the continuation of the log (i.e., the prior/earlier changes). This allows a client to be lazy and only request segments until it encounters an entry that has already been processed (on a previous check). The number of entries in an oslc:log:ChangeLog segment is implementation defined.

Notice that the change log segmentation/paging mechanism is different than other multi-page OSLC resources which use the OSLC-defined Resource Paging mechanism (e.g., the published resources describe in the previous section). This difference is due to the fact that the change log contents is an RDF List, a structure which is not easily separated into arbitrary pages.

An implementation MUST provide stable segment navigation. Other than old truncated entries (see below), no change entry in the log will ever be skipped during navigation.

Truncated Changelogs

A change log MAY continue all the way back to the time when the first resource was created by one of the associated services and would contain entries for every change made since then. However, to avoid maintaining this ever growing list of changes indefinitely, a Changelog provider MAY truncate the log by removing the oslc_log:priorChangeLog reference at a suitable point in the chain. To minimize the likelihood of clients falling too far behind and losing information, it is highly recommended that Changelog providers retain a minimum of seven days worth of changes before truncating the log.

Resources

This section formally defines the resources of the Changelog specification.

OSLC Changelog Namespace

The namespace used for resources and properties defined in this specification is as follows:

• Namespace URI: http://open-services.net/ns/core/log#
• Default Prefix: oslc_log

Resource: Change Log

A Change Log describes what resources have been created, modified or deleted, and when.

• Name: ChangeLog
• URI: http://open-services.net/ns/core/log#ChangeLog

Each entry in an oslc_log:changes list is an anonymous resource (blank node) with the following properties:

References

• RDF Collections http://www.w3.org/2007/02/turtle/primer/#L2986
• OSLC Resource Paging http://open-services.net/bin/view/Main/OslcCoreSpecification?sortcol=table;up=#Resource_Paging