Loading Element Configs

Table of Contents

• The Loading Sequence
• Publishing Config Parameters as Xentara Attributes
• Resolving Cross References
• Handling Errors
• Examples

See also

The Xentara Model File in the Xentara user manual

The Loading Sequence

Loading and an element is done in three steps:

1. First, the virtual function load() is called, passing it the JSON object that contains the element's configuration. This function must go through all the members of the JSON object and initialize the configuration accordingly. After reading all the parameters, the configuration must be checked for completeness and consistency.
2. Then, the virtual function realize() is called to allow the element to perform any initialization that can only be done once the entire model has been loaded.
3. Finally, the virtual function prepare() is called, to allow the element to perform additional initialization that can only be done once all the objects in the model have been realized realized.

Publishing Config Parameters as Xentara Attributes

An element can publish some or all of its configuration parameters as Xentara attributes, which can then be read by other entities, or by client applications. Xentara itself automatically publishes the name, the primary key, and the UUID of each element.

If you which to publish additional configuration parameters, you must do the following two things:

1. The attribute's existence must be advertised by including it in the forEachAttribute() callback.
2. A read handle for the attribute must be made available using the makeReadHandle() callback.

Unlike data attributes, configuration attributes do not have to be stored in a memory resource. Instead, you should obtain a shared or weak pointer to the configuration attribute and construct the read handle using [ReadHandle(const std::shared_ptr<Type> &)] (xentara::data::ReadHandle::ReadHandle(const std::shared_ptr<Type> &)) or [ReadHandle(const std::weak_ptr<Type> &)] (xentara::data::ReadHandle::ReadHandle(const std::weak_ptr<Type> &)). You can obtain a shared pointer to a member variable of your element by deriving the element from xentara::skill::EnableSharedFromThis and then using sharedFromThis(Alias *alias).

Examples

PublishingConfigAttributes.cpp

Resolving Cross References

Xentara elements can reference other elements, or attributes, events, or tasks of other elements. During the loading process, however, the referenced elements might not be available yet, since they might only appear later in the configuration file. For this reason, references to Xentara elements and their members must be resolved lazily, once the entire configuration has been loaded. To simplify this, the context passed to load() has a number of member functions resolve(), that allow you to submit requests for resolving cross references. Xentara will store these requests in the context object, and resolve them once all the elements and their primary keys are known.

You can use the context to resolve the following types of objects:

• You can reference any Xentara element using std::weak_ptr<xentara::model::Element> or std::reference_wrapper<xentara::model::Element>.
• You can reference any of your own elements using std::weak_ptr<Element> or std::reference_wrapper<Element>, where Element is the most derived type of your element class.
• You can reference a Xentara attribute using xentara::model::ElementAttribute.
• You can reference a Xentara event using std::weak_ptr<xentara::process::Event> or std::reference_wrapper<xentara::process::Event>.
• You can reference a Xentara extended event using xentara::process::ExtendedEvent.
• You can reference a Xentara task using std::weak_ptr<xentara::process::Task> or std::reference_wrapper<xentara::process::Task>.

The objects will be available from the realize() loading step onwards.

There are three main strategies for handling the reference once it is resolved:

• You can just store it in an std::weak_ptr, std::reference_wrapper, xentara::model::ElementAttribute, or xentara::process::ExtendedEvent. To accoplish this, simply pass a reference to the variable that will store the object reference to xentara::config::Context::resolve. if you have a member variable *_transaction* of type std::weak_ptr<MyTransaction>, for example, you can write:

  context.resolve<MyTransaction>(jsonValue, std::ref(_transaction));

• You can call a member function of the referring object. To accomplish this, use a lambda:

  context.resolve<MyTransaction>(jsonValue, [this](const std::shared_ptr<MyTransaction> &transaction)
      {
          setTransaction(transaction);
      });

• You can call a member function of the referred-to object. To accomplish this, you can also use a lambda:

  context.resolve<MyTransaction>(jsonValue, [this](MyTransaction &transaction)
      {
          transaction.addDataPoint(sharedFromThis());
      });

  sharedFromThis() is enabled by deriving from xentara::skill::EnableSharedFromThis. if MyTransaction::addDataPoint() takes a reference instead of an std::shared_ptr, you can of course just write transaction.addDataPoint(*this);

Handling Errors

You should check each configuration parameter for errors. After you have loaded all configuration parameters, you should check the configuration for completeness and consistency. If you encounter any errors, you should throw an exception of type std::runtime_error. Use the function xentara::utils::json::decoder::throwWithLocation() to throw the error, so that the error message will contain the line number in within the JSON file:

if (size <= 0)
{
    xentara::utils::json::decoder::throwWithLocation(value, "size must be greater than 0");
}

On error, this will print something like:

FATAL ERROR: /home/xentara/.config/xentara/model.json (line 1415): size must be greater than 0

Examples

Example for a class that loads an I/O component:

LoadingElementConfig.cpp

Example for a class that publishes some config attributes of an I/O component:

PublishingConfigAttributes.cpp