openhab-jrubyscripting 5.0.0.rc1

data/lib/openhab/dsl/things/builder.rb

@@ -0,0 +1,263 @@
+# frozen_string_literal: true
+
+module OpenHAB
+  module DSL
+    #
+    # Contains extensions to simplify working with {Core::Things::Thing Thing}s.
+    #
+    module Things
+      # Stores all things created in scripts, and notifies the ThingRegistry
+      # of their existence
+      # aa@!visibility private
+      class ThingProvider < org.openhab.core.common.registry.AbstractProvider
+        include org.openhab.core.thing.ThingProvider
+        include Singleton
+
+        def initialize
+          super
+
+          @things = []
+
+          $things.add_provider(self)
+          ScriptHandling.script_unloaded { $things.remove_provider(self) }
+        end
+
+        # Add a thing to this provider
+        def add(thing)
+          thing = thing.build
+          @things << thing
+          notify_listeners_about_added_element(thing)
+          thing
+        end
+
+        # Get all items in this provider
+        def getAll # rubocop:disable Naming/MethodName required by java interface
+          @things
+        end
+      end
+
+      # A thing builder allows you to dynamically create OpenHAB thing at runtime.
+      # This can be useful either to create things as soon as the script loads,
+      # or even later based on a rule executing.
+      #
+      # @example
+      #   things.build do
+      #     thing "astro:sun:home", "Astro Sun Data", config: { "geolocation" => "0,0" }
+      #   end
+      class Builder
+        # Create a new Bridge
+        # @see BridgeBuilder#initialize
+        def bridge(*args, **kwargs, &block)
+          build(BridgeBuilder, *args, **kwargs, &block)
+        end
+
+        # Create a new Thing
+        # @see ThingBuilder#initialize
+        def thing(*args, **kwargs, &block)
+          build(ThingBuilder, *args, **kwargs, &block)
+        end
+
+        private
+
+        def build(klass, *args, **kwargs, &block)
+          builder = klass.new(*args, **kwargs)
+          builder.instance_eval(&block) if block
+          thing = ThingProvider.instance.add(builder)
+          thing = Core::Things::Proxy.new(thing)
+          thing.enable(enabled: builder.enabled) unless builder.enabled.nil?
+          thing
+        end
+      end
+
+      # The ThingBuilder DSL allows you to customize a thing
+      class ThingBuilder
+        # The label for this thing
+        # @return [String, nil]
+        attr_accessor :label
+        # The location for this thing
+        # @return [String, nil]
+        attr_accessor :location
+        # The id for this thing
+        # @return [Core::Things::ThingUID]
+        attr_reader :uid
+        # The type of this thing
+        # @return [ThingTypeUID]
+        attr_reader :thing_type_uid
+        # The bridge of this thing
+        # @return [Core::Things::ThingUID, nil]
+        attr_reader :bridge_uid
+        # The config for this thing
+        # @return [Hash, nil]
+        attr_reader :config
+        # If the thing should be enabled after it is created
+        # @return [true, false, nil]
+        attr_reader :enabled
+        # Explicitly configured channels on this thing
+        # @return [Array<ChannelBuilder>]
+        attr_reader :channels
+
+        class << self
+          # @!visibility private
+          def thing_type_registry
+            @thing_type_registry ||= OSGi.service("org.openhab.core.thing.type.ThingTypeRegistry")
+          end
+
+          # @!visibility private
+          def config_description_registry
+            @config_description_registry ||=
+              OSGi.service("org.openhab.core.config.core.ConfigDescriptionRegistry")
+          end
+
+          # @!visibility private
+          def thing_factory_helper
+            @thing_factory_helper ||= begin
+              # this is an internal class, so OSGi doesn't put it on the main class path,
+              # so we have to go find it ourselves manually
+              bundle = org.osgi.framework.FrameworkUtil.get_bundle(org.openhab.core.thing.Thing)
+              bundle.load_class("org.openhab.core.thing.internal.ThingFactoryHelper").ruby_class
+            end
+          end
+        end
+
+        def initialize(uid, label = nil, binding: nil, type: nil, bridge: nil, location: nil, config: {}, enabled: nil)
+          @channels = []
+          uid = uid.to_s
+          uid_segments = uid.split(org.openhab.core.common.AbstractUID::SEPARATOR)
+          @bridge_uid = nil
+          bridge = bridge.uid if bridge.is_a?(org.openhab.core.thing.Bridge) || bridge.is_a?(BridgeBuilder)
+          bridge = bridge&.to_s
+          bridge_segments = bridge&.split(org.openhab.core.common.AbstractUID::SEPARATOR) || []
+          type = type&.to_s
+
+          # infer missing components
+          type ||= uid_segments[0] if uid_segments.length == 2
+          type ||= uid_segments[1] if uid_segments.length > 2
+          binding ||= uid_segments[0] if uid_segments.length > 2
+          binding ||= bridge_segments[0] if bridge_segments && bridge_segments.length > 2
+
+          if bridge
+            bridge_segments.unshift(binding) if bridge_segments.length < 3
+            @bridge_uid = org.openhab.core.thing.ThingUID.new(*bridge_segments)
+          end
+
+          @uid = org.openhab.core.thing.ThingUID.new(*[binding, type, @bridge_uid&.id,
+                                                       uid_segments.last].compact)
+          @thing_type_uid = org.openhab.core.thing.ThingTypeUID.new(*@uid.all_segments[0..1])
+          @label = label
+          @location = location
+          @location = location.label if location.is_a?(GenericItem)
+          @config = config
+          @enabled = enabled
+        end
+
+        # Add an explicitly configured channel to this item
+        # @see ChannelBuilder#initialize
+        def channel(*args, **kwargs, &block)
+          channel = ChannelBuilder.new(*args, thing: self, **kwargs)
+          channel.instance_eval(&block) if block
+          @channels << channel
+        end
+
+        # @!visibility private
+        def build
+          configuration = org.openhab.core.config.core.Configuration.new(config)
+          if thing_type
+            self.class.thing_factory_helper.apply_default_configuration(
+              configuration, thing_type,
+              self.class.config_description_registry
+            )
+          end
+          builder = org.openhab.core.thing.binding.builder.ThingBuilder
+                       .create(thing_type_uid, uid)
+                       .with_label(label)
+                       .with_configuration(configuration)
+                       .with_bridge(bridge_uid)
+                       .with_channels(channels)
+
+          if thing_type
+            # can't use with_channels, or it will wipe out custom channels from above
+            self.class.thing_factory_helper.create_channels(thing_type, uid,
+                                                            self.class.config_description_registry).each do |channel|
+              builder.with_channel(channel)
+            end
+            builder.with_properties(thing_type.properties)
+          end
+
+          thing = builder.build
+          Core::Things.manager.set_enabled(uid, enabled) unless enabled.nil?
+          thing
+        end
+
+        private
+
+        def thing_type
+          @thing_type ||= self.class.thing_type_registry.get_thing_type(thing_type_uid)
+        end
+      end
+
+      # The BridgeBuilder DSL allows you to customize a thing
+      class BridgeBuilder < ThingBuilder
+        # Create a new Bridge with this Bridge as its Bridge
+        # @see BridgeBuilder#initialize
+        def bridge(*args, **kwargs, &block)
+          super(*args, bridge: self, **kwargs, &block)
+        end
+
+        # Create a new Thing with this Bridge as its Bridge
+        # @see ThingBuilder#initialize
+        def thing(*args, **kwargs, &block)
+          super(*args, bridge: self, **kwargs, &block)
+        end
+      end
+
+      # The ChannelBuilder DSL allows you to customize a channel
+      class ChannelBuilder
+        attr_accessor :label
+        attr_reader :uid, :parameters
+
+        def initialize(uid, type, label, thing:, group: nil, **parameters)
+          @thing = thing
+
+          uid = uid.to_s
+          uid_segments = uid.split(org.openhab.core.common.AbstractUID::SEPARATOR)
+          group_segments = uid_segments.last.split(org.openhab.core.thing.ChannelUID::CHANNEL_GROUP_SEPARATOR)
+          if group
+            if group_segments.length == 2
+              group_segments[0] = group
+            else
+              group_segments.unshift(group)
+            end
+            uid_segments[-1] = group_segments.join(org.openhab.core.thing.ChannelUID::CHANNEL_GROUP_SEPARATOR)
+          end
+          @uid = org.openhab.core.thing.ChannelUID.new(thing.uid, uid_segments.last)
+          unless type.is_a?(org.openhab.core.thing.ChannelTypeUID)
+            type = org.openhab.core.thing.ChannelTypeUID.new(thing.uid.binding_id,
+                                                             type)
+          end
+          @type = type
+          @label = label
+          @parameters = parameters
+        end
+
+        # @!visibility private
+        def build
+          org.openhab.core.thing.binding.builder.ChannelBuilder.create(uid)
+             .with_kind(kind)
+             .with_type(type)
+             .with_configuration(org.openhab.core.config.core.Configuration.new(parameters))
+             .build
+        end
+
+        private
+
+        def kind
+          if @type == :trigger
+            org.openhab.core.thing.type.ChannelKind::TRIGGER
+          else
+            org.openhab.core.thing.type.ChannelKind::STATE
+          end
+        end
+      end
+    end
+  end
+end

data/lib/openhab/dsl/thread_local.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module OpenHAB
+  module DSL
+    #
+    # Manages thread local variables for access inside of blocks
+    #
+    # @!visibility private
+    module ThreadLocal
+      module_function
+
+      # Keys to persist
+      KNOWN_KEYS = %i[
+        openhab_rule_uid
+        openhab_rule_type
+        openhab_units
+        openhab_persistence_service
+        openhab_ensure_states
+      ].freeze
+
+      #
+      # Fetch all {KNOWN_KEYS} from thread local storage.
+      #
+      # @return [Hash<Symbol=>Object>]
+      #
+      def persist
+        KNOWN_KEYS.to_h do |key|
+          [key, Thread.current[key]]
+        end
+      end
+
+      #
+      # Execute the supplied block with the supplied values set for the currently running thread
+      # The previous values for each key are restored after the block is executed
+      #
+      # @param [Hash] values Keys and values to set for running thread, if hash is nil no values are set
+      #
+      def thread_local(**values)
+        old_values = values.to_h { |key, _value| [key, Thread.current[key]] }
+        values.each { |key, value| Thread.current[key] = value }
+        logger.trace "Executing block with thread local context: #{values} - old context: #{old_values}"
+        yield
+      ensure
+        old_values.each { |key, value| Thread.current[key] = value }
+      end
+    end
+  end
+end

data/lib/openhab/dsl/timer_manager.rb

@@ -0,0 +1,191 @@
+# frozen_string_literal: true
+
+require "set"
+require "singleton"
+
+module OpenHAB
+  module DSL
+    #
+    # Manages timers created by {OpenHAB::DSL.after after}, or {#schedule}.
+    #
+    class TimerManager
+      include Singleton
+
+      ScriptHandling.script_unloaded { instance.cancel_all }
+
+      # @!visibility private
+      def initialize
+        # Tracks active timers
+        @timers = java.util.concurrent.ConcurrentHashMap.new
+        @timers_by_id = java.util.concurrent.ConcurrentHashMap.new
+      end
+
+      #
+      # Create a new timer, managing ids if necessary
+      #
+      # @!visibility private
+      def create(duration, thread_locals:, block:, id:, reschedule:)
+        if id
+          return @timers_by_id.compute(id) do |_key, old_timer|
+            # return the existing timer if we're only supposed to create a new
+            # timer when one doesn't already exist
+            next old_timer if !reschedule && old_timer
+
+            old_timer&.cancel
+            Core::Timer.new(duration, id: id, thread_locals: thread_locals, block: block)
+          end
+        end
+
+        Core::Timer.new(duration, id: id, thread_locals: thread_locals, block: block)
+      end
+
+      # Add a timer that is now active
+      # @!visibility private
+      def add(timer)
+        logger.trace("Adding #{timer} to timers")
+        @timers[timer] = 1
+      end
+
+      #
+      # Delete a timer that is no longer active
+      #
+      # @!visibility private
+      def delete(timer)
+        logger.trace("Removing #{timer} from timers")
+        @timers.remove(timer)
+        return unless timer.id
+
+        @timers_by_id.delete(timer.id)
+      end
+
+      #
+      # Cancel a single timer by id
+      #
+      # @param [Object] id
+      # @return [true, false] if the timer was able to be cancelled
+      #
+      def cancel(id)
+        result = false
+        @timers_by_id.compute_if_present(id) do |_key, timer|
+          result = timer.cancel
+          nil
+        end
+        result
+      end
+
+      #
+      # Reschedule a single timer by id
+      #
+      # @param [Object] id
+      # @param [java.time.temporal.TemporalAmount, #to_zoned_date_time, Proc, nil] duration
+      #   When to reschedule the timer for. `nil` to retain its current interval.
+      # @return [Timer, nil] the timer if it was rescheduled, otherwise `nil`
+      #
+      def reschedule(id, duration = nil)
+        @timers_by_id.compute_if_present(id) do |_key, timer|
+          timer.reschedule(duration)
+        end
+      end
+
+      #
+      # Schedule a timer by id
+      #
+      # Schedules a timer by id, but passes the current timer -- if it exists --
+      # to the block so that you can decide how you want to proceed based on that
+      # state. The timer is created in a thread-safe manner.
+      #
+      # @param [Object] id
+      # @yieldparam [Timer, nil] timer The existing timer with this id, if one exists.
+      # @yieldreturn [Timer, nil] A new timer to associate with this id, the existing
+      #   timer, or nil. If nil, any existing timer will be cancelled.
+      # @return [Timer, nil]
+      #
+      # @example Extend an existing timer, or schedule a new one
+      #   # This is technically the same functionality as just calling `after()` with an `id`,
+      #   # but allows you to performa extra steps if the timer is actually scheduled.
+      #   timers.schedule(item) do |timer|
+      #     next timer.tap(&:reschedule) if timer
+      #
+      #     notify("The lights were turned on")
+      #
+      #     after(30.seconds) { item.off }
+      #   end
+      #
+      # @example Keep trying to turn something on, up to 5 times
+      #   timers.schedule(item) do |timer|
+      #     next if timer # don't interrupt a retry cycle if it already exists
+      #
+      #     retries = 5
+      #     after(2.seconds) do |inner_timer|
+      #       next if (retries -= 1).zero?
+      #       next inner_timer.reschedule unless item.on?
+      #
+      #       item.on
+      #     end
+      #   end
+      #
+      def schedule(id)
+        @timers_by_id.compute(id) do |_key, timer|
+          new_timer = yield timer
+          raise ArgumentError, "Block must return a timer or nil" unless timer.is_a?(Core::Timer) || timer.nil?
+
+          if !new_timer.equal?(timer) && new_timer&.id
+            raise ArgumentError,
+                  "Do not schedule a new timer with an ID inside a #schedule block"
+          end
+
+          if timer&.cancelled?
+            new_timer = nil
+          elsif new_timer.nil? && !timer&.cancelled?
+            timer&.cancel
+          end
+          next unless new_timer
+
+          new_timer.id ||= id
+          if new_timer.id != id
+            raise ArgumentError,
+                  "The new timer cannot have a different ID than what you're attempting to schedule"
+          end
+
+          new_timer
+        end
+      end
+
+      #
+      # Checks if a timer exists by id
+      #
+      # @note This method is not recommended for normal use in rules.
+      #   Timers are prone to race conditions if accessed from multiple rules,
+      #   or from timers themselves. Rescheduling, canceling, or scheduling
+      #   a new timer based on the results of this method may cause problems,
+      #   since the state may have changed in the meantime. Instead, use
+      #   {OpenHAB::DSL.after after} with an `id`, {#cancel}, {#reschedule}, or
+      #   {#schedule} to perform those actions atomically.
+      #
+      # @param [Object] id
+      # @return [true, false]
+      #
+      def include?(id)
+        @timers_by_id.key?(id)
+      end
+      alias_method :key?, :include?
+      alias_method :member?, :include?
+
+      #
+      # Cancels all active timers in the current script/UI rule
+      #
+      # Including timers with or without an id.
+      #
+      # @return [void]
+      #
+      def cancel_all
+        logger.trace("Canceling #{@timers.length} timers")
+        # don't use #each, in case timers are scheduling more timers
+        until @timers.empty?
+          timer = @timers.keys.first
+          timer.cancel
+        end
+      end
+    end
+  end
+end

data/lib/openhab/dsl/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module OpenHAB
+  module DSL
+    # Version of OpenHAB helper libraries
+    # @return [String]
+    VERSION = "5.0.0.rc1"
+  end
+end