openhab-jrubyscripting 5.0.0.rc1

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

@@ -0,0 +1,46 @@
+# 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?, :[]
+
+        #
+        # Explicit conversion to array
+        #
+        # @return [Array<Thing>]
+        #
+        def to_a
+          $things.all.map { |thing| Proxy.new(thing) }
+        end
+
+        # Enter the Thing Builder DSL.
+        # @yield Block executed in the context of a {DSL::Things::Builder}.
+        # @return [Object] The result of the block.
+        def build(&block)
+          DSL::Things::Builder.new.instance_eval(&block)
+        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 {GenericItem 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,128 @@
+# 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}.
+    #
+    # @!attribute [r] execution_time
+    #   @return [ZonedDateTime] the scheduled execution time, or null if the timer was cancelled
+    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, :execution_time, :active?, :cancelled?, :running?
+
+      # @return [Object, nil]
+      attr_accessor :id
+
+      # @!visibility private
+      # @!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 = org.openhab.core.model.script.actions.ScriptExecution.create_timer(
+          # create it far enough in the future so it won't execute until we finish setting it up
+          1.minute.from_now,
+          # when running in rspec, it may have troubles finding this class
+          # for auto-conversion of block to interface, so use .impl
+          org.eclipse.xtext.xbase.lib.Procedures::Procedure0.impl { 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
+
+      #
+      # Reschedule 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)
+        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)
+        @timer.cancel
+      end
+
+      private
+
+      #
+      # Calls the block with thread locals set up, and cleans up after itself
+      #
+      # @return [void]
+      #
+      def execute
+        last_execution_time = execution_time
+        DSL::ThreadLocal.thread_local(**@thread_locals) do
+          @block.call(self)
+        end
+        # don't remove ourselves if we were rescheduled in the block
+        DSL.timers.delete(self) if execution_time == last_execution_time
+      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/core/types/comparable_type.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require_relative "type"
+
+module OpenHAB
+  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
+      # re-implement
+      # @!visibility private
+      def ==(other)
+        r = self <=> other
+
+        return false if r.nil?
+
+        r.zero?
+      end
+    end
+  end
+end

data/lib/openhab/core/types/date_time_type.rb

@@ -0,0 +1,259 @@
+# frozen_string_literal: true
+
+require "forwardable"
+require "time"
+
+require_relative "type"
+
+module OpenHAB
+  module Core
+    module Types
+      DateTimeType = org.openhab.core.library.types.DateTimeType
+
+      # {DateTimeType} uses a {ZonedDateTime} internally.
+      class DateTimeType
+        # @!parse include Command, State
+
+        # remove the JRuby default == so that we can inherit the Ruby method
+        remove_method :==
+
+        extend Forwardable
+        include Comparable
+
+        #
+        # Regex expression to identify strings defining a time in hours, minutes and optionally seconds
+        #
+        TIME_ONLY_REGEX = /\A(?<hours>\d\d):(?<minutes>\d\d)(?<seconds>:\d\d)?\Z/.freeze
+
+        #
+        # Regex expression to identify strings defining a time in year, month, and day
+        #
+        DATE_ONLY_REGEX = /\A\d{4}-\d\d-\d\d\Z/.freeze
+        private_constant :TIME_ONLY_REGEX, :DATE_ONLY_REGEX
+
+        class << self
+          #
+          # Parses a String representing a time into an OpenHAB DateTimeType. First tries to parse it
+          #   using java's DateTimeType's parser, then falls back to the Ruby Time.parse
+          #
+          # @param [String] time_string
+          #
+          # @return [DateTimeType]
+          #
+          def parse(time_string)
+            time_string = "#{time_string}Z" if TIME_ONLY_REGEX.match?(time_string)
+            DateTimeType.new(time_string)
+          rescue java.lang.StringIndexOutOfBoundsException, java.lang.IllegalArgumentException => e
+            # Try Ruby's Time.parse if OpenHAB's DateTimeType parser fails
+            begin
+              DateTimeType.new(::Time.parse(time_string))
+            rescue ArgumentError
+              raise ArgumentError, e.message
+            end
+          end
+        end
+
+        # @param [ZonedDateTime, nil] context
+        #   A {ZonedDateTime} used to fill in missing
+        #   fields during conversion. Not used in this class.
+        # @return [ZonedTimeTime]
+        def to_zoned_date_time(context = nil) # rubocop:disable Lint/UnusedMethodArgument
+          zoned_date_time
+        end
+
+        # act like a Ruby Time
+        def_delegator :zoned_date_time, :month_value, :month
+        def_delegator :zoned_date_time, :day_of_month, :mday
+        def_delegator :zoned_date_time, :day_of_year, :yday
+        def_delegator :zoned_date_time, :minute, :min
+        def_delegator :zoned_date_time, :second, :sec
+        def_delegator :zoned_date_time, :nano, :nsec
+        def_delegator :zoned_date_time, :to_epoch_second, :to_i
+        def_delegator :zoned_date_time, :to_time
+
+        alias_method :day, :mday
+
+        #
+        # Create a new instance of DateTimeType
+        #
+        # @param value [#to_zoned_date_time, #to_time, #to_str, #to_d, nil]
+        #
+        def initialize(value = nil)
+          if value.respond_to?(:to_zoned_date_time)
+            super(value.to_zoned_date_time)
+            return
+          elsif value.respond_to?(:to_time)
+            super(value.to_time.to_zoned_date_time)
+            return
+          elsif value.respond_to?(:to_str)
+            # strings respond_do?(:to_d), but we want to avoid that conversion
+            super(value.to_str)
+            return
+          elsif value.respond_to?(:to_d)
+            super(Time.at(value.to_d).to_zoned_date_time)
+            return
+          end
+
+          super
+        end
+
+        #
+        # Check equality without type conversion
+        #
+        # @return [true,false] if the same value is represented, without type
+        #   conversion
+        def eql?(other)
+          return false unless other.instance_of?(self.class)
+
+          zoned_date_time.compare_to(other.zoned_date_time).zero?
+        end
+
+        #
+        # Comparison
+        #
+        # @param [Object] other object to compare to
+        #
+        # @return [Integer, nil] -1, 0, +1 depending on whether `other` is
+        #   less than, equal to, or greater than self
+        #
+        #   `nil` is returned if the two values are incomparable.
+        #
+        def <=>(other)
+          logger.trace("(#{self.class}) #{self} <=> #{other} (#{other.class})")
+          if other.is_a?(self.class)
+            zoned_date_time <=> other.zoned_date_time
+          elsif other.respond_to?(:to_time)
+            to_time <=> other.to_time
+          elsif other.respond_to?(:coerce)
+            return nil unless (lhs, rhs = other.coerce(self))
+
+            lhs <=> rhs
+          end
+        end
+
+        #
+        # Type Coercion
+        #
+        # Coerce object to a DateTimeType
+        #
+        # @param [Time] other object to coerce to a DateTimeType
+        #
+        # @return [[DateTimeType, DateTimeType], nil]
+        #
+        def coerce(other)
+          logger.trace("Coercing #{self} as a request from #{other.class}")
+          return [other, zoned_date_time] if other.respond_to?(:to_zoned_date_time)
+          return [DateTimeType.new(other), self] if other.respond_to?(:to_time)
+        end
+
+        #
+        # Returns the value of time as a floating point number of seconds since the Epoch
+        #
+        # @return [Float] Number of seconds since the Epoch, with nanosecond presicion
+        #
+        def to_f
+          zoned_date_time.to_epoch_second + (zoned_date_time.nano / 1_000_000_000)
+        end
+
+        #
+        # The offset in seconds from UTC
+        #
+        # @return [Integer] The offset from UTC, in seconds
+        #
+        def utc_offset
+          zoned_date_time.offset.total_seconds
+        end
+
+        #
+        # Returns true if time represents a time in UTC (GMT)
+        #
+        # @return [true,false] true if utc_offset == 0, false otherwise
+        #
+        def utc?
+          utc_offset.zero?
+        end
+
+        #
+        # Returns an integer representing the day of the week, 0..6, with Sunday == 0.
+        #
+        # @return [Integer] The day of week
+        #
+        def wday
+          zoned_date_time.day_of_week.value % 7
+        end
+
+        #
+        # The timezone
+        #
+        # @return [String] The timezone in `[+-]hh:mm(:ss)` format (`Z` for UTC)
+        #
+        def zone
+          zoned_date_time.zone.id
+        end
+
+        # @!visibility private
+        def respond_to_missing?(method, _include_private = false)
+          return true if zoned_date_time.respond_to?(method)
+          return true if ::Time.instance_methods.include?(method.to_sym)
+
+          super
+        end
+
+        #
+        # Forward missing methods to the `ZonedDateTime` object or a ruby `Time`
+        # object representing the same instant
+        #
+        def method_missing(method, *args, &block)
+          return zoned_date_time.send(method, *args, &block) if zoned_date_time.respond_to?(method)
+          return to_time.send(method, *args, &block) if ::Time.instance_methods.include?(method.to_sym)
+
+          super
+        end
+
+        # Add other to self
+        #
+        # @param other [Duration, Numeric]
+        #
+        # @return [DateTimeType]
+        def +(other)
+          if other.is_a?(Duration)
+            DateTimeType.new(zoned_date_time.plus(other))
+          elsif other.respond_to?(:to_d)
+            DateTimeType.new(zoned_date_time.plus_nanos((other.to_d * 1_000_000_000).to_i))
+          elsif other.respond_to?(:coerce) && (lhs, rhs = other.coerce(to_d))
+            lhs + rhs
+          else
+            raise TypeError, "\#{other.class} can't be coerced into \#{self.class}"
+          end
+        end
+
+        # Subtract other from self
+        #
+        # if other is a Duration-like object, the result is a new
+        # {DateTimeType} of duration seconds earlier in time.
+        #
+        # if other is a DateTime-like object, the result is a Duration
+        # representing how long between the two instants in time.
+        #
+        # @param other [Duration, Time, Numeric]
+        #
+        # @return [DateTimeType, Duration]
+        def -(other)
+          if other.is_a?(Duration)
+            DateTimeType.new(zoned_date_time.minus(other))
+          elsif other.respond_to?(:to_time)
+            to_time - other.to_time
+          elsif other.respond_to?(:to_d)
+            DateTimeType.new(zoned_date_time.minus_nanos((other.to_d * 1_000_000_000).to_i))
+          elsif other.respond_to?(:coerce) && (lhs, rhs = other.coerce(to_d))
+            lhs - rhs
+          else
+            raise TypeError, "\#{other.class} can't be coerced into \#{self.class}"
+          end
+        end
+      end
+    end
+  end
+end
+
+# @!parse DateTimeType = OpenHAB::Core::Types::DateTimeType