openhab-scripting 4.46.2 → 5.0.0

data/lib/openhab/core/items/persistence.rb

@@ -0,0 +1,416 @@
+# frozen_string_literal: true
+
+require "delegate"
+
+require_relative "generic_item"
+
+module OpenHAB
+  module Core
+    module Items
+      #
+      # Items extensions to support
+      # {https://www.openhab.org/docs/configuration/persistence.html openHAB's Persistence} feature.
+      #
+      # @see OpenHAB::DSL.persistence Persistence Block
+      #
+      # @example The following examples are based on these items
+      #   Number        UV_Index
+      #   Number:Power  Power_Usage "Power Usage [%.2f W]"
+      #
+      # @example Getting persistence data from the system default persistence service
+      #   UV_Index.average_since(1.hour.ago)      # returns a DecimalType
+      #   Power_Usage.average_since(12.hours.ago) # returns a QuantityType that corresponds to the item's type
+      #
+      # @example Querying a non-default persistence service
+      #   UV_Index.average_since(1.hour.ago, :influxdb)
+      #   Power_Usage.average_since(12.hours.ago, :rrd4j)
+      #
+      # @example Comparison using Quantity
+      #   # Because Power_Usage has a unit, the return value
+      #   # from average_since is a QuantityType which can be
+      #   # compared against a string with quantity
+      #   if Power_Usage.average_since(15.minutes.ago) > 5 | "kW"
+      #     logger.info("The power usage exceeded its 15 min average)
+      #   end
+      #
+      # @example HistoricState
+      #   max = Power_Usage.maximum_since(LocalTime::MIDNIGHT)
+      #   logger.info("Max power usage today: #{max}, at: #{max.timestamp})
+      #
+      module Persistence
+        GenericItem.prepend(self)
+
+        #
+        # A state class with an added timestamp attribute.
+        #
+        # This wraps {org.openhab.core.persistence.HistoricItem HistoricItem}
+        # to allow implicitly treating the object as its state, and wrapping of
+        # that state into a {QuantityType} as necessary.
+        #
+        class HistoricState < SimpleDelegator
+          # @!attribute [r] state
+          # @return [Types::State]
+          alias_method :state, :__getobj__
+
+          def initialize(state, historic_item)
+            @historic_item = historic_item
+            super(state)
+          end
+
+          # @!attribute [r] timestamp
+          # @return [ZonedDateTime]
+          def timestamp
+            @historic_item.timestamp
+          end
+        end
+
+        # All persistence methods that could return a QuantityType
+        QUANTITY_METHODS = %i[average_since
+                              delta_since
+                              deviation_since
+                              sum_since
+                              variance_since].freeze
+
+        # All persistence methods that require a timestamp
+        # Note the _between methods are automatically created from the _since methods
+        PERSISTENCE_METHODS = (QUANTITY_METHODS +
+                              %i[changed_since?
+                                 count_since
+                                 count_state_changes_since
+                                 historic_state
+                                 maximum_since
+                                 minimum_since
+                                 updated_since?]).freeze
+        private_constant :QUANTITY_METHODS, :PERSISTENCE_METHODS
+
+        # @!method persist(service = nil)
+        #   Persists the state of the item
+        #   @param [Symbol, String] service An optional persistence id instead of the default persistence service.
+        #   @return [void]
+
+        # @!method last_update(service = nil)
+        #   Returns the time the item was last updated.
+        #   @param [Symbol, String] service An optional persistence id instead of the default persistence service.
+        #   @return [ZonedDateTime, nil] The timestamp of the last update
+
+        # @!method average_since(timestamp, service = nil)
+        #   Returns the average value of the item's state since the given time
+        #   @param [#to_zoned_date_time] timestamp The point in time from which to search
+        #   @param [Symbol, String] service An optional persistence id instead of the default persistence service.
+        #   @return [DecimalType, QuantityType, nil] The average value since `timestamp`,
+        #     or nil if no previous state could be found.
+
+        # @!method average_between(start, finish, service = nil)
+        #   Returns the average value of the item's state between two points in time
+        #   @param [#to_zoned_date_time] start The point in time from which to search
+        #   @param [#to_zoned_date_time] finish The point in time to which to search
+        #   @param [Symbol, String] service An optional persistence id instead of the default persistence service.
+        #   @return [DecimalType, QuantityType, nil] The average value between `start` and `finish`,
+        #     or nil if no previous state could be found.
+
+        # @!method delta_since(timestamp, service = nil)
+        #   Returns the difference value of the item's state since the given time
+        #   @param [#to_zoned_date_time] timestamp The point in time from which to search
+        #   @param [Symbol, String] service An optional persistence id instead of the default persistence service.
+        #   @return [DecimalType, QuantityType, nil] The difference value since `timestamp`,
+        #     or nil if no previous state could be found.
+
+        # @!method delta_between(start, finish, service = nil)
+        #   Returns the difference value of the item's state between two points in time
+        #   @param [#to_zoned_date_time] start The point in time from which to search
+        #   @param [#to_zoned_date_time] finish The point in time to which to search
+        #   @param [Symbol, String] service An optional persistence id instead of the default persistence service.
+        #   @return [DecimalType, QuantityType, nil] The difference value between `start` and `finish`,
+        #     or nil if no previous state could be found.
+
+        # @!method deviation_since(timestamp, service = nil)
+        #   Returns the standard deviation of the item's state since the given time
+        #   @param [#to_zoned_date_time] timestamp The point in time from which to search
+        #   @param [Symbol, String] service An optional persistence id instead of the default persistence service.
+        #   @return [DecimalType, QuantityType, nil] The standard deviation since `timestamp`,
+        #     or nil if no previous state could be found.
+
+        # @!method deviation_between(start, finish, service = nil)
+        #   Returns the standard deviation of the item's state between two points in time
+        #   @param [#to_zoned_date_time] start The point in time from which to search
+        #   @param [#to_zoned_date_time] finish The point in time to which to search
+        #   @param [Symbol, String] service An optional persistence id instead of the default persistence service.
+        #   @return [DecimalType, QuantityType, nil] The standard deviation between `start` and `finish`,
+        #     or nil if no previous state could be found.
+
+        # @!method sum_since(timestamp, service = nil)
+        #   Returns the sum of the item's state since the given time
+        #   @param [#to_zoned_date_time] timestamp The point in time from which to search
+        #   @param [Symbol, String] service An optional persistence id instead of the default persistence service.
+        #   @return [DecimalType, QuantityType, nil] The sum since `timestamp`,
+        #     or nil if no previous state could be found.
+
+        # @!method sum_between(start, finish, service = nil)
+        #   Returns the sum of the item's state between two points in time
+        #   @param [#to_zoned_date_time] start The point in time from which to search
+        #   @param [#to_zoned_date_time] finish The point in time to which to search
+        #   @param [Symbol, String] service An optional persistence id instead of the default persistence service.
+        #   @return [DecimalType, QuantityType, nil] The sum between `start` and `finish`,
+        #     or nil if no previous state could be found.
+
+        # @!method variance_since(timestamp, service = nil)
+        #   Returns the variance of the item's state since the given time
+        #   @param [#to_zoned_date_time] timestamp The point in time from which to search
+        #   @param [Symbol, String] service An optional persistence id instead of the default persistence service.
+        #   @return [DecimalType, QuantityType, nil] The variance since `timestamp`,
+        #     or nil if no previous state could be found.
+
+        # @!method variance_between(start, finish, service = nil)
+        #   Returns the variance of the item's state between two points in time
+        #   @param [#to_zoned_date_time] start The point in time from which to search
+        #   @param [#to_zoned_date_time] finish The point in time to which to search
+        #   @param [Symbol, String] service An optional persistence id instead of the default persistence service.
+        #   @return [DecimalType, QuantityType, nil] The variance between `start` and `finish`,
+        #     or nil if no previous state could be found.
+
+        # @!method changed_since?(timestamp, service = nil)
+        #   Whether the item's state has changed since the given time
+        #   @param [#to_zoned_date_time] timestamp The point in time from which to search
+        #   @param [Symbol, String] service An optional persistence id instead of the default persistence service.
+        #   @return [true,false] True if the item's state has changed since the given `timestamp`, False otherwise.
+
+        # @!method changed_between?(start, finish, service = nil)
+        #   Whether the item's state changed between two points in time
+        #   @param [#to_zoned_date_time] start The point in time from which to search
+        #   @param [#to_zoned_date_time] finish The point in time to which to search
+        #   @param [Symbol, String] service An optional persistence id instead of the default persistence service.
+        #   @return [true,false] True if the item's state changed between `start` and `finish`, False otherwise.
+
+        # @!method evolution_rate(timestamp, service = nil)
+        #   Returns the evolution rate of the item's state
+        #   @return [DecimalType, QuantityType, nil] The evolution rate since `timestamp`,
+        #     or nil if no previous state could be found.
+        #   @overload evolution_rate(timestamp, service = nil)
+        #     Returns the evolution rate of the item's state since the given time
+        #     @param [#to_zoned_date_time] timestamp The point in time from which to search
+        #     @param [Symbol, String] service An optional persistence id instead of the default persistence service.
+        #     @return [DecimalType, QuantityType, nil] The evolution rate since `timestamp`,
+        #       or nil if no previous state could be found.
+        #   @overload evolution_rate(start, finish, service = nil)
+        #     Returns the evolution rate of the item's state between two points in time
+        #     @param [#to_zoned_date_time] start The point in time from which to search
+        #     @param [#to_zoned_date_time] finish The point in time to which to search
+        #     @param [Symbol, String] service An optional persistence id instead of the default persistence service.
+        #     @return [DecimalType, QuantityType, nil] The evolution rate between `start` and `finish`,
+        #       or nil if no previous state could be found.
+
+        # @!method historic_state(timestamp, service = nil)
+        #   Returns the the item's state at the given time
+        #   @param [#to_zoned_date_time] timestamp The point in time at which to search
+        #   @param [Symbol, String] service An optional persistence id instead of the default persistence service.
+        #   @return [HistoricState, nil] The item's state at `timestamp`,
+        #     or nil if no previous state could be found.
+
+        # @!method maximum_since(timestamp, service = nil)
+        #   Returns the maximum value of the item's state since the given time
+        #   @param [#to_zoned_date_time] timestamp The point in time from which to search
+        #   @param [Symbol, String] service An optional persistence id instead of the default persistence service.
+        #   @return [HistoricState, nil] The maximum value since `timestamp`,
+        #     or nil if no previous state could be found.
+
+        # @!method maximum_between(start, finish, service = nil)
+        #   Returns the maximum value of the item's state between two points in time
+        #   @param [#to_zoned_date_time] start The point in time from which to search
+        #   @param [#to_zoned_date_time] finish The point in time to which to search
+        #   @param [Symbol, String] service An optional persistence id instead of the default persistence service.
+        #   @return [HistoricState, nil] The maximum value between `start` and `finish`,
+        #     or nil if no previous state could be found.
+
+        # @!method minimum_since(timestamp, service = nil)
+        #   Returns the minimum value of the item's state since the given time
+        #   @param [#to_zoned_date_time] timestamp The point in time from which to search
+        #   @param [Symbol, String] service An optional persistence id instead of the default persistence service.
+        #   @return [HistoricState, nil] The minimum value since `timestamp`,
+        #     or nil if no previous state could be found.
+
+        # @!method minimum_between(start, finish, service = nil)
+        #   Returns the minimum value of the item's state between two points in time
+        #   @param [#to_zoned_date_time] start The point in time from which to search
+        #   @param [#to_zoned_date_time] finish The point in time to which to search
+        #   @param [Symbol, String] service An optional persistence id instead of the default persistence service.
+        #   @return [HistoricState, nil] The minimum value between `start` and `finish`,
+        #     or nil if no previous state could be found.
+
+        # @!method updated_since?(timestamp, service = nil)
+        #   Whether the item's state has been updated since the given time
+        #   @param [#to_zoned_date_time] timestamp The point in time from which to search
+        #   @param [Symbol, String] service An optional persistence id instead of the default persistence service.
+        #   @return [true,false] True if the item's state has been updated since the given `timestamp`, False otherwise.
+
+        # @!method updated_between?(start, finish, service = nil)
+        #   Whether the item's state was updated between two points in time
+        #   @param [#to_zoned_date_time] start The point in time from which to search
+        #   @param [#to_zoned_date_time] finish The point in time to which to search
+        #   @param [Symbol, String] service An optional persistence id instead of the default persistence service.
+        #   @return [true,false] True if the item's state was updated between `start` and `finish`, False otherwise.
+
+        # @!method count_since(timestamp, service = nil)
+        #   Returns the number of available historic data points from a point in time until now.
+        #   @param [#to_zoned_date_time] timestamp The point in time from which to search
+        #   @param [Symbol, String] service An optional persistence id instead of the default persistence service.
+        #   @return [Integer] The number of values persisted for this item.
+
+        # @!method count_between(start, finish, service = nil)
+        #   Returns the number of available historic data points between two points in time.
+        #   @param [#to_zoned_date_time] start The point in time from which to search
+        #   @param [#to_zoned_date_time] finish The point in time to which to search
+        #   @param [Symbol, String] service An optional persistence id instead of the default persistence service.
+        #   @return [Integer] The number of values persisted for this item.
+
+        # @!method count_state_changes_since(timestamp, service = nil)
+        #   Returns the number of changes in historic data points from a point in time until now.
+        #   @param [#to_zoned_date_time] timestamp The point in time from which to search
+        #   @param [Symbol, String] service An optional persistence id instead of the default persistence service.
+        #   @return [Integer] The number of values persisted for this item.
+
+        # @!method count_state_changes_between(start, finish, service = nil)
+        #   Returns the number of changes in historic data points between two points in time.
+        #   @param [#to_zoned_date_time] start The point in time from which to search
+        #   @param [#to_zoned_date_time] finish The point in time to which to search
+        #   @param [Symbol, String] service An optional persistence id instead of the default persistence service.
+        #   @return [Integer] The number of values persisted for this item.
+
+        %i[persist last_update].each do |method|
+          define_method(method) do |service = nil|
+            service ||= persistence_service
+            Actions::PersistenceExtensions.public_send(method, self, service&.to_s)
+          end
+        end
+
+        #
+        # Return the previous state of the item
+        #
+        # @param skip_equal [true,false] if true, skips equal state values and
+        #        searches the first state not equal the current state
+        # @param service [String] the name of the PersistenceService to use
+        #
+        # @return [HistoricState, nil] the previous state or nil if no previous state could be found,
+        #         or if the default persistence service is not configured or
+        #         does not refer to a valid service
+        #
+        def previous_state(service = nil, skip_equal: false)
+          service ||= persistence_service
+          result = Actions::PersistenceExtensions.previous_state(self, skip_equal, service&.to_s)
+          HistoricState.new(quantify(result.state), result) if result
+        end
+
+        PERSISTENCE_METHODS.each do |method|
+          define_method(method) do |timestamp, service = nil|
+            service ||= persistence_service
+            result = Actions::PersistenceExtensions.public_send(
+              method.to_s.delete_suffix("?"),
+              self,
+              timestamp.to_zoned_date_time,
+              service&.to_s
+            )
+            wrap_result(result, method)
+          end
+
+          next unless /_since\??$/.match?(method.to_s)
+
+          between_method = method.to_s.sub("_since", "_between").to_sym
+          define_method(between_method) do |start, finish, service = nil|
+            service ||= persistence_service
+            result = Actions::PersistenceExtensions.public_send(
+              between_method.to_s.delete_suffix("?"),
+              self,
+              start.to_zoned_date_time,
+              finish.to_zoned_date_time,
+              service&.to_s
+            )
+            wrap_result(result, method)
+          end
+        end
+
+        # evolution_rate's "between" method is overloaded with the same name
+        method = :evolution_rate
+        define_method(method) do |start, finish_or_service = nil, service = nil|
+          if service.nil?
+            if finish_or_service.respond_to?(:to_zoned_date_time)
+              service = persistence_service
+              finish = finish_or_service
+            else
+              service = finish_or_service || persistence_service
+              finish = nil
+            end
+          else
+            finish = finish_or_service
+          end
+
+          result = if finish
+                     Actions::PersistenceExtensions.public_send(
+                       method,
+                       self,
+                       start.to_zoned_date_time,
+                       finish.to_zoned_date_time,
+                       service&.to_s
+                     )
+                   else
+                     Actions::PersistenceExtensions.public_send(
+                       method,
+                       self,
+                       start.to_zoned_date_time,
+                       service&.to_s
+                     )
+                   end
+          wrap_result(result, method)
+        end
+
+        alias_method :state_changes_since, :count_state_changes_since
+        alias_method :state_changes_between, :count_state_changes_between
+
+        private
+
+        #
+        # Convert value to QuantityType if it is a DecimalType and a unit is defined
+        #
+        # @param [Object] value The value to convert
+        #
+        # @return [Object] QuantityType or the original value
+        #
+        def quantify(value)
+          if value.is_a?(DecimalType) && respond_to?(:unit) && unit
+            logger.trace("Unitizing #{value} with unit #{unit}")
+            QuantityType.new(value.to_big_decimal, unit)
+          else
+            value
+          end
+        end
+
+        #
+        # Wrap the result into a more convenient object type depending on the method and result.
+        #
+        # @param [Object] result the raw result type to be wrapped
+        # @param [Symbol] method the name of the called method
+        #
+        # @return [HistoricState] a {HistoricState} object if the result was a HistoricItem
+        # @return [QuantityType] a `QuantityType` object if the result was an average, delta, deviation,
+        #                        sum, or variance.
+        # @return [Object] the original result object otherwise.
+        #
+        def wrap_result(result, method)
+          if result.is_a?(org.openhab.core.persistence.HistoricItem)
+            return HistoricState.new(quantify(result.state), result)
+          end
+          return quantify(result) if QUANTITY_METHODS.include?(method)
+
+          result
+        end
+
+        #
+        # Get the specified persistence service from the current thread local variable
+        #
+        # @return [Object] Persistence service name as String or Symbol, or nil if not set
+        #
+        def persistence_service
+          Thread.current[:openhab_persistence_service]
+        end
+      end
+    end
+  end
+end

data/lib/openhab/core/items/player_item.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require_relative "generic_item"
+
+module OpenHAB
+  module Core
+    module Items
+      java_import org.openhab.core.library.items.PlayerItem
+
+      #
+      # A {PlayerItem} allows control of a player, e.g. an audio player.
+      #
+      # @!attribute [r] state
+      #   @return [PlayPauseType, RewindFastforwardType, nil]
+      #
+      # @example Start playing on a player item
+      #   Chromecast.play
+      # @example Check if a player is paused
+      #   logger.warn("#{item.name} is paused") if Chromecast.paused?
+      #
+      class PlayerItem < GenericItem
+        # @!method play?
+        #   Check if the item state == {PLAY}
+        #   @return [true,false]
+
+        # @!method paused?
+        #   Check if the item state == {PAUSE}
+        #   @return [true,false]
+
+        # @!method rewinding?
+        #   Check if the item state == {REWIND}
+        #   @return [true,false]
+
+        # @!method fast_forwarding?
+        #   Check if the item state == {FASTFORWARD}
+        #   @return [true,false]
+
+        # @!method play
+        #   Send the {PLAY} command to the item
+        #   @return [PlayerItem] `self`
+
+        # @!method pause
+        #   Send the {PAUSE} command to the item
+        #   @return [PlayerItem] `self`
+
+        # @!method rewind
+        #   Send the {REWIND} command to the item
+        #   @return [PlayerItem] `self`
+
+        # @!method fast_forward
+        #   Send the {FASTFORWARD} command to the item
+        #   @return [PlayerItem] `self`
+
+        # @!method next
+        #   Send the {NEXT} command to the item
+        #   @return [PlayerItem] `self`
+
+        # @!method previous
+        #   Send the {PREVIOUS} command to the item
+        #   @return [PlayerItem] `self`
+      end
+    end
+  end
+end
+
+# @!parse PlayerItem = OpenHAB::Core::Items::PlayerItem

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

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module OpenHAB
+  module Core
+    module Items
+      #
+      # Provides {Item Items} created in Ruby to openHAB
+      #
+      class Provider < Core::Provider
+        include org.openhab.core.items.ItemProvider
+
+        class << self
+          #
+          # The Item registry
+          #
+          # @return [org.openhab.core.items.ItemRegistry]
+          #
+          def registry
+            $ir
+          end
+        end
+
+        #
+        # Remove an item from this provider
+        #
+        # @param [String] item_name
+        # @param [true, false] recursive
+        # @return [Item, nil] The removed item, if found.
+        #
+        def remove(item_name, recursive = false) # rubocop:disable Style/OptionalBooleanParameter matches Java method
+          return nil unless @elements.key?(item_name)
+
+          item = super(item_name)
+          item.members.each { |member| remove(member.name, true) } if recursive && item.is_a?(GroupItem)
+          item
+        end
+
+        def initialize
+          super(unload_priority: 50)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require "delegate"
+require_relative "../proxy"
+
+module OpenHAB
+  module Core
+    module Items
+      # Class is a proxy to underlying {Item}
+      # @!visibility private
+      class Proxy < Delegator
+        # Not really an Item, but pretends to be
+        # @!parse include Item
+
+        # @!visibility private
+        EVENTS = [Events::ItemAddedEvent::TYPE, Events::ItemUpdatedEvent::TYPE, Events::ItemRemovedEvent::TYPE].freeze
+        # @!visibility private
+        UID_METHOD = :name
+
+        include Core::Proxy
+
+        # @return [String]
+        attr_reader :name
+
+        #
+        # Set the proxy item (called by super)
+        #
+        def __setobj__(item)
+          @item = item.is_a?(Item) ? item : nil
+          @name ||= item.name if item
+        end
+
+        #
+        # @return [Item, nil]
+        #
+        def __getobj__
+          @item
+        end
+
+        # @return [Module]
+        def class
+          return Item if __getobj__.nil?
+
+          __getobj__.class
+        end
+
+        # @return [true, false]
+        def is_a?(klass)
+          obj = __getobj__
+          # only claim to be a Delegator if we're backed by an actual item at the moment
+          klass == Item || obj.is_a?(klass) || klass == Proxy || (!obj.nil? && super)
+        end
+        alias_method :kind_of?, :is_a?
+
+        #
+        # 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
+
+        # @return [GroupItem::Members]
+        # @raise [NoMethodError] if item is not a GroupItem, or a dummy.
+        def members
+          return GroupItem::Members.new(self) if __getobj__.nil?
+
+          __getobj__.members
+        end
+
+        # @return [String]
+        def inspect
+          return super unless __getobj__.nil?
+
+          "#<OpenHAB::Core::Items::Proxy #{name}>"
+        end
+
+        #
+        # Supports inspect from IRB when we're a dummy item.
+        #
+        # @return [void]
+        # @!visibility private
+        def pretty_print(printer)
+          return super unless __getobj__.nil?
+
+          printer.text(inspect)
+        end
+
+        # needs to return `false` if we know we're not a {GroupItem}
+        def respond_to?(method, *args)
+          obj = __getobj__
+          return obj.respond_to?(method, *args) if method.to_sym == :members && !obj.nil?
+
+          super
+        end
+
+        # needs to return `false` if we know we're not a {GroupItem}
+        def respond_to_missing?(method, *args)
+          obj = __getobj__
+          return obj.respond_to_missing?(method, *args) if method.to_sym == :members && !obj.nil?
+
+          super
+        end
+      end
+    end
+  end
+end