runbox v7.0.1

Runbox.Scenario.Template.StageBased behaviour (runbox v7.0.1)

Module defines behaviour used in scenarios as template.

Scenario template implementations are main components of scenario. Runtime uses callbacks of this behaviour to start scenario in run and to handle incomming messages. Each template behaviour implementation is represented as separate process in runtime called TemplateCarrier.

Template is inteded to be used to model behaviour of assets of single type per template. Individual asset states are represented as Toolbox.Runtime.Stage.Unit.t/0. Initial assets are defined via Runbox.Scenario.Template.StageBased.instances/0 callback. This callback should return list of unit definitions (Runbox.Scenario.Template.StageBased.instances_def/0).

Templates are linked together via subscriptions provided by callback Runbox.Scenario.Template.StageBased.subscriptions/0. Subscription is defined as tuple containing component definition and routing rule list. It is possible to subscribe to other templates, input and load topics. Routing rules are used to locate units when message is handled. When routing rule succeeds, callback Runbox.Scenario.Template.StageBased.handle_message/2 is called, when routing rule fails to locat existing unit, Runbox.Scenario.Template.StageBased.handle_asset_discovery/1 gets called instead.

Unit initialization can produce side effects via Runbox.Scenario.Template.StageBased.init/2 callback. This callback is triggered when instances are produced by Runbox.Scenario.Template.StageBased.instances/0 or Runbox.Scenario.Template.StageBased.handle_asset_discovery/1 callbacks. Units are already registered in the time when this callback is triggered, so changes in unit attributes won't change unit registration (defined by Runbox.Scenario.Template.StageBased.subscriptions/0).

When message from subscribed publisher is handled by the TemplateCarrier, runtime tries to locate asset unit using given subscription configuration. If there is such a unit, runtime calls Runbox.Scenario.Template.StageBased.handle_message/2 callback and uses message and located message as attributes. In case that no unit was found, Runbox.Scenario.Template.StageBased.handle_asset_discovery/1 gets called instead.

Link to this section Summary

Types

handle_asset_discovery_resp()
handle_message_resp()
instances_def()
routing_key_definition()
subscription_def()
template_output()

Callbacks

handle_asset_discovery(t)
handle_message(t, t)
init(integer, t)
instances()
subscriptions()

Functions

handle_asset_discovery(template_module, msg)

Invokes template_module.asset_discovery with given message.

handle_message(template_module, msg, unit)

Invokes template_module.handle_message with given message and unit.

init(template_module, timestamp, unit)

Updates unit and sets initial unit state.

instances(template_module)

Returns list of of asset units.

subscriptions(template_module)

Returns subscriptions defined in template_module.

Link to this section Types

Link to this type

handle_asset_discovery_resp()

@type handle_asset_discovery_resp() ::
  {:reply, template_output()}
  | {:reply, template_output(), Toolbox.Runtime.Stage.Unit.t()}
Link to this type

handle_message_resp()

@type handle_message_resp() ::
  {:reply, template_output(), Toolbox.Runtime.Stage.Unit.t()}
  | {:stop, template_output(), Toolbox.Runtime.Stage.Unit.t()}
Link to this type

instances_def()

@type instances_def() :: [{:unit, id :: String.t(), attributes :: map()}]
Link to this type

routing_key_definition()

@type routing_key_definition() ::
  {message_type :: String.t() | atom(),
   {function :: := | :in, [path_to_msg_body_key :: [String.t() | atom()]],
    [path_to_attribute_key :: [String.t() | atom()]]}}
Link to this type

subscription_def()

@type subscription_def() ::
  {:input_topic, topic_name :: String.t(), [routing_key_definition()]}
  | {:load_topic, topic_name :: String.t(), [routing_key_definition()]}
  | {:template, template_name :: module(), [routing_key_definition()]}
Link to this type

template_output()

@type template_output() :: [
  Toolbox.Message.t()
  | Runbox.Scenario.OutputAction.oa_params()
  | Runbox.Runtime.RuntimeInstruction.t()
]

Link to this section Callbacks

Link to this callback

handle_asset_discovery(t)

(optional) 
@callback handle_asset_discovery(Toolbox.Message.t()) :: handle_asset_discovery_resp()
Link to this callback

handle_message(t, t)

@callback handle_message(Toolbox.Message.t(), Toolbox.Runtime.Stage.Unit.t()) ::
  handle_message_resp()
Link to this callback

init(integer, t)

(optional) 
@callback init(integer(), Toolbox.Runtime.Stage.Unit.t()) ::
  {:ok, template_output(), Toolbox.Runtime.Stage.Unit.t()}
Link to this callback

instances()

@callback instances() :: instances_def()
Link to this callback

subscriptions()

@callback subscriptions() :: [subscription_def()]

Link to this section Functions

Link to this function

handle_asset_discovery(template_module, msg)

@spec handle_asset_discovery(template :: module(), Toolbox.Message.t()) ::
  handle_asset_discovery_resp() | any()

Invokes template_module.asset_discovery with given message.

Link to this function

handle_message(template_module, msg, unit)

@spec handle_message(
  template :: module(),
  Toolbox.Message.t(),
  Toolbox.Runtime.Stage.Unit.t()
) ::
  handle_message_resp() | any()

Invokes template_module.handle_message with given message and unit.

Link to this function

init(template_module, timestamp, unit)

@spec init(
  template :: module(),
  timestamp :: integer(),
  Toolbox.Runtime.Stage.Unit.t()
) ::
  {:ok, template_output(), Toolbox.Runtime.Stage.Unit.t()} | any()

Updates unit and sets initial unit state.

Link to this function

instances(template_module)

@spec instances(template :: module()) :: instances_def()

Returns list of of asset units.

Link to this function

subscriptions(template_module)

@spec subscriptions(template :: module()) :: [subscription_def()]

Returns subscriptions defined in template_module.