Package org.openhab.core.automation

Interface RuleRegistry

All Superinterfaces:

Registry<Rule,String>

All Known Implementing Classes:

RuleSupportRuleRegistryDelegate

@NonNullByDefault
public interface RuleRegistry
extends Registry<Rule,String>

The RuleRegistry provides basic functionality for managing Rules. It can be used to

• Add Rules with the add(Rule) method.
• Get the existing rules with the getByTag(String), getByTags(String[]) methods.
• Update the existing rules with the Registry.update(E) method.
• Remove Rules with the Registry.remove(Object) method.
• Manage the state (enabled or disabled) of the Rules:
  • A newly added Rule is always enabled.
  • To check a Rule's state, use the RuleManager.isEnabled(String) method.
  • To change a Rule's state, use the RuleManager.setEnabled(String, boolean) method.

The RuleRegistry manages the status of the Rules:

• To check a Rule's status info, use the RuleManager.getStatusInfo(String) method.
• The status of a Rule enabled with RuleManager.setEnabled(String, boolean), is first set to RuleStatus.UNINITIALIZED.
• After a Rule is enabled, a verification procedure is initiated. If the verification of the modules IDs, connections between modules and configuration values of the modules is successful, and the module handlers are correctly set, the status is set to RuleStatus.IDLE.
• If some of the module handlers disappear, the Rule will become RuleStatus.UNINITIALIZED again.
• If one of the Rule's Triggers is triggered, the Rule becomes RuleStatus.RUNNING. When the execution is complete, it will become RuleStatus.IDLE again.
• If a Rule is disabled with RuleManager.setEnabled(String, boolean), it's status is set to RuleStatusDetail.DISABLED.

Author:

Yordan Mihaylov - Initial contribution

Method Summary

Modifier and Type	Method	Description
Rule	add(Rule rule)	This method is used to register a Rule into the RuleRegistry.
Collection<Rule>	getByTag(@Nullable String tag)	Gets a collection of Rules which shares same tag.
Collection<Rule>	getByTags(String... tags)	Gets a collection of Rules which has specified tags.
void	regenerateFromTemplate(String ruleUID)	This method triggers a new generation of the rule from its template by reverting the rule to its "rule stub" state only containing the template configuration.

Methods inherited from interface org.openhab.core.common.registry.Registry

addRegistryChangeListener, get, getAll, remove, removeRegistryChangeListener, stream, update

Method Details

add

Rule add(Rule rule)

This method is used to register a Rule into the RuleRegistry. First the Rule become RuleStatus.UNINITIALIZED. Then verification procedure will be done and the Rule become RuleStatus.IDLE. If the verification fails, the Rule will stay RuleStatus.UNINITIALIZED.

Specified by:

add in interface Registry<Rule,String>

Parameters:

rule - a Rule instance which have to be added into the RuleRegistry.

Returns:

a copy of the added Rule

Throws:

IllegalArgumentException - when a rule with the same UID already exists or some of the conditions or actions has wrong format of input reference.

IllegalStateException - when the RuleManagedProvider is unavailable.

getByTag

Collection<Rule> getByTag(@Nullable String tag)

Gets a collection of Rules which shares same tag.

Parameters:

tag - specifies a tag that will filter the rules.

Returns:

collection of Rules having specified tag.

getByTags

Collection<Rule> getByTags(String... tags)

Gets a collection of Rules which has specified tags.

Parameters:

tags - specifies tags that will filter the rules.

Returns:

collection of Rules having specified tags.

regenerateFromTemplate

void regenerateFromTemplate(String ruleUID)

This method triggers a new generation of the rule from its template by reverting the rule to its "rule stub" state only containing the template configuration.

Parameters:

ruleUID - the UID of the Rule.

Throws:

IllegalArgumentException - if the rule doesn't exist or isn't linked to a template.