openhab-jrubyscripting 5.0.0.rc1

data/lib/openhab/dsl/items/timed_command.rb

@@ -0,0 +1,236 @@
+# frozen_string_literal: true
+
+module OpenHAB
+  module DSL
+    module Items
+      # Extensions for {GenericItem} to implement timed commands
+      #
+      # All items have an implicit timer associated with them, enabling to
+      # easily set an item into a specific state for a specified duration and
+      # then at the expiration of that duration have the item automatically
+      # change to another state. These timed commands are reentrant, meaning
+      # if the same timed command is triggered while an outstanding timed
+      # command exist, that timed command will be rescheduled rather than
+      # creating a distinct timed command.
+      #
+      # Timed commands are initiated by using the 'for:' argument with the
+      # command. This is available on both the 'command' method and any
+      # command-specific methods, e.g. {SwitchItem#on}.
+      #
+      # Any update to the timed command state will result in the timer being
+      # cancelled. For example, if you have a Switch on a timer and another
+      # rule sends OFF or ON to that item the timer will be automatically
+      # canceled. Sending a different duration (for:) value for the timed
+      # command will reschedule the timed command for that new duration.
+      #
+      module TimedCommand
+        #
+        # Provides information about why the expiration block of a
+        # {TimedCommand#command timed command} is being called.
+        #
+        # @attr [GenericItem] item
+        #   @!visibility private
+        # @attr [Types::Type, Proc] on_expire
+        #   @!visibility private
+        # @attr [Core::Timer] timer
+        #   @!visibility private
+        # @attr [Symbol] resolution
+        #   @!visibility private
+        # @attr [String] rule_uid
+        #   @!visibility private
+        # @attr [Mutex] mutex
+        #   @!visibility private
+        #
+        TimedCommandDetails = Struct.new(:item,
+                                         :on_expire,
+                                         :timer,
+                                         :resolution,
+                                         :rule_uid,
+                                         :mutex,
+                                         keyword_init: true) do
+          # @return [true, false]
+          def expired?
+            resolution == :expired
+          end
+
+          # @return [true, false]
+          def cancelled?
+            resolution == :cancelled
+          end
+        end
+
+        @timed_commands = java.util.concurrent.ConcurrentHashMap.new
+
+        class << self
+          # @!visibility private
+          attr_reader :timed_commands
+        end
+
+        Core::Items::GenericItem.prepend(self)
+
+        #
+        # Sends command to an item for specified duration, then on timer expiration sends
+        # the expiration command to the item
+        #
+        # @note If a block is provided, and the timer is canceled because the
+        #   item changed state while it was waiting, the block will still be
+        #   executed. Be sure to check {TimedCommandDetails#expired? #expired?}
+        #   and/or {TimedCommandDetails#cancelled? #cancelled?} to determine why
+        #   the block was called.
+        #
+        # @param [Command] command to send to object
+        # @param [Duration] for duration for item to be in command state
+        # @param [Command] on_expire Command to send when duration expires
+        # @yield If a block is provided, `on_expire` is ignored and the block
+        #   is expected to set the item to the desired state or carry out some
+        #   other action.
+        # @yieldparam [TimedCommandDetails] timed_command
+        # @return [self]
+        #
+        # @example
+        #   Switch.command(ON, for: 5.minutes)
+        # @example
+        #   Switch.on for: 5.minutes
+        # @example
+        #   Dimmer.on for: 5.minutes, on_expire: 50
+        # @example
+        #   Dimmer.on(for: 5.minutes) { |event| Dimmer.off if Light.on? }
+        #
+        def command(command, for: nil, on_expire: nil, &block)
+          duration = binding.local_variable_get(:for)
+          return super(command) unless duration
+
+          on_expire = block if block
+
+          TimedCommand.timed_commands.compute(self) do |_key, timed_command_details|
+            if timed_command_details.nil?
+              # no prior timed command
+              on_expire ||= default_on_expire(command)
+              super(command)
+              create_timed_command(duration: duration, on_expire: on_expire)
+            else
+              timed_command_details.mutex.synchronize do
+                if timed_command_details.resolution
+                  # timed command that finished, but hadn't removed itself from the map yet
+                  # (it doesn't do so under the mutex to prevent a deadlock).
+                  # just create a new one
+                  on_expire ||= default_on_expire(command)
+                  super(command)
+                  create_timed_command(duration: duration, on_expire: on_expire)
+                else
+                  # timed command still pending; reset it
+                  logger.trace "Outstanding Timed Command #{timed_command_details} encountered - rescheduling"
+                  timed_command_details.on_expire = on_expire unless on_expire.nil?
+                  timed_command_details.timer.reschedule(duration)
+                  # disable the cancel rule while we send the new command
+                  Core.rule_manager.set_enabled(timed_command_details.rule_uid, false)
+                  super(command)
+                  Core.rule_manager.set_enabled(timed_command_details.rule_uid, true)
+                  timed_command_details
+                end
+              end
+            end
+          end
+
+          self
+        end
+
+        private
+
+        # Creates a new timed command and places it in the TimedCommand hash
+        def create_timed_command(duration:, on_expire:)
+          timed_command_details = TimedCommandDetails.new(item: self,
+                                                          on_expire: on_expire,
+                                                          mutex: Mutex.new)
+
+          timed_command_details.timer = timed_command_timer(timed_command_details, duration)
+          cancel_rule = TimedCommandCancelRule.new(timed_command_details)
+          timed_command_details.rule_uid = Core.automation_manager
+                                               .add_rule(cancel_rule)
+                                               .uid
+          Rules.script_rules[timed_command_details.rule_uid] = cancel_rule
+          logger.trace "Created Timed Command #{timed_command_details}"
+          timed_command_details
+        end
+
+        # Creates the timer to handle changing the item state when timer expires or invoking user supplied block
+        # @param [TimedCommandDetailes] timed_command_details details about the timed command
+        # @return [Timer] Timer
+        def timed_command_timer(timed_command_details, duration)
+          DSL.after(duration) do
+            timed_command_details.mutex.synchronize do
+              logger.trace "Timed command expired - #{timed_command_details}"
+              DSL.remove_rule(timed_command_details.rule_uid)
+              timed_command_details.resolution = :expired
+              case timed_command_details.on_expire
+              when Proc
+                logger.trace "Invoking block #{timed_command_details.on_expire} after timed command for #{name} expired"
+                timed_command_details.on_expire.call(timed_command_details)
+              when Core::Types::UnDefType
+                update(timed_command_details.on_expire)
+              else
+                command(timed_command_details.on_expire)
+              end
+            end
+            TimedCommand.timed_commands.delete(timed_command_details.item)
+          end
+        end
+
+        #
+        # The default expire for ON/OFF is their inverse
+        #
+        def default_on_expire(command)
+          return !command if command.is_a?(Core::Types::OnOffType)
+
+          raw_state
+        end
+
+        #
+        # Rule to cancel timed commands
+        #
+        # @!visibility private
+        class TimedCommandCancelRule < org.openhab.core.automation.module.script.rulesupport.shared.simple.SimpleRule
+          def initialize(timed_command_details)
+            super()
+            @timed_command_details = timed_command_details
+            # Capture rule name if known
+            @thread_locals = ThreadLocal.persist
+            self.name = "Cancel implicit timer for #{timed_command_details.item.name}"
+            self.triggers = [Rules::RuleTriggers.trigger(
+              type: Rules::Triggers::Changed::ITEM_STATE_CHANGE,
+              config: { "itemName" => timed_command_details.item.name }
+            )]
+          end
+
+          # Cleanup the rule; nothing to do here.
+          def cleanup; end
+
+          #
+          # 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
+          #
+          def execute(_mod = nil, inputs = nil)
+            ThreadLocal.thread_local(**@thread_locals) do
+              @timed_command_details.mutex.synchronize do
+                logger.trace "Canceling implicit timer #{@timed_command_details.timer} for "\
+                             "#{@timed_command_details.item.name}  because received event #{inputs}"
+                @timed_command_details.timer.cancel
+                DSL.remove_rule(@timed_command_details.rule_uid)
+                @timed_command_details.resolution = :cancelled
+                if @timed_command_details.on_expire.is_a?(Proc)
+                  logger.trace "Executing user supplied block on timed command cancelation"
+                  @timed_command_details.on_expire.call(@timed_command_details)
+                end
+              end
+              TimedCommand.timed_commands.delete(@timed_command_details.item)
+            rescue Exception => e
+              logger.log_exception(e)
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,308 @@
+# frozen_string_literal: true
+
+module OpenHAB
+  module DSL
+    module Rules
+      #
+      # OpenHAB rules engine object
+      #
+      # @!visibility private
+      class AutomationRule < org.openhab.core.automation.module.script.rulesupport.shared.simple.SimpleRule
+        field_writer :uid
+
+        #
+        # Create a new Rule
+        #
+        # @param [Config] config Rule configuration
+        #
+        # Constructor sets a number of variables, no further decomposition necessary
+        def initialize(config:)
+          # Metrics disabled because only setters are called or defaults set.
+          super()
+          set_name(config.name)
+          set_description(config.description)
+          set_tags(to_string_set(config.tags))
+          set_triggers(config.triggers)
+          self.uid = config.uid
+          @run_context = config.caller
+          @run_queue = config.run
+          @guard = config.guard
+          @between = config.between && DSL.between(config.between)
+          @trigger_conditions = config.trigger_conditions
+          @attachments = config.attachments
+          @thread_locals = ThreadLocal.persist
+        end
+
+        #
+        # 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
+        #
+        #
+        def execute(mod = nil, inputs = nil)
+          ThreadLocal.thread_local(**@thread_locals) do
+            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)
+            end
+          rescue Exception => e
+            @run_context.send(:logger).log_exception(e)
+          end
+        end
+
+        #
+        # Cleanup any resources associated with automation rule
+        #
+        def cleanup
+          @trigger_conditions.each_value(&:cleanup)
+        end
+
+        private
+
+        #
+        # Create the run queue based on guards
+        #
+        # @param [Map] inputs rule inputs
+        # @return [Queue] <description>
+        #
+        def create_queue(inputs)
+          case check_guards(event: extract_event(inputs))
+          when true
+            @run_queue.dup.grep_v(Builder::Otherwise)
+          when false
+            @run_queue.dup.grep(Builder::Otherwise)
+          end
+        end
+
+        #
+        # Extract the event object from inputs
+        # and merge other inputs keys/values into the event
+        #
+        # @param [Map] inputs rule inputs
+        #
+        # @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")
+          end
+          add_attachment(event, inputs)
+        end
+
+        #
+        # Get the trigger_id for the trigger that caused the rule creation
+        #
+        # @return [Hash] Input hash potentially containing trigger id
+        #
+        def trigger_id(inputs)
+          inputs&.dig("module")
+        end
+
+        #
+        # Returns trigger conditions from inputs if it exists
+        #
+        # @param [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
+        #
+        # @return [true,false] True if guards says rule should execute, false otherwise
+        #
+        # Loggging inflates method length
+        def check_guards(event:)
+          return true if @guard.nil?
+
+          if @guard.should_run? event
+            return true if @between.nil?
+
+            now = Time.now
+            return true if @between.cover? 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}")
+          end
+          false
+        end
+
+        #
+        # 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
+        #
+        def process_queue(run_queue, mod, inputs)
+          event = extract_event(inputs)
+
+          while (task = run_queue.shift)
+            if task.is_a?(Builder::Delay)
+              process_delay_task(inputs, mod, run_queue, task)
+            else
+              process_task(event, task)
+            end
+          end
+        end
+
+        #
+        # Dispatch execution block tasks to different methods
+        #
+        # @param [OpenHab Event] event that triggered the rule
+        # @param [Task] task task containing otherwise block to execute
+        #
+        def process_task(event, task)
+          ThreadLocal.thread_local(**@thread_locals) do
+            case task
+            when Builder::Run then process_run_task(event, task)
+            when Builder::Script then process_script_task(task)
+            when Builder::Trigger then process_trigger_task(event, task)
+            when Builder::Otherwise then process_otherwise_task(event, task)
+            end
+          end
+        end
+
+        #
+        # Process an otherwise block
+        #
+        # @param [OpenHab Event] event that triggered the rule
+        # @param [Task] task task containing otherwise block to execute
+        #
+        #
+        def process_otherwise_task(event, task)
+          logger.trace { "Executing rule '#{name}' otherwise block with event(#{event})" }
+          @run_context.instance_exec(event, &task.block)
+        end
+
+        #
+        # Process delay task
+        #
+        # @param [Map] inputs Rule trigger inputs
+        # @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)
+          remaining_queue = run_queue.slice!(0, run_queue.length)
+          DSL.after(task.duration) { process_queue(remaining_queue, mod, inputs) }
+        end
+
+        #
+        # Process a task that is caused by a group item
+        #
+        # @param [Map] event Rule event map
+        # @param [Trigger] task to execute
+        #
+        #
+        def process_trigger_task(event, task)
+          return unless event&.item
+
+          logger.trace { "Executing rule '#{name}' trigger block with item (#{event.item})" }
+          @run_context.instance_exec(event.item, &task.block)
+        end
+
+        #
+        # Process a run task
+        #
+        # @param [OpenHab Event] event information
+        # @param [Run] task to execute
+        #
+        #
+        def process_run_task(event, task)
+          logger.trace { "Executing rule '#{name}' run block with event(#{event})" }
+          @run_context.instance_exec(event, &task.block)
+        end
+
+        #
+        # Process a script task
+        #
+        # @param [Script] task to execute
+        #
+        def process_script_task(task)
+          logger.trace { "Executing script '#{name}' run block" }
+          @run_context.instance_exec(&task.block)
+        end
+
+        #
+        # Convert the given array to a set of strings.
+        # Convert Semantics classes to their simple name
+        #
+        # @example
+        #   to_string_set("tag1", Semantics::LivingRoom)
+        #
+        # @param tags [Array] An array of strings or Semantics classes
+        #
+        # @return [Set] A set of strings
+        #
+        def to_string_set(*tags)
+          tags = tags.flatten.map do |tag|
+            if tag.respond_to?(:java_class) && tag < org.openhab.core.semantics.Tag
+              tag.java_class.simple_name
+            else
+              tag.to_s
+            end
+          end
+          Set.new(tags)
+        end
+
+        #
+        # Create a new hash in which all elements are converted to strings
+        #
+        # @param [Map] hash in which all elements should be converted to strings
+        #
+        # @return [Map] new map with values converted to strings
+        #
+        def inspect_hash(hash)
+          hash.each_with_object({}) do |(key, value), new_hash|
+            new_hash[inspect_item(key)] = inspect_item(value)
+          end
+        end
+
+        #
+        # Convert an individual element into a string based on if it a Ruby or Java object
+        #
+        # @param [Object] item to convert to a string
+        #
+        # @return [String] representation of item
+        #
+        def inspect_item(item)
+          if item.respond_to? :to_string
+            item.to_string
+          elsif item.respond_to? :to_str
+            item.to_str
+          end
+        end
+      end
+    end
+  end
+end