substation 0.0.10.beta2 → 0.0.10

data/lib/substation/processor.rb

@@ -1,23 +1,254 @@
+# encoding: utf-8
+
 module Substation
 
   # Namespace for chain processors
   module Processor
 
-    include AbstractType
-    include Adamantium::Flat
+    include Equalizer.new(:name, :handler, :config)
+
+    # FIXME: include this once the bug with deep freezing
+    # is resolved (currently this deep freezes and thus
+    # tries to incorrectly freeze observers too.
+    #
+    # include Adamantium::Flat
+
+    # Initialize a new instance
+    #
+    # @param [Symbol] name
+    #   the processor's name
+    #
+    # @param [Config] config
+    #   the processor's configuration
+    #
+    # @return [undefined]
+    #
+    # @api private
+    def initialize(name, handler, config)
+      @name          = name
+      @handler       = handler
+      @config        = config
+      @executor      = @config.executor
+      @observers     = @config.observers
+      @failure_chain = @config.failure_chain
+    end
+
+    # This processor's name
+    #
+    # @return [Symbol]
+    #
+    # @api private
+    attr_reader :name
+
+    # This processor's config
+    #
+    # @return [Builder::Config]
+    #
+    # @api private
+    attr_reader :config
+    protected   :config
+
+    # Return handler
+    #
+    # @return [#call]
+    #
+    # @api private
+    attr_reader :handler
+    protected   :handler
+
+    # Return failure chain
+    #
+    # @return [Chain]
+    #
+    # @api private
+    attr_reader :failure_chain
+    private     :failure_chain
+
+    # Return executor
+    #
+    # @return [Executor]
+    #
+    # @api private
+    attr_reader :executor
+    private     :executor
+
+    # Return the observers
+    #
+    # @return [Enumerable<#call>]
+    #
+    # @api private
+    attr_reader :observers
+    private     :observers
+
+    # Test wether chain processing should continue
+    #
+    # @param [Response] response
+    #   the response returned from invoking the processor
+    #
+    # @return [true] for a successful response
+    # @return [false] otherwise
+    #
+    # @api private
+    def success?(response)
+      response.success?
+    end
+
+    # The response passed on to the next processor in a {Chain}
+    #
+    # @param [Response] response
+    #   the response returned from invoking the processor
+    #
+    # @return [Response]
+    #   the response passed on to the next processor in a {Chain}
+    #
+    # @api private
+    def result(response)
+      response
+    end
+
+    private
+
+    # Execute processor on state
+    #
+    # @param [Object] state
+    #   the state to execute with
+    #
+    # @return [Object]
+    #
+    # @api private
+    def execute(state)
+      compose(state, invoke(decompose(state)))
+    end
+
+    # Transform response data into something else
+    #
+    # @param [Response] response
+    #   the response to process
+    #
+    # @return [Response]
+    #
+    # @api private
+    def invoke(state)
+      notify_observers(handler.call(state))
+    end
+
+    # Decompose +input+ before processing
+    #
+    # @param [Request, Response] input
+    #   the object to decompose
+    #
+    # @return [Object]
+    #   the decomposed object
+    #
+    # @api private
+    def decompose(input)
+      executor.decompose(input)
+    end
+
+    # Compose a new object based on +input+ and +output+
+    #
+    # @param [Request, Response] input
+    #   the input as it was before calling {#decompose}
+    #
+    # @param [Object] output
+    #   the data used to compose a new object
+    #
+    # @return [Object]
+    #   the composed object
+    #
+    # @api private
+    def compose(input, output)
+      executor.compose(input, output)
+    end
 
-    abstract_method :call
-    abstract_method :result
+    # Notify all observers
+    #
+    # @param [Response] response
+    #   the response returned from {handler#call}
+    #
+    # @return [Response]
+    #
+    # @api private
+    def notify_observers(response)
+      observers.each { |observer| observer.call(response) }
+      response
+    end
+
+    # Supports {Processor} instances with a defined failure {Chain}
+    module Fallible
+
+      # Return a new processor with +chain+ as failure_chain
+      #
+      # @param [#call] chain
+      #   the failure chain to use for the new processor
+      #
+      # @return [#call]
+      #
+      # @api private
+      def with_failure_chain(chain)
+        self.class.new(name, handler, config.with_failure_chain(chain))
+      end
+    end
 
+    # Supports incoming {Processor} instances
     module Incoming
       include Processor
-      include Chain::Incoming
+      include Fallible
+
+      # The request passed on to the next processor in a {Chain}
+      #
+      # @param [Response] _response
+      #   the response returned from invoking this processor
+      #
+      # @return [Request]
+      #   the request passed on to the next processor in a {Chain}
+      #
+      # @api private
+      def result(_response)
+        super.to_request
+      end
     end
 
-    module Outgoing
+    # Supports pivot {Processor} instances
+    module Pivot
       include Processor
-      include Chain::Outgoing
+      include Fallible
     end
 
+    # Supports outgoing {Processor} instances
+    module Outgoing
+      include Processor
+
+      # Test wether chain processing should continue
+      #
+      # @param [Response] _response
+      #   the response returned from invoking the processor
+      #
+      # @return [true]
+      #
+      # @api private
+      def success?(_response)
+        true
+      end
+
+      private
+
+      # Build a new {Response} based on +response+ and +output+
+      #
+      # @param [Response] response
+      #   the original response
+      #
+      # @param [Object] output
+      #   the data to be wrapped within the new {Response}
+      #
+      # @return [Response]
+      #
+      # @api private
+      def respond_with(response, output)
+        response.class.new(response.request, output)
+      end
+
+    end # module Outgoing
+
   end # module Processor
 end # module Substation

data/lib/substation/processor/builder.rb

@@ -0,0 +1,26 @@
+# encoding: utf-8
+
+module Substation
+  module Processor
+
+    # Supports building new {Processor} instances
+    class Builder
+
+      include Concord.new(:name, :klass, :executor)
+
+      # Build processor
+      #
+      # @param [#call] handler
+      # @param [Chain] failure_chain
+      #
+      # @return [Processor]
+      #
+      # @api private
+      def call(handler, failure_chain, observers)
+        klass.new(name, handler, Config.new(executor, failure_chain, observers))
+      end
+
+    end # class Builder
+
+  end # module Processor
+end # module Substation

data/lib/substation/processor/config.rb

@@ -0,0 +1,24 @@
+# encoding: utf-8
+
+module Substation
+  module Processor
+
+    # Wraps {Processor} configuration
+    class Config
+      include Concord::Public.new(:executor, :failure_chain, :observers)
+
+      # Add failure chain
+      #
+      # @param [Chain] chain
+      #
+      # @return [Processor]
+      #
+      # @api private
+      def with_failure_chain(chain)
+        self.class.new(executor, chain, observers)
+      end
+
+    end # class Config
+
+  end # module Processor
+end # module Substation

data/lib/substation/processor/evaluator.rb

@@ -1,30 +1,40 @@
+# encoding: utf-8
+
 module Substation
   module Processor
 
-    # A processor to evaluate a chain's request input data
+    # Abstract processor to evaluate a request coming into a chain
     class Evaluator
 
-      include Incoming
+      # Processor to evaluate an incoming request
+      class Request < self
+        include Processor::Incoming
+      end
 
-      # Initialize a new instance
-      #
-      # @param [Environment] env
-      #   the substation environment used to build chains
-      #
-      # @param [#call] handler
-      #   the handler to perform evaluation
-      #
-      # @param [Proc] block
-      #   a block to construct a failure chain
-      #
-      # @return [undefined]
-      #
-      # @api private
-      def initialize(env, handler, &block)
-        @env, @handler = env, handler
-        @failure_chain = block ? @env.chain(&block) : Undefined
+      # Processor to evaluate a pivot chain handler
+      class Pivot < self
+        include Processor::Pivot
+
+        private
+
+        # Return a successful response
+        #
+        # @param [Request] _request
+        #   the evaluated request
+        #
+        # @param [#output] result
+        #   the evaluation result
+        #
+        # @return [Response::Success]
+        #
+        # @api private
+        def on_success(_request, response)
+          response
+        end
       end
 
+      include AbstractType
+
       # Evaluate a chain's request input data
       #
       # @param [Request] request
@@ -34,47 +44,61 @@ module Substation
       #
       # @api private
       def call(request)
-        result = handler.call(request.input)
-        output = result.output
+        result = invoke(decompose(request))
         if result.success?
-          request.success(output)
+          on_success(request, result)
         else
-          response = request.error(output)
-          if fail_safe?
-            failure_chain.call(response)
-          else
-            response
-          end
+          on_failure(request, result)
         end
       end
 
-      protected
+      private
 
-      # The handler used to perform evaluation
+      # Return a successful response
       #
-      # @return [#call]
+      # @param [Request] request
+      #   the evaluated request
+      #
+      # @param [#output] result
+      #   the evaluation result
+      #
+      # @return [Response::Success]
       #
       # @api private
-      attr_reader :handler
-
-      private
+      def on_success(request, result)
+        request.success(output(request, result))
+      end
 
-      # The chain to invoke if evaluation returned an error
+      # Return a failure response by invoking a failure chain
+      #
+      # @param [Request] request
+      #   the evaluated request
       #
-      # @return [Chain]
+      # @param [#output] result
+      #   the evaluation result
+      #
+      # @return [Response::Failure]
       #
       # @api private
-      attr_reader :failure_chain
+      def on_failure(request, result)
+        failure_chain.call(request.error(output(request, result)))
+      end
 
-      # Test wether this evaluator has a failure chain
+      # Return a new composed output
+      #
+      # @param [Request] request
+      #   the evaluated request
+      #
+      # @param [Response] response
+      #   the evaluation result
       #
-      # @return [TrueClass] if a failure chain is registered
-      # @return [FalseClass] otherwise
+      # @return [Object]
       #
       # @api private
-      def fail_safe?
-        !@failure_chain.equal?(Undefined)
+      def output(request, result)
+        compose(request, result.output)
       end
+
     end # class Evaluator
   end # module Processor
 end # module Substation