batch-kit 0.3

data/lib/batch-kit/events.rb

@@ -0,0 +1,157 @@
+class BatchKit
+
+    # Manages batch event notifications and subscriptions, which provide a
+    # useful means of decoupling different components of the batch library.
+    #
+    # The problem we are looking to solve here is that we want our batch jobs,
+    # tasks etc to be able to notify interested parties when something happens
+    # (e.g. a task starts, a job fails, etc) without these event sources needing
+    # to know all the interested parties to notify. We therefore introduce an
+    # intermediary, which is the Events system.
+    #
+    # Interested parties register their interest in specific events or event
+    # classes by subscribing to the events of interest. Framework classes then
+    # notify the Event system when an event occurs, and the event system routes
+    # these notifications on to all registered subscribers.
+    #
+    # One of the problems we need to solve for is how subscribers can define the
+    # scope of their interest. Is it all events of a particular type, regardless
+    # of source? Or are we only interested in events from a specific source (e.g
+    # job or task)?
+    class Events
+
+        # Records subscription details
+        class Subscription
+
+            attr_reader :source, :event, :callback, :raise_on_error
+
+
+            def initialize(source, event, options, callback)
+                @source = source
+                @event = event
+                @raise_on_error = options.fetch(:raise_on_error, true)
+                @callback = callback
+            end
+
+
+            def ===(obj)
+                @source.nil? ||             # Nil source means match any obj
+                    (@source == obj) ||     # Source is obj
+                    (@source === obj) ||    # obj is an instance of source class
+                    (@source.instance_of?(Module) && obj.instance_of?(Class) &&
+                     obj.include?(@source))   # Source is a module included by obj
+            end
+
+        end
+
+
+
+        class << self
+
+            # @param source [Object] The source of the event
+            # @param event [String] The name of the event
+            # @return [Boolean] whether there are any subscribers for the specified
+            #   event.
+            def has_subscribers?(source, event)
+                subscribers.has_key?(event) && subscribers[event].size > 0 &&
+                    subscribers[event].find{ |sub| sub === source }
+            end
+
+
+            # Setup a subscription for a particular event. When a matching event
+            # occurs, the supplied block will be called with the published
+            # arguments.
+            #
+            # @param source [Object] The type of source object from which to
+            #   listen for events.
+            # @param event [String] The name of the event to subscribe to.
+            # @param options [Hash] An options hash defining optional settings
+            #   for the subscription.
+            # @option options [Fixnum] :position The position within the list to
+            #   insert the subscriber. Default is to add to the end of the list.
+            # @param callback [Proc] A block to be invoked when the event occurs.
+            def subscribe(source, event, options = {}, &callback)
+                @log.trace "Adding subscriber for #{source} event '#{event}'" if @log
+                position = options.fetch(:position, -1)
+                if event.is_a?(Array)
+                    event.each{ |e| subscribers[e].insert(position, Subscription.new(source, e, options, callback)) }
+                else
+                    subscribers[event].insert(position, Subscription.new(source, event, options, callback))
+                end
+            end
+
+
+            # Remove a subscriber
+            #
+            # @param source [Object] The object that is the source of the event
+            #   from which to unsubscribe.
+            # @param event [String] The name of the event to unsubscribe from.
+            def unsubscribe(source, event)
+                @log.trace "Removing subscriber(s) for #{source} event '#{event}'" if @log
+                subscribers[event].delete_if{ |sub| sub === source }
+            end
+
+
+            # Publishes an event to all registered subscribers.
+            #
+            # @param source [Object] The source from which the event has been
+            #   generated.
+            # @param event [String] The name of the event that has occurred.
+            # @param payload [*Object] Arguments passed with the event.
+            def publish(source, event, *payload)
+                @log.trace "Publishing event '#{event}' for #{source}" if @log
+                res = true
+                count = 0
+                if subscribers.has_key?(event)
+                    subscribers[event].each do |sub|
+                        if sub === source
+                            begin
+                                r = sub.callback.call(source, *payload)
+                                count += 1
+                                res &&= r
+                            rescue StandardError => ex
+                                if sub.raise_on_error
+                                    raise
+                                else
+                                    STDERR.puts "Exception in '#{event}' event listener for #{source}: #{ex}\n" +
+                                        "  at: #{ex.backtrace[0...10].join("\n")}"
+                                end
+                            end
+                        end
+                    end
+                    @log.debug "Notified #{count} listeners of '#{event}'" if @log
+                end
+                res
+            end
+
+
+            # Enable/disable event debugging
+            def debug=(dbg)
+                @log = dbg ? LogManager.logger('batch.events') : nil
+            end
+
+
+            # Dumps a list of events and their subscribers to the logger
+            def dump_subscribers(show_event = nil, log = @log)
+                if log
+                    subscribers.each do |event, subs|
+                        if show_event.nil? || show_event == event
+                            log.info "Subscribers for event '#{event}':"
+                            subs.each{ |sub| log.detail sub.inspect }
+                        end
+                    end
+                end
+            end
+
+
+            private
+
+            def subscribers
+                @subscribers ||= Hash.new{ |h, k| h[k] = [] }
+            end
+
+        end
+
+    end
+
+end

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

@@ -0,0 +1,197 @@
+class BatchKit
+
+    # When included into a class, marks the class as a BatchKit job.
+    # The including class has the following class methods added, which act as a
+    # DSL for specifying the job properties and behaviour:
+    # - {ClassMethods#desc desc} A method for setting a description for a
+    #   subsequent job or task
+    # - {ClassMethods#job job} Defines a job entry method
+    # - {ClassMethods#task task} Defines a task method
+    # - {ClassMethods#job_definition job_definition} Returns the Job::Definition
+    #   object for the including class
+    # - {ClassMethods#on_success on_success} defines a callback to be called if
+    #   the job completes successfully.
+    # - {ClassMethods#on_failure on_failure} defines a callback to be called if
+    #   the job encounters an unhandled exception.
+    # - {ClassMethods#on_completion} defines a callback to be called when the
+    #   job completes.
+    #
+    # Instances of the including class also get the following instance methods:
+    # - {#job} Returns the Job::Definition for the class
+    # - {#job_run} Returns the Job::Run associated with this object instance.
+    module ActsAsJob
+
+        # Define methods to be added to the class that includes this module.
+        module ClassMethods
+
+            # @return The Job::Definition object used to hold attributes of this
+            #   job.
+            def job_definition
+                @__job__
+            end
+            alias_method :definition, :job_definition
+
+
+            # Captures a description for the following task or job definition.
+            #
+            # @param desc [String] The description to associate with the next
+            #   task or job that is defined.
+            def desc(desc)
+                @__desc__ = desc
+            end
+
+
+            # Defines the method that is used to run this job.
+            # This may be an existing method, in which case the name of the
+            # method must be passed as the first argument.
+            # Alternatively, a block may be supplied, which will be used to
+            # create the job method.
+            #
+            # @param job_method [Symbol] The name of an existing method that is
+            #   to be the job entry point.
+            # @param job_opts [Hash] Options that affect the job definition.
+            # @option job_opts [Symbol] :method_name The name to be assigned to
+            #   the job method created from the supplied block. Default is
+            #   :execute.
+            # @option job_opts [String] :description A description for the job.
+            def job(job_method = nil, job_opts = @__desc__, &body)
+                # If called as an accessor, just return the @__job__
+                if  job_method || job_opts || body
+                    unless job_method.is_a?(Symbol)
+                        job_opts = job_method
+                        job_method = (job_opts && job_opts.is_a?(Hash) &&
+                            job_opts[:method_name]) || :execute
+                    end
+
+                    job_desc = nil
+                    if job_opts.is_a?(Hash)
+                        job_desc = @__desc__
+                    elsif job_opts.is_a?(String)
+                        job_desc = job_opts
+                        job_opts = {}
+                    elsif job_opts.nil?
+                        job_opts = {}
+                    end
+                    @__desc__ = nil
+
+                    # Define job method if a body block was supplied
+                    define_method(job_method, &body) if body
+
+                    opts = job_opts.clone
+                    opts[:description] = job_desc unless opts[:description]
+                    opts[:method_name] = job_method
+                    # The @__job__ instance variable is crated when this module is included
+                    @__job__.set_from_options(opts)
+                end
+                @__job__
+            end
+
+
+            # Defines the method that is used to run a task.
+            # This may be an existing method, in which case the name of the
+            # method must be passed as the first argument.
+            # Alternatively, a block may be supplied, which will be used to
+            # create the task method.
+            #
+            # @param task_method [Symbol] The name for the method that is to be
+            #  this task. May be the name of an existing method (in which case
+            #  no block should be supplied), or the name to give to the method
+            #  that will be created from the supplied block.
+            # @param task_opts [Hash] A hash containing options for the task
+            #  being defined.
+            # @option task_opts [Symbol] :method_name The name for the method
+            #  if no symbol was provided as the first argument.
+            # @option job_opts [String] :description A description for the task.
+            def task(task_method, task_opts = @__desc__, &body)
+                unless task_method.is_a?(Symbol)
+                    task_opts = task_method
+                    task_method = task_opts && task_opts[:method_name]
+                end
+                raise ArgumentError, "No method name specified for task" unless task_method
+
+                task_desc = nil
+                if task_opts.is_a?(Hash)
+                    task_desc = @__desc__
+                elsif task_opts.is_a?(String)
+                    task_desc = task_opts
+                    task_opts = {}
+                elsif task_opts.nil?
+                    task_opts = {}
+                end
+                @__desc__ = nil
+
+                # Define task method if a body block was supplied
+                define_method(task_method, &body) if body
+
+                opts = task_opts.clone
+                opts[:description] = task_desc unless opts[:description]
+
+                # Create a new TaskDefinition class for the task
+                task_defn = Task::Definition.new(self, task_method)
+                task_defn.set_from_options(opts)
+                task_defn
+            end
+
+
+            # Defines a handler to be invoked if the job encounters an unhandled
+            # exception.
+            def on_failure(mthd = nil, &blk)
+                Events.subscribe(self, 'job_run.failure'){ |jr, obj, ex| obj.send(mthd, ex) } if mthd
+                Events.subscribe(self, 'job_run.failure'){ |jr, obj, ex| obj.instance_exec(ex, &blk) } if blk
+            end
+
+
+            # Defines a handler to be invoked if the job ends successfully.
+            def on_success(mthd = nil, &blk)
+                Events.subscribe(self, 'job_run.success'){ |jr, obj| obj.send(mthd) } if mthd
+                Events.subscribe(self, 'job_run.success'){ |jr, obj| obj.instance_exec(&blk) } if blk
+            end
+
+
+            # Defines a handler to be invoked on completion of the job, whether
+            # the job completes successfully or fails. The handler may be specified
+            # as either a method name and/or via a block. Multiple calls to this
+            # method can be made to register multiple callbacks if desired.
+            #
+            # @param mthd [Symbol] The name of an existing method on the including
+            #   class. This method will be called with the Job::Run object that
+            #   represents the completing job run.
+            # 
+            def on_completion(mthd = nil, &blk)
+                Events.subscribe(self, 'job_run.post-execute'){ |jr, obj, ok| obj.send(mthd, jr) } if mthd
+                Events.subscribe(self, 'job_run.post-execute'){ |jr, obj, ok| obj.instance_exec(jr, &blk) } if blk
+            end
+
+        end
+
+
+        # Hook used to extend the including class with class methods defined in
+        # the ActsAsJob::ClassMethods module.
+        #
+        # Creates a Job::Definition object to hold details of the job, and stores
+        # it away in a @__job__ class instance variable.
+        def self.included(base)
+            base.extend(ClassMethods)
+            caller.find{ |f| !(f =~ /batch-kit.framework/) } =~ /^((?:[a-zA-Z]:)?[^:]+)/
+            job_file = File.realpath($1)
+            job_defn = Job::Definition.new(base, job_file)
+            base.instance_variable_set :@__job__, job_defn
+            Events.publish(base, 'acts_as_job.included', job_defn)
+        end
+
+
+        # @return [Job::Definition] The JobDefinition for this job instance.
+        def job
+            self.class.job_definition
+        end
+
+
+        # @return [Job::Run] The JobRun for this job instance.
+        def job_run
+            @__job_run__
+        end
+
+    end
+
+end
+

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

@@ -0,0 +1,123 @@
+class BatchKit
+
+    # When included into a class, marks the class as a BatchKit sequence.
+    # The including class has the following class methods added, which act as a
+    # DSL for specifying the sequence properties and behaviour:
+    # - {ClassMethods#desc desc} A method for setting a description for a
+    #   subsequent sequence
+    # - {ClassMethods#sequence sequence} Defines a sequence entry method
+    # - {ClassMethods#sequence_definition sequence_definition} Returns the
+    #   Sequence::Definition object for the including class
+    # - {ClassMethods#on_success on_success} defines a callback to be called if
+    #   the sequence completes successfully.
+    # - {ClassMethods#on_failure on_failure} defines a callback to be called if
+    #   the sequence encounters an unhandled exception.
+    #
+    # Instances of the including class also get the following instance methods:
+    # - {#sequence} Returns the Sequence::Definition for the class
+    # - {#sequence_run} Returns the Sequence::Run associated with this object instance.
+    module ActsAsSequence
+
+        # Define methods to be added to the class that includes this module.
+        module ClassMethods
+
+            # @return The Sequence::Definition object used to hold attributes of this
+            #   sequence.
+            def sequence_definition
+                @__sequence__
+            end
+            alias_method :definition, :sequence_definition
+
+
+            # Captures a description for the following sequence definition.
+            #
+            # @param desc [String] The description to associate with the next
+            #   sequence, job, or task that is defined.
+            def desc(desc)
+                @__desc__ = desc
+            end
+
+
+            # Defines the method that is used to run this job.
+            # This may be an existing method, in which case the name of the
+            # method must be passed as the first argument.
+            # Alternatively, a block may be supplied, which will be used to
+            # create the job method.
+            #
+            # @param sequence_method [Symbol] The name of an existing method that is
+            #   to be the sequence entry point.
+            # @param sequence_opts [Hash] Options that affect the sequence definition.
+            # @option sequence_opts [Symbol] :method_name The name to be assigned to
+            #   the sequence method created from the supplied block. Default is
+            #   :execute.
+            # @option sequence_opts [String] :description A description for the sequence.
+            def sequence(sequence_method = nil, sequence_opts = @__desc__, &body)
+                # If called as an accessor, just return the @__sequence__
+                if  sequence_method || sequence_opts || body
+                    unless sequence_method.is_a?(Symbol)
+                        sequence_opts = sequence_method
+                        sequence_method = (sequence_opts && sequence_opts.is_a?(Hash) &&
+                            sequence_opts[:method_name]) || :execute
+                    end
+
+                    sequence_desc = nil
+                    if sequence_opts.is_a?(Hash)
+                        sequence_desc = @__desc__
+                    elsif sequence_opts.is_a?(String)
+                        sequence_desc = sequence_opts
+                        sequence_opts = {}
+                    elsif sequence_opts.nil?
+                        sequence_opts = {}
+                    end
+                    @__desc__ = nil
+
+                    # Define sequence method if a body block was supplied
+                    define_method(sequence_method, &body) if body
+
+                    opts = sequence_opts.clone
+                    opts[:description] = sequence_desc unless opts[:description]
+                    opts[:method_name] = sequence_method
+                    # The @__sequence__ instance variable is crated when this module is included
+                    @__sequence__.set_from_options(opts)
+                end
+                @__sequence__
+            end
+
+        end
+
+
+        # Hook used to extend the including class with class methods defined in
+        # the ActsAsSequence::ClassMethods module.
+        #
+        # Creates a Sequence::Definition object to hold details of the sequence,
+        # and stores it away in a @__sequence__ class instance variable.
+        def self.included(base)
+            base.extend(ClassMethods)
+            caller.find{ |f| !(f =~ /batch.framework/) } =~ /^((?:[a-zA-Z]:)?[^:]+)/
+            sequence_file = File.realpath($1)
+            sequence_defn = Sequence::Definition.new(base, sequence_file)
+            base.instance_variable_set :@__sequence__, sequence_defn
+        end
+
+
+        def parallel
+            # TODO: Implement running contents of block in parallel
+            yield
+        end
+
+
+        # @return [Sequence::Definition] The SequenceDefinition for this Sequence instance.
+        def sequence
+            self.class.sequence_definition
+        end
+
+
+        # @return [Sequence::Run] The SequenceRun for this Sequence instance.
+        def sequence_run
+            @__sequence_run__
+        end
+
+    end
+
+end
+