NAME

       classes - introduction in Elektra´s classes

       This    overview    complements    the    introduction    in    the    API   documentation
       http://doc.libelektra.org/api/current/html/.

Key

       A Key consists of a name, a value and metadata. It is the atomic unit in the key database.
       Its  main  purpose is that it can be serialised to be written out to permanent storage. It
       can be added to several aggregates using reference  counting.  Putting  Key  objects  into
       other data structures of supported programming languages presents no problem.

KeySet

       The  central  data structure in Elektra is a KeySet. It aggregates Key objects in order to
       describe configuration in an easy but complete way. As the name  ´´set´´  already  implies
       every  Key  in  a  KeySet  has a unique name. A user can iterate over the Key objects of a
       KeySet. KeySet sorts the keys by their names. This yields a deterministic order advantage.
       So,  independent  of  the appending sequence and, in particular, the number of fetches and
       updates, KeySet guarantees the same order of the Key objects. Some  configuration  storage
       systems  need  this  property, because they cannot remember a specific order. On the other
       hand, any particular order can easily be introduced (See order /doc/METADATA.ini).

       On the one side backends generate or store  a  KeySet  object  and,  on  the  other  side,
       elektrified applications receive and send a KeySet object. Both sides, as well as the core
       in between, have the possibility to iterate, update, modify, extend  and  reduce  the  key
       set.  Appending  of  new  or existing Key objects extends the key set. Otherwise it can be
       reduced if keys are popped out.  The  Key  object  becomes  independent  from  the  KeySet
       afterwards.  The  user  can still change such a key or append it into another key set. The
       affiliation to a key set is not exclusive.

       Every key in a KeySet object has a unique name. Appending Key objects with the  same  name
       will override the already existing Key object.

KDB

       While  objects of Key and KeySet only reside in memory, Elektra´s third class KDB actually
       provides access to the global key database. KDB,  an  abbreviation  of  key  database,  is
       responsible  for  actually  storing  and  receiving  configuration.  KeySet represents the
       configuration when communicating with KDB. The typical  elektrified  application  collects
       its  configuration  by  one or many calls of kdbGet(). As soon as the program finishes its
       work with the KeySet, kdbSet() is in charge  of  writing  all  changes  back  to  the  key
       database.

       This  technique  has some advantages. First, applications have full control over modifying
       Key and KeySet objects without touching the key database. Second, the  decision  how  many
       KeySet objects the application administrates is left to the application. It can choose how
       to split up the KeySet objects. The main reason for this technique  is  that  for  backend
       development  the  same  data structure is used, and as we will see, the borderline between
       application and backend development becomes blurred.

       The application adapts the configuration between kdbGet()  and  kdbSet()  in  memory.  The
       modifications  are  not  only faster, they also allow large atomic configuration upgrades,
       robust merging of settings and handling of complicated  inter-relationships  between  keys
       without  problematic  interstages.  Elektrified  applications, however, should be aware of
       conflicts. It can happen that the key database is changed while  working  with  a  KeySet.
       Then,  attempts to use kdbSet() lead to a conflict. KDB detects such situations gracefully
       and lets the application decide which configuration should be used.

       For   details   and   background    read    more    about    elektra    data    structures
       elektra-data-structures.md.   For   further   information   see   the   API  documentation
       http://doc.libelektra.org/api/current/html/.

                                            July 2017                                  CLASSES(7)