This section gives an overview of how the BASE annotation system works.
An item must implement the AnnotatableData
interface to be able to use the annotation system. This interface gives
a link to a AnnotationSetData
item. This class
encapsulates all annotations for the item. There are two types of
annotations:
Primary annotations are annotations that
explicitely belong to the item. An annotation set can contain
only one primary annotation of each annotation type. The primary
annotation are linked with the annotations
property. This property is a map with an
AnnotationTypeData
as the key.
Inherited annotations are annotations that belong to a parent item, but that we want to use on another item as well. Inherited annotations are saved as references to either a single annotation or to another annotation set. Thus, it is possible for an item to inherit multiple annotations of the same annotation type.
The AnnotationData
class is also
just a placeholder. It connects the annotation set and
annotation type with a ParameterValueData
object. This is the object that holds the actual annotation
values.
Instances of the AnnotationTypeData
class
defines the various annotations. It must have a valueType
property which cannot be changed. The value of this property controls
which ParameterValueData
subclass is used to store
the annotation values, ie. IntegerParameterValueData
,
StringParameterValueData
, etc.
The multiplicity property holds the maximum allowed
number of values for an annotation, or 0 if an unlimited number is
allowed.
The itemTypes collection holds the codes for the types of items the annotation type can be used on. This is checked when new annotations are created but already existing annotations are not affected if the collection is modified.
Annotation types with the protocolParameter flag set are treated a bit differently. They will not show up as annotations to items with a type found in the itemTypes collection. Instead, a protocol parameter should be attached to a protocol. Then, when an item is using that protocol it becomes possible to add annotation values for the annotation types specified as protocol parameters. It doesn't matter if the item's type is found in the itemTypes collection or not.
The options collection is used to store additional options required by some of the value types, for example a max string length for string annotations or the max and min allowed value for integer annotations.
The enumeration property is a boolean flag indicating if the allowed values are predefined as an enumeration. In that case those values are found in the enumerationValues property. The actual subclass is determined by the valueType property.
Most of the other properties are hints to client applications how to render the input field for the annotation.
Numerical annotation values can have units. A unit is described by
a UnitData
object.
Each unit belongs to a QuantityData
object which defines the class of units. For example, if the quantity is
weight, we can have units, kg,
mg, µg, etc. The UnitData
contains a factor and offset that relates all units to a common reference
defined by the QuantityData
class. For example,
1 meter is the reference unit for distance, and we
have 1 meter * 0.001 = 1 millimeter
. In this case, the factor is
0.001 and the offset 0. Another example is the relationship between
kelvin and Celsius, which is 1 kelvin + 273.15 = 1 °Celsius
.
Here, the factor is 1 and the offset is +273.15.
The UnitSymbolData
is used to make it possible to assign alternative symbols to a single unit.
This is needed to simplify input where it may be hard to know what to
type to get m² or °C. Instead,
m2 and C can be used as
alternative symbols.
The creator of an annotation type may select a
QuantityData
, which can't be changed later, and
a default UnitData
. When entering annotation values
a user may select any unit for the selected quantity (unless annotation type
owner has limited this by selecting usableUnits
). Before
the values are stored in the database, they are converted to the default
unit. This makes it possible to compare and filter on annotation values
using different units. For example, filtering with >5mg
also finds items that are annotated with 2g.
The core should automatically update the stored annotation values if the default unit is changed for an annotation type, or if the reference factor for a unit is changed.
The AnnotationTypeCategoryData
class defines
categories that are used to group annotation types that are related to
each other. This information is mainly useful for client applications
when displaying forms for annotating items, that wish to provide a
clearer interface when there are many (say 50+) annotations type for
an item. An annotation type can belong to more than one category.