lev 0.0.3 → 1.0.0

data/lib/lev/handler_helper.rb

@@ -1,3 +1,3 @@
 def handler_errors
-  @errors || Lev::Handler::Errors.new
+  @errors || (@handler_result ? @handler_result.errors : Lev::Errors.new)
 end

data/lib/lev/routine.rb

@@ -0,0 +1,424 @@
+module Lev
+  
+  # A "routine" in the Lev world is a piece of code that is responsible for
+  # doing one thing, normally acting on one or more other objects.  Routines
+  # are particularly useful when the thing that needs to be done involves 
+  # making changes to multiple other objects.  In an OO/MVC world, an operation
+  # that involves multiple objects might be implemented by spreading that logic
+  # among those objects.  However, that leads to classes having more
+  # responsibilities than they should (and more knowlege of other classes than
+  # they should) as well as making the code hard to follow.
+  #
+  # Routines typically don't have any persistent state that is used over and 
+  # over again; they are created, used, and forgotten.  A routine is a glorified
+  # function with a special single-responsibility purpose.
+  #
+  # Routines can be nested -- there is built-in functionality for calling
+  # one routine inside another.
+  #
+  # A class becomes a routine by adding:
+  #
+  #   include Lev::Routine
+  #
+  # in its definition.
+  #
+  # Other than that, all a routine has to do is implement an "exec" method 
+  # that takes arbitrary arguments and that adds errors to an internal
+  # array-like "errors" object and outputs to a "outputs" hash.
+  #
+  # A routine returns an "Result" object, which is just a simple wrapper
+  # of the outputs and errors objects. 
+  #
+  # A routine will automatically get both class- and instance-level "call"
+  # methods that take the same arguments as the "exec" method.  The class-level
+  # call method simply instantiates a new instance of the routine and calls 
+  # the instance-level call method (side note here is that this means that 
+  # routines aren't typically instantiated with state).
+  # 
+  # A routine is automatically run within a transaction.  The isolation level
+  # of the routine can be set by overriding the "default_transaction_isolation"
+  # class method and having it return an instance of Lev::TransactionIsolation.
+  # This is also how routines can be set to not be run in a transaction.
+  #
+  # As mentioned above, routines can call other routines.  While this is of
+  # course possible just by calling the other routine's call method directly,
+  # it is strongly recommended that one routine call another routine using the
+  # provided "run" method.  This method takes the name of the routine class 
+  # and the arguments/block it expects in its call/exec methods.  By using the
+  # run method, the called routine will be hooked into the common error and 
+  # transaction mechanisms.
+  #
+  # When one routine is called within another using the run method, there is
+  # only one transaction used (barring any explicitly made in the code) and
+  # its isolation level is sufficiently strict for all routines involved.
+  #
+  # It is highly recommend, though not required, to call the "uses_routine"
+  # method to let the routine know which subroutines will be called within it.
+  # This will let a routine set its isolation level appropriately, and will
+  # enforce that only one transaction be used and that it be rolled back 
+  # appropriately if any errors occur.
+  #
+  # Once a routine has been registered with the "uses_routine" call, it can
+  # be run by passing run the routine's Class or a symbol identifying the 
+  # routine.  This symbol can be set with the :as option.  If not set, the
+  # symbol will be automatically set by converting the routine class' full
+  # name to a symbol. e.g:
+  #
+  #   uses_routine CreateUser
+  #                as: :cu
+  #
+  # and then you can say either:
+  #
+  #   run(:cu, ...)
+  #
+  # or
+  #
+  #   run(:create_user, ...)
+  #
+  # uses_routine also provides a way to specify how errors relate to routine 
+  # inputs. Take the following example.  A user calls Routine1 which calls 
+  # Routine2.
+  #
+  #   User --> Routine1.call(foo: "abcd4") --> Routine2.call(bar: "abcd4")
+  #
+  # An error occurs in Routine2, and Routine2 notes that the error is related
+  # to its "bar" input.  If that error and its metadata bubble up to the User,
+  # the User won't have any idea what "bar" relates to -- the User only knows
+  # about the interface to Routine1 and the "foo" parameter it gave it.
+  #
+  # Routine1 knows that it will call Routine2 and knows what its interface is.  
+  # It can then specify how to map terminology from Routine2 into Routine1's 
+  # context.  E.g., in the following class:
+  #
+  #   class Routine1
+  #     include Lev::Routine
+  #     uses_routine Routine2,
+  #                  translations: { 
+  #                    inputs: { map: {bar: :foo} }
+  #                  }
+  #     def exec(options)
+  #       run(Routine2, bar: options[:foo])
+  #     end
+  #   end
+  #
+  # Routine1 notes that any errors coming back from the call to Routine2 
+  # related to :bar should be transfered into Routine1's errors object
+  # as being related to :foo.  In this way, the caller of Routine1 will see
+  # errors related to the arguments he understands.
+  #
+  # Translations can also be supplied for "outputs" in addition to "inputs".
+  # Output translations control how a called routine's Result outputs are 
+  # transfered to the calling routine's outputs.  Note if multiple outputs are
+  # transferred into the same named output, an array of those outputs will be 
+  # store.  The contents of the "inputs" and "outputs" hashes can be of the 
+  # following form:
+  #
+  # 1) Scoped.  Appends the provided scoping symbol (or symbol array) to
+  #    the input symbol.  
+  #
+  #    {scope: SCOPING_SYMBOL_OR_SYMBOL_ARRAY}
+  #
+  #    e.g. with {scope: :register} and a call to a routine that has an input
+  #    named :first_name, an error in that called routine related to its 
+  #    :first_name input will be translated so that the offending input is 
+  #    [:register, :first_name].
+  #
+  # 2) Verbatim.  Uses the same term in the caller as the callee.
+  #
+  #    {type: :verbatim}
+  #
+  # 3) Mapped.  Give an explicit, custom mapping:
+  #
+  #    {map: {called_input1: caller_input1, called_input2: :caller_input2}}
+  #
+  # 4) Scoped and mapped.  Give an explicit mapping, and also scope the 
+  #    translated terms.  Just use scope: and map: from above in the same hash.
+  #
+  # Via the uses_routine call, you can also ignore specified errors that occur
+  # in the called routine. e.g.:
+  #
+  #   uses_routine DestroyUser,
+  #                ignored_errors: [:cannot_destroy_non_temp_user]
+  #
+  # ignores errors with the provided code.  The ignore_errors key must point
+  # to an array of code symbols or procs.  If a proc is given, the proc will
+  # be called with the error that the routine is trying to add.  If the proc
+  # returns true, the error will be ignored.
+  #
+  # Any option passed to uses_routine can also be passed directly to the run
+  # method.  To achieve this, pass an array as the first argument to "run".
+  # The array should have the routine class or symbol as the first argument,
+  # and the hash of options as the second argument.  Options passed in this
+  # manner override any options provided in uses_routine (though those options
+  # are still used if not replaced in the run call).
+  #
+  # Two methods are provided for adding errors: "fatal_error" and "nonfatal_error".
+  # Both take a hash of args used to create an Error and the former stops routine
+  # execution.  In its current implementation, "nonfatal_error" may still cause
+  # a routine higher up in the execution hierarchy to halt running.
+  #
+  # Routine class have access to a few other methods:
+  #
+  #  1) a "runner" accessor which points to the routine which called it. If
+  #     runner is nil that means that no other routine called it (some other 
+  #     code did)
+  # 
+  #  2) a "topmost_runner" which points to the highest routine in the calling
+  #     hierarchy (that routine whose 'runner' is nil)
+  #   
+  # References:
+  #   http://ducktypo.blogspot.com/2010/08/why-inheritance-sucks.html
+  #
+  module Routine
+
+    class Result
+      attr_reader :outputs
+      attr_reader :errors
+
+      def initialize
+        @outputs = {}
+        @errors = Errors.new
+      end
+
+      def add_output(name, value)
+        outputs[name] = [outputs[name], value].flatten.compact
+        outputs[name] = outputs[name].first if outputs[name].size == 1
+      end
+    end
+
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    module ClassMethods
+      def call(*args, &block)
+        new.call(*args, &block)
+      end
+
+      # Called at a routine's class level to foretell which other routines will
+      # be used when this routine executes.  Helpful for figuring out ahead of
+      # time what kind of transaction isolation level should be used.
+      def uses_routine(routine_class, options={})
+        symbol = options[:as] || class_to_symbol(routine_class)
+
+        raise IllegalArgument, "Routine #{routine_class} has already been registered" \
+          if nested_routines[symbol]
+
+        nested_routines[symbol] = {
+          routine_class: routine_class,
+          options: options
+        }
+
+        transaction_isolation.replace_if_more_isolated(routine_class.transaction_isolation)
+      end
+
+      def transaction_isolation
+        @transaction_isolation ||= default_transaction_isolation
+      end
+
+      def default_transaction_isolation
+        TransactionIsolation.mysql_default
+      end
+
+      def nested_routines
+        @nested_routines ||= {}
+      end
+
+      def class_to_symbol(klass)
+        klass.name.underscore.gsub('/','_').to_sym
+      end
+    end
+
+    attr_reader :runner
+
+    def call(*args, &block)
+      in_transaction do
+        catch :fatal_errors_encountered do
+          exec(*args, &block)
+        end
+      end
+
+      result
+    end
+
+    # Returns true iff the given instance is responsible for running itself in a
+    # transaction
+    def transaction_run_by?(who)
+      who == topmost_runner && who.class.transaction_isolation != TransactionIsolation.no_transaction
+    end
+
+    def run(other_routine, *args, &block)
+      options = {}
+
+      if other_routine.is_a? Array
+        if other_routine.size != 2
+          raise IllegalArgument, "when first arg to run is an array, it must have two arguments" 
+        end
+
+        other_routine = other_routine[0]
+        options = other_routine[1]
+      end
+
+      symbol = case other_routine
+               when Symbol
+                 other_routine
+               when Class
+                 self.class.class_to_symbol(other_routine)
+               else 
+                 self.class.class_to_symbol(other_routine.class)
+               end
+
+      nested_routine = self.class.nested_routines[symbol] || {}
+
+      if nested_routine.empty? && other_routine == symbol
+        raise IllegalArgument, 
+              "Routine symbol #{other_routine} does not point to a registered routine"
+      end      
+
+      #
+      # Get an instance of the routine and make sure it is a routine
+      #
+
+      other_routine = nested_routine[:routine_class] || other_routine
+      other_routine = other_routine.new if other_routine.is_a? Class
+
+      raise IllegalArgument, "Can only run another nested routine" \
+        if !(other_routine.includes_module? Lev::Routine)
+
+      #
+      # Merge passed-in options with those set in uses_routine, the former taking
+      # priority.
+      #
+
+      nested_routine_options = nested_routine[:options] || {}
+      options = Lev::Utilities.deep_merge(nested_routine_options, options)
+
+      #
+      # Setup the input/output mappers
+      #
+
+      options[:translations] ||= {}
+
+      input_mapper  = new_term_mapper(options[:translations][:inputs]) || 
+                      new_term_mapper({ scope: symbol })
+
+      output_mapper = new_term_mapper(options[:translations][:outputs]) || 
+                      new_term_mapper({ scope: symbol })
+
+      #
+      # Set up the ignored errors in the routine instance
+      #
+
+      (options[:ignored_errors] || []).each do |ignored_error|
+        other_routine.errors.ignore(ignored_error)
+      end
+
+      #
+      # Attach the subroutine to self, call it, transfer errors and results
+      #
+
+      other_routine.runner = self
+      run_result = other_routine.call(*args, &block)
+
+      options[:errors_are_fatal] = true if !options.has_key?(:errors_are_fatal)
+      transfer_errors_from(run_result.errors, input_mapper, options[:errors_are_fatal])
+
+      run_result.outputs.each do |name, value|
+        self.result.add_output(output_mapper.map(name), value)
+      end
+
+      run_result
+    end
+
+    # Convenience accessor for errors object
+    def errors
+      result.errors
+    end
+
+    # Convenience test for presence of errors
+    def errors?
+      result.errors.any?
+    end
+
+    def fatal_error(args={})
+      errors.add(true, args)
+    end
+
+    def nonfatal_error(args={})
+      errors.add(false, args)
+    end
+
+    # Utility method to transfer errors from a source to this routine.  The 
+    # provided input_mapper maps the language of the errors in the source to
+    # the language of this routine.  If fail_if_errors is true, this routine
+    # will throw an error condition that causes execution of this routine to stop
+    # *after* having transfered all of the errors.
+    def transfer_errors_from(source, input_mapper, fail_if_errors=false)
+      if input_mapper.is_a? Hash
+        input_mapper = new_term_mapper(input_mapper)
+      end
+
+      ErrorTransferer.transfer(source, self, input_mapper, fail_if_errors)
+    end
+
+  protected
+
+    def result
+      @result ||= Result.new
+    end
+
+    attr_writer :runner
+
+    def outputs
+      result.outputs
+    end
+
+    def topmost_runner
+      runner.nil? ? self : runner.topmost_runner
+    end
+
+    def runner=(runner)
+      @runner = runner
+
+      if topmost_runner.class.transaction_isolation.weaker_than(self.class.default_transaction_isolation)
+        raise IsolationMismatch, 
+              "The routine being run has a stronger isolation requirement than " + 
+              "the isolation being used by the routine(s) running it; call the " +
+              "'uses' method in the running routine's initializer"
+      end
+    end
+
+    def in_transaction(options={}) 
+      if transaction_run_by?(self)
+        ActiveRecord::Base.isolation_level( self.class.transaction_isolation.symbol ) do
+          ActiveRecord::Base.transaction do 
+            yield 
+            raise ActiveRecord::Rollback if errors?
+          end
+        end
+      else
+        yield
+      end
+    end
+
+    def new_term_mapper(options)
+      return nil if options.nil?
+
+      if options[:type]
+        case options[:type]
+        when :verbatim
+          return TermMapper.verbatim
+        else
+          raise IllegalArgument, "unknown :type value: #{options[:type]}"
+        end
+      end
+
+      if options[:scope] || options[:map]
+        return TermMapper.scope_and_map(options[:scope], options[:map])
+      end
+
+      nil
+    end
+
+  end
+end

data/lib/lev/term_mapper.rb

@@ -0,0 +1,41 @@
+module Lev
+
+  class TermMapper
+
+    def self.verbatim
+      ScopedAndMapped.new(nil, nil)
+    end
+
+    def self.scope_and_map(scope, mapping)
+      ScopedAndMapped.new(scope, mapping)
+    end
+
+    def self.scope(scope)
+      ScopedAndMapped.new(scope, nil)
+    end
+
+    def map(inputs)
+      raise AbstractMethodCalled
+    end
+
+  protected
+
+    class ScopedAndMapped < TermMapper
+      def initialize(scope=nil, mapping=nil)
+        @scope = scope
+        @mapping = mapping
+      end
+
+      def map(inputs)
+        inputs = [inputs].flatten.compact
+        result = inputs.collect do |input|
+          mapped = (@mapping || {})[input] || input
+          @scope.nil? ? mapped : [@scope, mapped].flatten
+        end
+        result.size == 1 ? result.first : result
+      end
+    end
+
+  end
+
+end