Trace

This class is the base class of Stored Trace and Computed Trace. It has no direct instances (only the two subclasses above can be instantiated), but everything described here is valid for any indirect instance.

Traces have two aspect resource:

Original resource

GET

Retrieve the description of the trace, augmented with the following generated properties:

PUT

This allows to change the description of the trace itself.

DELETE

Deletes the trace and its aspect resources.

TODO: what happens if the trace is the source of a computed trace?

Description Constraints

The description of a trace must be star shaped.

@obsels

This aspect resource stands for the obsel collection of the trace.

GET

Return the description of all the obsels of the trace. This description can be filtered by passing the following query-string arguments:

after:an obsel URI, only obsels after this one will be returned
before:an obsel URI, only obsels before this one will be returned
limit:an int, only that many obsels (at most) will be returned
minb:an int, the minimum begin value for returned obsels
mine:an int, the minimum end value for returned obsels
maxb:an int, the maximum begin value for returned obsels
maxe:an int, the maximum end value for returned obsels
offset:an int, skip that many obsels
reverse:a boolean[1], reverse the order (see below)

For example http://localhost:8001/base1/t01/@obsels?minb=42&maxe=101 will return only those obsel beginning at or after 42 and ending at or before 101.

Some of these parameters (after, before, limit, offset and reverse) rely on the Obsel total ordering. For example, @obsels?limit=10 will return the first ten obsels, while @obsels?reverse&limit=10 will return the last ten obsels. Remember however that most RDF serializations have no notion of order (they convey a set of triples) so the representation of those resources may appear unordered. The JSON-LD serializer in kTBS is a notable exception: the obsel list is sorted according to the obsel ordering.

Even with unordered serializations, however, this still allows to retrieve obsels of a big trace in a paginated fashion, using limit to specify the size of the page, and after to browse from one page to another (setting its value to the latest obsel of the previous page), or before when paginating in the reverse order[2]. To make it easier, kTBS provides a next Link HTTP header (per RFC 5988) pointing to the next page.

Representation completeness

Obsels with a complex structure (see below) may not be entirely described in the representations of @obsels. More precisely, all attributes (i.e. outgoing properties) of obsels, and all inter-obsel relations will always be represented. However, if an attribute has a complex value, represented as a blank node with its own properties, then the representations of @obsels will usually[3] truncate such property paths to a length of 3.

This limitation has been introduced to ensure good performances, and is deemed acceptable as obsels typically have a flat structure (depth of 1), and occasionnally a depth of 2. In order to get the full description of an obsel, you can of course still get it from the obsel URI.

Also, note that transformation methods sill have access to the whole structure of obsels

PUT

This method can be used to modify the obsels of a trace. Be aware that kTBS performs absolutely no control on the put graph, so this is at your own risks.

DELETE

This method deletes the obsel collection, and with it all the obsels of the trace.

Note that a trace must always have an obsel collection, so a new (empty) one will immediately be created. Hence, this method can be thought of as simply deleting all obsels, and leaving the obsel collection resource intact.

[1]The value is case insensitive, and any value different from false, no or 0 will be considered true. Note that the empty string is considered true, so that this parameter can be used without any value, as in @obsels?reverse&limit=10.
[2]The offset option would be simpler to use, but its use is not always allowed on big traces (for example, Virtuoso forbids it beyond a certain amount of obsels), so using after/before is more robust (and potentially more efficient).
[3]You may retrieve longer paths in some situations, but this should not be relied upon.

@stats

This aspect resource provides general statistics about the trace.

GET

Provide the statistics; by default, those statistics include:

  • the total number of obsels,
  • the time-span of the obsels of the traces (min and max timestamp, and duration).

Plugins can add more information to the statistics.