synapse-core 0.1.2

data/lib/synapse/uow/nesting.rb

@@ -0,0 +1,262 @@
+module Synapse
+  module UnitOfWork
+    # Partial implementation of a unit of work that can be nested
+    #
+    # This implementation provides common actions that will be needed for nestable units
+    # of work, such as registration with the unit of work provider and nested commit
+    # and rollback operations
+    #
+    # @abstract
+    class NestableUnitOfWork
+      # @param [UnitOfWorkProvider] provider
+      # @return [undefined]
+      def initialize(provider)
+        @inner_units = Array.new
+        @provider = provider
+        @started = false
+      end
+
+      # Commits this unit of work
+      #
+      # All reigstered aggregates that have not been registered as stored are saved in their
+      # respective repositories, buffered events are sent to their respective event buses, and
+      # all registered listeners are notified of the commit.
+      #
+      # After the commit (successful or not), the unit of work is unregistered and cleans up any
+      # resources it acquired. The effectively means that a rollback is done if the unit of work
+      # failed to commit.
+      #
+      # @raise [RuntimeError] If unit of work hasn't been started yet
+      # @return [undefined]
+      def commit
+        unless started?
+          raise 'Unit of work has not been started yet'
+        end
+
+        begin
+          notify_prepare_commit
+          store_aggregates
+
+          unless @outer_unit
+            perform_commit
+            stop
+            perform_cleanup
+          end
+        rescue => cause
+          perform_rollback cause
+          stop
+
+          unless @outer_unit
+            perform_cleanup
+          end
+
+          raise cause
+        ensure
+          clear
+        end
+      end
+
+      # Clears this unit of work of any buffered changes
+      #
+      # Any buffered events and registered aggregates are discarded and any registered unit of work
+      # listeners are notified of the rollback.
+      #
+      # @param [Error] cause
+      # @return [undefined]
+      def rollback(cause = nil)
+        begin
+          if started?
+            @inner_units.each do |inner_unit|
+              @provider.push inner_unit
+              inner_unit.rollback cause
+            end
+            perform_rollback cause
+          end
+        ensure
+          finalize_rollback
+        end
+      end
+
+      # Starts the unit of work, preparing it for aggregate registration
+      #
+      # @raise [RuntimeError] If unit of work has already been started
+      # @return [undefined]
+      def start
+        if started?
+          raise 'Unit of work has already been started'
+        end
+
+        perform_start
+
+        if @provider.started?
+          # This is a nested unit of work
+          @outer_unit = @provider.current
+
+          if NestableUnitOfWork === @outer_unit
+            @outer_unit.register_inner_unit self
+          else
+            # Outer unit is not aware of inner units, hook in with a listener
+            @outer_unit.register_listener OuterCommitUnitOfWorkListener.new self, @provider
+          end
+        end
+
+        @provider.push self
+        @started = true
+      end
+
+      # Returns true if this unit of work has been started
+      # @return [Boolean]
+      def started?
+        @started
+      end
+
+    protected
+
+      # Executes logic required to commit this unit of work
+      #
+      # @abstract
+      # @return [undefined]
+      def perform_commit; end
+
+      # Executes logic required to rollback this unit of work
+      #
+      # @abstract
+      # @param [Error] cause
+      # @return [undefined]
+      def perform_rollback(cause = nil); end
+
+      # Notifies listeners that this unit of work is cleaning up
+      #
+      # @abstract
+      # @return [undefined]
+      def notify_cleanup; end
+
+      # Notifies listeners that this unit of work is preparing to be committed
+      #
+      # @abstract
+      # @return [undefined]
+      def notify_prepare_commit; end
+
+      # Executes logic required when starting this unit of work
+      #
+      # @abstract
+      # @return [undefined]
+      def perform_start; end
+
+      # Storages aggregates registered with this unit of work
+      #
+      # @abstract
+      # @return [undefined]
+      def store_aggregates; end
+
+      # Commits all registered inner units of work. This should be invoked after events have been
+      # dispatched and before any listeners are notified of the commit.
+      #
+      # @return [undefined]
+      def commit_inner_units
+        @inner_units.each do |inner_unit|
+          if inner_unit.started?
+            inner_unit.perform_inner_commit
+          end
+        end
+      end
+
+      # Registers a unit of work nested in this unit of work
+      #
+      # @private
+      # @param [UnitOfWork] inner_unit
+      # @return [undefined]
+      def register_inner_unit(inner_unit)
+        @inner_units.push inner_unit
+      end
+
+      # Executes logic required to clean up this unit of work
+      #
+      # @private
+      # @return [undefined]
+      def perform_cleanup
+        @inner_units.each do |inner_unit|
+          inner_unit.perform_cleanup
+        end
+
+        notify_cleanup
+      end
+
+      # Commits this unit of work as an inner unit of work
+      #
+      # @private
+      # @return [undefined]
+      def perform_inner_commit
+        @provider.push self
+
+        begin
+          perform_commit
+        rescue => cause
+          perform_rollback cause
+        end
+
+        clear
+        stop
+      end
+
+    private
+
+      # @return [undefined]
+      def finalize_rollback
+        unless @outer_unit
+          perform_cleanup
+        end
+
+        clear
+        stop
+      end
+
+      # @return [undefined]
+      def clear
+        @provider.clear self
+      end
+
+      # @return [undefined]
+      def stop
+        @started = false
+      end
+    end
+
+    # Listener that allows a nested unit of work to properly operate within in a unit of
+    # work that is not aware of nesting
+    class OuterCommitUnitOfWorkListener < UnitOfWorkListener
+      # @param [UnitOfWork] inner_unit
+      # @param [UnitOfWorkProvider] provider
+      # @return [undefined]
+      def initialize(inner_unit, provider)
+        @inner_unit = inner_unit
+        @provider = provider
+      end
+
+      # @param [UnitOfWork] outer_unit
+      # @return [undefined]
+      def after_commit(outer_unit)
+        @inner_unit.perform_inner_commit
+      end
+
+      # @param [UnitOfWork] outer_unit
+      # @param [Error] cause
+      # @return [undefined]
+      def on_rollback(outer_unit, cause = nil)
+        @provider.push @inner_unit
+
+        begin
+          @inner_unit.perform_rollback cause
+        ensure
+          @provider.clear @inner_unit
+        end
+      end
+
+      # @param [UnitOfWork] outer_unit
+      # @return [undefined]
+      def on_cleanup(outer_unit)
+        @inner_unit.perform_cleanup
+      end
+    end
+  end
+end

data/lib/synapse/uow/provider.rb

@@ -0,0 +1,71 @@
+module Synapse
+  module UnitOfWork
+    # Entry point for components to access units of work. Components managing transactional
+    # boundaries can register and clear unit of work instances.
+    class UnitOfWorkProvider
+      def initialize
+        @threads = Hash.new
+      end
+
+      # Clears the given unit of work from this provider
+      #
+      # If the given unit of work is not known to the provider, or it is not the active unit
+      # of work, then this method will raise an exception.
+      #
+      # @param [UnitOfWork] unit
+      # @return [undefined]
+      def clear(unit)
+        unless stack.last == unit
+          raise ArgumentError, 'The given unit of work is not the active unit of work'
+        end
+
+        stack.pop
+      end
+
+      # Commits the current unit of work
+      # @return [undefined]
+      def commit
+        current.commit
+      end
+
+      # Returns the current unit of work if one is set
+      #
+      # @raise [RuntimeError] If no unit of work is active
+      # @return [UnitOfWork]
+      def current
+        if stack.empty?
+          raise 'No unit of work is active'
+        end
+
+        stack.last
+      end
+
+
+      # Pushes the given unit of work onto the top of the stack, making it the active unit of work
+      #
+      # If there are other units of work bound to this provider, they will be held until the given
+      # unit of work is cleared.
+      #
+      # @param [UnitOfWork] unit
+      # @return [undefined]
+      def push(unit)
+        stack.push unit
+      end
+
+      # Returns true if there is an active unit of work
+      # @return [Boolean]
+      def started?
+        !stack.empty?
+      end
+
+    private
+
+      # @return [Array<UnitOfWork>]
+      def stack
+        @threads.fetch Thread.current
+      rescue KeyError
+        @threads.store Thread.current, Array.new
+      end
+    end
+  end
+end

data/lib/synapse/uow/storage_listener.rb

@@ -0,0 +1,14 @@
+module Synapse
+  module UnitOfWork
+    # Represents a mechanism for a unit of work to commit an aggregate to an underlying store
+    # @abstract
+    class StorageListener
+      # Commits the given aggregate to the underlying storage mechanism
+      #
+      # @abstract
+      # @param [AggregateRoot] aggregate
+      # @return [undefined]
+      def store(aggregate); end
+    end
+  end
+end

data/lib/synapse/uow/transaction_manager.rb

@@ -0,0 +1,27 @@
+module Synapse
+  module UnitOfWork
+    # Represents a mechanism for a unit of work to integrate with an underlying transaction
+    # management system
+    #
+    # @abstract
+    class TransactionManager
+      # Creates and returns a transaction for use by the unit of work
+      #
+      # @abstract
+      # @return [Object]
+      def start; end
+
+      # Commits the given transaction
+      #
+      # @param [Object] transaction
+      # @return [undefined]
+      def commit(transaction); end
+
+      # Rolls back the given transaction
+      #
+      # @param [Object] transaction
+      # @return [undefined]
+      def rollback(transaction); end
+    end
+  end
+end

data/lib/synapse/uow/uow.rb

@@ -0,0 +1,178 @@
+module Synapse
+  module UnitOfWork
+    # Default implementation of a unit of work
+    class UnitOfWork < NestableUnitOfWork
+      # @param [UnitOfWorkProvider] provider
+      # @return [undefined]
+      def initialize(provider)
+        super
+
+        @aggregates = Hash.new
+        @events = Hash.new
+        @listeners = UnitOfWorkListenerCollection.new
+      end
+
+      # Returns true if this unit of work is bound to a transaction
+      # @return [Boolean]
+      def transactional?
+        !!@transaction_manager
+      end
+
+      # Registers a listener that is notified of state changes in this unit of work
+      #
+      # @param [UnitOfWorkListener] listener
+      # @return [undefined]
+      def register_listener(listener)
+        @listeners.push listener
+      end
+
+      # Registers an aggregate with this unit of work
+      #
+      # This unit of work adds an event listener to the aggregate so that any events generated
+      # are published to the given event bus when this unit of work is committed.
+      #
+      # The provided storage listener is used to commit the aggregate to its respective
+      # underlying storage mechanism.
+      #
+      # If there is already an aggregate registered with this unit of work of the same type
+      # and with the same identifier, that aggregate will be returned instead of the given
+      # aggregate.
+      #
+      # @param [AggregateRoot] aggregate
+      # @param [EventBus] event_bus
+      # @param [StorageListener] storage_listener
+      # @return [AggregateRoot]
+      def register_aggregate(aggregate, event_bus, storage_listener)
+        similar = find_similar_aggregate aggregate
+        if similar
+          return similar
+        end
+
+        aggregate.add_registration_listener do |event|
+          publish_event event, event_bus
+        end
+
+        @aggregates.store aggregate, storage_listener
+
+        aggregate
+      end
+
+      # Buffers an event for publication to the given event bus until this unit of work is
+      # committed
+      #
+      # @param [EventMessage] event
+      # @param [EventBus] event_bus
+      # @return [EventMessage] The event that will be published to the event bus
+      def publish_event(event, event_bus)
+        event = @listeners.on_event_registered self, event
+
+        begin
+          events = @events.fetch event_bus
+        rescue KeyError
+          events = @events.store event_bus, Array.new
+        end
+
+        events.push event
+        event
+      end
+
+      # Sets the transaction manager that will be used by this unit of work
+      #
+      # @raise [RuntimeError] If unit of work has been started
+      # @param [TransactionManager] transaction_manager
+      # @return [undefined]
+      def transaction_manager=(transaction_manager)
+        if started?
+          raise 'Transaction manager not permitted to change after unit of work has started'
+        end
+
+        @transaction_manager = transaction_manager
+      end
+
+    protected
+
+      # @return [undefined]
+      def perform_commit
+        publish_events
+        commit_inner_units
+
+        if transactional?
+          @listeners.on_prepare_transaction_commit self, @transaction
+          @transaction_manager.commit @transaction
+        end
+
+        @listeners.after_commit self
+      end
+
+      # @param [Error] cause
+      # @return [undefined]
+      def perform_rollback(cause = nil)
+        @aggregates.clear
+        @events.clear
+
+        begin
+          if @transaction
+            @transaction_manager.rollback @transaction
+          end
+        ensure
+          @listeners.on_rollback self, cause
+        end
+      end
+
+      # @return [undefined]
+      def notify_cleanup
+        @listeners.on_cleanup self
+      end
+
+      # @return [undefined]
+      def notify_prepare_commit
+        @listeners.on_prepare_commit self, @aggregates.keys, @events
+      end
+
+      # @return [undefined]
+      def perform_start
+        if transactional?
+          @transaction = @transaction_manager.start
+        end
+
+        @listeners.on_start self
+      end
+
+      # @return [undefined]
+      def store_aggregates
+        @aggregates.each_pair do |aggregate, storage_listener|
+          storage_listener.store aggregate
+        end
+        @aggregates.clear
+      end
+
+    private
+
+      # Checks if an aggregate of the same type and identifier as the given aggregate has been
+      # previously registered with this unit work. If one is found, it is returned.
+      #
+      # @param [AggregateRoot] aggregate
+      # @return [AggregateRoot] Returns nil if no similar aggregate was found
+      def find_similar_aggregate(aggregate)
+        @aggregates.each_key do |candidate|
+          if aggregate.class === candidate and aggregate.id == candidate.id
+            return candidate
+          end
+        end
+
+        return
+      end
+
+      # Continually publishes all buffered events to their respective event buses until all
+      # events have been published
+      def publish_events
+        until @events.empty?
+          @events.keys.each do |event_bus|
+            events = @events.delete event_bus
+            event_bus.publish events
+          end
+        end
+      end
+    end
+  end
+end