Abstract KTBS API¶

Below is a language independant API that has been designed to document the functionalities of KTBS in a programmer-friendly way, and guide the implementers of client APIs in other languages.

Warning

TODO

traceBegin and traceEnd on storedTraces

Resource¶

get_id()¶

Return the URI of this resource relative to its “containing” resource; basically, this is short ‘id’ that could have been used to create this resource in the corresponding ‘create_X’ method

Return type:	str

get_uri()¶

Return the absolute URI of this resource.

Return type:	uri

force_state_refresh()¶

Ensure this resource is up-to-date. While remote resources are expected to perform best-effort to keep in sync with the server, it may sometimes be required to strongly ensure they are up-to-date.

For local resources, this is has obviously no effect.

get_readonly()¶

Return true if this resource is not modifiable.

Return type:	bool

remove()¶: Remove this resource from the KTBS. If the resource can not be removed, an exception must be raised.

get_label()¶

Returns a user-friendly label

Return type:	str

set_label(str)¶: Set a user-friendly label.

reset_label()¶: Reset the user-friendly label to its default value.

Ktbs (Resource)¶

list_builtin_methods()¶

List the builtin methods supported by the kTBS.

Return type:	[Method]

get_builtin_method(uri:str)¶

Return the builtin method identified by the given URI if supported, or null.

Return type:	Method

list_bases()¶

Return type:	[Base]

get_base(id:uri)¶

Return the trace base identified by the given URI, or null.

Return type:	Base

create_base(id:uri?, label:str?)¶

Return type:	Base

Base (Base)¶

get(id:uri)¶

Return the element of this base identified by the given URI, or null.

Return type:	Trace\|Model\|Method\|Base\|DataGraph

list_traces()¶

Return type:	[Trace]

list_models()¶

List the models stored in that base.

Return type:	[Model]

list_methods()¶

List the methods stored in that base.

Return type:	[Method]

list_bases()

List the bases stored in that base.

Return type:	[Base]

list_data_graphs()¶

List the data graphs stored in that base.

Return type:	[DataGraph]

create_stored_trace(id:uri?, model:Model, origin:str?, default_subject:str?, label:str?)¶

Creates a stored trace in that base If origin is not specified, a fresh opaque string is generated

Return type:	StoredTrace

create_computed_trace(id:uri?, method:Method, parameters:[str=>any]?, sources:[Trace]?, label:str?)¶

Creates a computed trace in that base.

Return type:	ComputedTrace

create_model(id:uri?, parents:[Model]?, label:str?)¶

Return type:	Model

create_method(id:uri, parent:Method, parameters:[str=>any]?, label:str?)¶

Return type:	Method

create_base(id:uri?, label:str?)

Return type:	Base

create_data_graph(id:uri?, label:str?)¶

Return type:	DataGraph

Trace (Resource)¶

get_base()

Return type:	Base

get_model()¶

Return type:	Model

get_origin()¶

An opaque string representing the temporal origin of the trace: two traces with the same origin can be temporally compared.

Return type:	str

get_trace_begin()¶

The timestamp from which this trace was being collected, relative to the origin. This may be omitted (and then return null).

Return type:	int

get_trace_begin_dt()¶

The datetime from which this trace was being collected, relative to the origin. This may be omitted (and then return null).

Return type:	str

get_trace_end()¶

The timestamp until which this trace was being collected, relative to the origin. This may be omitted (and then return null).

Return type:	int

get_trace_end_dt()¶

The datetime until which this trace was being collected, relative to the origin. This may be omitted (and then return null).

Return type:	str

list_source_traces()¶

Return type:	[Trace]

list_transformed_traces()¶

Return the list of the traces of which this trace is a source.

Return type:	[Trace]

list_contexts()¶

Return the data graphs providing contextual information for this trace.

Return type:	[DataGraph]

list_obsels(begin:int?, end:int?, reverse:bool?)¶

Return a list of the obsel of this trace matching the parameters.

Return type:	[Obsel]

get_obsel(id:uri)¶

Return the obsel of this trace identified by the URI, or null.

Return type:	Obsel

StoredTrace (Trace)¶

set_model(model:Model)¶

set_origin(origin:str)¶

set_trace_begin(begin:int)¶

set_trace_begin_dt(begin_dt:str)¶

set_trace_end(end:int)¶

set_trace_end_dt(end_dt:str)¶

get_default_subject()¶

The default subject is associated to new obsels if they do not specify a subject at creation time.

Return type:	str

set_default_subject(subject:str)¶

create_obsel(id:uri?, type:ObselType, begin:int, end:int?, subject:str?, attributes:[AttributeType=>any]?, relations:[(RelationType, Obsel)]?, inverse_relations:[(Obsel, RelationType)]?, source_obsels:[Obsel]?, label:str?)¶

Return type:	Obsel

ComputedTrace(Trace)¶

get_method()¶

Return type:	Method

set_method(method:Method)¶

list_parameters(include_inherited:bool?)¶

List the names of all the parameters of this trace.

Parameters:	include_inherited – defaults to true and means that parameters inherited from the method should be included
Return type:	[str]

get_parameter(key:str)¶

Get the value of a parameter (own or inherited from the method).

Return type:	str

set_parameter(key:str, value:any)¶: Set the value of a parameter. An exception must be raised if the parameter is inherited.

del_parameter(key:str)¶: Unset a parameter. An exception must be raised if the parameter is inherited.

Model (Resource)¶

get_base()

Return type:	Base

get_unit()¶

TODO find stable reference to unit names

Return type:	str

set_unit(unit:str)¶

get(id:uri)

Return the element of this model identified by the URI, or null.

Return type:	ObselType \| AttributeType \| RelationType

list_parents(include_indirect:bool?)¶

List parent models. Note that some of these models may not belong to the same KTBS, and may be readonly —see get_readonly.

Parameters:	include_indirect – defaults to false and means that parent’s parents should be returned as well.
Return type:	[Model]

list_attribute_types(include_inherited:bool?)¶

Parameters:	include_inherited – defaults to true and means that attributes types from inherited models should be included
Return type:	[AttributeType]

list_relation_types(include_inherited:bool?)¶

Parameters:	include_inherited – defaults to true and means that relation types from inherited models should be included
Return type:	[RelationType]

list_obsel_types(include_inherited:bool?)¶

Parameters:	include_inherited – defaults to true and means that obsel types from inherited models should be included
Return type:	[ObselType]

add_parent(m:Model)¶

remove_parent(m:Model)¶

create_obsel_type(id:uri?, supertypes:[ObselType]?, label:str)¶

NB: if id is not provided, label is used to mint a human-friendly URI

Return type:	ObselType

create_attribute_type(id:uri?, obsel_types:[ObselType]?, data_types:[uri]?, value_is_list:bool?, label:str)¶

NB: if data_type represent a “list datatype”, value_is_list must not be true NB: if id is not provided, label is used to mint a human-friendly URI TODO specify a minimum list of datatypes that must be supported TODO define a URI for representing “list of X” for each supported datatype?

Parameters:	data_type – uri is an XML-Schema datatype URI. value_is_list – indicates whether the attributes accepts a single value (false, default) or a list of values (true).
Return type:	AttributeType

create_relation_type(id:uri?, origins:[ObselType]?, destinations:[ObselType]?, supertypes:[RelationType]?, label:str)¶

NB: if id is not provided, label is used to mint a human-friendly URI

Return type:	RelationType

Method (Resource)¶

get_base()

Return type:	Base

get_parent()¶

Return the parent method, or null. Note that returned method may not be stored on this KTBS, or can even be a built-in method.

Return type:	Method

set_parent(method:Method)¶

list_parameters(include_inherited:bool?)

List the names of all the parameters set by this method or its parent.

Parameters:	include_inherited – defaults to true and means that parameters from the parent method should be included
Return type:	[str]

get_parameter(key:str)

Get the value of a parameter (own or inherited from the parent method).

Return type:	str

set_parameter(key:str, value:any): set the value of a parameter. An exception must be raised if the parameter is inherited.

del_parameter(key:str): Unset a parameter. An exception must be raised if the parameter is inherited.

DataGraph (Resource)¶

This class has no additional method.

ObselType (Resource)¶

get_model()

Return type:	Model

list_supertypes(include_indirect:bool?)¶

List the supertypes of this obsel type.

Parameters:	include_indirect – defaults to false; if true, all supertypes are listed, including indirect supertypes and this obsel type itself
Return type:	[ObselType]

add_supertype(ot:ObselType)¶

remove_supertype(ot:ObselType)¶

list_subtypes(include_indirect:bool?)¶

List the subtypes of this obsel type from the same model.

Parameters:	include_indirect – defaults to false; if true, all subtypes from the same model are listed, including indirect supertypes and this obsel type itself
Return type:	[ObselType]

list_attribute_types(include_inherited:bool?)

List the attribute types of this obsel type (direct or inherited).

Parameters:	include_inherited – defaults to true and means that attributes types inherited from supertypes should be included
Return type:	[AttributeType]

list_relation_types(include_inherited:bool?)

List the outgoing relation types of this obsel type (direct or inherited).

Parameters:	include_inherited – defaults to true and means that relation types inherited from supertypes should be included
Return type:	[RelationType]

list_inverse_relation_types(include_inherited:bool?)¶

List the inverse relation types of this obsel type (direct or inherited).

Parameters:	include_inherited – defaults to true and means that inverse relation types inherited from supertypes should be included
Return type:	[RelationType]

create_attribute_type(id:uri?, data_types:[uri]?, value_is_list:book?, label:str)

Shortcut to get_model().create_attribute_type where this ObselType is the obsel type.

Return type:	AttributeType

create_relation_type(id:uri?, destinations:[ObselType]?, supertypes:[RelationType]?, label:str)

Shortcut to get_model().create_relation_type where this ObselType is the origin.

Return type:	RelationType

AttributeType (Resource)¶

get_model()

Return type:	Model

list_obsel_types()

Return type:	[ObselType]

add_obsel_type(ot:ObselType)¶

remove_obsel_type(ot:ObselType)¶

list_data_types()¶

Return type:	[uri]

add_data_type(data_type:uri, is_list:bool?)¶

NB: if data_type represent a “list datatype”, value_is_list must not be true

Parameters:	is_list – indicates whether the attribute accepts a single value (false, default) or a list of values (true)

remove_data_type(data_type:uri)¶

RelationType (Resource)¶

get_model()

Return type:	Model

list_supertypes(include_indirect:bool?)

List the supertypes of this relation type.

Parameters:	include_indirect – defaults to false; if true, all supertypes are listed, including indirect supertypes and this relation type itself
Return type:	[RelationType]

add_supertype(rt:RelationType)

remove_supertype(rt:RelationType)

list_subtypes(include_indirect:bool?)

List the subtypes of this relation type from the same model.

Parameters:	include_indirect – defaults to false; if true, all subtypes from the same model are listed, including indirect supertypes and this relation type itself
Return type:	[RelationType]

list_origins()¶

Return type:	[ObselType]

add_origin(ot:ObselType)¶

remove_origin(ot:ObselType)¶

list_destinations()¶

Return type:	[ObselType]

add_destination(ot:ObselType)¶

remove_destination(ot:ObselType)¶

Obsel (Resource)¶

get_trace()¶

Return type:	Trace

get_obsel_type()¶

Return type:	ObselType

get_begin()¶

Return type:	int

get_end()¶

Return type:	int

list_source_obsels()¶

Return type:	[Obsel]

list_attribute_types()

Return type:	[AttributeType]

list_relation_types()

Return type:	[RelationType]

list_related_obsels(rt:RelationType)¶

Return type:	[Obsel]

list_inverse_relation_types()

Return type:	[RelationTtype]

get_attribute_value(at:AttributeType)¶

Return the value of the given attribute type for this obsel.

Return type:	any

Obsel modification (trace amendment)

set_attribute_value(at:AttributeType, value:any)¶

del_attribute_value(at:AttributeType)¶

add_related_obsel(rt:RelationType, value:Obsel)¶

del_related_obsel(rt:RelationType, value:Obsel)¶

General Rules¶

Whenever parameter is named ‘id:uri’, it must be possible to provide a relative URI, which will be resolved against the URI of the target object.
The order of the parameter is important. Whenever an optional parameter is to be omitted, it can be set to NULL or named parameters (language permitting) can be used for the following parameters.
For all get_X methods accepting a parameter, the result should be null if no object matches the parameter.
For all create_X methods, an exception must be raised if the given URI is invalid or already in use.
All modification operations (set_*, remove) on model elements (ObselType, AttributeType, RelationType) actually modify the model from which they were accessed. If the model is readonly (see the get_readonly method), those methods must raise an exception.

Design Rationale¶

As method-controlled attributes are not possible or easy to implement in some/ languages, this abstract API only defines methods, in order to provide the least common denominator.
For the same reason, whenever mutiple values are to be returned, it prescribes the use of a list (or the closest match in the target language, e.g. Array in javascript).
However, adaptations are also recommended, depending on the features of the target language. All those adaptations should be documented with the given API. Below is a list of recommended adaptations:
- for languages supporting read-only attributes, it is recommended to provide a read-only attribute ‘x’ for every method get_x(); if get_x has optional parameters, ‘x’ should be equivalent to calling it with 0 parameters.
  
  It is also recommended to provide a read-only attribute ‘xs’ for every method list_xs(); if list_xs has optional parameters, ‘xs’ should be equivalent to calling it with 0 parameters.
- for languages supporting method-controlled attributes, it is recommended to make attribute ‘x’ settable whenever there is a method set_x(val); if set_x has additional optional parameters, ‘x’ should be equivalent to calling it with only the first parameter.
- for language supporting a notion of iterator (which may be more efficient than lists), it is recommended to provide a method iter_xs(…) for every method list_xs(…), acceptin the same parameters.
  
  NB: implementing list_xs(…) on top of iter_xs(…) should be trivial, and would probably be the way to do.
- for language having a tradition of using CamelCase instead of underscore, all method may be renamed by replacing _[a-z] with the corresponding capital letter.