openhab-jrubyscripting 5.0.0.rc1

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

@@ -0,0 +1,327 @@
+# frozen_string_literal: true
+
+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 is used to hold OpenHAB's HistoricItem.
+        class HistoricState < SimpleDelegator
+          attr_reader :timestamp
+
+          alias_method :state, :__getobj__
+
+          def initialize(state, timestamp)
+            @timestamp = timestamp
+            super(state)
+          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
+        PERSISTENCE_METHODS = (QUANTITY_METHODS +
+                              %i[changed_since?
+                                 evolution_rate
+                                 historic_state
+                                 maximum_since
+                                 minimum_since
+                                 updated_since?]).freeze
+        private_constant :QUANTITY_METHODS, :PERSISTENCE_METHODS
+
+        # @!method persist(service = nil)
+        #   Persist 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)
+        #   Return the time the item was last updated.
+        #   @param [Symbol, String] service An optional persistence id instead of the default persistence service.
+        #   @return [ZonedDateTime] The timestamp of the last update
+
+        # @!method average_since(timestamp, service = nil)
+        #   Return 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)
+        #   Return 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)
+        #   Return 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)
+        #   Return 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)
+        #   Return 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)
+        #   Return 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)
+        #   Return 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)
+        #   Return 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)
+        #   Return 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)
+        #   Return 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)
+        #   Return 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.
+
+        # @!method historic_state(timestamp, service = nil)
+        #   Return 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)
+        #   Return 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)
+        #   Return 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)
+        #   Return 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)
+        #   Return 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.
+
+        %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.timestamp)
+        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
+
+        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) && 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.timestamp)
+          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/proxy.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require "delegate"
+require "forwardable"
+
+module OpenHAB
+  module Core
+    module Items
+      # Class is a proxy to underlying item
+      # @!visibility private
+      class Proxy < Delegator
+        extend Forwardable
+        def_delegators :__getobj__, :class, :is_a?, :kind_of?
+
+        #
+        # Set the proxy item (called by super)
+        #
+        def __setobj__(item)
+          # Convert name to java version for faster lookups
+          @item_name = item.name.to_java
+        end
+
+        #
+        # Lookup item from item registry
+        #
+        def __getobj__
+          $ir.get(@item_name)
+        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
+      end
+    end
+  end
+end

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

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require "singleton"
+
+require "openhab/core/entity_lookup"
+require "openhab/core/lazy_array"
+require "openhab/dsl/items/builder"
+
+module OpenHAB
+  module Core
+    module Items
+      #
+      # Provides access to all OpenHAB {GenericItem items}, and acts like an array.
+      #
+      class Registry
+        include LazyArray
+        include Singleton
+
+        # Fetches the named item from the the ItemRegistry
+        # @param [String] name
+        # @return [GenericItem] Item from registry, nil if item missing or requested item is a Group Type
+        def [](name)
+          EntityLookup.lookup_item(name)
+        rescue org.openhab.core.items.ItemNotFoundException
+          nil
+        end
+
+        # Returns true if the given item name exists
+        # @param name [String] Item name to check
+        # @return [true,false] true if the item exists, false otherwise
+        def key?(name)
+          !$ir.getItems(name).empty?
+        end
+        alias_method :include?, :key?
+
+        # Explicit conversion to array
+        # @return [Array]
+        def to_a
+          $ir.items.map { |item| Proxy.new(item) }
+        end
+
+        # Enter the Item Builder DSL.
+        # @yield Block executed in the context of a {DSL::Items::Builder}
+        # @return [Object] The return value of the block.
+        def build(&block)
+          DSL::Items::BaseBuilderDSL.new.instance_eval(&block)
+        end
+
+        # Remove an item.
+        #
+        # The item must have either been created by this script, or be a
+        # managed item (typically created in the UI).
+        #
+        # @param recursive [true, false] Remove the item's members if it's a group
+        # @return [GenericItem, nil] The removed item, if found.
+        def remove(item_name, recursive: false)
+          item_name = item_name.name if item_name.is_a?(GenericItem)
+          result = DSL::Items::ItemProvider.instance.remove(item_name, recursive: recursive)
+          return result if result
+
+          $ir.remove(item_name, recursive)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require_relative "generic_item"
+require_relative "numeric_item"
+
+module OpenHAB
+  module Core
+    module Items
+      java_import org.openhab.core.library.items.RollershutterItem
+
+      #
+      # A {RollershutterItem} allows the control of roller shutters, i.e.
+      # moving them up, down, stopping or setting it to close to a certain
+      # percentage.
+      #
+      # @!attribute [r] state
+      #   @return [PercentType, UpDownType, nil]
+      #
+      # @example Roll up all Rollershutters in a group
+      #   Shutters.up
+      #
+      # @example Log a warning for all rollershutters that are not up
+      #   Shutters.reject(&:up?).each do |item|
+      #     logger.warn("#{item.name} is not rolled up!")
+      #   end
+      #
+      # @example Set rollershutter to a specified position
+      #   Example_Rollershutter << 40
+      class RollershutterItem < GenericItem
+        include NumericItem
+
+        # @!method up?
+        #   Check if the item state == {UP}
+        #   @return [true,false]
+
+        # @!method down?
+        #   Check if the item state == {DOWN}
+        #   @return [true,false]
+
+        # @!method up
+        #   Send the {UP} command to the item
+        #   @return [RollershutterItem] `self`
+
+        # @!method down
+        #   Send the {DOWN} command to the item
+        #   @return [RollershutterItem] `self`
+
+        # @!method stop
+        #   Send the {STOP} command to the item
+        #   @return [RollershutterItem] `self`
+
+        # @!method move
+        #   Send the {MOVE} command to the item
+        #   @return [RollershutterItem] `self`
+
+        # raw numbers translate directly to PercentType, not a DecimalType
+        # @!visibility private
+        def format_type(command)
+          return Types::PercentType.new(command) if command.is_a?(Numeric)
+
+          super
+        end
+      end
+    end
+  end
+end
+
+# @!parse RollershutterItem = OpenHAB::Core::Items::RollershutterItem