amqp-events 0.0.2 → 0.0.3

data/HISTORY

@@ -9,3 +9,7 @@
 == 0.0.2 / 2010-10-22
 
 * C# example extended
+
+== 0.0.3 / 2010-10-28
+
+* Project updated for RSpec 2

data/Rakefile

@@ -11,13 +11,7 @@ require 'version'
 CLASS_NAME = AMQP::Events
 VERSION = CLASS_NAME::VERSION
 
-begin
-  require 'rake'
-rescue LoadError
-  require 'rubygems'
-  gem 'rake', '~> 0.8.3.1'
-  require 'rake'
-end
+require 'rake'
 
 # Load rakefile tasks
 Dir['tasks/*.rake'].sort.each { |file| load file }

data/VERSION

@@ -1 +1 @@
-0.0.2
+0.0.3

data/lib/amqp-events.rb

@@ -17,10 +17,23 @@ module AMQP
         Pathname.glob(name.to_s).sort.each { |rb| require rb }
       end
     end
+
+    if RUBY_PLATFORM =~ /mingw|mswin|windows/ #Windows!
+      require 'uuid'
+      UUID = UUID
+    else
+      require 'em/pure_ruby' unless defined? EventMachine::UuidGenerator
+      UUID = EventMachine::UuidGenerator
+    end
+
+    class HandlerError < TypeError
+    end
+
+    class EventError < TypeError
+    end
   end
 end
 
 # Require all ruby source files located under directory lib/amqp-events
 # If you need files in specific order, you should specify it here before the glob
-AMQP::Events.require_libs %W[**/*]
-
+AMQP::Events.require_libs %W[events event **/*]

data/lib/amqp-events/event.rb

@@ -0,0 +1,140 @@
+module AMQP
+  module Events
+
+    # Represent Event that can be subscribed to (by subscribers/observers)
+    # All subscribed observers will be called when this Event 'fires'.
+    #
+    # TODO: Mutexes to synchronize @subscribers update/event fire ?
+    # http://github.com/snuxoll/ruby-event/blob/master/lib/ruby-event/event.rb
+    # TODO: Meta-methods that allow Events to fire on method invocations:
+    # http://github.com/nathankleyn/ruby_events/blob/85f8e6027fea22e9d828c91960ce2e4099a9a52f/lib/ruby_events.rb
+    # TODO: Add exception handling and subscribe/unsubscribe notifications:
+    # http://github.com/matsadler/rb-event-emitter/blob/master/lib/events.rb
+    class Event
+
+      class << self
+        protected :new
+
+        # Creates Event of appropriate subclass, depending on arguments
+        def create host, name, opts={}, &block
+          opts.empty? ? Event.new(host, name, &block ) : ExternalEvent.new(host, name, opts, &block)
+        end
+      end
+
+      attr_reader :host, :name, :subscribers
+      alias_method :listeners, :subscribers
+
+      def initialize(host, name)
+        @host = host
+        @name = name.to_sym
+        @subscribers = {}
+      end
+
+      # You can subscribe anything callable to the event, such as lambda/proc,
+      # method(:method_name), attached block or a custom Handler. The only requirements,
+      # it should respond to a #call and accept arguments given to Event#fire.
+      #
+      # You can give optional name to your subscriber. If you do, you can later
+      # unsubscribe it using this name. If you do not give subscriber a name, it will
+      # be auto-generated using its #name method and uuid.
+      #
+      # You can unsubscribe your subscriber later, provided you know its name.
+      #
+      # :call-seq:
+      #   event.subscribe("subscriber_name", proc{|*args| "Subscriber 1"})
+      #   event.subscribe("subscriber_name", method(:method_name))
+      #   event.subscribe(method(:method_name) # Implicit subscriber name == :method_name
+      #   event.subscribe("subscriber_name") {|*args| "Named subscriber block" }
+      #   event += method(:method_name)  # C# compatible syntax, just without useless "delegates"
+      #
+      def subscribe(*args, &block)
+        subscriber = block ? block : args.pop
+        name = args.empty? ? generate_subscriber_name(subscriber) : args.first.to_sym
+
+        raise HandlerError.new "Handler #{subscriber.inspect} does not respond to #call" unless subscriber.respond_to? :call
+        raise HandlerError.new "Handler name #{name} already in use" if @subscribers.has_key? name
+        @subscribers[name] = subscriber
+
+        self # This allows C#-like syntax : my_event += subscriber
+      end
+
+      # Unsubscribe existing subscriber by name
+      def unsubscribe(name)
+        raise HandlerError.new "Unable to unsubscribe handler #{name}" unless @subscribers.has_key? name
+        @subscribers.delete(name)
+
+        self # This allows C#-like syntax : my_event -= subscriber
+      end
+
+      # TODO: make fire async: just fire and continue, instead of waiting for all subscribers to return,
+      # as it is right now. AMQP callbacks and EM:Deferrable?
+      def fire(*args)
+        @subscribers.each do |key, subscriber|
+          subscriber.call *args
+        end
+      end
+
+      alias_method :listen, :subscribe
+      alias_method :+, :subscribe
+      alias_method :remove, :unsubscribe
+      alias_method :-, :unsubscribe
+      alias_method :call, :fire
+
+      # Clears all the subscribers for a given Event
+      def clear
+        @subscribers.clear
+      end
+
+      def == (other)
+        case other
+          when Event
+            super
+          when nil
+            @subscribers.empty?
+          else
+            false
+        end
+      end
+
+      private
+      def generate_subscriber_name(subscriber)
+        "#{subscriber.respond_to?(:name) ? subscriber.name : 'subscriber'}-#{UUID.generate}".to_sym
+      end
+    end
+
+
+    # Represent external Event that can be subscribed to (by subscribers/observers).
+    # External means, it happens outside of this Ruby process, and is delivered through Transport.
+    # When Transport informs ExternalEvent that it happened (someplace else),
+    # ExternalEvent 'fires' and makes sure that all subscribers are called.
+    #
+    # Any evented object (host) that defines ExternalEvent should provide it with transport either
+    # explicitly (via option :transport) or expose its own #transport.
+    #
+    class ExternalEvent < Event
+      attr_reader :transport
+
+      def initialize(host, name, opts)
+        @routing = opts[:routing]
+        @transport = opts[:transport] || host.transport rescue nil
+        raise EventError.new "Unable to create ExternalEvent #{name.inspect} without routing" unless @routing
+        raise EventError.new "Unable to create ExternalEvent #{name.inspect} without transport" unless @transport
+        super host, name
+      end
+
+      # Subscribe to external event... Uses @host's transport for actual subscription
+      def subscribe(*args, &block)
+        super *args, &block
+        @transport.subscribe(@routing) {|routing, data| fire(routing, data) } if @subscribers.size == 1
+        self # This allows C#-like syntax : my_event += subscriber
+      end
+
+      # Unsubscribe from external event... Cancels @host's transport subscription if no subscribers left
+      def unsubscribe(name)
+        super name
+        @transport.unsubscribe(@routing) if @subscribers.empty?
+        self # This allows C#-like syntax : my_event -= subscriber_name
+      end
+    end
+  end
+end

data/lib/amqp-events/event_manager.rb

@@ -0,0 +1,19 @@
+#require 'mq'
+
+module AMQP
+  module Events
+
+    # Exposes external Events (received via transport) as its own local Events:
+    #
+    class EventManager
+      include AMQP::Events
+
+      attr_accessor :transport
+
+      def initialize(transport)
+        @transport = transport
+      end
+
+    end
+  end
+end

data/lib/amqp-events/events.rb

@@ -1,157 +1,78 @@
 module AMQP
   module Events
-    if RUBY_PLATFORM =~ /mingw|mswin|windows/ #Windows!
-      require 'uuid'
-      UUID = UUID
-    else
-      require 'em/pure_ruby'
-      UUID = EventMachine::UuidGenerator
-    end
-
-    class HandlerError < TypeError
-    end
-
-    # TODO: Mutexes to synchronize @subscribers update ?
-    # http://github.com/snuxoll/ruby-event/blob/master/lib/ruby-event/event.rb
-    # TODO: Meta-methods that allow Events to fire on method invocations:
-    # http://github.com/nathankleyn/ruby_events/blob/85f8e6027fea22e9d828c91960ce2e4099a9a52f/lib/ruby_events.rb
-    # TODO: Add exception handling and subscribe/unsubscribe notifications:
-    # http://github.com/matsadler/rb-event-emitter/blob/master/lib/events.rb
-    class Event
-
-      attr_reader :name, :subscribers
-      alias_method :listeners, :subscribers
-
-      def initialize(name)
-        @name = name
-        @subscribers = {}
-      end
-
-      # You can subscribe anything callable to the event, such as lambda/proc,
-      # method(:method_name), attached block or a custom Handler. The only requirements,
-      # it should respond to a #call and accept arguments given to Event#fire.
-      #
-      # You can give optional name to your subscriber. If you do, you can later
-      # unsubscribe it using this name. If you do not give subscriber a name, it will
-      # be auto-generated using its #name method and uuid.
-      #
-      # You can unsubscribe your subscriber later, provided you know its name.
-      #
-      # :call-seq:
-      #   event.subscribe("subscriber_name", proc{|*args| "Subscriber 1"})
-      #   event.subscribe("subscriber_name", method(:method_name))
-      #   event.subscribe(method(:method_name) # Implicit subscriber name == :method_name
-      #   event.subscribe("subscriber_name") {|*args| "Named subscriber block" }
-      #   event += method(:method_name)  # C# compatible syntax, just without useless "delegates"
-      #
-      def subscribe(*args, &block)
-        subscriber = block ? block : args.pop
-        name = args.empty? ? generate_subscriber_name(subscriber) : args.first
-
-        raise HandlerError.new "Handler #{subscriber.inspect} does not respond to #call" unless subscriber.respond_to? :call
-        raise HandlerError.new "Handler name #{name} already in use" if @subscribers.has_key? name
-        @subscribers[name] = subscriber
-
-        self # This allows C#-like syntax : my_event += subscriber
-      end
-
-      alias_method :listen, :subscribe
-      alias_method :+, :subscribe
-
-      # Unsubscribe existing subscriber by name
-      def unsubscribe(name)
-        raise HandlerError.new "Unable to unsubscribe handler #{name}" unless @subscribers.has_key? name
-        @subscribers.delete(name)
-
-        self # This allows C#-like syntax : my_event -= subscriber
-      end
-
-      alias_method :remove, :unsubscribe
-      alias_method :-, :unsubscribe
-
-      # TODO: make fire async: just fire and continue, instead of waiting for all subscribers to return,
-      # as it is right now. AMQP callbacks and EM:Deferrable?
-      def fire(*args)
-        @subscribers.each do |key, subscriber|
-          subscriber.call *args
-        end
-      end
-
-      alias_method :call, :fire
-
-      # Clears all the subscribers for a given Event
-      def clear
-        @subscribers.clear
-      end
 
-      def == (other)
-        case other
-          when Event
-            super
-          when nil
-            @subscribers.empty?
-          else
-            false
-        end
+    def events
+      @events ||= self.class.instance_events.inject({}) do |events, (name, opts)|
+        events[name] = Event.create(self, name, opts)
+        events
       end
+    end
 
-      private
-      def generate_subscriber_name(subscriber)
-        "#{subscriber.respond_to?(:name) ? subscriber.name : 'subscriber'}-#{UUID.generate}".to_sym
-      end
+    def event(name, opts = {})
+      sym_name = name.to_sym
+      self.class.event(sym_name, opts)
+      events[sym_name] ||= Event.create(self, sym_name, opts)
     end
 
-    def events
-      @events ||= self.class.instance_events.inject({}) { |hash, name| hash[name]=Event.new(name); hash }
+    # object#subscribe(:Event) is a sugar-coat for object.Event#subscribe
+    def subscribe(event, *args, &block)
+      event(event).subscribe(*args, &block)
     end
 
-    def event(name)
-      sym_name = name.to_sym
-      self.class.event(sym_name)
-      events[sym_name] ||= Event.new(sym_name)
+    # object#unsubscribe(:Event) is a sugar-coat for object.Event#unsubscribe
+    def unsubscribe(event, *args, &block)
+      raise HandlerError.new "Unable to unsubscribe, there is no event #{event}" unless events[event.to_sym]
+      events[event.to_sym].unsubscribe(*args, &block)
     end
 
+    alias_method :listen, :subscribe
+    alias_method :remove, :unsubscribe
+
 # Once included into a class/module, gives this module .event macros for declaring events
     def self.included(host)
 
       host.instance_exec do
         def instance_events
-          @instance_events ||= []
+          @instance_events ||= {}
         end
 
-        def event (name)
+        def event(name, opts = {})
+          sym_name = name.to_sym
 
-          instance_events << name.to_sym
-          # Defines instance method that has the same name as the Event being declared.
-          # Calling it without arguments returns Event object itself
-          # Calling it with block adds unnamed subscriber for Event
-          # Calling it with arguments fires the Event
-          # Such a messy interface provides some compatibility with C# events behavior
-          define_method name do |*args, &block|
-            events[name] ||= Event.new(name)
-            if args.empty?
-              if block
-                events[name].subscribe &block
+          if instance_events.has_key? sym_name
+            raise EventError.new "Unable to redefine Event #{name} with options #{opts.inspect}" if instance_events[sym_name] != opts
+          else
+            instance_events[sym_name] = opts
+
+            # Defines instance method that has the same name as the Event being declared.
+            # Calling it without arguments returns Event object itself
+            # Calling it with block adds unnamed subscriber for Event
+            # Calling it with arguments fires the Event
+            # Such a messy interface provides some compatibility with C# events behavior
+            define_method name do |*args, &block|
+              events[sym_name] ||= Event.create(self, sym_name, opts)
+              if args.empty?
+                if block
+                  events[sym_name].subscribe &block
+                else
+                  events[sym_name]
+                end
               else
-                events[name]
+                events[sym_name].fire(*args)
               end
-            else
-              events[name].fire(*args)
             end
-          end
 
-          # Needed to support C#-like syntax : my_event -= subscriber
-          define_method "#{name}=" do |event|
-            if event.kind_of? Event
-              events[name] = event
-            else
-              raise Events::SubscriberTypeError.new "Attempted assignment #{event.inspect} is not an Event"
+            # Only supports assignment of the Event to self
+            # Needed to support C#-like syntax : my_event += subscriber
+            define_method "#{name}=" do |event|
+              raise EventError.new("Wrong assignment of #{event.inspect} to #{events[name.to_sym].inspect}"
+                    ) unless event.equal? events[name.to_sym]
             end
           end
+          sym_name # .event macro returns defined sym name
         end
       end
 
     end
-
   end
 end

data/spec/amqp-events/event_manager_spec.rb

@@ -0,0 +1,63 @@
+require 'spec_helper'
+
+describe AMQP::Events::EventManager, " as class" do
+  subject { described_class }
+
+  it_should_behave_like 'evented class'
+
+#  its(:instance_events) { should include :ExternalEventReceived}
+
+end
+
+describe AMQP::Events::EventManager, " when initialized" do
+  before { @transport ||= mock('transport').as_null_object }
+  subject { described_class.new @transport }
+
+  it_should_behave_like 'evented object'
+  specify { should respond_to :transport }
+  its(:transport) { should_not be nil }
+
+  it "should allow external events to be defined" do
+    res = subject.event :ExternalBar, routing: '#.bar.#'
+    res.should be_an AMQP::Events::ExternalEvent
+  end
+
+  context 'with a mix of external and internal Events' do
+    before do
+      @event_manager = described_class.new @transport
+      @event_manager.event :Foo
+      @event_manager.event :ExternalBar, routing: '#.bar.#'
+    end
+    subject { @event_manager }
+
+    its(:events) { should_not be_empty }
+    its(:events) { should have_key :Foo }
+    its(:events) { should have_key :ExternalBar }
+
+    context 'any of its defined external Events' do
+      subject { @event_manager.ExternalBar }
+      specify {should be_an AMQP::Events::ExternalEvent}
+      it_should_behave_like 'event'
+    end
+
+    context 'any of its defined internal Events' do
+      subject { @event_manager.Foo }
+      specify {should be_an AMQP::Events::Event}
+      it_should_behave_like 'event'
+    end
+  end
+
+  context 'subscribing to EventManager`s Events' do
+    it "should allow objects to subscribe to its internal Events (without engaging Transport)" do
+      event = subject.subscribe(:Burp) { |key, data| p key, data }
+      event.should be_an AMQP::Events::Event
+      @transport.should_not_receive :subscribe
+    end
+
+    it "should allow objects to subscribe to external Events (through Transport)" do
+      @transport.should_receive(:subscribe).with '#.log.#'
+      event = subject.event(:LogEvent, routing: '#.log.#').subscribe(:my_log) { |key, data| p key, data }
+      event.should be_an AMQP::Events::ExternalEvent
+    end
+  end
+end