openhab-scripting 4.46.2 → 5.0.0

data/lib/openhab/core/items.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require_relative "types"
+
+Dir[File.expand_path("items/*.rb", __dir__)].sort.each do |f|
+  require f
+end
+
+module OpenHAB
+  module Core
+    #
+    # Contains the core types that openHAB uses to represent items.
+    # Items have states from the {Types} module.
+    #
+    # You may use an item or group name anywhere {DSL} (or just {Core::EntityLookup})
+    # is available, and it will automatically be loaded.
+    #
+    module Items
+      class << self
+        # Imports all of the item classes into the global namespace
+        # for convenient access.
+        def import_into_global_namespace
+          concrete_item_classes.each do |k|
+            const_name = k.java_class.simple_name
+            Object.const_set(const_name, k) unless Object.const_defined?(const_name)
+          end
+          Object.const_set(:GenericItem, GenericItem) unless Object.const_defined?(:GenericItem)
+          Object.const_set(:Item, Item) unless Object.const_defined?(:Item)
+        end
+
+        private
+
+        # takes an array of Type java classes and returns
+        # all the Enum values, in a flat array
+        def values_for_enums(enums)
+          enums.map(&:ruby_class)
+               .select { |k| k < java.lang.Enum }
+               .flat_map(&:values)
+        end
+
+        # define predicates for checking if an item is in one of the Enum states
+        def def_predicate_methods(klass)
+          values_for_enums(klass.ACCEPTED_DATA_TYPES).each do |state|
+            _command_predicate, state_predicate = Types::PREDICATE_ALIASES[state.to_s]
+            next if klass.instance_methods.include?(state_predicate)
+
+            logger.trace("Defining #{klass}##{state_predicate} for #{state}")
+            klass.class_eval <<~RUBY, __FILE__, __LINE__ + 1
+              def #{state_predicate}                                                  # def on?
+                raw_state.as(#{state.class.java_class.simple_name}).equal?(#{state})  #   raw_state.as(OnOffType) == ON
+              end                                                                     # end
+            RUBY
+          end
+        end
+
+        # define methods for commanding an item to one of the Enum states
+        # as well as predicates for if an ItemCommandEvent is one of those commands
+        def def_command_methods(klass)
+          values_for_enums(klass.ACCEPTED_COMMAND_TYPES).each do |value|
+            command = Types::COMMAND_ALIASES[value.to_s]
+            next if klass.instance_methods.include?(command)
+
+            logger.trace("Defining #{klass}##{command} for #{value}")
+            klass.class_eval <<~RUBY, __FILE__, __LINE__ + 1
+              ruby2_keywords def #{command}(*args, &block)  # ruby2_keywords def on(*args, &block)
+                command(#{value}, *args, &block)            #   command(ON, *args, &block)
+              end                                           # end
+            RUBY
+
+            logger.trace("Defining Enumerable##{command} for #{value}")
+            Enumerable.class_eval <<~RUBY, __FILE__, __LINE__ + 1
+              def #{command}        # def on
+                each(&:#{command})  #   each(&:on)
+              end                   # end
+            RUBY
+
+            logger.trace("Defining ItemCommandEvent##{command}? for #{value}")
+            Events::ItemCommandEvent.class_eval <<~RUBY, __FILE__, __LINE__ + 1
+              def #{command}?                                                       # def refresh?
+                command.as(#{value.class.java_class.simple_name}).equal?(#{value})  #   command.as(RefreshType).equal?(REFRESH)
+              end                                                                   # end
+            RUBY
+          end
+        end
+
+        def concrete_item_classes
+          constants.map { |c| const_get(c) }
+                   .grep(Module)
+                   .select { |k| k < GenericItem }
+        end
+      end
+
+      # sort classes by hierarchy so we define methods on parent classes first
+      constants.map { |c| const_get(c) }
+               .grep(Module)
+               .select { |k| k <= GenericItem && k != GroupItem && k != StringItem }
+               .sort { |a, b| (a < b) ? 1 : -1 }
+               .each do |klass|
+        klass.field_reader :ACCEPTED_COMMAND_TYPES, :ACCEPTED_DATA_TYPES unless klass == GenericItem
+
+        def_predicate_methods(klass)
+        def_command_methods(klass)
+      end
+
+      prepend_accepted_data_types
+    end
+  end
+end

data/lib/openhab/{dsl → core}/lazy_array.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module OpenHAB
-  module DSL
+  module Core
     # Common base class for array-like collections that have lookup
     # methods to avoid instantiating the elements if you only use
     # the lookup method
@@ -11,6 +11,12 @@ module OpenHAB
     module LazyArray
       include Enumerable
 
+      # @!visibility private
+      def self.included(klass)
+        klass.undef_method :inspect
+        klass.undef_method :to_s
+      end
+
       # Calls the given block once for each object, passing that object as a
       # parameter. Returns self.
       #
@@ -30,14 +36,14 @@ module OpenHAB
 
       # Delegate any other methods to the actual array, exclude mutating methods
       def method_missing(method, *args, &block)
-        return to_a.send(method, *args, &block) if method[-1] != '!' && Array.instance_methods.include?(method)
+        return to_a.send(method, *args, &block) if method[-1] != "!" && Array.instance_methods.include?(method)
 
         super
       end
 
       # @!visibility private
       def respond_to_missing?(method, include_private = false)
-        return true if method[-1] != '!' && Array.instance_methods.include?(method.to_sym)
+        return true if method[-1] != "!" && Array.instance_methods.include?(method.to_sym)
 
         super
       end

data/lib/openhab/core/profile_factory.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+require "singleton"
+
+require_relative "script_handling"
+
+module OpenHAB
+  module Core
+    # @!visibility private
+    class ProfileFactory
+      include org.openhab.core.thing.profiles.ProfileFactory
+      include Singleton
+
+      # rubocop:disable Naming/MethodName
+      class Profile
+        include org.openhab.core.thing.profiles.StateProfile
+
+        def initialize(callback, context, uid, thread_locals, block)
+          unless callback.class.ancestors.include?(Things::ProfileCallback)
+            callback.class.prepend(Things::ProfileCallback)
+            callback.class.field_reader :link
+          end
+
+          @callback = callback
+          @context = context
+          @uid = uid
+          @thread_locals = thread_locals
+          @block = block
+        end
+
+        # @!visibility private
+        def getProfileTypeUID
+          @uid
+        end
+
+        # @!visibility private
+        def onCommandFromItem(command)
+          return unless process_event(:command_from_item, command: command) == true
+
+          logger.trace("Forwarding original command")
+          @callback.handle_command(command)
+        end
+
+        # @!visibility private
+        def onStateUpdateFromHandler(state)
+          return unless process_event(:state_from_handler, state: state) == true
+
+          logger.trace("Forwarding original update")
+          @callback.send_update(state)
+        end
+
+        # @!visibility private
+        def onCommandFromHandler(command)
+          return unless process_event(:command_from_handler, command: command) == true
+
+          logger.trace("Forwarding original command")
+          callback.send_command(command)
+        end
+
+        # @!visibility private
+        def onStateUpdateFromItem(state)
+          process_event(:state_from_item, state: state)
+        end
+
+        private
+
+        def process_event(event, **params)
+          logger.trace("Handling event #{event.inspect} in profile #{@uid} with param #{params.values.first.inspect}.")
+
+          params[:callback] = @callback
+          params[:context] = @context
+          params[:configuration] = @context.configuration.properties
+          params[:link] = @callback.link
+          params[:item] = @callback.link.item
+          params[:channel_uid] = @callback.link.linked_uid
+          params[:state] ||= nil
+          params[:command] ||= nil
+
+          kwargs = {}
+          @block.parameters.each do |(param_type, name)|
+            case param_type
+            when :keyreq, :key
+              kwargs[name] = params[name] if params.key?(name)
+            when :keyrest
+              kwargs = params
+            end
+          end
+
+          DSL::ThreadLocal.thread_local(**@thread_locals) do
+            @block.call(event, **kwargs)
+          rescue Exception => e
+            raise if defined?(::RSpec)
+
+            @block.binding.eval("self").logger.log_exception(e)
+          end
+        end
+      end
+      private_constant :Profile
+      # rubocop:enable Naming/MethodName
+
+      def initialize
+        @profiles = {}
+
+        @registration = OSGi.register_service(self)
+        ScriptHandling.script_unloaded { unregister }
+      end
+
+      #
+      # Unregister the ProfileFactory OSGi service
+      #
+      # @!visibility private
+      # @return [void]
+      #
+      def unregister
+        @registration.unregister
+      end
+
+      # @!visibility private
+      def register(uid, block)
+        @profiles[uid] = [DSL::ThreadLocal.persist, block]
+      end
+
+      def createProfile(type, callback, context) # rubocop:disable Naming/MethodName
+        @profiles[type].then { |(thread_locals, block)| Profile.new(callback, context, type, thread_locals, block) }
+      end
+
+      def getSupportedProfileTypeUIDs # rubocop:disable Naming/MethodName
+        @profiles.keys
+      end
+    end
+  end
+end

data/lib/openhab/core/provider.rb

@@ -0,0 +1,230 @@
+# 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.compute(element.uid) do |_k, old_element|
+          raise ArgumentError, "Element #{element.uid} already exists, and cannot be added again" if old_element
+
+          element
+        end
+        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 = nil
+        @elements.compute(element.uid) do |_k, old_element|
+          raise ArgumentError, "Element #{element.uid} does not exist to update" unless old_element
+
+          old = old_element
+          element
+        end
+        notify_listeners_about_updated_element(old, element)
+        old
+      end
+
+      # @!visibility private
+      def unregister
+        self.class.registry.remove_provider(self)
+      end
+
+      private
+
+      def initialize(unload_priority: nil)
+        super()
+        @elements = java.util.concurrent.ConcurrentHashMap.new
+        self.class.registry.add_provider(self)
+        ScriptHandling.script_unloaded(priority: unload_priority) { unregister }
+      end
+    end
+  end
+end

data/lib/openhab/core/proxy.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+require "singleton"
+require "weakref"
+
+require_relative "script_handling"
+
+module OpenHAB
+  module Core
+    #
+    # Contains the infrastructure necessary to listen for events when objects are
+    # added/removed from their registry, and keep Proxy objects up-to-date with
+    # their underlying object.
+    #
+    # The including class must meet a few requirements:
+    #  * Have an `EVENTS` constant that is an Array<String> of the events to
+    #    listen for
+    #  * The _last_ entry in the `EVENTS` array must be the "removed" event
+    #  * It must have a sibling class called `Provider`, with a `.registry`
+    #    method
+    #  * It's parent module, downcased and with trailing "s" stripped, must be
+    #    the method name to retrieve an object from one of the incoming events
+    #
+    # @!visibility private
+    #
+    module Proxy
+      #
+      # Registers and listens to openHAB bus events for objects getting
+      # added/updated/removed, and updates references from proxy objects
+      # to real objects.
+      #
+      # Proxies are tracked (via a WeakRef), and their underlying object is
+      # if it has changed.
+      #
+      class EventSubscriber
+        include Singleton
+        include org.openhab.core.events.EventSubscriber
+
+        def initialize
+          @proxies = java.util.concurrent.ConcurrentHashMap.new
+          @parent_module = Object.const_get(self.class.name.split("::")[0..-3].join("::"), false)
+          @object_type = @parent_module.name.split("::").last.downcase[0..-2].to_sym
+
+          @event_types = @parent_module::Proxy::EVENTS
+          @uid_method = @parent_module::Proxy::UID_METHOD
+          @registry = @parent_module::Provider.registry
+          @registration = OSGi.register_service(self, "event.topics": "openhab/*")
+          ScriptHandling.script_unloaded { @registration.unregister }
+        end
+
+        #
+        # @!attribute [r] subscribed_event_types
+        # @return [Set<String>]
+        #
+        def subscribed_event_types
+          @event_types.to_set
+        end
+
+        # @return [org.openhab.core.events.EventFilter, nil]
+        def event_filter
+          nil
+        end
+
+        #
+        # @param [Events::AbstractEvent] event
+        # @return [void]
+        #
+        def receive(event)
+          uid = event.__send__(@object_type).__send__(@uid_method)
+          object = @registry.get(uid) unless event.class.simple_name == @event_types.last
+
+          @proxies.compute_if_present(uid) do |_, proxy_ref|
+            proxy = resolve_ref(proxy_ref)
+            next nil unless proxy
+
+            proxy.__setobj__(object)
+            proxy_ref
+          end
+        end
+
+        #
+        # Get or create a Proxy for the given raw openHAB object.
+        #
+        def fetch(object)
+          result = nil
+
+          @proxies.compute(object.__send__(@uid_method)) do |_k, proxy_ref|
+            result = resolve_ref(proxy_ref)
+            proxy_ref = nil unless result
+            result ||= yield
+
+            proxy_ref || WeakRef.new(result)
+          end
+
+          result
+        end
+
+        private
+
+        def resolve_ref(proxy_ref)
+          proxy_ref.__getobj__ if proxy_ref&.weakref_alive?
+        rescue WeakRef::RefError
+          nil
+        end
+      end
+
+      # @!visibility private
+      module ClassMethods
+        # Intercepts calls to create new proxies, and returns the already
+        # existing (and tracked) proxy if it exists. Otherwise it does create
+        # a new instance of Proxy.
+        def new(object)
+          self::EventSubscriber.instance.fetch(object) { super }
+        end
+      end
+
+      # @!visibility private
+      def self.included(klass)
+        klass.singleton_class.prepend(ClassMethods)
+        # define a sub-class of EventSubscriber as a child class of the including class
+        klass.const_set(:EventSubscriber, Class.new(EventSubscriber))
+      end
+
+      # @!visibility private
+      def to_java
+        __getobj__
+      end
+    end
+  end
+end

data/lib/openhab/core/registry.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module OpenHAB
+  module Core
+    Registry = org.openhab.core.common.registry.AbstractRegistry
+
+    Registry.field_reader :elementToProvider, :elementReadLock, :identifierToElement, :providerToElements
+
+    # @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
+        if key.is_a?(org.openhab.core.common.registry.Identifiable)
+          element = key
+        else
+          return nil unless (element = identifierToElement[key])
+        end
+
+        elementToProvider[element]
+      ensure
+        elementReadLock.unlock
+      end
+
+      # @!attribute [r] providers
+      # @return [Enumerable<org.openhab.core.common.registry.Provider>]
+      def providers
+        providerToElements.keys
+      end
+    end
+  end
+end