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.
-
remove
()¶ Remove this resource from the KTBS. If the resource can not be removed, an exception must be raised.
-
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
-
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
-
list_source_obsels
()¶ Return type: [Obsel]
-
list_attribute_types
() Return type: [AttributeType]
-
list_relation_types
() Return type: [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)¶
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.