openhab-jrubyscripting 5.0.0.rc1

data/lib/openhab/dsl/rules/triggers/cron/cron_handler.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require_relative "cron"
+
+module OpenHAB
+  module DSL
+    module Rules
+      module Triggers
+        # @!visibility private
+        #
+        # Cron trigger handler that provides trigger ID
+        #
+        module CronHandler
+          # Cron Trigger Handler that provides trigger IDs
+          # Unfortunatly because the CronTriggerHandler in OpenHAB core is marked internal
+          # the entire thing must be recreated here
+          class CronTriggerHandler < org.openhab.core.automation.handler.BaseTriggerModuleHandler
+            include org.openhab.core.scheduler.SchedulerRunnable
+            include org.openhab.core.automation.handler.TimeBasedTriggerHandler
+
+            # Provides access to protected fields
+            field_accessor :callback
+
+            # Creates a new CronTriggerHandler
+            # @param [Trigger] trigger OpenHAB trigger associated with handler
+            #
+            def initialize(trigger)
+              @trigger = trigger
+              @scheduler = OSGi.service("org.openhab.core.scheduler.CronScheduler")
+              @schedule = nil
+              @expression = trigger.configuration.get("cronExpression")
+              super(trigger)
+            end
+
+            #
+            # Set the callback to execute when cron trigger fires
+            # @param [Object] callback to run
+            #
+            def setCallback(callback) # rubocop:disable Naming/MethodName
+              synchronized do
+                super(callback)
+                @schedule = @scheduler.schedule(self, @expression)
+                logger.trace("Scheduled cron job '#{@expression}' for trigger '#{@trigger.id}'.")
+              end
+            end
+
+            #
+            # Get the temporal adjuster
+            # @return [CronAdjuster]
+            #
+            def getTemporalAdjuster # rubocop:disable Naming/MethodName
+              org.openhab.core.scheduler.CronAdjuster.new(expression)
+            end
+
+            #
+            # Execute the callback
+            #
+            def run
+              callback&.triggered(@trigger, { "module" => @trigger.id })
+            end
+
+            #
+            # Displose of the handler
+            # cancel the cron scheduled task
+            #
+            def dispose
+              synchronized do
+                super
+                return unless @schedule
+
+                @schedule.cancel(true)
+                @schedule = nil
+              end
+              logger.trace("cancelled job for trigger '#{@trigger.id}'.")
+            end
+          end
+
+          # Implements the ScriptedTriggerHandlerFactory interface to create a new Cron Trigger Handler
+          class CronTriggerHandlerFactory
+            include org.openhab.core.automation.module.script.rulesupport.shared.factories.ScriptedTriggerHandlerFactory
+
+            # Invoked by the OpenHAB core to get a trigger handler for the supllied trigger
+            # @param [Trigger] trigger OpenHAB trigger
+            #
+            # @return [WatchTriggerHandler] trigger handler for supplied trigger
+            def get(trigger)
+              CronTriggerHandler.new(trigger)
+            end
+          end
+
+          class << self
+            private
+
+            #
+            # Creates trigger types and trigger type factories for OpenHAB
+            #
+            def add_script_cron_handler
+              Core.automation_manager.add_trigger_handler(
+                Cron::CRON_TRIGGER_MODULE_ID,
+                CronTriggerHandlerFactory.new
+              )
+
+              Core.automation_manager.add_trigger_type(cron_trigger_type)
+              logger.trace("Added script cron trigger handler")
+            end
+
+            #
+            # Creates trigger types and trigger type factories for OpenHAB
+            #
+            def cron_trigger_type
+              org.openhab.core.automation.type.TriggerType.new(
+                Cron::CRON_TRIGGER_MODULE_ID,
+                nil,
+                "A specific instant occurs",
+                "Triggers when the specified instant occurs",
+                nil,
+                org.openhab.core.automation.Visibility::VISIBLE,
+                nil
+              )
+            end
+          end
+          add_script_cron_handler
+        end
+      end
+    end
+  end
+end

data/lib/openhab/dsl/rules/triggers/trigger.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require "forwardable"
+
+module OpenHAB
+  module DSL
+    module Rules
+      module Triggers
+        # @!visibility private
+        #
+        # Class for creating and managing triggers
+        #
+        class Trigger
+          extend Forwardable
+
+          delegate append_trigger: :@rule_triggers
+
+          #
+          # Creates a new Trigger
+          # @param [RuleTrigger] rule_triggers rule trigger information
+          def initialize(rule_triggers:)
+            @rule_triggers = rule_triggers
+          end
+
+          #
+          # Create a trigger for a thing
+          #
+          # @param [Thing] thing to create trigger for
+          # @param [Trigger] type trigger to map with thing
+          # @param [State] to for thing
+          # @param [State] from state of thing
+          #
+          # @return [Array] Trigger and config for thing
+          #
+          def trigger_for_thing(thing:, type:, to: nil, from: nil)
+            config = { "thingUID" => thing.uid.to_s }
+            config["status"] = trigger_state_from_symbol(to).to_s if to
+            config["previousStatus"] = trigger_state_from_symbol(from).to_s if from
+            [type, config]
+          end
+
+          #
+          # converts object to upcase string if its a symbol
+          #
+          # @param [sym] sym potential symbol to convert
+          #
+          # @return [String] Upcased symbol as string
+          #
+          def trigger_state_from_symbol(sym)
+            sym.to_s.upcase if sym.is_a?(Symbol) || sym
+          end
+        end
+      end
+    end
+  end
+end

data/lib/openhab/dsl/rules/triggers/updated.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+require_relative "trigger"
+
+module OpenHAB
+  module DSL
+    module Rules
+      module Triggers
+        # @!visibility private
+        #
+        # Creates updated triggers
+        #
+        class Updated < Trigger
+          #
+          # Create the trigger
+          #
+          # @param [Object] item item to create trigger for
+          # @param [Item State] to state to restrict trigger to
+          # @param [Object] attach object to be attached to the trigger
+          #
+          # @return [Trigger] OpenHAB triggers
+          #
+          def trigger(item:, to:, attach:)
+            case to
+            when Range then range_trigger(item: item, to: to, attach: attach)
+            when Proc then proc_trigger(item: item, to: to, attach: attach)
+            else update_trigger(item: item, to: to, attach: attach)
+            end
+          end
+
+          private
+
+          # @return [String] A thing status update trigger
+          THING_UPDATE = "core.ThingStatusUpdateTrigger"
+
+          # @return [String] An item state update trigger
+          ITEM_STATE_UPDATE = "core.ItemStateUpdateTrigger"
+
+          # @return [String] A group state update trigger for items in the group
+          GROUP_STATE_UPDATE = "core.GroupStateUpdateTrigger"
+
+          #
+          # Creates a trigger with a range condition on the 'to' field
+          # @param [Object] item to create changed trigger on
+          # @param [Object] to state restrict trigger to
+          # @param [Object] attach object to be attached to the trigger
+          # @return [Trigger] OpenHAB trigger
+          #
+          def range_trigger(item:, to:, attach:)
+            to, * = Conditions::Proc.range_procs(to)
+            proc_trigger(item: item, to: to, attach: attach)
+          end
+
+          #
+          # Creates a trigger with a proc condition on the 'to' field
+          # @param [Object] item to create changed trigger on
+          # @param [Object] to state restrict trigger to
+          # @param [Object] attach object to be attached to the trigger
+          # @return [Trigger] OpenHAB trigger
+          #
+          def proc_trigger(item:, to:, attach:)
+            conditions = Conditions::Proc.new(to: to)
+            update_trigger(item: item, to: nil, attach: attach, conditions: conditions)
+          end
+
+          #
+          # Create a trigger for updates
+          #
+          # @param [Object] item Type of item [Group,Thing,Item] to create update trigger for
+          # @param [State] to state restriction on trigger
+          # @param [Object] attach object to be attached to the trigger
+          #
+          # @return [Trigger] OpenHAB triggers
+          #
+          def update_trigger(item:, to:, attach: nil, conditions: nil)
+            type, config = case item
+                           when GroupItem::Members then group_update(item: item, to: to)
+                           when Core::Things::Thing then thing_update(thing: item, to: to)
+                           else item_update(item: item, to: to)
+                           end
+            append_trigger(type: type, config: config, attach: attach, conditions: conditions)
+          end
+
+          #
+          # Create an update trigger for an item
+          #
+          # @param [Item] item to create trigger for
+          # @param [State] to optional state restriction for target
+          #
+          # @return [Array<Hash,String>] first element is a String specifying trigger type
+          #  second element is a Hash configuring trigger
+          #
+          def item_update(item:, to:)
+            config = { "itemName" => item.name }
+            config["state"] = to.to_s unless to.nil?
+            [ITEM_STATE_UPDATE, config]
+          end
+
+          #
+          # Create an update trigger for a group
+          #
+          # @param [Item] item to create trigger for
+          # @param [State] to optional state restriction for target
+          #
+          # @return [Array<Hash,String>] first element is a String specifying trigger type
+          #  second element is a Hash configuring trigger
+          #
+          def group_update(item:, to:)
+            config = { "groupName" => item.group.name }
+            config["state"] = to.to_s unless to.nil?
+            [GROUP_STATE_UPDATE, config]
+          end
+
+          #
+          # Create an update trigger for a thing
+          #
+          # @param [Thing] thing to create trigger for
+          # @param [State] to optional state restriction for target
+          #
+          # @return [Array<Hash,String>] first element is a String specifying trigger type
+          #  second element is a Hash configuring trigger
+          #
+          def thing_update(thing:, to:)
+            trigger_for_thing(thing: thing, type: THING_UPDATE, to: to)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/openhab/dsl/rules/triggers/watch/watch.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "openhab/dsl/rules/triggers/trigger"
+
+module OpenHAB
+  module DSL
+    module Rules
+      module Triggers
+        # @!visibility private
+        #
+        # Creates watch triggers
+        #
+        class Watch < Trigger
+          # Characters in an fnmatch compatible glob
+          GLOB_CHARS = ["**", "*", "?", "[", "]", "{", "}"].freeze
+          private_constant :GLOB_CHARS
+
+          #
+          # Automatically creates globs for supplied paths if necessary
+          #
+          # @param [Pathname] path to check
+          # @param [String] glob
+          #
+          # @return [Pathname,String] Pathname to watch and glob to match
+          #
+          def self.glob_for_path(path, glob)
+            # Checks if the supplied pathname last element contains a glob char
+            if GLOB_CHARS.any? { |char| path.basename.to_s.include? char }
+              # Splits the supplied pathname into a glob string and parent path
+              [path.basename.to_s, path.parent]
+            elsif path.file? || !path.exist?
+              # glob string matching end of Pathname and parent path
+              ["*/#{path.basename}", path.parent]
+            else
+              [glob, path]
+            end
+          end
+
+          #
+          # Create a watch trigger based on item type
+          #
+          # @param [Config] config Rule configuration
+          # @param [Object] attach object to be attached to the trigger
+          #
+          #
+          def trigger(config:, attach:)
+            append_trigger(type: WatchHandler::WATCH_TRIGGER_MODULE_ID,
+                           config: config,
+                           attach: attach)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/openhab/dsl/rules/triggers/watch/watch_handler.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+module OpenHAB
+  module DSL
+    module Rules
+      module Triggers
+        # @!visibility private
+        #
+        # Module for watching directories/files
+        #
+        module WatchHandler
+          #
+          # Creates trigger types and trigger type factories for OpenHAB
+          #
+          private_class_method def self.watch_trigger_type
+            org.openhab.core.automation.type.TriggerType.new(
+              WATCH_TRIGGER_MODULE_ID,
+              nil,
+              "A path change event is detected",
+              "Triggers when a path change event is detected",
+              nil,
+              org.openhab.core.automation.Visibility::VISIBLE,
+              nil
+            )
+          end
+
+          # Trigger ID for Watch Triggers
+          WATCH_TRIGGER_MODULE_ID = "jsr223.jruby.WatchTrigger"
+
+          # Extends the OpenHAB watch service to watch directories
+          #
+          # Must match java method name style
+          # rubocop:disable Naming/MethodName
+          class Watcher < org.openhab.core.service.AbstractWatchService
+            java_import java.nio.file.StandardWatchEventKinds
+
+            # Hash of event symbols as strings to map to NIO events
+            STRING_TO_EVENT = {
+              created: StandardWatchEventKinds::ENTRY_CREATE,
+              deleted: StandardWatchEventKinds::ENTRY_DELETE,
+              modified: StandardWatchEventKinds::ENTRY_MODIFY
+            }.transform_keys(&:to_s).freeze
+
+            # Hash of NIO event kinds to ruby symbols
+            EVENT_TO_SYMBOL = STRING_TO_EVENT.invert.transform_values(&:to_sym).freeze
+
+            # Creates a new Watch Service
+            def initialize(path, types, &block)
+              super(path)
+              @types = types.map { |type| STRING_TO_EVENT[type] }
+              @block = block
+            end
+
+            # Invoked by java super class to get type of events to watch for
+            # @param [String] _path ignored
+            #
+            # @return [Array] array of NIO event kinds
+            def getWatchEventKinds(_path)
+              @types
+            end
+
+            # Invoked by java super class to check if sub directories should be watched
+            # @return [false] false
+            def watchSubDirectories
+              false
+            end
+
+            # Invoked by java super class when an watch event occurs
+            # @param [String] _event ignored
+            # @param [StandardWatchEventKind] kind NIO watch event kind
+            # @param [java.nio.Path] path that had an event
+            def processWatchEvent(_event, kind, path)
+              @block.call(Events::WatchEvent.new(EVENT_TO_SYMBOL[kind], Pathname.new(path.to_s)))
+            end
+          end
+          # rubocop:enable Naming/MethodName
+
+          # Implements the OpenHAB TriggerHandler interface to process Watch Triggers
+          class WatchTriggerHandler
+            include org.openhab.core.automation.handler.TriggerHandler
+
+            # Creates a new WatchTriggerHandler
+            # @param [Trigger] trigger OpenHAB trigger associated with handler
+            #
+            def initialize(trigger)
+              @trigger = trigger
+              config = trigger.configuration.properties.to_hash.transform_keys(&:to_sym)
+              @path = config[:path]
+              @watcher = Watcher.new(@path, config[:types], &watch_event_handler(config[:glob]))
+              @watcher.activate
+              logger.trace("Created watcher for #{@path}")
+            end
+
+            # Create a lambda to use to invoke rule engine when file watch notification happens
+            # @param [String] glob to match for notification events
+            #
+            # @return [Lambda] lambda to execute on notification events
+            #
+            def watch_event_handler(glob)
+              lambda { |watch_event|
+                logger.trace("Received event(#{watch_event})")
+                if watch_event.path.fnmatch?(glob)
+                  @rule_engine_callback&.triggered(@trigger, { "event" => watch_event })
+                else
+                  logger.trace("Event #{watch_event} did not match glob(#{glob})")
+                end
+              }
+            end
+
+            # Called by OpenHAB to set the rule engine to invoke when triggered
+            # Must match java method name style
+            def setCallback(callback) # rubocop:disable Naming/MethodName
+              @rule_engine_callback = callback
+            end
+
+            #
+            # Dispose of handler which deactivates watcher
+            #
+            def dispose
+              logger.trace("Deactivating watcher for #{@path}")
+              @watcher&.deactivate
+            end
+          end
+
+          # Implements the ScriptedTriggerHandlerFactory interface to create a new Trigger Handler
+          class WatchTriggerHandlerFactory
+            include org.openhab.core.automation.module.script.rulesupport.shared.factories.ScriptedTriggerHandlerFactory
+
+            # Invoked by the OpenHAB core to get a trigger handler for the supllied trigger
+            # @param [Trigger] trigger OpenHAB trigger
+            #
+            # @return [WatchTriggerHandler] trigger handler for supplied trigger
+            def get(trigger)
+              WatchTriggerHandler.new(trigger)
+            end
+          end
+
+          #
+          # Creates trigger types and trigger type factories for OpenHAB
+          #
+          def self.add_watch_handler
+            Core.automation_manager.add_trigger_handler(
+              WATCH_TRIGGER_MODULE_ID,
+              WatchTriggerHandlerFactory.new
+            )
+
+            Core.automation_manager.add_trigger_type(watch_trigger_type)
+            logger.trace("Added watch trigger handler")
+          end
+          add_watch_handler
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module OpenHAB
+  module DSL
+    module Rules
+      # Contains helper classes for implementing triggers.
+      # @!visibility private
+      module Triggers
+      end
+    end
+  end
+end

data/lib/openhab/dsl/rules.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative "script_handling"
+
+module OpenHAB
+  module DSL
+    module Rules
+      @script_rules = {}
+
+      @scripted_rule_provider = OSGi.service(
+        "org.openhab.core.automation.module.script.rulesupport.shared.ScriptedRuleProvider"
+      )
+      class << self
+        # @!visibility private
+        attr_reader :script_rules, :scripted_rule_provider
+
+        #
+        # Cleanup rules in this script file
+        #
+        # @return [void]
+        #
+        def cleanup_rules
+          script_rules.each_value(&:cleanup)
+        end
+      end
+      ScriptHandling.script_unloaded { cleanup_rules }
+    end
+  end
+end

data/lib/openhab/dsl/script_handling.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module OpenHAB
+  module DSL
+    #
+    # Provide callback mechanisms for script handling
+    #
+    module ScriptHandling
+      module_function
+
+      #
+      # Add a block of code to be executed once the rule script has finished loading.
+      #
+      # This can occur on OpenHAB start up, when the script is first created, or updated.
+      #
+      # Multiple hooks can be added by calling {#script_loaded} multiple times.
+      # They can be used to perform final initializations.
+      #
+      # @return [void]
+      #
+      # @example
+      #   script_loaded do
+      #     logger.info 'Hi, this script has just finished loading'
+      #   end
+      #
+      # @example
+      #   script_loaded do
+      #     logger.info 'I will be called after the script finished loading too'
+      #   end
+      #
+      def script_loaded(&block)
+        Core::ScriptHandlingCallbacks.script_loaded_hooks << block
+      end
+
+      #
+      # Add a block of code to be executed when the script is unloaded.
+      #
+      # This can occur when OpenHAB shuts down, or when the script is being reloaded.
+      #
+      # Multiple hooks can be added by calling {#script_unloaded} multiple times.
+      # They can be used to perform final cleanup.
+      #
+      # @return [void]
+      #
+      # @example
+      #   script_unloaded do
+      #     logger.info 'Hi, this script has been unloaded'
+      #   end
+      #
+      def script_unloaded(&block)
+        Core::ScriptHandlingCallbacks.script_unloaded_hooks << block
+      end
+    end
+  end
+end