batch-kit 0.3

data/lib/batch-kit/framework/runnable.rb

@@ -0,0 +1,235 @@
+require 'forwardable'
+
+
+class BatchKit
+
+    # Captures details of a single execution of a runnable batch process, e.g. a
+    # Task or Job.
+    class Runnable
+
+        # Runnables delegate to their definitions for properties that are common
+        # across all runs.
+        extend Forwardable
+
+        # Add locking functionality for obtaining a lock during execution of a
+        # Runnable
+        include Lockable
+
+
+        class << self
+
+            # Add delegates for each specified property in +props+.
+            def add_delegated_properties(*props)
+                del_props = props.reject{ |prop| self.instance_methods.include?(prop) }
+                def_delegators :@definition, *del_props
+            end
+
+        end
+
+
+        # The definition object for this runnable
+        attr_reader :definition
+        # The object instance that is running this runnable
+        attr_reader :object
+        # The instance qualifier for this runnable, if it has an instance
+        # qualifier.
+        attr_reader :instance
+        # Current status of this process.
+        # One of the following states:
+        #   :initialized
+        #   :skipped
+        #   :executing
+        #   :completed
+        #   :failed
+        #   :aborted
+        attr_reader :status
+        # Time at which processing began (or nil)
+        attr_reader :start_time
+        # Time at which processing completed (or nil)
+        attr_reader :end_time
+        # Exit code of the process
+        attr_reader :exit_code
+        # Exception thrown that caused process to fail
+        attr_accessor :exception
+        # Name of any exclusive lock needed by this run
+        attr_reader :lock_name
+        # Number of seconds before the lock times out
+        attr_reader :lock_timeout
+        # Number of seconds to wait for the lock to be released before giving up
+        attr_reader :lock_wait_timeout
+
+
+
+        # Sets the state of the runnable to :initialized.
+        def initialize(definition, obj, run_args)
+            @definition = definition
+            @object = obj
+            @instance = eval_property_expr(definition.instance, obj, run_args)
+            @status = :initialized
+            @lock_name = eval_property_expr(definition.lock_name, obj, run_args)
+            @lock_timeout = case definition.lock_timeout
+                when Numeric then definition.lock_timeout
+                when String then eval_property_expr(definition.lock_timeout, obj, run_args, :to_i)
+            end
+            @lock_wait_timeout = case definition.lock_wait_timeout
+                when Numeric then definition.lock_wait_timeout
+                when String then eval_property_expr(definition.lock_wait_timeout, obj, run_args, :to_i)
+            end
+            Events.publish(self, event_name('initialized'))
+        end
+
+
+        # Returns an event name for publication, based on the sub-class of Runnable
+        # that is triggering the event.
+        def event_name(event)
+            "#{self.class.name.split('::')[1..-1].join('_').downcase}.#{event}"
+        end
+
+
+        # @return a label consisting of the name and any instance qualifier.
+        def label
+            lbl = @definition.name.gsub(/_/, ' ').gsub(/\b([a-z])/) { $1.upcase }
+            @instance ? "#{lbl} [#{@instance}]" : lbl
+        end
+
+
+        # Returns the elapsed time in seconds
+        def elapsed
+            @start_time ? (@end_time || Time.now) - @start_time : 0
+        end
+
+
+        # A pre-execute pointcut for execution of a process. Return value
+        # determines whether execution should proceed.
+        #
+        # @param process_obj [Object] Object that is executing the batch
+        #   process.
+        # @param args [*Object] Any arguments passed to the method that is
+        #   executing the process.
+        # @return [Boolean] True if the process should proceed, or false if it
+        #   should be skipped.
+        def pre_execute(process_obj, *args)
+            if Events.has_subscribers?(process_obj, event_name('pre-execute'))
+                run = Events.publish(process_obj, event_name('pre-execute'), self, *args)
+            else
+                run = true
+            end
+            unless run
+                @status = :skipped unless run
+                Events.publish(process_obj, event_name('skipped'), self, *args)
+            end
+            run
+        end
+
+
+        # Called as the process is executing.
+        #
+        # @param process_obj [Object] Object that is executing the batch
+        #   process.
+        # @param args [*Object] Any arguments passed to the method that is
+        #   executing the process.
+        # @yield at the point when the process should execute.
+        def around_execute(process_obj, *args, &blk)
+            @start_time = Time.now
+            @status = :executing
+            @exit_code = nil
+            Events.publish(process_obj, event_name('execute'), self, *args)
+            begin
+                if @lock_name
+                    self.with_lock(@lock_name, @lock_timeout, @lock_wait_timeout, &blk)
+                else
+                    yield
+                end
+            ensure
+                @end_time = Time.now
+            end
+        end
+
+
+        # Called after the process executes and completes successfully.
+        #
+        # @param process_obj [Object] Object that is executing the batch
+        #   process.
+        # @param result [Object] The return value of the process.
+        def success(process_obj, result)
+            @status = :completed
+            @exit_code = 0 unless @exit_code
+            Events.publish(process_obj, event_name('success'), self, result)
+        end
+
+
+        # Called after the process executes and fails.
+        #
+        # @param process_obj [Object] Object that is executing the batch
+        #   process.
+        # @param exception [Exception] The exception that caused this runnable
+        #   to fail.
+        def failure(process_obj, exception)
+            @status = :failed
+            @exit_code = 1 unless @exit_code
+            @exception = exception
+            Events.publish(process_obj, event_name('failure'), self, exception)
+        end
+
+
+        # Called if a batch process is aborted.
+        #
+        # @param process_obj [Object] Object that is executing the batch
+        #   process.
+        def abort(process_obj)
+            @status = :aborted
+            Events.publish(process_obj, event_name('abort'), self)
+        end
+
+
+        # Called after the process executes.
+        #
+        # @param process_obj [Object] Object that is executing the batch
+        #   process.
+        # @param success [Boolean] True if the process completed without
+        #   throwing an exception.
+        def post_execute(process_obj, success)
+            Events.publish(process_obj, event_name('post-execute'), self, success)
+            @object = nil
+        end
+
+
+        private
+
+
+        # Replaces placeholder expressions in a property expression to return a
+        # property value for a job, task, etc. Property expressions may contain
+        # both references to arguments passed to a method, as well as Ruby
+        # expressions. Both are indicated by %{} or ${} delimiters surrounding
+        # the expression to be evaluated and replaced.
+        #
+        # @param property_expr [String] The expression to be evaluated.
+        # @param instance_obj [Object] The object against which Ruby expressions
+        #   in the property_expr will be evaluated.
+        # @param run_args [Array<Object>] An array of arguments passed to the
+        #   method used to execute the job, task, etc.
+        # @param conv_mthd [Symbol] The optional name of a method to call on the
+        #   result String to convert it to another type (Fixnum, Symbol, etc)
+        # @return [Object] The evaluated property value for this run.
+        def eval_property_expr(property_expr, instance_obj, run_args, conv_mthd = nil)
+            if property_expr
+                raise ArgumentError, "property_expr must be a String" unless property_expr.is_a?(String)
+                # Replace references to run arguments (i.e. ${0} to ${9}) first...
+                property = property_expr.gsub(/(?:\$|%)\{([0-9])\}/) do
+                    val = run_args[$1.to_i]
+                    val.is_a?(Array) ? val.join(', ') : val
+                end
+                # ... then evaluate any remaining expressions between ${} or %{}
+                property.gsub!(/(?:\$|%)\{([^\}]+)\}/) do
+                    val = instance_obj.instance_eval($1)
+                    val.is_a?(Array) ? val.join(', ') : val
+                end
+                property = property.length > 0 ?
+                    (conv_mthd ? property.send(conv_mthd) : property) : nil
+            end
+        end
+
+    end
+
+end
+

data/lib/batch-kit/framework/sequence.rb

@@ -0,0 +1,87 @@
+class BatchKit
+
+    class Sequence
+
+        include Arguments
+        include Configurable
+        include Loggable
+
+
+        # Include ActsAsSequence into any inheriting class
+        def self.inherited(sub_class)
+            sub_class.class_eval do
+                include ActsAsSequence
+            end
+        end
+
+
+        # A class variable for controlling whether sequences run; defaults to true.
+        # Provides a means for orchestration programs to prevent the running
+        # of sequences on require when sequences need to be runnable as standalone progs.
+        @@enabled = true
+        def self.enabled=(val)
+            @@enabled = val
+        end
+
+
+        # Import arguments defined on a Job into this sequence
+        def self.import_args(source, options={})
+            unless source.is_a?(ArgParser::Definition)
+                source = source.args_def
+            end
+            exclude = [options[:except]].flatten
+            source.args.each do |arg|
+                unless exclude.include?(arg.key)
+                    arg = arg.clone
+                    if self.args_def.short_keys.include?(arg.short_key)
+                        arg.instance_variable_set :@short_key, nil
+                    end
+                    self.args_def << arg
+                end
+            end
+        end
+
+
+        # A method that instantiates an instance of this job, parses
+        # arguments from the command-line, and then executes the job.
+        def self.run
+            if @@enabled
+                sequence = self.new
+                sequence.parse_arguments
+                unless self.sequence.method_name
+                    raise "No sequence entry method has been defined; use sequence :<method_name> or sequence do ... end in your class"
+                end
+                sequence.send(self.sequence.method_name)
+            end
+        end
+
+
+        def run(job_cls, args)
+            job = job_cls.new
+            keys, vals = [], []
+            job_cls.args_def.args.each do |arg|
+                keys << arg.key
+                if args.has_key?(arg.key)
+                    vals << args[arg.key]
+                elsif self.args_def.has_key?(arg.key)
+                    vals << self.arguments.send(arg.key)
+                else
+                    vals << nil
+                end
+            end
+            job_args = Struct.new(*keys)
+            job_arg_vals = job_args.new(*vals)
+            job.instance_variable_set(:@arguments, job_arg_vals)
+            if block_given?
+                yield job, job_arg_vals
+            else
+                unless job_cls.job.method_name
+                    raise "No job entry method has been defined; use job :<method_name> or job do ... end in your class"
+                end
+                job.send(job_cls.job.method_name)
+            end
+        end
+
+    end
+
+end

data/lib/batch-kit/framework/sequence_definition.rb

@@ -0,0 +1,38 @@
+class BatchKit
+
+    class Sequence
+
+        # Captures details about a sequence definition: the jobs contained,
+        # order of execution, etc.
+        class Definition < Definable
+
+            add_properties(
+                # Properties from job/task declarations
+                :sequence_class, :method_name, :computer, :file, :do_not_track, :jobs,
+                # Properties required by persistence layer
+                :sequence_id, :sequence_version
+            )
+
+
+            def initialize(sequence_class, sequence_file, sequence_name = nil)
+                raise ArgumentError, "sequence_class must be a Class" unless sequence_class.is_a?(Class)
+                @sequence_class = sequence_class
+                @file = sequence_file
+                @name = sequence_name || sequence_class.name.gsub(/([^A-Z ])([A-Z])/, '\1 \2').
+                    gsub(/_/, ' ').gsub('::', ':').gsub(/\b([a-z])/) { $1.upcase }
+                @computer = Socket.gethostname
+                @method_name = nil
+                @tasks = {}
+                super()
+            end
+
+
+            def to_s
+                "<BatchKit::Sequence::Definition #{name}>"
+            end
+
+        end
+
+    end
+
+end

data/lib/batch-kit/framework/sequence_run.rb

@@ -0,0 +1,48 @@
+class BatchKit
+
+    module Sequence
+
+        # Captures details of an execution of a task.
+        class Run < Runnable
+
+            # @return [Fixnum] An integer identifier that uniquely identifies
+            #    this task run.
+            attr_accessor :sequence_run_id
+
+            # Make Task::Defintion properties accessible off this Task::Run.
+            add_delegated_properties(*Sequence::Definition.properties)
+
+
+            # Create a new sequence run.
+            #
+            # @param task_def [Sequence::Definition] The Sequence::Definition to
+            #   which this run relates.
+            # @param job_object [Object] The job object instance from which the
+            #   sequence is being executed.
+            # @param run_args [Array<Object>] An array of the argument values
+            #   passed to the sequence method.
+            def initialize(seq_def, job_object, *run_args)
+                raise ArgumentError, "seq_def not a Sequence::Definition" unless seq_def.is_a?(Sequence::Definition)
+                super(seq_def, job_object, run_args)
+            end
+
+
+            # @return [Boolean] True if this sequence run should be persisted in
+            #   any persistence layer.
+            def persist?
+                !definition.do_not_track
+            end
+
+
+            # @return [String] A short representation of this Sequence::Run.
+            def to_s
+                "<BatchKit::Sequence::Run label='#{label}'>"
+            end
+
+        end
+
+    end
+
+end
+
+

data/lib/batch-kit/framework/task_definition.rb

@@ -0,0 +1,89 @@
+class BatchKit
+
+    module Task
+
+        # Captures details about a task definition - the job that it belongs to, the
+        # method name that performs the task work, etc.
+        class Definition < Definable
+
+            # @!attribute :task_name [String] The name of the task (defaults to the
+            #    method name).
+            # @!attribute :job [Job::Definition] The job that this task belongs to.
+            # @!attribute :method_name [Symbol] The name of the method that
+            #   performs the work for this task.
+            # @!attribute :task_id [Fixnum] A unique id for this Task::Definition,
+            #   assigned by the persistence layer.
+            add_properties(
+                # Properties defined by a task declaration
+                :job, :method_name,
+                # Properties defined by persistence layer
+                :task_id
+            )
+
+
+            # Create a new Task::Definition object for the task defined in +job_class+
+            # in +method_name+.
+            def initialize(job_class, method_name, task_name = nil)
+                raise ArgumentError, "job_class must be a Class" unless job_class.is_a?(Class)
+                raise ArgumentError, "method_name must be a Symbol" unless method_name.is_a?(Symbol)
+                job_defn = job_class.job
+                raise ArgumentError, "job_class must have a Job::Definition" unless job_defn
+
+                @name = task_name || method_name.to_s.gsub(/([^A-Z ])([A-Z])/, '\1 \2').
+                    gsub(/_/, ' ').gsub('::', ':').gsub(/\b([a-z])/) { $1.upcase }
+                @job = job_defn
+                @method_name = nil
+                self.method_name = method_name
+                @job << self
+                super()
+            end
+
+
+            # Return the class that defines the task.
+            def task_class
+                @job.job_class
+            end
+
+
+            # Define a task method - the method to be run to trigger the execution
+            # of a task.
+            #
+            # @param mthd_name [Symbol] The name of a method on the task class
+            #   that is executed to begin the task processing. Note: This method
+            #   must already exist on the task class when this setter is called, so
+            #   that it can be wrapped in an aspect with before/after processing.
+            def method_name=(mthd_name)
+                unless task_class.instance_methods.include?(mthd_name)
+                    raise ArgumentError, "Task class #{task_class.name} does not define a ##{mthd_name} method"
+                end
+                if @method_name
+                    raise "Task class #{task_class.name} already has a task method defined for ##{@method_name}"
+                end
+                @method_name = mthd_name
+
+                # Add an aspect for executing task
+                add_aspect(task_class, mthd_name)
+            end
+
+
+            # Create a new Task::Run object for a run of this task.
+            #
+            # @param job_obj [Object] The job object that is running this task.
+            # @param args [Array<Object>] The arguments passed to the task method.
+            def create_run(job_obj, *args)
+                task_run = Task::Run.new(self, job_obj, job_obj.job_run, *args)
+                @runs << task_run
+                task_run
+            end
+
+
+            def to_s
+                "<BatchKit::Task::Definition #{task_class.name}##{@method_name}>"
+            end
+
+        end
+
+    end
+
+end
+