openhab-jrubyscripting 5.0.0.rc4 → 5.0.0.rc6

data/lib/openhab/dsl/rules/automation_rule.rb

@@ -8,6 +8,20 @@ module OpenHAB
       #
       # @!visibility private
       class AutomationRule < org.openhab.core.automation.module.script.rulesupport.shared.simple.SimpleRule
+        # @!visibility private
+        INPUT_KEY_PATTERN = /^[a-z_]+[a-zA-Z0-9_]*$/.freeze
+
+        class << self
+          #
+          # Caches dynamically generated Struct classes so that they don't have
+          # to be re-generated for every event, blowing the method cache.
+          #
+          # @!visibility private
+          # @return [java.util.Map<Array<Symbol>, Class>]
+          attr_reader :event_structs
+        end
+        @event_structs = java.util.concurrent.ConcurrentHashMap.new
+
         field_writer :uid
 
         #
@@ -41,8 +55,8 @@ module OpenHAB
         #
         # Execute the rule
         #
-        # @param [Map] mod map provided by OpenHAB rules engine
-        # @param [Map] inputs map provided by OpenHAB rules engine containing event and other information
+        # @param [java.util.Map] mod map provided by openHAB rules engine
+        # @param [java.util.Map] inputs map provided by openHAB rules engine containing event and other information
         #
         #
         def execute(mod = nil, inputs = nil)
@@ -50,7 +64,8 @@ module OpenHAB
             logger.trace { "Execute called with mod (#{mod&.to_string}) and inputs (#{inputs.inspect})" }
             logger.trace { "Event details #{inputs["event"].inspect}" } if inputs&.key?("event")
             trigger_conditions(inputs).process(mod: mod, inputs: inputs) do
-              process_queue(create_queue(inputs), mod, inputs)
+              event = extract_event(inputs)
+              process_queue(create_queue(event), mod, event)
             end
           rescue Exception => e
             raise if defined?(::RSpec)
@@ -87,11 +102,11 @@ module OpenHAB
         #
         # Create the run queue based on guards
         #
-        # @param [Map] inputs rule inputs
+        # @param [Map] event Event object
         # @return [Queue] <description>
         #
-        def create_queue(inputs)
-          case check_guards(event: extract_event(inputs))
+        def create_queue(event)
+          case check_guards(event: event)
           when true
             @run_queue.dup.grep_v(BuilderDSL::Otherwise)
           when false
@@ -108,12 +123,30 @@ module OpenHAB
         # @return [Object] event object
         #
         def extract_event(inputs)
-          event = inputs&.dig("event")
-          unless event
-            event = Struct.new(:event, :attachment, :command).new
-            event.command = inputs&.dig("command")
+          attachment = @attachments[trigger_id(inputs)]
+          if inputs&.key?("event")
+            event = inputs["event"]
+            unless event
+              if attachment
+                logger.warn("Unable to attach #{attachment.inspect} to event " \
+                            "object for rule #{uid} since the event is nil.")
+              end
+              return nil
+            end
+
+            event.attachment = attachment
+            return event
           end
-          add_attachment(event, inputs)
+
+          inputs = inputs.to_h
+                         .select { |key, _value| key != "module" && INPUT_KEY_PATTERN.match?(key) }
+                         .transform_keys(&:to_sym)
+          inputs[:attachment] = attachment
+          keys = inputs.keys.sort
+          struct_class = self.class.event_structs.compute_if_absent(keys) do
+            Struct.new(*keys, keyword_init: true)
+          end
+          struct_class.new(**inputs)
         end
 
         #
@@ -128,35 +161,18 @@ module OpenHAB
         #
         # Returns trigger conditions from inputs if it exists
         #
-        # @param [Map] inputs map from OpenHAB containing UID
+        # @param [java.util.Map] inputs map from openHAB containing UID
         #
         # @return [Array] Array of trigger conditions that match rule UID
         #
         def trigger_conditions(inputs)
-          # Parse this to get the trigger UID:
-          # ["72698819-83cb-498a-8e61-5aab8b812623.event", "oldState", "module", \
-          #  "72698819-83cb-498a-8e61-5aab8b812623.oldState", "event", "newState",\
-          #  "72698819-83cb-498a-8e61-5aab8b812623.newState"]
           @trigger_conditions[trigger_id(inputs)]
         end
 
-        # If an attachment exists for the trigger for this event add it to the event object
-        # @param [Object] event Event
-        # @param [Hash] inputs Inputs into event
-        # @return [Object] Event with attachment added
-        #
-        def add_attachment(event, inputs)
-          attachment = @attachments[trigger_id(inputs)]
-          return event unless attachment
-
-          event.attachment = attachment
-          event
-        end
-
         #
         # Check if any guards prevent execution
         #
-        # @param [Map] event OpenHAB rule trigger event
+        # @param [Object] event openHAB rule trigger event
         #
         # @return [true,false] True if guards says rule should execute, false otherwise
         #
@@ -170,7 +186,7 @@ module OpenHAB
             now = Time.now
             return true if @between.cover? now
 
-            logger.trace("Skipped execution of rule '#{name}' because the current time #{now} "\
+            logger.trace("Skipped execution of rule '#{name}' because the current time #{now} " \
                          "is not between #{@between.begin} and #{@between.end}")
           else
             logger.trace("Skipped execution of rule '#{name}' because of guard #{@guard}")
@@ -182,15 +198,13 @@ module OpenHAB
         # Process the run queue
         #
         # @param [Array] run_queue array of procs of various types to execute
-        # @param [Map] mod OpenHAB map object describing rule trigger
-        # @param [Map] inputs OpenHAB map object describing rule trigge
+        # @param [java.util/Map] mod openHAB map object describing rule trigger
+        # @param [Object] event openHAB map object describing rule trigger
         #
-        def process_queue(run_queue, mod, inputs)
-          event = extract_event(inputs)
-
+        def process_queue(run_queue, mod, event)
           while (task = run_queue.shift)
             if task.is_a?(BuilderDSL::Delay)
-              process_delay_task(inputs, mod, run_queue, task)
+              process_delay_task(event, mod, run_queue, task)
             else
               process_task(event, task)
             end
@@ -229,15 +243,15 @@ module OpenHAB
         #
         # Process delay task
         #
-        # @param [Map] inputs Rule trigger inputs
+        # @param [Map] event Rule trigger event
         # @param [Map] mod Rule modes
         # @param [Queue] run_queue Queue of tasks for this rule
         # @param [Delay] task to process
         #
         #
-        def process_delay_task(inputs, mod, run_queue, task)
+        def process_delay_task(event, mod, run_queue, task)
           remaining_queue = run_queue.slice!(0, run_queue.length)
-          DSL.after(task.duration) { process_queue(remaining_queue, mod, inputs) }
+          DSL.after(task.duration) { process_queue(remaining_queue, mod, event) }
         end
 
         #

data/lib/openhab/dsl/rules/builder.rb

@@ -14,15 +14,18 @@ end
 module OpenHAB
   module DSL
     #
-    # Creates and manages OpenHAB Rules
+    # Creates and manages openHAB Rules
     #
     module Rules
-      # A rules builder allows you to create OpenHAB rules.
+      # A rules builder allows you to create openHAB rules.
       #
       # Note that all methods on this module are also availabe directly on {OpenHAB::DSL}.
       #
       class Builder
         include Terse
+        include Core::EntityLookup
+
+        self.create_dummy_items = true
 
         # @return [org.openhab.core.automation.RuleProvider]
         attr_reader :provider
@@ -34,21 +37,24 @@ module OpenHAB
         #
         # Create a new rule
         #
+        # The rule must have at least one trigger and one execution block.
+        # To create a "script" without any triggers, use {#script}.
+        #
         # @param [String] name The rule name
-        # @yield Block executed in the context of a {Rules::Builder}
-        # @yieldparam [Rules::Builder] rule
+        # @yield Block executed in the context of a {Rules::BuilderDSL}
+        # @yieldparam [Rules::BuilderDSL] rule
         #   Optional parameter to access the rule configuration from within execution blocks and guards.
-        # @return [Rule]
+        # @return [Core::Rules::Rule, nil] The rule object, or nil if no rule was created.
         #
-        # @see OpenHAB::DSL::Rules::Builder Rule builder for details on rule triggers, guards and execution blocks
+        # @see OpenHAB::DSL::Rules::BuilderDSL Rule BuilderDSL for details on rule triggers, guards and execution blocks
         # @see Rules::Terse Terse Rules
         #
         # @example
         #   require "openhab/dsl"
         #
         #   rule "name" do
-        #     <zero or more triggers>
-        #     <zero or more execution blocks>
+        #     <one or more triggers>
+        #     <one or more execution blocks>
         #     <zero or more guards>
         #   end
         #
@@ -85,7 +91,7 @@ module OpenHAB
         # @param [String] name A descriptive name
         # @param [String] id The script's ID
         # @yield [] Block executed when the script is executed.
-        # @return [Rule]
+        # @return [Core::Rules::Rule]
         #
         def script(name = nil, id: nil, script: nil, &block)
           raise ArgumentError, "Block is required" unless block
@@ -108,7 +114,7 @@ module OpenHAB
       end
 
       #
-      # Rule configuration for OpenHAB Rules engine
+      # Rule configuration for openHAB Rules engine
       #
       class BuilderDSL
         include Core::EntityLookup
@@ -117,6 +123,8 @@ module OpenHAB
         extend Property
         extend Forwardable
 
+        self.create_dummy_items = true
+
         delegate %i[triggers trigger_conditions attachments] => :@rule_triggers
 
         # @!visibility private
@@ -259,7 +267,7 @@ module OpenHAB
         #
         # @example
         #   rule 'Delay sleeps between execution elements' do
-        #     on_start
+        #     on_load
         #     run { logger.info("Sleeping") }
         #     delay 5.seconds
         #     run { logger.info("Awake") }
@@ -267,7 +275,7 @@ module OpenHAB
         #
         # @example Like other execution blocks, multiple can exist in a single rule.
         #   rule 'Multiple delays can exist in a rule' do
-        #     on_start
+        #     on_load
         #     run { logger.info("Sleeping") }
         #     delay 5.seconds
         #     run { logger.info("Sleeping Again") }
@@ -277,7 +285,7 @@ module OpenHAB
         #
         # @example You can use Ruby code in your rule across multiple execution blocks like a run and a delay.
         #   rule 'Dim a switch on system startup over 100 seconds' do
-        #     on_start
+        #     on_load
         #     100.times do
         #       run { DimmerSwitch.dim }
         #       delay 1.second
@@ -302,7 +310,7 @@ module OpenHAB
         #
         # @example
         #   rule 'Turn switch ON or OFF based on value of another switch' do
-        #     on_start
+        #     on_load
         #     run { TestSwitch << ON }
         #     otherwise { TestSwitch << OFF }
         #     only_if { OtherSwitch.on? }
@@ -425,28 +433,28 @@ module OpenHAB
         #
         # @example String of {LocalTime}
         #   rule 'Log an entry if started between 3:30:04 and midnight using strings' do
-        #     on_start
+        #     on_load
         #     run { logger.info ("Started at #{LocalTime.now}")}
         #     between '3:30:04'..LocalTime::MIDNIGHT
         #   end
         #
         # @example {LocalTime}
         #   rule 'Log an entry if started between 3:30:04 and midnight using LocalTime objects' do
-        #     on_start
+        #     on_load
         #     run { logger.info ("Started at #{LocalTime.now}")}
         #     between LocalTime.of(3, 30, 4)..LocalTime::MIDNIGHT
         #   end
         #
         # @example String of {MonthDay}
         #   rule 'Log an entry if started between March 9th and April 10ths' do
-        #     on_start
+        #     on_load
         #     run { logger.info ("Started at #{Time.now}")}
         #     between '03-09'..'04-10'
         #   end
         #
         # @example {MonthDay}
         #   rule 'Log an entry if started between March 9th and April 10ths' do
-        #     on_start
+        #     on_load
         #     run { logger.info ("Started at #{Time.now}")}
         #     between MonthDay.of(03,09)..'04-06'
         #   end
@@ -533,8 +541,8 @@ module OpenHAB
           @rule_triggers = RuleTriggers.new
           @caller = caller_binding.eval "self"
           @ruby_triggers = []
+          @on_load_id = nil
           enabled(true)
-          on_start(false)
           tags([])
         end
 
@@ -789,19 +797,19 @@ module OpenHAB
           # for is a reserved word in ruby, so use local_variable_get :for
           duration = binding.local_variable_get(:for)
 
+          @ruby_triggers << [:changed, items, { to: to, from: from, duration: duration }]
+
           from = [nil] if from.nil?
           to = [nil] if to.nil?
-
-          @ruby_triggers << [:changed, items, { to: to, from: from, duration: duration }]
           items.each do |item|
             case item
             when Core::Things::Thing,
                  Core::Things::ThingUID,
-                 Core::Items::GenericItem,
+                 Core::Items::Item,
                  Core::Items::GroupItem::Members
               nil
             else
-              raise ArgumentError, "items must be a GenericItem, GroupItem::Members, Thing, or ThingUID"
+              raise ArgumentError, "items must be an Item, GroupItem::Members, Thing, or ThingUID"
             end
 
             logger.trace("Creating changed trigger for entity(#{item}), to(#{to.inspect}), from(#{from.inspect})")
@@ -818,7 +826,7 @@ module OpenHAB
         # Create a cron trigger
         #
         # @overload cron(expression, attach: nil)
-        #   @param [String, nil] expression [OpenHAB style cron expression](https://www.openhab.org/docs/configuration/rules-dsl.html#time-based-triggers)
+        #   @param [String, nil] expression [openHAB style cron expression](https://www.openhab.org/docs/configuration/rules-dsl.html#time-based-triggers)
         #   @param [Object] attach object to be attached to the trigger
         #
         #   @example Using a cron expression
@@ -962,45 +970,116 @@ module OpenHAB
         end
 
         #
-        # Run this rule when the script is loaded.
+        # Creates a trigger that executes when the script is loaded
         #
-        # Execute the rule on OpenHAB start up and whenever the script is
-        # reloaded. This is useful to perform initialization routines,
-        # especially when combined with other triggers.
+        # Execute the rule whenever the script is first loaded, including on openHAB start up,
+        # and on subsequent reloads on file modifications.
+        # This is useful to perform initialization routines, especially when combined with other triggers.
         #
-        # @param [true, false] run_on_start Run this rule on start, defaults to True
-        # @param [Object] attach object to be attached to the trigger
+        # @param [Object] attach Object to be attached to the trigger
         # @return [void]
         #
         # @example
-        #   rule "startup rule" do
-        #     on_start
+        #   rule "script startup rule" do
+        #     on_load
         #     run do
         #       <calculate some item state>
         #     end
         #   end
         #
         # @example
-        #   rule 'Ensure all security lights are on' do
-        #     on_start
+        #   rule "Ensure all security lights are on" do
+        #     on_load
         #     run { Security_Lights.on }
         #   end
         #
-        # rubocop:disable Style/OptionalBooleanParameter
-        def on_start(run_on_start = true, attach: nil)
-          @on_start = Struct.new(:enabled, :attach).new(run_on_start, attach)
+        def on_load(attach: nil)
+          # prevent overwriting @on_load_id
+          raise ArgumentError, "on_load can only be used once within a rule" if @on_load_id
+
+          @on_load_id = SecureRandom.uuid
+          attachments[@on_load_id] = attach
+        end
+
+        #
+        # Creates a trigger that executes when openHAB reaches a certain start level
+        #
+        # This will only trigger once during openHAB start up. It won't trigger on script reloads.
+        #
+        # @param [Integer,:rules,:ruleengine,:ui,:things,:complete] at_level
+        #   Zero or more start levels. Note that Startlevels less than 40 are not available as triggers
+        #   because the rule engine needs to start up first before it can execute any rules
+        #
+        #   | Symbol        | Start Level |
+        #   | ------------- | ----------- |
+        #   | `:osgi`       | 10          |
+        #   | `:model`      | 20          |
+        #   | `:state`      | 30          |
+        #   | `:rules`      | 40          |
+        #   | `:ruleengine` | 50          |
+        #   | `:ui`         | 70          |
+        #   | `:things`     | 80          |
+        #   | `:complete`   | 100         |
+        # @param [Array<Integer,:rules,:ruleengine,:ui,:things,:complete>] at_levels Fluent alias for `at_level`
+        # @param [Object] attach Object to be attached to the trigger
+        # @return [void]
+        #
+        # @example
+        #   rule "Trigger at openHAB system start" do
+        #     on_start # trigger at the default startlevel 100
+        #     run { logger.info "openHAB start up complete." }
+        #   end
+        #
+        # @example Trigger at a specific start level
+        #   rule "Trigger after things are loaded" do
+        #     on_start at_level: :things
+        #     run { logger.info "Things are ready!" }
+        #   end
+        #
+        # @example Trigger at multiple levels
+        #   rule "Multiple start up triggers" do
+        #     on_start at_levels: %i[ui things complete]
+        #     run do |event|
+        #       logger.info "openHAB startlevel has reached level #{event.startlevel}"
+        #     end
+        #   end
+        #
+        # @see https://www.openhab.org/docs/configuration/rules-dsl.html#system-based-triggers System based triggers
+        #
+        def on_start(at_level: nil, at_levels: nil, attach: nil)
+          levels = Array.wrap(at_level) | Array.wrap(at_levels)
+          levels = [100] if levels.empty?
+
+          levels.map! do |level|
+            next level unless level.is_a?(Symbol)
+
+            begin
+              klass = org.openhab.core.service.StartLevelService.java_class
+              klass.declared_field("STARTLEVEL_#{level.upcase}").get_int(klass)
+            rescue java.lang.NoSuchFieldException
+              raise ArgumentError, "Invalid symbol for at_level: :#{level}"
+            end
+          end
+
+          @ruby_triggers << [:on_start, levels]
+          levels.each do |level|
+            logger.warn "Rule engine doesn't start until start level 40" if level < 40
+            config = { startlevel: level }
+            logger.trace("Creating a SystemStartlevelTrigger with startlevel=#{level}")
+            Triggers::Trigger.new(rule_triggers: @rule_triggers)
+                             .append_trigger(type: "core.SystemStartlevelTrigger", config: config, attach: attach)
+          end
         end
-        # rubocop:enable Style/OptionalBooleanParameter
 
         #
-        # Create a trigger for when an item or group receives a command
+        # Creates a trigger for when an item or group receives a command.
         #
         # The command/commands parameters are replicated for DSL fluency.
         #
         # The `event` passed to run blocks will be an
         # {Core::Events::ItemCommandEvent}.
         #
-        # @param [GenericItem, GroupItem::Members] items Items to create trigger for
+        # @param [Item, GroupItem::Members] items Items to create trigger for
         # @param [Core::TypesCommand, Array<Command>, Range, Proc] command commands to match for trigger
         # @param [Array<Command>, Range, Proc] commands Fluent alias for `command`
         # @param [Object] attach object to be attached to the trigger
@@ -1072,11 +1151,11 @@ module OpenHAB
 
           items.each do |item|
             case item
-            when Core::Items::GenericItem,
+            when Core::Items::Item,
                  Core::Items::GroupItem::Members
               nil
             else
-              raise ArgumentError, "items must be a GenericItem or GroupItem::Members"
+              raise ArgumentError, "items must be an Item or GroupItem::Members"
             end
             commands.each do |cmd|
               logger.trace "Creating received command trigger for items #{item.inspect} and commands #{cmd.inspect}"
@@ -1194,7 +1273,7 @@ module OpenHAB
         # {Core::Events::ThingStatusInfoEvent} depending on if the triggering
         # element was an item or a thing.
         #
-        # @param [GenericItem, GroupItem::Members, Thing] items
+        # @param [Item, GroupItem::Members, Thing] items
         #   Objects to create trigger for.
         # @param [State, Array<State>, Range, Proc, Symbol, String] to
         #   Only execute rule if the state matches `to` state(s). If the
@@ -1271,11 +1350,11 @@ module OpenHAB
             case item
             when Core::Things::Thing,
                  Core::Things::ThingUID,
-                 Core::Items::GenericItem,
+                 Core::Items::Item,
                  Core::Items::GroupItem::Members
               nil
             else
-              raise ArgumentError, "items must be a GenericItem, GroupItem::Members, Thing, or ThingUID"
+              raise ArgumentError, "items must be an Item, GroupItem::Members, Thing, or ThingUID"
             end
 
             logger.trace("Creating updated trigger for item(#{item}) to(#{to})")
@@ -1317,7 +1396,7 @@ module OpenHAB
         # @param [Object] attach object to be attached to the trigger
         # @return [void]
         #
-        # @example Watch `items` directory inside of the OpenHAB configuration path and log any changes.
+        # @example Watch `items` directory inside of the openHAB configuration path and log any changes.
         #   rule 'watch directory' do
         #     watch OpenHAB::Core.config_folder / 'items'
         #     run { |event| logger.info("#{event.path.basename} - #{event.type}") }
@@ -1358,36 +1437,6 @@ module OpenHAB
 
         # @!endgroup
 
-        #
-        # Checks if this rule should run on start
-        #
-        # @return [true, false] True if rule should run on start, false otherwise.
-        #
-        def on_start?
-          @on_start.enabled
-        end
-
-        #
-        # Get the optional start attachment
-        #
-        # @return [Object] optional user provided attachment to the on_start method
-        #
-        # @!visibility private
-        def start_attachment
-          @on_start.attach
-        end
-
-        # @!visibility private
-        #
-        # Run the supplied block inside the object instance of the object that created the rule
-        #
-        # @yield [] Block executed in context of the object creating the rule
-        #
-        #
-        def my(&block)
-          @caller.instance_eval(&block)
-        end
-
         #
         # @return [String]
         #
@@ -1396,7 +1445,7 @@ module OpenHAB
             #<OpenHAB::DSL::Rules::Builder: #{uid}
             triggers=#{triggers.inspect},
             run blocks=#{run.inspect},
-            on_start=#{on_start?},
+            on_load=#{!@on_load_id.nil?},
             Trigger Conditions=#{trigger_conditions.inspect},
             Trigger UIDs=#{triggers.map(&:id).inspect},
             Attachments=#{attachments.inspect}
@@ -1419,7 +1468,7 @@ module OpenHAB
           added_rule.actions.first.configuration.put("type", "application/x-ruby")
           added_rule.actions.first.configuration.put("script", script) if script
 
-          rule.execute(nil, { "event" => Struct.new(:attachment).new(start_attachment) }) if on_start?
+          rule.execute(nil, { "module" => @on_load_id }) if @on_load_id
           added_rule
         end
 
@@ -1456,7 +1505,7 @@ module OpenHAB
         # @return [true,false] True if rule has triggers, false otherwise
         #
         def triggers?
-          on_start? || !triggers.empty?
+          @on_load_id || !triggers.empty?
         end
 
         #

data/lib/openhab/dsl/rules/guard.rb

@@ -34,7 +34,7 @@ module OpenHAB
         #
         # Checks if a guard should run
         #
-        # @param [OpenHAB Trigger Event] event OpenHAB Trigger Event
+        # @param [Object] event openHAB Trigger Event
         #
         # @return [true,false] True if guard is satisfied, false otherwise
         #
@@ -51,7 +51,7 @@ module OpenHAB
         #
         # @param [Array] conditions to check
         # @param [Symbol] check_type type of check to perform (:only_if or :not_if)
-        # @param [Event] event OpenHAB event to see if it satisfies the guard
+        # @param [Event] event openHAB event to see if it satisfies the guard
         #
         # @return [true,false] True if guard is satisfied, false otherwise
         #
@@ -70,7 +70,7 @@ module OpenHAB
         # Execute the guard check
         #
         # @param [Symbol] check_type :only_if or :not_if to check
-        # @param [OpenHAB Event] event event to check if meets guard
+        # @param [Object] event event to check if meets guard
         # @param [Array<Item>] items to check if satisfy criteria
         # @param [Array] procs to check if satisfy criteria
         #
@@ -87,7 +87,7 @@ module OpenHAB
         #
         # Check not_if guard
         #
-        # @param [OpenHAB Event] event to check if meets guard
+        # @param [Object] event to check if meets guard
         # @param [Array<Item>] items to check if satisfy criteria
         # @param [Array] procs to check if satisfy criteria
         #
@@ -100,7 +100,7 @@ module OpenHAB
         #
         # Check only_if guard
         #
-        # @param [OpenHAB Event] event to check if meets guard
+        # @param [Object] event to check if meets guard
         # @param [Array<Item>] items to check if satisfy criteria
         # @param [Array] procs to check if satisfy criteria
         #