openhab-scripting 4.46.2 → 5.0.0

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

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module OpenHAB
+  module Core
+    module Things
+      #
+      # Contains methods for {OpenHAB::DSL.profile profile}'s callback to forward commands between items
+      # and channels.
+      #
+      module ProfileCallback
+        class << self
+          #
+          # Wraps the parent class's method to format non-Types.
+          #
+          # @!macro def_state_parsing_method
+          #   @!method $1($2)
+          #   @return [void]
+          # @!visibility private
+          def def_state_parsing_method(method, param_name)
+            class_eval <<~RUBY, __FILE__, __LINE__ + 1
+              def #{method}(type)                                                             # def handle_command(type)
+                type = link.item.format_#{(param_name == :state) ? :update : param_name}(type)  #   type = link.item.format_command(type)
+                super(type)                                                                   #   super(type)
+              end                                                                             # end
+            RUBY
+          end
+        end
+
+        #
+        # Forward the given command to the respective thing handler.
+        #
+        # @param [Command] command
+        #
+        def_state_parsing_method(:handle_command, :command)
+
+        #
+        # Send a command to the framework.
+        #
+        # @param [Command] command
+        #
+        def_state_parsing_method(:send_command, :command)
+
+        #
+        # Send a state update to the framework.
+        #
+        # @param [State] state
+        #
+        def_state_parsing_method(:send_update, :state)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,29 @@
+# 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
+
+        def initialize
+          super(unload_priority: 60)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require "delegate"
+require "forwardable"
+
+module OpenHAB
+  module Core
+    module Things
+      # Class is a proxy to underlying thing
+      # @!visibility private
+      class Proxy < Delegator
+        extend Forwardable
+        def_delegators :__getobj__, :class, :is_a?, :kind_of?
+
+        # @!visibility private
+        EVENTS = [Events::ThingAddedEvent::TYPE, Events::ThingUpdatedEvent::TYPE,
+                  Events::ThingRemovedEvent::TYPE].freeze
+        # @!visibility private
+        UID_METHOD = :uid
+
+        include Core::Proxy
+
+        # Returns the list of channels associated with this Thing
+        #
+        # @note This is defined on this class, and not on {Thing}, because
+        #   that's the interface and if you define it there, it will be hidden
+        #   by the method on ThingImpl.
+        #
+        # @return [Array] channels
+        def channels
+          Thing::ChannelsArray.new(super.to_a)
+        end
+
+        #
+        # Set the proxy item (called by super)
+        #
+        def __setobj__(thing)
+          @uid = thing.uid
+        end
+
+        #
+        # Lookup thing from thing registry
+        #
+        def __getobj__
+          $things.get(@uid)
+        end
+
+        #
+        # Need to check if `self` _or_ the delegate is an instance of the
+        # given class
+        #
+        # So that {#==} can work
+        #
+        # @return [true, false]
+        #
+        # @!visibility private
+        def instance_of?(klass)
+          __getobj__.instance_of?(klass) || super
+        end
+
+        #
+        # Check if delegates are equal for comparison
+        #
+        # Otherwise items can't be used in Java maps
+        #
+        # @return [true, false]
+        #
+        # @!visibility private
+        def ==(other)
+          return __getobj__ == other.__getobj__ if other.instance_of?(Proxy)
+
+          super
+        end
+
+        #
+        # Non equality comparison
+        #
+        # @return [true, false]
+        #
+        # @!visibility private
+        def !=(other)
+          !(self == other) # rubocop:disable Style/InverseMethods
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require "singleton"
+
+module OpenHAB
+  module Core
+    module Things
+      #
+      # Provides access to all openHAB {Thing things}, and acts like an array.
+      #
+      class Registry
+        include LazyArray
+        include Singleton
+
+        #
+        # Gets a specific {Thing}
+        #
+        # @param [String, ThingUID] uid Thing UID in the format `binding_id:type_id:thing_id`
+        #   or via the ThingUID
+        # @return [Thing, nil]
+        #
+        def [](uid)
+          EntityLookup.lookup_thing(uid)
+        end
+        alias_method :include?, :[]
+        alias_method :key?, :[]
+        # @deprecated
+        alias_method :has_key?, :[]
+
+        #
+        # Explicit conversion to array
+        #
+        # @return [Array<Thing>]
+        #
+        def to_a
+          $things.all.map { |thing| Proxy.new(thing) }
+        end
+
+        #
+        # Enter the Thing Builder DSL.
+        # @param (see Core::Provider.current)
+        # @yield Block executed in the context of a {DSL::Things::Builder}.
+        # @return [Object] The result of the block.
+        #
+        def build(preferred_provider = nil, &block)
+          DSL::Things::Builder.new(preferred_provider).instance_eval(&block)
+        end
+
+        #
+        # Remove a Thing.
+        #
+        # The thing must be a managed thing (typically created by Ruby or in the UI).
+        #
+        # @param [String, Thing, ThingUID] thing_uid
+        # @return [Thing, nil] The removed item, if found.
+        def remove(thing_uid)
+          thing_uid = thing.uid if thing_uid.is_a?(Thing)
+          thing_uid = ThingUID.new(thing_uid) if thing_uid.is_a?(String)
+          provider = Provider.registry.provider_for(thing_uid)
+          unless provider.is_a?(org.openhab.core.common.registry.ManagedProvider)
+            raise "Cannot remove thing #{thing_uid} from non-managed provider #{provider.inspect}"
+          end
+
+          Links::Provider.registry.providers.grep(ManagedProvider).each do |managed_provider|
+            managed_provider.remove_links_for_thing(thing_uid)
+          end
+
+          provider.remove(thing_uid)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,194 @@
+# frozen_string_literal: true
+
+module OpenHAB
+  module Core
+    module Things
+      # @interface
+      java_import org.openhab.core.thing.Thing
+
+      #
+      # A {Thing} is a representation of a connected part (e.g. physical device
+      # or cloud service) from the real world. It contains a list of
+      # {Channel Channels}, which can be bound to {Item Items}.
+      #
+      # @see OpenHAB::DSL.things things[]
+      # @see EntityLookup
+      #
+      # @example
+      #   thing = things["chromecast:audiogroup:dd9f8622-eee-4eaf-b33f-cdcdcdeee001121"]
+      #   logger.info("Audiogroup Status: #{thing&.status}")
+      #   logger.info("Audiogroup Online? #{thing&.online?}")
+      #   logger.info("Channel ids: #{thing.channels.map(&:uid)}")
+      #   logger.info("Items linked to volume channel: #{thing.channels['volume']&.items&.map(&:name)&.join(', ')}")
+      #   logger.info("Item linked to volume channel: #{thing.channels['volume']&.item&.name}")
+      #
+      # @example Thing actions can be called directly through a Thing object
+      #   things["mqtt:broker:mosquitto"].publish_mqtt("zigbee2mqttt/bridge/config/permit_join", "true")
+      #   things["mail:smtp:local"].send_mail("me@example.com", "Subject", "Email body")
+      #
+      # @example Thing can be accessed directly through {EntityLookup entity lookup}
+      #   # replace ':' with '_' in thing uid
+      #   mqtt_broker_mosquitto.online? # is mqtt:broker:mosquitto thing online?
+      #
+      # @!attribute [r] status
+      #   Return the {https://www.openhab.org/docs/concepts/things.html#thing-status thing status}
+      #   @return [org.openhab.core.thing.ThingStatus]
+      #
+      # @!attribute [r] channels
+      #   @return [ChannelArray]
+      #
+      module Thing
+        # Array wrapper class to allow searching a list of channels
+        # by channel id
+        class ChannelsArray < Array
+          # Allows indexing by both integer as an array or channel id acting like a hash.
+          # @param [Integer, String] index Numeric index or string channel id to search for.
+          def [](index)
+            if index.respond_to?(:to_str)
+              key = index.to_str
+              return find { |channel| channel.uid.id == key }
+            end
+
+            super
+          end
+        end
+
+        class << self
+          # @!visibility private
+          #
+          # Override to support Proxy
+          #
+          def ===(other)
+            other.is_a?(self)
+          end
+        end
+
+        #
+        # @!method uninitialized?
+        #   Check if thing status == UNINITIALIZED
+        #   @return [true,false]
+        #
+
+        #
+        # @!method initialized?
+        #   Check if thing status == INITIALIZED
+        #   @return [true,false]
+        #
+
+        #
+        # @!method unknown?
+        #   Check if thing status == UNKNOWN
+        #   @return [true,false]
+        #
+
+        #
+        # @!method online?
+        #   Check if thing status == ONLINE
+        #   @return [true,false]
+        #
+
+        #
+        # @!method offline?
+        #   Check if thing status == OFFLINE
+        #   @return [true,false]
+        #
+
+        #
+        # @!method removing?
+        #   Check if thing status == REMOVING
+        #   @return [true,false]
+        #
+
+        #
+        # @!method removed?
+        #   Check if thing status == REMOVED
+        #   @return [true,false]
+        #
+
+        ThingStatus.constants.each do |thingstatus|
+          define_method("#{thingstatus.to_s.downcase}?") { status == ThingStatus.value_of(thingstatus) }
+        end
+
+        #
+        # Enable the Thing
+        #
+        # @param [true, false] enabled
+        # @return [void]
+        #
+        def enable(enabled: true)
+          Things.manager.set_enabled(uid, enabled)
+        end
+
+        #
+        # Disable the Thing
+        #
+        # @return [void]
+        #
+        def disable
+          enable(enabled: false)
+        end
+
+        # @return [String]
+        def inspect
+          r = "#<OpenHAB::Core::Things::Thing #{uid}"
+          r += " #{label.inspect}" if label
+          r += " (#{location.inspect})" if location
+          r += " #{status}"
+          unless status_info.status_detail == org.openhab.core.thing.ThingStatusDetail::NONE
+            r += " (#{status_info.status_detail})"
+          end
+          r += " configuration=#{configuration.properties.to_h}" unless configuration.properties.empty?
+          r += " properties=#{properties.to_h}" unless properties.empty?
+          "#{r}>"
+        end
+
+        #
+        # Return Thing's uid as a string
+        #
+        # @return [String]
+        #
+        def to_s
+          uid.to_s
+        end
+
+        #
+        # Fetches the actions available for this thing.
+        #
+        # Default scope actions are available directly on the thing object, via
+        # {#method_missing}.
+        #
+        # @param [String, nil] scope The action scope. Default's to the thing's binding.
+        # @return [Object, nil]
+        #
+        # @example
+        #   things["max:thermostat:mybridge:thermostat"].actions("max-devices").delete_from_cube
+        #
+        # @example (see #method_missing)
+        #
+        def actions(scope = nil)
+          $actions.get(scope || uid.binding_id, uid.to_s)
+        end
+
+        #
+        # Delegate missing methods to the thing's default actions scope.
+        #
+        # @example
+        #   things['mail:smtp:local'].send_email('me@example.com', 'subject', 'message')
+        #
+        def method_missing(method, *args, &block)
+          return actions.public_send(method, *args, &block) if actions.respond_to?(method)
+
+          super
+        end
+
+        # @!visibility private
+        def respond_to_missing?(method_name, _include_private = false)
+          logger.trace("Checking if Thing #{uid} supports #{method_name} action")
+          return true if actions.respond_to?(method_name)
+
+          super
+        end
+      end
+    end
+  end
+end

data/lib/openhab/core/things.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module OpenHAB
+  module Core
+    #
+    # Contains the core {Thing} that bindings use to represent connected devices,
+    # as well as related infrastructure.
+    #
+    module Things
+      java_import org.openhab.core.thing.ThingStatus,
+                  org.openhab.core.thing.ThingUID,
+                  org.openhab.core.thing.ThingTypeUID
+
+      class << self
+        # @!visibility private
+        def manager
+          @manager ||= OSGi.service("org.openhab.core.thing.ThingManager")
+        end
+      end
+    end
+  end
+end

data/lib/openhab/core/timer.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+require "forwardable"
+
+module OpenHAB
+  module Core
+    #
+    # Timer allows you to administer the block of code that
+    # has been scheduled to run later with {OpenHAB::DSL.after after}.
+    #
+    class Timer
+      extend Forwardable
+
+      # @!method active?
+      #   Check if the timer will execute in the future.
+      #   @return [true,false]
+
+      # @!method cancelled?
+      #   Check if the timer has been cancelled.
+      #   @return [true,false]
+
+      # @!method running?
+      #   Check if the timer code is currently running.
+      #   @return [true,false]
+
+      # @!method terminated?
+      #   Check if the timer has terminated.
+      #   @return [true,false]
+
+      def_delegator :@timer, :has_terminated, :terminated?
+      def_delegators :@timer, :active?, :cancelled?, :running?, :execution_time
+
+      # @return [Object, nil]
+      attr_accessor :id
+
+      # @!visibility private
+      attr_reader :block
+
+      #
+      # Create a new Timer Object
+      #
+      # @param [java.time.temporal.TemporalAmount, #to_zoned_date_time, Proc] time When to execute the block
+      # @yield Block to execute when timer fires
+      # @yieldparam [self]
+      #
+      # @!visibility private
+      def initialize(time, id:, thread_locals:, block:)
+        @time = time
+        @id = id
+        @thread_locals = thread_locals
+        @block = block
+        @timer = ScriptExecution.create_timer(1.minute.from_now) { execute }
+        reschedule!(@time)
+      end
+
+      # @return [String]
+      def inspect
+        r = "#<#{self.class.name} #{"#{id.inspect} " if id}#{block.source_location.join(":")}"
+        if cancelled?
+          r += " (cancelled)"
+        else
+          r += " @ #{execution_time}"
+          r += " (executed)" if terminated?
+        end
+        "#{r}>"
+      end
+      alias_method :to_s, :inspect
+
+      # @!attribute [r] execution_time
+      #   @return [ZonedDateTime, nil] the scheduled execution time, or `nil` if the timer was cancelled
+
+      #
+      # Reschedule timer.
+      #
+      # If the timer had been cancelled or executed, restart the timer.
+      #
+      # @param [java.time.temporal.TemporalAmount, ZonedDateTime, Proc, nil] time When to reschedule the timer for.
+      #   If unspecified, the original time is used.
+      #
+      # @return [self]
+      #
+      def reschedule(time = nil)
+        return reschedule!(time) unless id
+
+        # re-add ourself to the TimerManager's @timers_by_id
+        DSL.timers.schedule(id) do |old_timer|
+          old_timer&.cancel unless old_timer.eql?(self)
+          self.id = nil
+          reschedule!(time)
+        end
+      end
+
+      # @return [self]
+      # @!visibility private
+      def reschedule!(time = nil)
+        Thread.current[:openhab_rescheduled_timer] = true if Thread.current[:openhab_rescheduled_timer] == self
+        DSL.timers.add(self)
+        @timer.reschedule(new_execution_time(time || @time))
+        self
+      end
+
+      #
+      # Cancel timer
+      #
+      # @return [true,false] True if cancel was successful, false otherwise
+      #
+      def cancel
+        DSL.timers.delete(self)
+        cancel!
+      end
+
+      #
+      # Cancel the timer but do not remove self from the timer manager
+      #
+      # To be used internally by {TimerManager} from inside ConcurrentHashMap's compute blocks
+      #
+      # @return [true,false] True if cancel was successful, false otherwise
+      #
+      # @!visibility private
+      def cancel!
+        @timer.cancel
+      end
+
+      private
+
+      #
+      # Calls the block with thread locals set up, and cleans up after itself
+      #
+      # @return [void]
+      #
+      def execute
+        Thread.current[:openhab_rescheduled_timer] = self
+        DSL::ThreadLocal.thread_local(**@thread_locals) { @block.call(self) }
+        DSL.timers.delete(self) unless Thread.current[:openhab_rescheduled_timer] == true
+        Thread.current[:openhab_rescheduled_timer] = nil
+      end
+
+      #
+      # @return [ZonedDateTime]
+      #
+      def new_execution_time(time)
+        time = time.call if time.is_a?(Proc)
+        time = time.from_now if time.is_a?(java.time.temporal.TemporalAmount)
+        time.to_zoned_date_time
+      end
+    end
+  end
+end

data/lib/openhab/{dsl → core}/types/comparable_type.rb

@@ -1,9 +1,11 @@
 # frozen_string_literal: true
 
+require_relative "type"
+
 module OpenHAB
-  module DSL
-    # Comparable#== is overwritten by Type, because DecimalType etc.
-    # inherits from Comparable on the Java side, so it's in the wrong place
+  module Core
+    # `Comparable#==` is overwritten by Type, because {DecimalType} etc.
+    # inherit from `Comparable` on the Java side, so it's in the wrong place
     # in the ancestor list
     # @!visibility private
     module ComparableType