openhab-scripting 4.47.0 → 5.0.1

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

@@ -1,108 +1,99 @@
 # frozen_string_literal: true
 
-require 'ruby2_keywords'
-require 'openhab/log/logger'
-require_relative 'generic_item'
+require "ruby2_keywords"
 
 module OpenHAB
   module DSL
-    # Functionality to implement +ensure+/+ensure_states+
-    module Ensure
-      # Contains the global +ensure_states+ method
-      module EnsureStates
-        # Global method that takes a block and for the duration of the block
-        # all commands sent will check if the item is in the command's state
-        # before sending the command.
-        #
-        # @example Turn on several switches only if they're not already on
-        #   ensure_states do
-        #     Switch1.on
-        #     Switch2.on
-        #   end
-        def ensure_states
-          old = Thread.current[:ensure_states]
-          Thread.current[:ensure_states] = true
-          yield
-        ensure
-          Thread.current[:ensure_states] = old
+    module Items
+      # Functionality to implement `ensure`/`ensure_states`
+      module Ensure
+        # Contains the `ensure` method mixed into {Item} and {GroupItem::Members}
+        module Ensurable
+          # Fluent method call that you can chain commands on to, that will
+          # then automatically ensure that the item is not in the command's
+          # state before sending the command.
+          #
+          # @example Turn switch on only if it's not on
+          #   MySwitch.ensure.on
+          # @example Turn on all switches in a group that aren't already on
+          #   MySwitchGroup.members.ensure.on
+          def ensure
+            ItemDelegate.new(self)
+          end
         end
-        module_function :ensure_states
-      end
 
-      # Contains the +ensure+ method mixed into {GenericItem} and {GroupItem::GroupMembers}
-      module Ensurable
-        # Fluent method call that you can chain commands on to, that will
-        # then automatically ensure that the item is not in the command's
-        # state before sending the command.
+        # Extensions for {::Item} to implement {Ensure}'s functionality
         #
-        # @example Turn switch on only if it's not on
-        #   MySwitch.ensure.on
-        # @example Turn on all switches in a group that aren't already on
-        #   MySwitchGroup.members.ensure.on
-        def ensure
-          GenericItemDelegate.new(self)
-        end
-      end
+        # @see OpenHAB::DSL.ensure ensure
+        # @see OpenHAB::DSL.ensure_states ensure_states
+        module Item
+          include Ensurable
 
-      # Extensions for {Items::GenericItem} to implement {Ensure}'s
-      # functionality
-      module GenericItem
-        include Ensurable
+          Core::Items::GenericItem.prepend(self)
 
-        # If +ensure_states+ is active (by block or chained method), then
-        # check if this item is in the command's state before actually
-        # sending the command
-        %i[command update].each do |ensured_method|
-          define_method(ensured_method) do |command|
-            return super(command) unless Thread.current[:ensure_states]
+          # If `ensure_states` is active (by block or chained method), then
+          # check if this item is in the command's state before actually
+          # sending the command
+          %i[command update].each do |ensured_method|
+            # def command(state)
+            #   return super(state) unless Thread.current[:openhab_ensure_states]
+            #
+            #   formatted_state = format_command(state)
+            #   logger.trace do
+            #     "#{name} ensure #{state}, format_command: #{formatted_state}, current state: #{raw_state}"
+            #   end
+            #   return if raw_state == formatted_state
+            #
+            #   super(formatted_state)
+            # end
+            class_eval <<~RUBY, __FILE__, __LINE__ + 1 # rubocop:disable Style/DocumentDynamicEvalDefinition
+              def #{ensured_method}(state)
+                return super(state) unless Thread.current[:openhab_ensure_states]
 
-            logger.trace do
-              "#{name} ensure #{command}, format_type_pre: #{format_type_pre(command)}, current state: #{state}"
-            end
-            return if state == format_type_pre(command)
+                formatted_state = format_#{ensured_method}(state)
+                logger.trace do
+                  "\#{name} ensure \#{state}, format_#{ensured_method}: \#{formatted_state}, current state: \#{raw_state}"
+                end
+                return if raw_state.as(formatted_state.class) == formatted_state
 
-            super(command)
+                super(formatted_state)
+              end
+            RUBY
           end
         end
-        alias << command
-      end
-
-      # "anonymous" class that wraps any method call in +ensure_states+
-      # before forwarding to the wrapped object
-      # @!visibility private
-      class GenericItemDelegate
-        def initialize(item)
-          @item = item
-        end
 
+        # "anonymous" class that wraps any method call in `ensure_states`
+        # before forwarding to the wrapped object
         # @!visibility private
-        # this is explicitly defined, instead of aliased, because #command
-        # doesn't actually exist as a method, and will go through method_missing
-        def <<(command)
-          command(command)
-        end
+        class ItemDelegate
+          def initialize(item)
+            @item = item
+          end
 
-        # activate +ensure_states+ before forwarding to the wrapped object
-        ruby2_keywords def method_missing(method, *args, &block)
-          return super unless @item.respond_to?(method)
+          # @!visibility private
+          # this is explicitly defined, instead of aliased, because #command
+          # doesn't actually exist as a method, and will go through method_missing
+          def <<(command)
+            command(command)
+          end
 
-          ensure_states do
-            @item.__send__(method, *args, &block)
+          # activate `ensure_states` before forwarding to the wrapped object
+          ruby2_keywords def method_missing(method, *args, &block)
+            return super unless @item.respond_to?(method)
+
+            DSL.ensure_states do
+              @item.__send__(method, *args, &block)
+            end
           end
-        end
 
-        # .
-        def respond_to_missing?(method, include_private = false)
-          @item.respond_to?(method, include_private) || super
+          # .
+          def respond_to_missing?(method, include_private = false)
+            @item.respond_to?(method, include_private) || super
+          end
         end
       end
-    end
 
-    module Items
-      GenericItem.prepend(OpenHAB::DSL::Ensure::GenericItem)
-      GroupItem::GroupMembers.include(OpenHAB::DSL::Ensure::Ensurable)
+      Core::Items::GroupItem::Members.include(Ensure::Ensurable)
     end
   end
 end
-
-Object.include OpenHAB::DSL::Ensure::EnsureStates

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

@@ -1,198 +1,253 @@
 # frozen_string_literal: true
 
-require 'openhab/dsl/timers'
-require 'openhab/dsl/rules/rule_triggers'
-require 'openhab/dsl/rules/triggers/triggers'
-require 'openhab/log/logger'
-require 'java'
-
-require_relative 'generic_item'
-
 module OpenHAB
   module DSL
     module Items
-      # Module enables timed commands e.g. Switch.on for: 3.minutes
+      # Extensions for {Item} 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}.
+      #
+      # The timer will be cancelled, and the item's state will not be changed
+      # to the on_expire state if:
+      # - The item receives any command within the timed command duration.
+      # - The item is updated to a different state, even if it is then updated
+      #   back to the same state.
+      #
+      # For example, if you have a Switch on a timer and another rule sends
+      # a command to that item, even when it's commanded to the same state,
+      # 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
-        # Stores information about timed commands
-        TimedCommandDetails = Struct.new(:item, :command, :was, :duration, :on_expire, :timer, :expired, :cancel_rule,
-                                         :rule_uid, keyword_init: true) do
+        #
+        # Provides information about why the expiration block of a
+        # {TimedCommand#command timed command} is being called.
+        #
+        # @attr [Item] 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?
-            expired
+            resolution == :expired
           end
 
-          def canceled?
-            !expired?
+          # @return [true, false]
+          def cancelled?
+            resolution == :cancelled
           end
         end
 
-        @timed_commands = {}
+        @timed_commands = java.util.concurrent.ConcurrentHashMap.new
 
         class << self
+          # @!visibility private
           attr_reader :timed_commands
         end
 
-        # Extensions for {Items::GenericItem} to implement timed commands
-        module GenericItem
-          #
-          #  Sends command to an item for specified duration, then on timer expiration sends
-          #  the expiration command to the item
-          #
-          # @param [Types::Type] command to send to object
-          # @param [Duration] for duration for item to be in command state
-          # @param [Types::Type] on_expire Command to send when duration expires
-          #
-          #
-          # rubocop: disable Metrics/MethodLength
-          # The mutex makes this over 10 lines, but there is usable way to break this method up
-          def command(command, for: nil, on_expire: nil, &block)
-            duration = binding.local_variable_get(:for)
-            return super(command) unless duration
-
-            # Timer needs access to rule to disable, rule needs access to timer to cancel.
-            # Using a mutex to ensure neither fires before the other is constructed
-            semaphore = Mutex.new
-
-            semaphore.synchronize do
-              timed_command_details = TimedCommand.timed_commands[self]
-              if timed_command_details.nil?
-                create_timed_command(command: command, duration: duration,
-                                     semaphore: semaphore, on_expire: on_expire, &block)
-              else
-                logger.trace "Outstanding Timed Command #{timed_command_details} encountered - rescheduling"
-                timed_command_details.duration = duration # Capture updated duration
-                timed_command_details.timer.reschedule duration
+        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(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(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
+                  DSL.rules[timed_command_details.rule_uid].disable
+                  super(command)
+                  DSL.rules[timed_command_details.rule_uid].enable
+                  timed_command_details
+                end
               end
             end
-
-            self
           end
-          # rubocop: enable Metrics/MethodLength
-          alias << command
-
-          private
-
-          # Creates a new timed command and places it in the TimedCommand hash
-          # rubocop: disable Metrics/AbcSize
-          # rubocop: disable Metrics/MethodLength
-          # There is no feasible way to break this method into smaller components
-          def create_timed_command(command:, duration:, semaphore:, on_expire:, &block)
-            on_expire ||= default_on_expire(command)
-            timed_command_details = TimedCommandDetails.new(item: self, command: command, was: state,
-                                                            on_expire: on_expire, duration: duration)
-
-            # Send specified command after capturing current state
-            command(command)
-
-            timed_command_details.timer = timed_command_timer(timed_command_details, semaphore, &block)
-            timed_command_details.cancel_rule = TimedCommandCancelRule.new(timed_command_details, semaphore,
-                                                                           &block)
-            timed_command_details.rule_uid = OpenHAB::DSL::Rules::Rule.automation_manager
-                                                                      .addRule(timed_command_details.cancel_rule)
-                                                                      .getUID
-            logger.trace "Created Timed Command #{timed_command_details}"
-            TimedCommand.timed_commands[self] = timed_command_details
-          end
-          # rubocop: enable Metrics/AbcSize
-          # rubocop: enable Metrics/MethodLength
-
-          # 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
-          # @param [Mutex] semaphore Semaphore to lock on to prevent race condition between rule and timer
-          # @return [Timer] Timer
-          # rubocop: disable Metrics/MethodLength
-          # There is no feasible way to break this method into smaller components
-          def timed_command_timer(timed_command_details, semaphore, &block)
-            after(timed_command_details.duration, id: self) do
-              semaphore.synchronize do
-                logger.trace "Timed command expired - #{timed_command_details}"
-                cancel_timed_command_rule(timed_command_details)
-                timed_command_details.expired = true
-                if block
-                  logger.trace "Invoking block #{block} after timed command for #{id} expired"
-                  yield(timed_command_details)
-                else
-                  command(timed_command_details.on_expire)
-                end
 
-                TimedCommand.timed_commands.delete(timed_command_details.item)
+          self
+        end
+
+        private
+
+        # Creates a new timed command and places it in the TimedCommand hash
+        def create_timed_command(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(command, timed_command_details)
+          unmanaged_rule = Core.automation_manager.add_unmanaged_rule(cancel_rule)
+          timed_command_details.rule_uid = unmanaged_rule.uid
+          Core::Rules::Provider.current.add(unmanaged_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.rules.remove(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
-          # rubocop: enable Metrics/MethodLength
+        end
 
-          # Cancels timed command rule
-          # @param [TimedCommandDetailed] timed_command_details details about the timed command
-          def cancel_timed_command_rule(timed_command_details)
-            logger.trace "Removing rule: #{timed_command_details.rule_uid}"
-            OpenHAB::DSL::Rules::Rule.registry.remove(timed_command_details.rule_uid)
-          end
+        #
+        # The default expire for ON/OFF is their inverse
+        #
+        def default_on_expire(command)
+          return !command if command.is_a?(Core::Types::OnOffType)
 
-          #
-          # The default expire for ON/OFF is their inverse
-          #
-          def default_on_expire(command)
-            case format_type_pre(command)
-            when ON then OFF
-            when OFF then ON
-            else state
-            end
+          raw_state
+        end
+
+        #
+        # Rule to cancel timed commands
+        #
+        # @!visibility private
+        class TimedCommandCancelRule < org.openhab.core.automation.module.script.rulesupport.shared.simple.SimpleRule
+          def initialize(command, 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,
+                  "previousState" => timed_command_details.item.format_command(command).to_s
+                }
+              ),
+              Rules::RuleTriggers.trigger(
+                type: Rules::Triggers::Command::ITEM_COMMAND,
+                config: {
+                  "itemName" => timed_command_details.item.name
+                }
+              )
+            ]
+            self.visibility = Core::Rules::Visibility::HIDDEN
           end
 
           #
-          # Rule to cancel timed commands
+          # Execute the rule
           #
-          class TimedCommandCancelRule < Java::OrgOpenhabCoreAutomationModuleScriptRulesupportSharedSimple::SimpleRule
-            include OpenHAB::Log
-            include OpenHAB::Core::ThreadLocal
-
-            def initialize(timed_command_details, semaphore, &block) # rubocop:disable Metrics/MethodLength
-              super()
-              @semaphore = semaphore
-              @timed_command_details = timed_command_details
-              @block = block
-              # Capture rule name if known
-              @thread_locals = Thread.current[:RULE_NAME] ? { RULE_NAME: Thread.current[:RULE_NAME] } : {}
-              set_name("Cancels implicit timer for #{timed_command_details.item.id}")
-              set_triggers([OpenHAB::DSL::Rules::RuleTriggers.trigger(
-                type: OpenHAB::DSL::Rules::Triggers::Changed::ITEM_STATE_CHANGE,
-                config: { 'itemName' => timed_command_details.item.name,
-                          'previousState' => timed_command_details.command.to_s }
-              )])
-            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
-            #
-            #
-            # rubocop: disable Metrics/MethodLength
-            # rubocop: disable Metrics/AbcSize
-            # There is no feasible way to break this method into smaller components
-            def execute(_mod = nil, inputs = nil)
-              OpenHAB::DSL.import_presets
-              @semaphore.synchronize do
-                thread_local(**@thread_locals) do
-                  logger.trace "Canceling implicit timer #{@timed_command_details.timer} for " \
-                               "#{@timed_command_details.item.id}  because received event #{inputs}"
-                  @timed_command_details.timer.cancel
-                  # Disabled due to OpenHAB design
-                  $scriptExtension.get('ruleRegistry').remove(@timed_command_details.rule_uid)
-                  TimedCommand.timed_commands.delete(@timed_command_details.item)
-                  if @block
-                    logger.trace 'Executing user supplied block on timed command cancelation'
-                    @block&.call(@timed_command_details)
-                  end
+          # @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)
+            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.rules.remove(@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
+              raise if defined?(::RSpec)
+
+              logger.log_exception(e)
             end
-            # rubocop: enable Metrics/MethodLength
-            # rubocop: enable Metrics/AbcSize
           end
         end
       end
-      GenericItem.prepend(TimedCommand::GenericItem)
     end
   end
 end