openhab-scripting 2.16.2 → 2.19.0

data/lib/openhab/dsl/monkey_patch/types/open_closed_type.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require 'java'
+
+module OpenHAB
+  module DSL
+    module MonkeyPatch
+      #
+      # Patches OpenHAB types
+      #
+      module Types
+        java_import Java::OrgOpenhabCoreLibraryTypes::OpenClosedType
+
+        #
+        # Monkey patch for DSL use
+        #
+        class OpenClosedType
+          java_import Java::OrgOpenhabCoreLibraryItems::ContactItem
+
+          #
+          # Check if the supplied object is case equals to self
+          #
+          # @param [Object] other object to compare
+          #
+          # @return [Boolean] True if the other object is a ContactItem and has the same state
+          #
+          def ===(other)
+            super unless other.is_a? ContactItem
+
+            self == other.state
+          end
+        end
+      end
+    end
+  end
+end

data/lib/openhab/dsl/monkey_patch/types/percent_type.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require 'java'
+module OpenHAB
+  module DSL
+    module MonkeyPatch
+      #
+      # Patches OpenHAB types
+      #
+      module Types
+        java_import Java::OrgOpenhabCoreLibraryTypes::PercentType
+
+        #
+        # MonkeyPatching PercentType
+        #
+        class PercentType
+          #
+          # Need to override and point to super because default JRuby implementation doesn't point to == of parent class
+          #
+          # @param [Object] other object to check equality for
+          # @return [Boolean] True if other equals self, false otherwise
+          #
+          # rubocop:disable Lint/UselessMethodDefinition
+          def ==(other)
+            super
+          end
+          # rubocop:enable Lint/UselessMethodDefinition
+        end
+      end
+    end
+  end
+end

data/lib/openhab/dsl/monkey_patch/types/quantity_type.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require 'java'
+
+module OpenHAB
+  module DSL
+    module MonkeyPatch
+      #
+      # Patches OpenHAB types
+      #
+      module Types
+        java_import Java::OrgOpenhabCoreLibraryTypes::QuantityType
+
+        #
+        # MonkeyPatching QuantityType
+        #
+        class QuantityType
+          #
+          # Compare QuantityType to supplied object
+          #
+          # @param [Object] other object to compare to
+          #
+          # @return [Integer] -1,0,1 or nil depending on value supplied,
+          #   nil comparison to supplied object is not possible.
+          #
+          def <=>(other)
+            logger.trace("#{self.class} #{self} <=> #{other} (#{other.class})")
+            case other
+            when Java::OrgOpenhabCoreTypes::UnDefType then 1
+            when String then self <=> Quantity.new(other)
+            when OpenHAB::DSL::Types::Quantity then self <=> other.quantity
+            else
+              other = other.state if other.respond_to? :state
+              compare_to(other)
+            end
+          end
+
+          #
+          # Coerce objects into a QuantityType
+          #
+          # @param [Object] other object to coerce to a QuantityType if possible
+          #
+          # @return [Object] Numeric when applicable
+          #
+          def coerce(other)
+            logger.trace("Coercing #{self} as a request from #{other.class}")
+            case other
+            when String
+              [Quantity.new(other), self]
+            else
+              [other, self]
+            end
+          end
+
+          #
+          # Compare self to other using the spaceship operator
+          #
+          # @param [Object] other object to compare to
+          #
+          # @return [Boolean] True if equals
+          #
+          def ==(other)
+            (self <=> other).zero?
+          end
+        end
+      end
+    end
+  end
+end

data/lib/openhab/dsl/monkey_patch/types/types.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+# Monkey patch types
+require 'openhab/dsl/monkey_patch/types/open_closed_type'
+require 'openhab/dsl/monkey_patch/types/on_off_type'
+require 'openhab/dsl/monkey_patch/types/decimal_type'
+require 'openhab/dsl/monkey_patch/types/percent_type'
+require 'openhab/dsl/monkey_patch/types/quantity_type'
+require 'openhab/dsl/monkey_patch/types/up_down_type'

data/lib/openhab/dsl/monkey_patch/types/up_down_type.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require 'java'
+module OpenHAB
+  module DSL
+    module MonkeyPatch
+      #
+      # Patches OpenHAB types
+      #
+      module Types
+        java_import Java::OrgOpenhabCoreLibraryTypes::UpDownType
+
+        #
+        # MonkeyPatching UpDownType
+        #
+        class UpDownType
+          #
+          # Check if the supplied object is case equals to self
+          #
+          # @param [Object] other object to compare
+          #
+          # @return [Boolean] True if the other object is a RollershutterItem and has the same state
+          #
+          def ===(other)
+            super unless other.is_a? OpenHAB::DSL::Items::RollershutterItem
+
+            equals(other.state.as(UpDownType))
+          end
+        end
+      end
+    end
+  end
+end

data/lib/openhab/dsl/persistence.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module OpenHAB
+  module DSL
+    #
+    # Provides support for interacting with OpenHAB Persistence service
+    #
+    module Persistence
+      #
+      # Sets a thread local variable to set the default persistence service
+      # for method calls inside the block
+      #
+      # @param [Object] service service either as a String or a Symbol
+      # @yield [] Block executed in context of the supplied persistence service
+      #
+      #
+      def persistence(service)
+        Thread.current.thread_variable_set(:persistence_service, service)
+        yield
+      ensure
+        Thread.current.thread_variable_set(:persistence_service, nil)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,342 @@
+# frozen_string_literal: true
+
+require 'java'
+
+module OpenHAB
+  module DSL
+    #
+    # Creates and manages OpenHAB Rules
+    #
+    module Rules
+      #
+      # JRuby extension to OpenHAB Rule
+      #
+      # rubocop: disable Metrics/ClassLength
+      # Disabled because this class has a single responsibility, there does not appear a logical
+      # way of breaking it up into multiple classes
+      class AutomationRule < Java::OrgOpenhabCoreAutomationModuleScriptRulesupportSharedSimple::SimpleRule
+        include OpenHAB::Log
+        include OpenHAB::DSL::TimeOfDay
+        java_import java.time.ZonedDateTime
+
+        #
+        # Create a new Rule
+        #
+        # @param [Config] config Rule configuration
+        #
+        def initialize(config:)
+          super()
+          set_name(config.name)
+          set_description(config.description)
+          set_triggers(config.triggers)
+          @run_queue = config.run
+          @guard = config.guard
+          between = config.between&.yield_self { between(config.between) }
+          @between = between || OpenHAB::DSL::TimeOfDay::ALL_DAY
+          # Convert between to correct range or nil if not set
+          @trigger_delays = config.trigger_delays
+        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)
+          logger.trace { "Execute called with mod (#{mod&.to_string}) and inputs (#{inputs&.pretty_inspect}" }
+          logger.trace { "Event details #{inputs['event'].pretty_inspect}" } if inputs&.key?('event')
+          if trigger_delay inputs
+            trigger_delay = trigger_delay(inputs)
+            process_trigger_delay(trigger_delay, mod, inputs)
+          else
+            # If guards are satisfied execute the run type blocks
+            # If they are not satisfied, execute the Othewise blocks
+            queue = create_queue(inputs)
+            process_queue(queue, mod, inputs)
+          end
+        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: inputs&.dig('event'))
+          when true
+            @run_queue.dup
+          when false
+            @run_queue.dup.grep(RuleConfig::Otherwise)
+          end
+        end
+
+        #
+        # Returns trigger delay from inputs if it exists
+        #
+        # @param [Map] inputs map from OpenHAB containing UID
+        #
+        # @return [Array] Array of trigger delays that match rule UID
+        #
+        def trigger_delay(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_delays[inputs&.keys&.grep(/\.event$/)&.first&.chomp('.event')]
+        end
+
+        #
+        # Check if trigger guards prevent rule execution
+        #
+        # @param [Delay] trigger_delay rules delaying trigger because of
+        # @param [Map] inputs OpenHAB map object describing rule trigger
+        #
+        # @return [Boolean] True if the rule should execute, false if trigger guard prevents execution
+        #
+        def check_trigger_guards(trigger_delay, inputs)
+          old_state = inputs['oldState']
+          new_state = inputs['newState']
+          if check_from(trigger_delay, old_state)
+            return true if check_to(trigger_delay, new_state)
+
+            logger.trace("Skipped execution of rule '#{name}' because to state #{new_state}"\
+                                 " does not equal specified state(#{trigger_delay.to})")
+          else
+            logger.trace("Skipped execution of rule '#{name}' because old state #{old_state}"\
+                                 " does not equal specified state(#{trigger_delay.from})")
+          end
+        end
+
+        #
+        # Check the from state against the trigger delay
+        #
+        # @param [TriggerDelay] trigger_delay Information about the trigger delay
+        # @param [Item State] state from state to check
+        #
+        # @return [Boolean] true if no from state is defined or defined state equals supplied state
+        #
+        def check_from(trigger_delay, state)
+          trigger_delay.from.nil? || trigger_delay.from == state
+        end
+
+        #
+        # Check the to state against the trigger delay
+        #
+        # @param [TriggerDelay] trigger_delay Information about the trigger delay
+        # @param [Item State] state to-state to check
+        #
+        # @return [Boolean] true if no to state is defined or defined state equals supplied state
+        #
+        def check_to(trigger_delay, state)
+          trigger_delay.to.nil? || trigger_delay.to == state
+        end
+
+        #
+        # Process any matching trigger delays
+        #
+        # @param [Map] mod OpenHAB map object describing rule trigger
+        # @param [Map] inputs OpenHAB map object describing rule trigger
+        #
+        #
+        def process_trigger_delay(trigger_delay, mod, inputs)
+          if check_trigger_guards(trigger_delay, inputs)
+            logger.trace("Trigger Guards Matched for #{trigger_delay}, delaying rule execution")
+            # Add timer and attach timer to delay object, and also state being tracked to so timer can be cancelled if
+            #   state changes
+            # Also another timer should not be created if changed to same value again but instead rescheduled
+            if trigger_delay.timer_active?
+              process_active_timer(inputs, mod, trigger_delay)
+            else
+              create_trigger_delay_timer(inputs, mod, trigger_delay)
+            end
+          else
+            logger.trace("Trigger Guards did not match for #{trigger_delay}, ignoring trigger.")
+          end
+        end
+
+        #
+        # Creatas a timer for trigger delays
+        #
+        # @param [Hash] inputs rule trigger inputs
+        # @param [Hash] mod rule trigger mods
+        # @param [TriggerDelay] trigger_delay specifications
+        #
+        #
+        def create_trigger_delay_timer(inputs, mod, trigger_delay)
+          logger.trace("Creating timer for rule #{name} and trigger delay #{trigger_delay}")
+          trigger_delay.timer = after(trigger_delay.duration) do
+            logger.trace("Delay Complete for #{trigger_delay}, executing rule")
+            trigger_delay.timer = nil
+            process_queue(@run_queue.dup, mod, inputs)
+          end
+          trigger_delay.tracking_to = inputs['newState']
+        end
+
+        #
+        # Process an active trigger timer
+        #
+        # @param [Hash] inputs rule trigger inputs
+        # @param [Hash] mod rule trigger mods
+        # @param [TriggerDelay] trigger_delay specifications
+        #
+        #
+        def process_active_timer(inputs, mod, trigger_delay)
+          state = inputs['newState']
+          if state == trigger_delay.tracking_to
+            logger.trace("Item changed to #{state} for #{trigger_delay}, rescheduling timer.")
+            trigger_delay.timer.reschedule(ZonedDateTime.now.plus(trigger_delay.duration))
+          else
+            logger.trace("Item changed to #{state} for #{trigger_delay}, cancelling timer.")
+            trigger_delay.timer.cancel
+            # Reprocess trigger delay after cancelling to track new state (if guards matched, etc)
+            process_trigger_delay(trigger_delay, mod, inputs)
+          end
+        end
+
+        #
+        # Check if any guards prevent execution
+        #
+        # @param [Map] event OpenHAB rule trigger event
+        #
+        # @return [Boolean] True if guards says rule should execute, false otherwise
+        #
+        def check_guards(event:)
+          if @guard.should_run? event
+            now = TimeOfDay::TimeOfDay.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
+
+        #
+        # Patch event to decorate event.item with our item wrapper
+        #
+        # @param [OpenHAB Event] event patch
+        #
+        def decorate_event_item(event)
+          return if event.nil?
+
+          class << event
+            def item
+              OpenHAB::Core::EntityLookup.lookup_item(item_name)
+            end
+          end
+        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 = inputs&.dig('event')
+
+          while (task = run_queue.shift)
+            case task
+            when RuleConfig::Run then process_run_task(event, task)
+            when RuleConfig::Trigger then process_trigger_task(event, task)
+            when RuleConfig::Delay then process_delay_task(inputs, mod, run_queue, task)
+            when RuleConfig::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)
+          decorate_event_item(event)
+          logger.trace { "Executing rule '#{name}' otherwise block with event(#{event})" }
+          task.block.call(event)
+        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)
+          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)
+          triggering_item = OpenHAB::Core::EntityLookup.lookup_item(event&.itemName)
+          logger.trace { "Executing rule '#{name}' trigger block with item (#{triggering_item})" }
+          task.block.call(triggering_item) if triggering_item
+        end
+
+        #
+        # Process a run task
+        #
+        # @param [OpenHab Event] event information
+        # @param [Run] task to execute
+        #
+        #
+        def process_run_task(event, task)
+          decorate_event_item(event)
+          logger.trace { "Executing rule '#{name}' run block with event(#{event})" }
+          task.block.call(event)
+        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
+# rubocop: enable Metrics/ClassLength