Class: Emittance::Event

Inherits:
Object
  • Object
show all
Defined in:
lib/emittance/event.rb

Overview

Basic usage of Emittance doesn’t require that you fiddle with objects of type Emittance::Event. However, this class is open for you to inherit from in the cases where you would like to customize some aspects of the event.

To define a custom event, just inherit from Emittance::Event:

class FooEvent < Emittance::Event
end

One common use case for this is to make sure all payloads share the same format. You can do this however you’d like. We’ve provided an InvalidPayloadError class for that purpose. Here’s one example of how that might happen:

class FooEvent < Emittance::Event
  def initialize(emitter, timestamp, payload)
    super
    validate_payload
  end

  private

  def validate_payload
    raise Emittance::InvalidPayloadError unless payload.is_a?(String)
  end
end

Identifiers

Events are identified by what we call “Identifiers.” These come in the form of symbols, and can be used to identify specific event types.

Identifier Naming

The naming convention for events and their identifiers goes like this: the name of an event class will be the CamelCase form of its identifier, plus the word Event. For example, FooEvent can be identified with :foo. Thus, the events received by watchers of :foo will be instances of FooEvent. Conversely, if you make an event class BarEvent that inherits from Emittance::Event, its built-in identifier will be :bar. You can see what a Emittance::Event subclass’s identifier is by calling .identifiers on it.

class SomethingHappenedEvent < Emittance::Event
end

MyEvent.identifiers
# => [:something_happened]

MyEvent.new.identifiers
# => [:something_happened]

The namespace resultion operator (::) in an event’s class name will translate to a / in the identifier name:

class Foo::BarEvent < Emittance::Event
end

Foo::BarEvent.identifiers
#=> [:'foo/bar']

Custom Identifiers

By default, the identifier for this event will be the snake_case form of the class name with Event chopped off:

FooEvent.identifiers
# => [:foo]

You can set a custom identifier for the event class like so:

FooEvent.add_identifier :bar
FooEvent.identifiers
# => [:foo, :bar]

Now, when emitters emit :bar, this will be the event received by watchers. #add_identifier will raise an IdentifierCollisionError if you attempt to add an identifier that has already been claimed. This error will also be raised if you try to add an identifier that already has an associated class. For example:

class FooEvent < Emittance::Event
end

class BarEvent < Emittance::Event
end

BarEvent.add_identifier :foo
# => Emittance::IdentifierCollisionError

This error is raised because, even though we haven’t explicitly add the identifier :foo for FooEvent, Emittance is smart enough to know that there exists a class whose name resolves to :foo.

It’s best to use custom identifiers very sparingly. One reason for this can be illustrated like so:

class FooEvent < Emittance::Event
end

FooEvent.add_identifier :bar
FooEvent.identifiers
# => [:foo, :bar]

class BarEvent < Emittance::Event
end

BarEvent.identifiers
# => []

Since BarEvent‘s default identifier was already reserved when it was created, it could not claim that identifier. We can manually add an identifier post-hoc, but this would nevertheless become confusing.

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(emitter, timestamp, payload) ⇒ Event

Returns a new instance of Event.

Parameters:

  • emitter —

    the object that emitted the event

  • timestamp (Time) —

    the time at which the event occurred

  • payload —

    any useful data that might be of use to event watchers



133
134
135
136
137
 
# File 'lib/emittance/event.rb', line 133

def initialize(emitter, timestamp, payload)
  @emitter = emitter
  @timestamp = timestamp
  @payload = payload
end

Instance Attribute Details

#emitter ⇒ Object (readonly)

Returns the value of attribute emitter.



128
129
130
 
# File 'lib/emittance/event.rb', line 128

def emitter
  @emitter
end

#payload ⇒ Object (readonly)

Returns the value of attribute payload.



128
129
130
 
# File 'lib/emittance/event.rb', line 128

def payload
  @payload
end

#timestamp ⇒ Object (readonly)

Returns the value of attribute timestamp.



128
129
130
 
# File 'lib/emittance/event.rb', line 128

def timestamp
  @timestamp
end

Class Method Details

.add_identifier(sym) ⇒ Object

Gives the Event object a custom identifier.

Parameters:

  • sym (Symbol) —

    the identifier you wish to identify this event by when emitting and watching for it

Raises:



116
117
118
119
 
# File 'lib/emittance/event.rb', line 116

def add_identifier(sym)
  raise Emittance::InvalidIdentifierError, 'Identifiers must respond to #to_sym' unless sym.respond_to?(:to_sym)
  EventLookup.register_identifier self, sym.to_sym
end

.event_klass_for(*identifiers) ⇒ Object

Parameters:

  • identifiers (*) —

    anything that can be derived into an identifier (or the event class itself) for the purposes of looking up an event class.



123
124
125
 
# File 'lib/emittance/event.rb', line 123

def event_klass_for(*identifiers)
  EventLookup.find_event_klass(*identifiers)
end

.identifiers ⇒ Array<Symbol>

Returns the identifier that can be used by the broker to find event handlers.

Returns:

  • (Array<Symbol>) —

    the identifier that can be used by the broker to find event handlers



109
110
111
 
# File 'lib/emittance/event.rb', line 109

def identifiers
  EventLookup.identifiers_for_klass(self).to_a
end

Instance Method Details

#identifiers ⇒ Array<Symbol>

Returns all identifiers that can be used to identify the event.

Returns:

  • (Array<Symbol>) —

    all identifiers that can be used to identify the event



140
141
142
 
# File 'lib/emittance/event.rb', line 140

def identifiers
  self.class.identifiers
end