openhab-jrubyscripting 5.0.0.rc5 → 5.0.0.rc6

data/lib/openhab/core/value_cache.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+OpenHAB::Core.import_preset("cache")
+unless defined?($sharedCache)
+  $sharedCache = nil
+  return
+end
+
+module OpenHAB
+  module Core
+    # @interface
+    java_import org.openhab.core.automation.module.script.rulesupport.shared.ValueCache
+
+    #
+    # ValueCache is the interface used to access a
+    # {OpenHAB::DSL.shared_cache shared cache} available between scripts and/or
+    # rule executions.
+    #
+    # While ValueCache looks somewhat like a Hash, it does not support
+    # iteration of the contained elements. So it's limited to strictly storing,
+    # fetching, or removing known elements.
+    #
+    # Shared caches are _not_ persisted between openHAB restarts. And in fact,
+    # if all scripts are unloaded that reference a particular key, that key is
+    # removed.
+    #
+    # @note Only the {OpenHAB::DSL.shared_cache sharedCache} is exposed in Ruby.
+    #   For a private cache, simply use an instance variable. See
+    #   {file:docs/ruby-basics.md#Variables Instance Variables}.
+    #
+    # @note Because every script or UI rule gets it own JRuby engine instance,
+    #   you cannot rely on being able to access Ruby objects between them. Only
+    #   objects that implement a Java interface that's part of Java or openHAB
+    #   Core (such as Hash implements {java.util.Map}, or other basic
+    #   datatypes) can be reliably stored and accessed from the shared cache.
+    #   Likewise, you can use the cache to access data from other scripting
+    #   languages, but they'll be all but useless in Ruby. It's best to stick
+    #   to simple data types. If you're having troubles, serializing to_json
+    #   before storing may help.
+    #
+    # @see https://www.openhab.org/docs/configuration/jsr223.html#cache-preset openHAB Cache Preset
+    #
+    # @example
+    #   shared_cache.compute_if_absent(:execution_count) { 0 }
+    #   shared_cache[:execution_count] += 1
+    #
+    module ValueCache
+      # @see https://ruby-doc.org/core-3.1.2/Hash.html#method-i-5B-5D Hash#[]
+      def [](key)
+        get(key.to_s)
+      end
+
+      #
+      # Compute and store new value for key if the key is absent. This method is atomic.
+      #
+      # @param [String] key
+      # @yieldreturn [Object] new value
+      # @return [Object] new value or current value
+      #
+      def compute_if_absent(key, &block)
+        get(key.to_s, &block)
+      end
+
+      # @see https://ruby-doc.org/core-3.1.2/Hash.html#method-i-5B-5D-3D Hash#[]=
+      def []=(key, value)
+        put(key.to_s, value)
+      end
+      alias_method :store, :[]
+
+      # @see https://ruby-doc.org/core-3.1.2/Hash.html#method-i-delete Hash#delete
+      def delete(key)
+        key = key.to_s
+        if block_given?
+          fetch(key) do
+            return yield(key)
+          end
+        end
+        remove(key)
+      end
+
+      # @see https://ruby-doc.org/core-3.1.2/Hash.html#method-i-fetch Hash#fetch
+      #
+      # @example
+      #   shared_cache.fetch(:key_from_another_script) # raises NoKeyError
+      #
+      def fetch(key, *default_value)
+        if default_value.length > 1
+          raise ArgumentError,
+                "wrong number of arguments (given #{default_value.length + 1}, expected 0..1)"
+        end
+
+        key = key.to_s
+        if default_value.empty?
+          if block_given?
+            get(key) do
+              return yield(key)
+            end
+          else
+            get(key) do
+              raise KeyError.new("key not found: #{key.inspect}", key: key)
+            end
+          end
+        else
+          get(key) { return default_value.first }
+        end
+      end
+
+      # @see https://ruby-doc.org/core-3.1.2/Hash.html#method-i-assoc Hash#assoc
+      def assoc(key)
+        [key, fetch(key) do
+          # return nil directly, without storing a value to the cache
+          return nil
+        end]
+      end
+
+      # @see https://ruby-doc.org/core-3.1.2/Hash.html#method-i-dig Hash#dig
+      def dig(key, *identifiers)
+        r = fetch(key) { return nil }
+        r&.dig(*identifiers)
+      end
+
+      # @see https://ruby-doc.org/core-3.1.2/Hash.html#method-i-fetch_values Hash#fetch_values
+      def fetch_values(*keys, &block)
+        result = []
+        keys.each do |key|
+          if block
+            result << fetch(key, &block)
+          else
+            has_value = true
+            value = fetch(key) { has_value = false }
+            result << value if has_value
+          end
+        end
+        result
+      end
+
+      # @see https://ruby-doc.org/core-3.1.2/Hash.html#method-i-key-3F Hash#key?
+      def key?(key)
+        !!fetch(key) { return false }
+      end
+      alias_method :has_key?, :key?
+      alias_method :include?, :key?
+      alias_method :member?, :key?
+
+      # @see https://ruby-doc.org/core-3.1.2/Hash.html#method-i-merge-21 Hash#merge!
+      def merge!(*other_hashes)
+        other_hashes.each do |hash|
+          hash.each do |(k, v)|
+            k = k.to_s
+            if block_given?
+              dup = true
+              old_value = fetch(k) do
+                dup = false
+              end
+              self[k] = dup ? yield(k, old_value, v) : v
+            else
+              self[k] = v
+            end
+          end
+        end
+        self
+      end
+      alias_method :update, :merge!
+
+      # @see https://ruby-doc.org/core-3.1.2/Hash.html#method-i-slice Hash#slice
+      def slice(*keys)
+        result = {}
+        keys.each do |k|
+          k = k.to_s
+          result[k] = self[k] if key?(k)
+        end
+        result
+      end
+
+      # @see https://ruby-doc.org/core-3.1.2/Hash.html#method-i-to_proc Hash#to_proc
+      def to_proc
+        @to_proc ||= ->(k) { self[k] }
+      end
+
+      # @see https://ruby-doc.org/core-3.1.2/Hash.html#method-i-values_at Hash#values_at
+      def values_at(*keys)
+        keys.map do |k|
+          self[k]
+        end
+      end
+    end
+  end
+end

data/lib/openhab/core.rb

@@ -1,21 +1,14 @@
 # frozen_string_literal: true
 
-# several classes rely on this, so force it to load earlier
-require_relative "core/provider"
-
-Dir[File.expand_path("core/**/*.rb", __dir__)].sort.each do |f|
-  require f
-end
-
 module OpenHAB
-  # Contains classes and modules that wrap actual OpenHAB objects
+  # Contains classes and modules that wrap actual openHAB objects
   module Core
-    # The OpenHAB Version. >= 3.3.0 is required.
+    # The openHAB Version. >= 3.3.0 is required.
     # @return [String]
     VERSION = org.openhab.core.OpenHAB.version.freeze
 
     unless Gem::Version.new(VERSION) >= Gem::Version.new("3.3.0")
-      raise "`openhab-jrubyscripting` requires OpenHAB >= 3.3.0"
+      raise "`openhab-jrubyscripting` requires openHAB >= 3.3.0"
     end
 
     # @return [Integer] Number of seconds to wait between checks for automation manager
@@ -23,18 +16,18 @@ module OpenHAB
     private_constant :CHECK_DELAY
     class << self
       #
-      # Wait until OpenHAB engine ready to process
+      # Wait until openHAB engine ready to process
       #
       # @return [void]
       #
       # @!visibility private
       def wait_till_openhab_ready
-        logger.trace("Checking readiness of OpenHAB")
+        logger.trace("Checking readiness of openHAB")
         until automation_manager
           logger.trace("Automation manager not loaded, checking again in #{CHECK_DELAY} seconds.")
           sleep CHECK_DELAY
         end
-        logger.trace "Automation manager instantiated, OpenHAB ready for rule processing."
+        logger.trace "Automation manager instantiated, openHAB ready for rule processing."
       end
 
       #
@@ -48,11 +41,60 @@ module OpenHAB
       #
       # @!attribute [r] automation_manager
       # @return [org.openhab.core.automation.module.script.rulesupport.shared.ScriptedAutomationManager]
-      #   The OpenHAB Automation manager.
+      #   The openHAB Automation manager.
       #
       def automation_manager
-        $scriptExtension.get("automationManager")
+        $se.get("automationManager")
+      end
+
+      #
+      # Imports a specific script extension preset into the global namespace
+      #
+      # @param [String] preset
+      # @return [void]
+      #
+      def import_preset(preset)
+        import_scope_values($se.import_preset(preset))
+      end
+
+      #
+      # Imports all default script extension presets into the global namespace
+      #
+      # @!visibility private
+      # @return [void]
+      #
+      def import_default_presets
+        $se.default_presets.each { |preset| import_preset(preset) }
+      end
+
+      #
+      # Imports concrete scope values into the global namespace
+      #
+      # @param [java.util.Map<String, Object>] scope_values
+      # @!visibility private
+      # @return [void]
+      #
+      def import_scope_values(scope_values)
+        scope_values.for_each do |key, value|
+          # convert Java classes to Ruby classes
+          value = value.ruby_class if value.is_a?(java.lang.Class) # rubocop:disable Lint/UselessAssignment
+          # variables are globals; constants go into the global namespace
+          key = case key[0]
+                when "a".."z" then "$#{key}"
+                when "A".."Z" then "::#{key}"
+                end
+          eval("#{key} = value unless defined?(#{key})", nil, __FILE__, __LINE__) # rubocop:disable Security/Eval
+        end
       end
     end
+
+    import_default_presets
   end
 end
+
+# several classes rely on this, so force it to load earlier
+require_relative "core/provider"
+
+Dir[File.expand_path("core/**/*.rb", __dir__)].sort.each do |f|
+  require f
+end

data/lib/openhab/core_ext/ruby/symbol.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+# Extensions to Symbol
+class Symbol
+  # Ruby 3.0 already has #name
+  alias_method :name, :to_s unless instance_methods.include?(:name)
+end

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

@@ -3,36 +3,40 @@
 module OpenHAB
   module DSL
     #
-    # Contains extensions to simplify working with [GenericItem]s.
+    # Contains extensions to simplify working with {Item Items}.
     #
     module Items
-      # An item builder allows you to dynamically create OpenHAB items at runtime.
+      # An item builder allows you to dynamically create openHAB items at runtime.
       # This can be useful either to create items as soon as the script loads,
       # or even later based on a rule executing.
       #
       # @example
       #   items.build do
-      #     switch_item "MySwitch", "My Switch"
-      #     switch_item "NotAutoupdating", autoupdate: false, channel: "mqtt:topic:1#light"
-      #     group_item "MyGroup" do
-      #       contact_item "ItemInGroup", channel: "binding:thing#channel"
+      #     switch_item MySwitch, "My Switch"
+      #     switch_item NotAutoupdating, autoupdate: false, channel: "mqtt:topic:1#light"
+      #     group_item MyGroup do
+      #       contact_item ItemInGroup, channel: "binding:thing#channel"
       #     end
       #     # passing `thing` to a group item will automatically use it as the base
       #     # for item channels
-      #     group_item "Equipment", tags: Semantics::HVAC, thing: "binding:thing"
-      #       string_item "Mode", tags: Semantics::Control, channel: "mode"
+      #     group_item Equipment, tags: Semantics::HVAC, thing: "binding:thing"
+      #       string_item Mode, tags: Semantics::Control, channel: "mode"
       #     end
       #   end
+      #
       module Builder
         include Core::EntityLookup
 
+        self.create_dummy_items = true
+
         class << self
           private
 
           # @!macro def_item_method
           #   @!method $1_item(name, label = nil, **kwargs)
           #   Create a new $1 item
-          #   @param name [String] The name for the new item
+          #   @param name [String, Symbol, Core::Items::Proxy] The name for the new item.
+          #     Note that you can use a string, a symbol, or even a literal constant name
           #   @param label [String] The item label
           #   @yieldparam [ItemBuilder] builder Item for further customization
           #   @see ItemBuilder#initialize ItemBuilder#initialize for additional arguments.
@@ -233,6 +237,7 @@ module OpenHAB
           raise ArgumentError, "`name` cannot be nil" if name.nil?
           raise ArgumentError, "`dimension` can only be specified with NumberItem" if dimension && type != :number
 
+          name = name.name if name.respond_to?(:name)
           if provider.is_a?(GroupItemBuilder)
             name = "#{provider.name_base}#{name}"
             label = "#{provider.label_base}#{label}".strip if label
@@ -365,7 +370,7 @@ module OpenHAB
         #
         # @example
         #   items.build do
-        #     date_time_item "Bedroom_Light_Updated" do
+        #     date_time_item Bedroom_Light_Updated do
         #       channel "hue:0210:1:bulb1:color", profile: "system:timestamp-update"
         #     end
         #   end
@@ -469,6 +474,8 @@ module OpenHAB
         include Builder
 
         Builder.public_instance_methods.each do |m|
+          next unless Builder.instance_method(m).owner == Builder
+
           class_eval <<~RUBY, __FILE__, __LINE__ + 1
             def #{m}(*args, groups: nil, **kwargs)  # def dimmer_item(*args, groups: nil, **kwargs)
               groups ||= []                         #   groups ||= []

data/lib/openhab/dsl/items/ensure.rb

@@ -7,7 +7,7 @@ module OpenHAB
     module Items
       # Functionality to implement `ensure`/`ensure_states`
       module Ensure
-        # Contains the `ensure` method mixed into {GenericItem} and {GroupItem::Members}
+        # Contains the `ensure` method mixed into {Item} and {GroupItem::Members}
         module Ensurable
           # Fluent method call that you can chain commands on to, that will
           # then automatically ensure that the item is not in the command's
@@ -18,15 +18,15 @@ module OpenHAB
           # @example Turn on all switches in a group that aren't already on
           #   MySwitchGroup.members.ensure.on
           def ensure
-            GenericItemDelegate.new(self)
+            ItemDelegate.new(self)
           end
         end
 
-        # Extensions for {::GenericItem} to implement {Ensure}'s functionality
+        # Extensions for {::Item} to implement {Ensure}'s functionality
         #
         # @see OpenHAB::DSL.ensure ensure
         # @see OpenHAB::DSL.ensure_states ensure_states
-        module GenericItem
+        module Item
           include Ensurable
 
           Core::Items::GenericItem.prepend(self)
@@ -63,7 +63,7 @@ module OpenHAB
         # "anonymous" class that wraps any method call in `ensure_states`
         # before forwarding to the wrapped object
         # @!visibility private
-        class GenericItemDelegate
+        class ItemDelegate
           def initialize(item)
             @item = item
           end

data/lib/openhab/dsl/items/timed_command.rb

@@ -3,7 +3,7 @@
 module OpenHAB
   module DSL
     module Items
-      # Extensions for {GenericItem} to implement timed commands
+      # Extensions for {Item} to implement timed commands
       #
       # All items have an implicit timer associated with them, enabling to
       # easily set an item into a specific state for a specified duration and
@@ -28,7 +28,7 @@ module OpenHAB
         # Provides information about why the expiration block of a
         # {TimedCommand#command timed command} is being called.
         #
-        # @attr [GenericItem] item
+        # @attr [Item] item
         #   @!visibility private
         # @attr [Types::Type, Proc] on_expire
         #   @!visibility private
@@ -205,8 +205,8 @@ module OpenHAB
           #
           # Execute the rule
           #
-          # @param [Map] _mod map provided by OpenHAB rules engine
-          # @param [Map] inputs map provided by OpenHAB rules engine containing event and other information
+          # @param [java.util.Map] _mod map provided by openHAB rules engine
+          # @param [java.util.Map] inputs map provided by openHAB rules engine containing event and other information
           #
           def execute(_mod = nil, inputs = nil)
             ThreadLocal.thread_local(**@thread_locals) do

data/lib/openhab/dsl/rules/automation_rule.rb

@@ -8,6 +8,20 @@ module OpenHAB
       #
       # @!visibility private
       class AutomationRule < org.openhab.core.automation.module.script.rulesupport.shared.simple.SimpleRule
+        # @!visibility private
+        INPUT_KEY_PATTERN = /^[a-z_]+[a-zA-Z0-9_]*$/.freeze
+
+        class << self
+          #
+          # Caches dynamically generated Struct classes so that they don't have
+          # to be re-generated for every event, blowing the method cache.
+          #
+          # @!visibility private
+          # @return [java.util.Map<Array<Symbol>, Class>]
+          attr_reader :event_structs
+        end
+        @event_structs = java.util.concurrent.ConcurrentHashMap.new
+
         field_writer :uid
 
         #
@@ -41,8 +55,8 @@ module OpenHAB
         #
         # Execute the rule
         #
-        # @param [Map] mod map provided by OpenHAB rules engine
-        # @param [Map] inputs map provided by OpenHAB rules engine containing event and other information
+        # @param [java.util.Map] mod map provided by openHAB rules engine
+        # @param [java.util.Map] inputs map provided by openHAB rules engine containing event and other information
         #
         #
         def execute(mod = nil, inputs = nil)
@@ -50,7 +64,8 @@ module OpenHAB
             logger.trace { "Execute called with mod (#{mod&.to_string}) and inputs (#{inputs.inspect})" }
             logger.trace { "Event details #{inputs["event"].inspect}" } if inputs&.key?("event")
             trigger_conditions(inputs).process(mod: mod, inputs: inputs) do
-              process_queue(create_queue(inputs), mod, inputs)
+              event = extract_event(inputs)
+              process_queue(create_queue(event), mod, event)
             end
           rescue Exception => e
             raise if defined?(::RSpec)
@@ -87,11 +102,11 @@ module OpenHAB
         #
         # Create the run queue based on guards
         #
-        # @param [Map] inputs rule inputs
+        # @param [Map] event Event object
         # @return [Queue] <description>
         #
-        def create_queue(inputs)
-          case check_guards(event: extract_event(inputs))
+        def create_queue(event)
+          case check_guards(event: event)
           when true
             @run_queue.dup.grep_v(BuilderDSL::Otherwise)
           when false
@@ -108,12 +123,30 @@ module OpenHAB
         # @return [Object] event object
         #
         def extract_event(inputs)
-          event = inputs&.dig("event")
-          unless event
-            event = Struct.new(:event, :attachment, :command).new
-            event.command = inputs&.dig("command")
+          attachment = @attachments[trigger_id(inputs)]
+          if inputs&.key?("event")
+            event = inputs["event"]
+            unless event
+              if attachment
+                logger.warn("Unable to attach #{attachment.inspect} to event " \
+                            "object for rule #{uid} since the event is nil.")
+              end
+              return nil
+            end
+
+            event.attachment = attachment
+            return event
           end
-          add_attachment(event, inputs)
+
+          inputs = inputs.to_h
+                         .select { |key, _value| key != "module" && INPUT_KEY_PATTERN.match?(key) }
+                         .transform_keys(&:to_sym)
+          inputs[:attachment] = attachment
+          keys = inputs.keys.sort
+          struct_class = self.class.event_structs.compute_if_absent(keys) do
+            Struct.new(*keys, keyword_init: true)
+          end
+          struct_class.new(**inputs)
         end
 
         #
@@ -128,35 +161,18 @@ module OpenHAB
         #
         # Returns trigger conditions from inputs if it exists
         #
-        # @param [Map] inputs map from OpenHAB containing UID
+        # @param [java.util.Map] inputs map from openHAB containing UID
         #
         # @return [Array] Array of trigger conditions that match rule UID
         #
         def trigger_conditions(inputs)
-          # Parse this to get the trigger UID:
-          # ["72698819-83cb-498a-8e61-5aab8b812623.event", "oldState", "module", \
-          #  "72698819-83cb-498a-8e61-5aab8b812623.oldState", "event", "newState",\
-          #  "72698819-83cb-498a-8e61-5aab8b812623.newState"]
           @trigger_conditions[trigger_id(inputs)]
         end
 
-        # If an attachment exists for the trigger for this event add it to the event object
-        # @param [Object] event Event
-        # @param [Hash] inputs Inputs into event
-        # @return [Object] Event with attachment added
-        #
-        def add_attachment(event, inputs)
-          attachment = @attachments[trigger_id(inputs)]
-          return event unless attachment
-
-          event.attachment = attachment
-          event
-        end
-
         #
         # Check if any guards prevent execution
         #
-        # @param [Map] event OpenHAB rule trigger event
+        # @param [Object] event openHAB rule trigger event
         #
         # @return [true,false] True if guards says rule should execute, false otherwise
         #
@@ -182,15 +198,13 @@ module OpenHAB
         # Process the run queue
         #
         # @param [Array] run_queue array of procs of various types to execute
-        # @param [Map] mod OpenHAB map object describing rule trigger
-        # @param [Map] inputs OpenHAB map object describing rule trigge
+        # @param [java.util/Map] mod openHAB map object describing rule trigger
+        # @param [Object] event openHAB map object describing rule trigger
         #
-        def process_queue(run_queue, mod, inputs)
-          event = extract_event(inputs)
-
+        def process_queue(run_queue, mod, event)
           while (task = run_queue.shift)
             if task.is_a?(BuilderDSL::Delay)
-              process_delay_task(inputs, mod, run_queue, task)
+              process_delay_task(event, mod, run_queue, task)
             else
               process_task(event, task)
             end
@@ -229,15 +243,15 @@ module OpenHAB
         #
         # Process delay task
         #
-        # @param [Map] inputs Rule trigger inputs
+        # @param [Map] event Rule trigger event
         # @param [Map] mod Rule modes
         # @param [Queue] run_queue Queue of tasks for this rule
         # @param [Delay] task to process
         #
         #
-        def process_delay_task(inputs, mod, run_queue, task)
+        def process_delay_task(event, mod, run_queue, task)
           remaining_queue = run_queue.slice!(0, run_queue.length)
-          DSL.after(task.duration) { process_queue(remaining_queue, mod, inputs) }
+          DSL.after(task.duration) { process_queue(remaining_queue, mod, event) }
         end
 
         #