guh - Developer documentation

Rules

EventDescriptor

Describes a certain Event

ParamDescriptor

Describes a certain Param

RuleAction

Describes an action for a guhserver::Rule

RuleActionParam

Holds the parameters for a RuleAction

StateDescriptor

Describes a certain State

guhserver::CalendarItem

Describes a clendar item for a time based Rule

guhserver::RepeatingOption

Describes the repeating option of a time item

guhserver::Rule

This class represents a rule

guhserver::RuleEngine

Engine that evaluates Rules and finds Actions to be executed

guhserver::StateEvaluator

This class helps to evaluate a State and

guhserver::TimeDescriptor

Describes the time elements of a time based Rule

guhserver::TimeEventItem

Describes a time event of a time based Rule

guhserver::TimeManager

Describes the centralized time manager of guh

Introduction

Rules define all the logic in guh. A rule is composed by a set of Events, States and Actions.

This diagram shows how rules are composed and interpreted by the guhserver::RuleEngine.

"Rules definition"

A basic concept of a guhserver::Rule is the trigger path. This is the path that defines when a guhserver::Rule is triggered for evaluation. Each element added on a trigger path (either red or blue) has the possibility to trigger the guhserver::RuleEngine to evaluate the complete rule and ultimately execute the defined Actions if the whole rule evaluates to true. Once the trigger path has been left (i.e. a black arrow is followed), subsequent elements will still be evaluated when the rule is triggered, but they won't trigger the evaluation themselves.

There are two mechanisms that can trigger a rule, described by the two trigger paths in the Rules definition figure.

Event based rules

Event based rules (trigger path 1) contain either one or more Events or are triggered by a State change (disregarding what the changed State's value actually is). Such rules may still evaluate States for a certain value (leaving Trigger path 1 and re-entering Trigger path 2), however, unless otherwise explicitly defined, the Rule is not evaluated when such a State change happens (given the Trigger path has been left by crossing a black arrow). Those rules are only executed for items on trigger path 1.

Examples

State bindings based rules

State binding rules (Trigger path 2) are rules which only contains States and Actions. Each time a State on that path changes, the rule is evaluated. That means, all the States in the Rule are examined. If all evaluations are fulfilled, the Rule's Actions are executed. Please note, that such Rules may only check if states are equal to, unequal, less than or greater then some value.

Examples

Mixing rules types

Having both types of triggers in a single rule is only possible by leaving the trigger path 1, crossing a black arrow and re-entering trigger path 2. This however, converts the rule to an Event based rule which means, only the elements on trigger path 1 will be able to trigger the rule evaluation.

Examples