openhab-jrubyscripting 5.0.0.rc1 → 5.0.0.rc3

data/lib/openhab/core/provider.rb

@@ -0,0 +1,223 @@
+# frozen_string_literal: true
+
+require "singleton"
+
+module OpenHAB
+  module Core
+    # @interface
+    java_import org.openhab.core.common.registry.ManagedProvider
+
+    # @!visibility private
+    module ManagedProvider
+      # Maps actual element types to the symbol used in Thread.local[:openhab_providers]
+      TYPE_TO_PROVIDER_TYPE = {
+        org.openhab.core.items.Item.java_class => :items,
+        org.openhab.core.items.Metadata.java_class => :metadata,
+        org.openhab.core.automation.Rule.java_class => :rules,
+        org.openhab.core.thing.Thing.java_class => :things,
+        org.openhab.core.thing.link.ItemChannelLink.java_class => :links
+      }.freeze
+      private_constant :TYPE_TO_PROVIDER_TYPE
+
+      # @return [Symbol, nil]
+      def type
+        java_class.generic_ancestors.each do |klass|
+          next unless klass.respond_to?(:raw_type)
+          next unless klass.raw_type == org.openhab.core.common.registry.Provider.java_class
+
+          type_arg = klass.actual_type_arguments.first
+          next unless type_arg.is_a?(java.lang.Class)
+          next unless klass.actual_type_arguments.first.is_a?(java.lang.Class)
+
+          return TYPE_TO_PROVIDER_TYPE[type_arg]
+        end
+        nil
+      end
+    end
+
+    # @abstract
+    class Provider < org.openhab.core.common.registry.AbstractProvider
+      include org.openhab.core.common.registry.ManagedProvider
+      include Enumerable
+      include Singleton
+      public_class_method :new
+
+      # Known supported provider types
+      # @return [Array<Symbol>]
+      KNOWN_TYPES = %i[items metadata things links].freeze
+
+      class << self
+        #
+        # Determines the current provider that should be used to create elements belonging to this registry.
+        #
+        # @param [org.openhab.core.common.registry.Provider, Proc, :persistent, :transient, nil] preferred_provider
+        #   An optional preferred provider to use. Can be one of several types:
+        #    * An explicit instance of {org.openhab.core.common.registry.ManagedProvider ManagedProvider}
+        #    * A Proc, which can calculate the preferred provider based on whatever conditions it wants,
+        #      and then is further processed as this parameter.
+        #    * `:persistent`, meaning the default {org.openhab.core.common.registry.ManagedProvider ManagedProvider}
+        #      for this registry. Managed providers persist their objects to JSON, and will survive after the
+        #      Ruby script is unloaded. This is where objects you configure with MainUI are stored. You should
+        #      use this provider when you're creating something in response to a one-time event.
+        #    * `:transient`, meaning a {org.openhab.core.common.registry.ManagedProvider ManagedProvider} that
+        #      will remove all of its contents when the Ruby script is unloaded. You should use this if you're
+        #      generating objects dynamically, either based on some sort of other configuration, or simply
+        #      hard coded and you're using Ruby as a more expressive way to define things than a `.items` or
+        #      `.things` file. If you _don't_ use this provider for something such as metadata, then you
+        #      may have issues such as metadata still showing up even though you're no longer creating items
+        #      with it anymore.
+        #    * `nil`, meaning to fall back to the current thread setting. See {OpenHAB::DSL.provider}.
+        #      If there is no thread setting (or the thread setting was Proc that returned `nil`),
+        #      it defaults to `:transient`.
+        # @return [org.openhab.core.common.registry.Provider]
+        #
+        def current(preferred_provider = nil, element = nil)
+          preferred_provider ||= Thread.current[:openhab_providers]&.[](type)
+          if preferred_provider.is_a?(Proc)
+            preferred_provider = if preferred_provider.arity.zero? || element.nil?
+                                   preferred_provider.call
+                                 else
+                                   preferred_provider.call(element)
+                                 end
+          end
+
+          case preferred_provider
+          when nil, :transient
+            instance
+          when :persistent
+            registry.managed_provider.get
+          when org.openhab.core.common.registry.ManagedProvider
+            preferred_provider
+          else
+            raise ArgumentError, "#{preferred_provider.inspect} is not a ManagedProvider"
+          end
+        end
+
+        # @abstract
+        # @!attribute [r] registry
+        #
+        # The registry that this provider provides elements for.
+        #
+        # @return [org.openhab.core.common.registry.Registry]
+        #
+        def registry
+          raise NotImplementedError
+        end
+
+        #
+        # Creates a new instance of a provider, registers it, sets it as the
+        # default for the thread, calls the block, and then unregisters it.
+        #
+        # @param [true, false] thread_provider Set this new provider as the default for the thread
+        # @yieldparam [Provider] provider The provider
+        # @return [Object] The result of the block
+        #
+        # @!visibility private
+        def new(thread_provider: true)
+          unless @singleton__instance__.nil? || block_given?
+            raise NoMethodError,
+                  "private method `new' called for #{self}:Class"
+          end
+
+          r = provider = super()
+          if block_given?
+            if thread_provider
+              DSL.provider(provider) do
+                r = yield provider
+              end
+            else
+              r = yield provider
+            end
+            provider.unregister
+          end
+          r
+        end
+
+        # @!attribute [r] type
+        # @!visibility private
+        # @return [Symbol]
+        #
+        def type
+          name.split("::")[-2].downcase.to_sym
+        end
+      end
+
+      # @!visibility private
+      def each(&block)
+        @elements.each_value(&block)
+      end
+
+      # @return [String]
+      def inspect
+        "#<#{self.class.name}:#{object_id}>"
+      end
+
+      # @!visibility private
+      def add(element)
+        @elements[element.uid] = element
+        notify_listeners_about_added_element(element)
+        element
+      end
+
+      #
+      # Get an element from this provider
+      #
+      # @param [Object] key The proper key type for the elements in this provider.
+      # @return [Object]
+      #
+      def [](key)
+        @elements[key]
+      end
+      alias_method :get, :[]
+
+      #
+      # Get all elements in this provider
+      #
+      # @return [Array<Object>]
+      #
+      def all
+        @elements.values
+      end
+      alias_method :getAll, :all
+
+      #
+      # Remove an element from this provider
+      #
+      # @return [Object, nil] the removed element
+      #
+      # @!visibility private
+      #
+      def remove(key)
+        @elements.delete(key)&.tap do |element|
+          notify_listeners_about_removed_element(element)
+        end
+      end
+
+      # @return [Object, nil] the previous version of the element
+      # @!visibility private
+      #
+      def update(element)
+        old_element = @elements[element.uid]
+        if old_element
+          @elements[element.uid] = element
+          notify_listeners_about_updated_element(old_element, element)
+        end
+        old_element
+      end
+
+      # @!visibility private
+      def unregister
+        self.class.registry.remove_provider(self)
+      end
+
+      private
+
+      def initialize
+        super
+        @elements = {}
+        self.class.registry.add_provider(self)
+        ScriptHandling.script_unloaded { unregister }
+      end
+    end
+  end
+end

data/lib/openhab/core/registry.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module OpenHAB
+  module Core
+    Registry = org.openhab.core.common.registry.AbstractRegistry
+
+    Registry.field_reader :elementToProvider, :elementReadLock, :identifierToElement
+
+    # @abstract
+    #
+    # The base class for all registries in openHAB.
+    #
+    class Registry
+      #
+      # Determines which provider an element is associated with.
+      #
+      # @param [Object] key
+      # @return [org.openhab.core.common.registry.Provider]
+      #
+      def provider_for(key)
+        elementReadLock.lock
+        return nil unless (element = identifierToElement[key])
+
+        elementToProvider[element]
+      ensure
+        elementReadLock.unlock
+      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(&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] rule_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

@@ -2,6 +2,56 @@
 
 module OpenHAB
   module Core
+    #
+    # Provide callback mechanisms for script handling
+    #
+    module ScriptHandling
+      module_function
+
+      #
+      # 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)
+        Core::ScriptHandlingCallbacks.script_loaded_hooks << block
+      end
+
+      #
+      # 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.
+      #
+      # @return [void]
+      #
+      # @example
+      #   script_unloaded do
+      #     logger.info 'Hi, this script has been unloaded'
+      #   end
+      #
+      def script_unloaded(&block)
+        Core::ScriptHandlingCallbacks.script_unloaded_hooks << block
+      end
+    end
+
     #
     # Manages script loading and unloading
     #

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

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module OpenHAB
+  module Core
+    module Things
+      #
+      # Contains the link between a {Thing Thing's} {Channel Channels} and {GenericItem Items}.
+      #
+      module Links
+        #
+        # Provides {Items::GenericItem 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.ItemChanneLinkRegistry]
+            #
+            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
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module OpenHAB
+  module Core
+    module Things
+      #
+      # Provides {Thing Things} created in Ruby to openHAB
+      #
+      class Provider < Core::Provider
+        include org.openhab.core.thing.ThingProvider
+
+        class << self
+          #
+          # The Thing registry
+          #
+          # @return [org.openhab.core.thing.ThingRegistry]
+          #
+          def registry
+            $things
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -63,6 +63,16 @@ module OpenHAB
 
           super
         end
+
+        #
+        # Non equality comparison
+        #
+        # @return [true, false]
+        #
+        # @!visibility private
+        def !=(other)
+          !(self == other) # rubocop:disable Style/InverseMethods
+        end
       end
     end
   end