openhab-scripting 4.47.0 → 5.0.0

data/lib/openhab/core/rules/module.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module OpenHAB
+  module Core
+    module Rules
+      # @interface
+      java_import org.openhab.core.automation.Module
+
+      # @!visibility private
+      module Module
+        # @return [String]
+        def inspect
+          r = "#<OpenHAB::Core::Rules::#{self.class.simple_name} #{id} (#{type_uid})"
+          r += " #{label.inspect}" if label
+          r += " configuration=#{configuration.properties.to_h}" unless configuration.properties.empty?
+          "#{r}>"
+        end
+
+        # @return [String]
+        def to_s
+          id
+        end
+      end
+    end
+  end
+end

data/lib/openhab/core/rules/provider.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module OpenHAB
+  module Core
+    module Rules
+      #
+      # Provides rules created in Ruby to openHAB
+      #
+      class Provider < Core::Provider
+        include org.openhab.core.automation.RuleProvider
+
+        class << self
+          #
+          # The Rule registry
+          #
+          # @return [org.openhab.core.automation.RuleRegistry]
+          #
+          def registry
+            $rules
+          end
+        end
+      end
+    end
+  end
+end

data/lib/openhab/core/rules/registry.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require "singleton"
+
+module OpenHAB
+  module Core
+    module Rules
+      #
+      # Provides access to all openHAB {Rule rules}, and acts like an array.
+      #
+      class Registry
+        include LazyArray
+        include Singleton
+
+        #
+        # Gets a specific Rule
+        #
+        # @param [String] uid Rule UID
+        # @return [Rule, nil]
+        #
+        def [](uid)
+          $rules.get(uid)
+        end
+        alias_method :include?, :[]
+        alias_method :key?, :[]
+        # @deprecated
+        alias_method :has_key?, :[]
+
+        #
+        # Explicit conversion to array
+        #
+        # @return [Array<Rule>]
+        #
+        def to_a
+          $rules.all.to_a
+        end
+
+        #
+        # Enter the Rule Builder DSL.
+        # @param (see Core::Provider.current)
+        # @yield Block executed in the context of a {DSL::Rules::Builder}.
+        # @return [Object] The result of the block.
+        #
+        def build(preferred_provider = nil, &block)
+          DSL::Rules::Builder.new(preferred_provider).instance_eval_with_dummy_items(&block)
+        end
+
+        #
+        # Remove a Rule.
+        #
+        # The rule must be a managed thing (typically created by Ruby or in the UI).
+        #
+        # @param [String, Rule] rule_uid
+        # @return [Rule, nil] The removed rule, if found.
+        #
+        # @example
+        #   my_rule = rule do
+        #     every :day
+        #     run { nil }
+        #   end
+        #
+        #   rules.remove(my_rule)
+        #
+        def remove(rule_uid)
+          rule_uid = rule_uid.uid if rule_uid.is_a?(Rule)
+          provider = Provider.registry.provider_for(rule_uid)
+          unless provider.is_a?(org.openhab.core.common.registry.ManagedProvider)
+            raise "Cannot remove rule #{rule_uid} from non-managed provider #{provider.inspect}"
+          end
+
+          provider.remove(rule_uid)
+        end
+      end
+    end
+  end
+end

data/lib/openhab/core/rules/rule.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+module OpenHAB
+  module Core
+    module Rules
+      # @interface
+      java_import org.openhab.core.automation.Rule
+
+      #
+      # A {Rule} is a chunk of code that can execute when certain conditions are
+      # met, enabling the core dynamic functionality of openHAB.
+      #
+      module Rule
+        #
+        # @!method visible?
+        #   Check if visibility == `VISIBLE`
+        #   @return [true,false]
+        #
+
+        #
+        # @!method hidden?
+        #   Check if visibility == `HIDDEN`
+        #   @return [true,false]
+        #
+
+        #
+        # @!method expert?
+        #   Check if visibility == `EXPERT`
+        #   @return [true,false]
+        #
+
+        #
+        # @!method initializing?
+        #   Check if rule status == `INITIALIZING`
+        #   @return [true,false]
+        #
+        #
+        # @!method idle?
+        #   Check if rule status == `IDLE`
+        #   @return [true,false]
+        #
+        #
+        # @!method running?
+        #   Check if rule status == `RUNNING`
+        #   @return [true,false]
+        #
+
+        Visibility.constants.each do |visibility|
+          class_eval <<~RUBY, __FILE__, __LINE__ + 1
+            def #{visibility.to_s.downcase}?           # def visibile?
+              visibility == Visibility::#{visibility}  #   visibility == Visibility::VISIBLE
+            end                                        # end
+          RUBY
+        end
+
+        RuleStatus.constants.each do |status|
+          next if status == :UNINITIALIZED
+
+          class_eval <<~RUBY, __FILE__, __LINE__ + 1
+            def #{status.to_s.downcase}?       # def initializing?
+              status == RuleStatus::#{status}  #   status == RuleStatus::INITIALIZING
+            end                                # end
+          RUBY
+        end
+
+        #
+        # Check if rule status == `UNINITIALIZED`
+        #
+        # @return [true,false]
+        #
+        def uninitialized?
+          s = status
+          s.nil? || s == RuleStatus::UNINITIALIZED
+        end
+
+        #
+        # Enable the Rule
+        #
+        # @param [true, false] enabled
+        # @return [void]
+        #
+        def enable(enabled: true)
+          Rules.manager.set_enabled(uid, enabled)
+        end
+
+        #
+        # Disable the Rule
+        #
+        # @return [void]
+        #
+        def disable
+          enable(enabled: false)
+        end
+
+        #
+        # Check if the rule's status detail == `DISABLED`
+        #
+        # @return [true, false]
+        #
+        def disabled?
+          info = status_info
+          info.nil? || info.status_detail == RuleStatusDetail::DISABLED
+        end
+
+        #
+        # @!attribute [r] status
+        # @return [RuleStatus nil]
+        #
+        def status
+          Rules.manager.get_status(uid)
+        end
+
+        #
+        # @!attribute [r] status_info
+        # @return [RuleStatusInfo, nil]
+        #
+        def status_info
+          Rules.manager.get_status_info(uid)
+        end
+
+        # @return [String]
+        def inspect
+          r = "#<OpenHAB::Core::Rules::Rule #{uid}"
+          r += " #{name.inspect}" if name
+          r += " #{visibility}" unless visible?
+          r += " #{status || "<detached>"}"
+          r += " (#{status_info.status_detail})" if status_info && status_info.status_detail != RuleStatusDetail::NONE
+          r += " tags=#{tags.to_a.inspect}" unless tags.empty?
+          r += " configuration=#{configuration.properties.to_h}" if configuration && !configuration.properties.empty?
+          "#{r}>"
+        end
+
+        # @return [String]
+        def to_s
+          uid
+        end
+
+        #
+        # Manually trigger the rule
+        #
+        # @param [Object, nil] event The event to pass to the rule's execution blocks.
+        # @return [void]
+        #
+        def trigger(event = nil)
+          Rules.manager.run_now(uid, false, { "event" => event })
+        end
+      end
+    end
+  end
+end

data/lib/openhab/core/rules.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module OpenHAB
+  module Core
+    #
+    # Contains the core {Rule} as well as related infrastructure.
+    #
+    module Rules
+      java_import org.openhab.core.automation.RuleStatus,
+                  org.openhab.core.automation.RuleStatusInfo,
+                  org.openhab.core.automation.RuleStatusDetail,
+                  org.openhab.core.automation.Visibility
+
+      class << self
+        #
+        # @!attribute [r] manager
+        # @return [org.openhab.core.automation.RuleManager] The openHAB rule manager/engine
+        #
+        def manager
+          @manager ||= OSGi.service("org.openhab.core.automation.RuleManager")
+        end
+      end
+    end
+  end
+end

data/lib/openhab/core/script_handling.rb

@@ -1,8 +1,5 @@
 # frozen_string_literal: true
 
-require 'openhab/log/logger'
-
-# OpenHAB main module
 module OpenHAB
   module Core
     #
@@ -11,24 +8,67 @@ module OpenHAB
     module ScriptHandling
       module_function
 
-      # Add a callback to be run when the script has been fully loaded
+      #
+      # Add a block of code to be executed once the rule script has finished loading.
+      #
+      # This can occur on openHAB start up, when the script is first created, or updated.
+      #
+      # Multiple hooks can be added by calling {#script_loaded} multiple times.
+      # They can be used to perform final initializations.
+      #
+      # @return [void]
+      #
+      # @example
+      #   script_loaded do
+      #     logger.info 'Hi, this script has just finished loading'
+      #   end
+      #
+      # @example
+      #   script_loaded do
+      #     logger.info 'I will be called after the script finished loading too'
+      #   end
+      #
       def script_loaded(&block)
         ScriptHandlingCallbacks.script_loaded_hooks << block
       end
 
-      # Add a callback to be run when the script is unloaded
-      def script_unloaded(&block)
-        ScriptHandlingCallbacks.script_unloaded_hooks << block
+      #
+      # Add a block of code to be executed when the script is unloaded.
+      #
+      # This can occur when openHAB shuts down, or when the script is being reloaded.
+      #
+      # Multiple hooks can be added by calling {#script_unloaded} multiple times.
+      # They can be used to perform final cleanup.
+      #
+      # @param [Integer, nil] priority The order at which the the given hook will be executed.
+      #   The higher the number, the lower the priority. Higher priority hooks will be executed
+      #   first, before the lower priority hooks. When nil, the default priority of zero will
+      #   be used.
+      # @return [void]
+      #
+      # @example
+      #   script_unloaded do
+      #     logger.info 'Hi, this script has been unloaded'
+      #   end
+      #
+      def script_unloaded(priority: nil, &block)
+        ScriptHandlingCallbacks.script_unloaded_hooks[priority || 0] << block
       end
     end
 
     #
     # Manages script loading and unloading
     #
+    # @!visibility private
     module ScriptHandlingCallbacks
-      include OpenHAB::Log
-
       class << self
+        #
+        # Has the script completed loading?
+        #
+        # @!visibility private
+        # @return [true, false]
+        attr_accessor :script_loaded
+
         #
         # Return script_loaded_hooks
         #
@@ -42,35 +82,53 @@ module OpenHAB
         #
         # @!visibility private
         def script_unloaded_hooks
-          @script_unloaded_hooks ||= []
+          @script_unloaded_hooks ||= Hash.new { |hash, key| hash[key] = [] }
         end
       end
+      self.script_loaded = false
 
       #
-      # Executed when OpenHAB unloads a script file
+      # Executed when openHAB unloads a script file
       #
-      # @!visibility private
-      def scriptUnloaded # rubocop:disable Naming/MethodName method name dictated by OpenHAB
-        logger.trace('Script unloaded')
-        ScriptHandlingCallbacks.script_unloaded_hooks.each do |hook|
+      def scriptUnloaded # rubocop:disable Naming/MethodName method name dictated by openHAB
+        logger.trace("Script unloaded")
+        ScriptHandlingCallbacks.script_unloaded_hooks.sort_by(&:first).flat_map(&:last).each do |hook|
           hook.call
-        rescue StandardError => e
+        rescue => e
           logger.error("Failed to call script_unloaded hook #{hook}: #{e}")
         end
+
+        return if ScriptHandlingCallbacks.script_loaded
+
+        # Make sure we terminate the main thread if it's still set up, in case
+        # it's timing out and that's why we're unloading.
+        #
+        # It would seem simpler to just record Thread.current when this file
+        # loads, but if the user is using the autorequire feature of the
+        # jrubyscripting addon, this file will load before the main script.
+        #
+        # Note that Thread.list only includes threads that have had Ruby
+        # execute in them, so we don't need to worry about accidentally killing
+        # a random Java thread.
+        #
+        main_thread = Thread.list.find { |t| t != Thread.current && t.name.include?("-safeCall-") }
+        main_thread&.raise(Interrupt.new)
       end
 
       #
-      # Executed when OpenHAB loads a script file
+      # Executed when openHAB loads a script file
       #
-      # @!visibility private
-      def scriptLoaded(filename) # rubocop:disable Naming/MethodName method name dictated by OpenHAB
+      def scriptLoaded(filename) # rubocop:disable Naming/MethodName method name dictated by openHAB
         logger.trace("Script loaded: #{filename}")
         ScriptHandlingCallbacks.script_loaded_hooks.each do |hook|
           hook.call
-        rescue StandardError => e
+        rescue => e
           logger.error("Failed to call script_loaded hook #{hook}: #{e}")
         end
+        ScriptHandlingCallbacks.script_loaded = true
       end
     end
   end
 end
+
+singleton_class.include(OpenHAB::Core::ScriptHandlingCallbacks)

data/lib/openhab/core/things/channel.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require "forwardable"
+
+module OpenHAB
+  module Core
+    module Things
+      java_import org.openhab.core.thing.Channel
+
+      #
+      # {Channel} is a part of a {Thing} that represents a functionality of it.
+      # Therefore {Item Items} can be linked a to a channel.
+      #
+      # @!attribute [r] item
+      #   (see ChannelUID#item)
+      #
+      # @!attribute [r] items
+      #   (see ChannelUID#items)
+      #
+      # @!attribute [r] thing
+      #   (see ChannelUID#thing)
+      #
+      # @!attribute [r] uid
+      #   @return [ChannelUID]
+      #
+      class Channel
+        extend Forwardable
+
+        delegate %i[item items thing] => :uid
+
+        # @return [String]
+        def inspect
+          r = "#<OpenHAB::Core::Things::Channel #{uid}"
+          r += " #{label.inspect}" if label
+          r += " auto_update_policy=#{auto_update_policy}" if auto_update_policy
+          r += " configuration=#{configuration.properties.to_h}" unless configuration.properties.empty?
+          r += " properties=#{properties.to_h}" unless properties.empty?
+          "#{r}>"
+        end
+
+        # @return [String]
+        def to_s
+          uid.to_s
+        end
+      end
+    end
+  end
+end

data/lib/openhab/core/things/channel_uid.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require "forwardable"
+
+module OpenHAB
+  module Core
+    module Things
+      java_import org.openhab.core.thing.ChannelUID
+
+      #
+      # {ChannelUID} represents a unique identifier for {Channel channels}.
+      #
+      class ChannelUID
+        #
+        # @attribute [r] thing
+        #
+        # Return the thing this channel is associated with.
+        #
+        # @return [Thing, nil]
+        #
+        def thing
+          EntityLookup.lookup_thing(thing_uid)
+        end
+
+        #
+        # @attribute [r] item
+        #
+        # Return the item if this channel is linked with an item. If a channel is linked to more than one item,
+        # this method only returns the first item.
+        #
+        # @return [Item, nil]
+        #
+        def item
+          items.first
+        end
+
+        #
+        # @attribute [r] items
+        #
+        # Returns all of the channel's linked items.
+        #
+        # @return [Array<Item>] An array of things or an empty array
+        #
+        def items
+          registry = OSGi.service("org.openhab.core.thing.link.ItemChannelLinkRegistry")
+          registry.get_linked_items(self).map { |i| Items::Proxy.new(i) }
+        end
+      end
+    end
+  end
+end

data/lib/openhab/core/things/item_channel_link.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module OpenHAB
+  module Core
+    module Things
+      java_import org.openhab.core.thing.link.ItemChannelLink
+
+      #
+      # Represents the link between an {Item} and a {Thing Thing's}
+      # {Channel}.
+      #
+      # @!attribute [r] thing
+      #   @return [Thing]
+      #
+      # @!attribute [r] channel_uid
+      #   @return [ChannelUID]
+      #
+      class ItemChannelLink
+        extend Forwardable
+
+        def_delegator :linked_uid, :thing
+
+        # @!attribute [r] item
+        # @return [Item]
+        def item
+          DSL.items[item_name]
+        end
+
+        alias_method :channel_uid, :linked_uid
+      end
+    end
+  end
+end

data/lib/openhab/core/things/links/provider.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module OpenHAB
+  module Core
+    module Things
+      #
+      # Contains the link between a {Thing Thing's} {Channel Channels} and {Item Items}.
+      #
+      module Links
+        #
+        # Provides {Items::Item items} linked to {Channel channels} in Ruby to openHAB.
+        #
+        class Provider < Core::Provider
+          include org.openhab.core.thing.link.ItemChannelLinkProvider
+
+          class << self
+            #
+            # The ItemChannelLink registry
+            #
+            # @return [org.openhab.core.thing.link.ItemChannelLinkRegistry]
+            #
+            def registry
+              @registry ||= OSGi.service("org.openhab.core.thing.link.ItemChannelLinkRegistry")
+            end
+
+            # @!visibility private
+            def link(item, channel, config = {})
+              config = org.openhab.core.config.core.Configuration.new(config.transform_keys(&:to_s))
+              channel = ChannelUID.new(channel) if channel.is_a?(String)
+              channel = channel.uid if channel.is_a?(Channel)
+              link = org.openhab.core.thing.link.ItemChannelLink.new(item.name, channel, config)
+
+              current.add(link)
+            end
+          end
+
+          #
+          # Removes all links to a given item.
+          #
+          # @param [String] item_name
+          # @return [Integer] how many links were removed
+          #
+          def remove_links_for_item(item_name)
+            count = 0
+            @elements.delete_if do |_k, v|
+              next unless v.item_name == item_name
+
+              count += 1
+              notify_listeners_about_removed_element(v)
+              true
+            end
+            count
+          end
+          alias_method :removeLinksForItem, :remove_links_for_item
+
+          #
+          # Removes all links to a given thing.
+          #
+          # @param [ThingUID] thing_uid
+          # @return [Integer] how many links were removed
+          #
+          def remove_links_for_thing(thing_uid)
+            count = 0
+            @elements.delete_if do |_k, v|
+              next unless v.linked_uid.thing_uid == thing_uid
+
+              count += 1
+              notify_listeners_about_removed_element(v)
+              true
+            end
+            count
+          end
+          alias_method :removeLinksForThing, :remove_links_for_thing
+        end
+      end
+    end
+  end
+end