Class: OpenHAB::Core::Events::Source

Inherits:
Delegator
  • Object
show all
Defined in:
lib/openhab/core/events/source.rb

Overview

Represents the source of an event as a chain of delegated Components.

This class behaves like a String representing the event source, but also provides methods to access the individual components in the delegation chain.

Starting from openHAB 5.1, the source can contain multiple components that contain information about the delegation chain of the event.

Each component contains:

  • bundle: The module or app. For example: org.openhab.automation.jrubyscripting when a rule sends a command, or org.openhab.core.io.rest when a command comes from the REST API (UI).
  • actor: Optional. The rule, user or thinguid (e.g., "lighting_rule", "mqtt:topic:livingroom-switch:switch4")

Examples:

Log commands with source information

rule "Log item commands" do
  received_command MyItem
  run do |event|
    logger.info "#{MyItem.name} received command #{event.command} from: #{event.source}"
    logger.info "  Source components:"
    event.source.components.each_with_index do |component, index|
      logger.info "    #{index}: bundle=#{component.bundle}, actor=#{component.actor}"
    end
  end
end

Ignore commands from specific integrations

rule "Ignore UI commands" do
  received_command MyItem
  run do |event|
    next if event.source.sender?("org.openhab.core.io.rest")
    # process the command
  end
end

See Also:

Defined Under Namespace

Classes: Component

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(source) ⇒ Source #initialize(components) ⇒ Source

Construct a new OpenHAB::Core::Events::Source object.

Overloads:

  • #initialize(source) ⇒ Source

    Parameters:

    • source (String) —

      The event source as a string.

  • #initialize(components) ⇒ Source

    Parameters:

    • components (Array<Component>) —

      The components in the event source delegation chain.



63
64
65
66
67
68
69
70
71
# File 'lib/openhab/core/events/source.rb', line 63

def initialize(source_or_components) # rubocop:disable Lint/MissingSuper
  @components = if source_or_components.is_a?(Array)
                  @source = nil
                  source_or_components.dup
                else
                  @source = -source_or_components
                  @source.split("=>").map { |s| Component.parse(s) }
                end.freeze
end

Instance Attribute Details

#actor ⇒ String? (readonly)

The actor (user, device, etc.) of the initial component that sent the event.

Returns:

  • (String, nil)


172
173
174
# File 'lib/openhab/core/events/source.rb', line 172

def actor
  components.first&.actor
end

#bundle ⇒ String? (readonly)

The bundle (module, app, etc.) of the initial component that sent the event.

Returns:

  • (String, nil)


162
163
164
# File 'lib/openhab/core/events/source.rb', line 162

def bundle
  components.first&.bundle
end

#components ⇒ Array<Component> (readonly)

The components in the event source delegation chain.

Returns:



52
53
54
# File 'lib/openhab/core/events/source.rb', line 52

def components
  @components
end

#source ⇒ String (readonly) Also known as: to_s, to_str, inspect, __getobj__

The event source as a string.

Returns:

  • (String)


152
153
154
# File 'lib/openhab/core/events/source.rb', line 152

def source
  @source ||= components.join("=>").freeze
end

Instance Method Details

#!=(other) ⇒ true, false

Returns:

  • (true, false)


190
191
192
# File 'lib/openhab/core/events/source.rb', line 190

def !=(other)
  !(self == other) # rubocop:disable Style/InverseMethods
end

#<=>(other) ⇒ Integer?

Returns:



195
196
197
198
199
200
# File 'lib/openhab/core/events/source.rb', line 195

def <=>(other)
  return 0 if self == other
  return nil unless other.respond_to?(:to_str)

  to_s <=> other.to_str
end

#==(other) ⇒ true, false

Returns:

  • (true, false)


182
183
184
185
186
187
# File 'lib/openhab/core/events/source.rb', line 182

def ==(other)
  return components == other.components if other.is_a?(Source)
  return to_s == other.to_str if other.respond_to?(:to_str)

  false
end

#actor_for(bundle) ⇒ String?

Returns the actor (user, device, etc.) for the specified bundle, if any.

Parameters:

  • bundle (#===) —

    The bundle (module, app, etc.) to find the actor for.

Returns:

  • (String, nil) —

    the actor (user, device, etc.) for the specified bundle, if any.



118
119
120
# File 'lib/openhab/core/events/source.rb', line 118

def actor_for(bundle)
  components.find { |c| bundle === c.bundle }&.actor # rubocop:disable Style/CaseEquality
end

#delegate(bundle, actor = nil) ⇒ Source

Construct a new OpenHAB::Core::Events::Source by adding an additional component to the delegation chain.

Parameters:

  • bundle (String) —

    The bundle (module, app, etc.) of the new component to add to the chain.

  • actor (String, nil) (defaults to: nil) —

    The actor (user, device, etc.) of the new component to add to the chain.

Returns:



80
81
82
# File 'lib/openhab/core/events/source.rb', line 80

def delegate(bundle, actor = nil)
  Source.new(components + [Component.build(bundle, actor)])
end

#eql?(other) ⇒ Boolean

Returns:

  • (Boolean)


202
203
204
# File 'lib/openhab/core/events/source.rb', line 202

def eql?(other)
  other.is_a?(Source) && components == other.components
end

#hash ⇒ Integer

Returns:



207
208
209
# File 'lib/openhab/core/events/source.rb', line 207

def hash
  components.hash
end

#reject(bundle) ⇒ Source #reject({ |component| ... }) {|component| ... } ⇒ Source

Construct a new OpenHAB::Core::Events::Source without any components from the specified bundle.

This is useful if you consider events from a specific bundle as sensitive, and want to filter that component out from an untrusted sender.

Overloads:

  • #reject(bundle) ⇒ Source

    Returns a new Source without any components from the specified bundle.

    Parameters:

    • bundle (#===) —

      The bundle (module, app, etc.) to reject.

    Returns:

    • (Source) —

      a new Source without any components from the specified bundle.

  • #reject({ |component| ... }) {|component| ... } ⇒ Source

    Returns a new Source without any components for which the block returns true.

    Yield Parameters:

    • component (Component) —

      Each component in the delegation chain.

    Returns:

    • (Source) —

      a new Source without any components for which the block returns true.

Raises:

  • (ArgumentError)


136
137
138
139
140
141
142
143
144
# File 'lib/openhab/core/events/source.rb', line 136

def reject(bundle = nil, &)
  raise ArgumentError, "Either a bundle or a block must be given" unless bundle || block_given?

  Source.new(if block_given?
               components.reject(&)
             else
               components.reject { |c| bundle === c.bundle } # rubocop:disable Style/CaseEquality
             end)
end

#sender?(bundle_or_actor) ⇒ true, false #sender?(bundle: nil, actor: nil) ⇒ true, false

Check if the event was sent by the specified bundle or actor.

Checks if any component matches the specified bundle or actor.

Overloads:

  • #sender?(bundle_or_actor) ⇒ true, false

    Parameters:

    • bundle_or_actor (#===) —

      The bundle (module, app, etc.) or actor (user, device, etc.) to check. If either a bundle or actor in any component in the source matches, this method returns true.

    Returns:

    • (true, false)
  • #sender?(bundle: nil, actor: nil) ⇒ true, false

    Parameters:

    • bundle (#===) (defaults to: nil)
    • actor (#===) (defaults to: nil)

    Returns:

    • (true, false)


100
101
102
103
104
105
106
107
108
109
110
111
112
# File 'lib/openhab/core/events/source.rb', line 100

def sender?(bundle_or_actor = nil, bundle: nil, actor: nil)
  unless bundle_or_actor || bundle || actor
    raise ArgumentError, "Specify one of bundle_or_actor, bundle or actor"
  end

  # rubocop:disable-next Style/CaseEquality
  components.any? do |sender|
    (bundle && bundle === sender.bundle) ||
      (actor && actor === sender.actor) ||
      (bundle_or_actor && bundle_or_actor === sender.bundle) ||
      (bundle_or_actor && bundle_or_actor === sender.actor)
  end
end