batch-kit 0.3

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

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

data/lib/batch-kit/helpers/date_time.rb

@@ -0,0 +1,54 @@
+
+class BatchKit
+
+    module Helpers
+
+        # Methods for displaying times/durations
+        module DateTime
+
+            # Converts the elapsed time in seconds to a string showing days, hours,
+            # minutes and seconds.
+            def display_duration(elapsed)
+                return nil unless elapsed
+                elapsed = elapsed.round
+                display = ''
+                [['days', 86400], ['h', 3600], ['m', 60], ['s', 1]].each do |int, seg|
+                    if elapsed >= seg
+                        count, elapsed = elapsed.divmod(seg)
+                        display << "#{count}#{int.length > 1 && count == 1 ? int[0..-2] : int} "
+                    elsif display.length > 0
+                        display << "0#{int}"
+                    end
+                end
+                display = "0s" if display == ''
+                display.strip
+            end
+            module_function :display_duration
+
+
+            # Displays a date/time in abbreviated format, suppressing elements of
+            # the format string for more recent dates/times.
+            #
+            # @param ts [Time, Date, DateTime] The date/time object to be displayed
+            # @return [String] A formatted representation of the date/time.
+            def display_timestamp(ts)
+                return unless ts
+                ts_date = ts.to_date
+                today = Date.today
+                if today - ts_date < 7
+                    # Date is within the last week
+                    ts.strftime('%a %H:%M:%S')
+                elsif today.year != ts.year
+                    # Data is from a different year
+                    ts.strftime('%a %b %d %Y %H:%M:%S')
+                else
+                    ts.strftime('%a %b %d %H:%M:%S')
+                end
+            end
+            module_function :display_timestamp
+
+        end
+
+    end
+
+end

data/lib/batch-kit/helpers/email.rb

@@ -0,0 +1,198 @@
+require 'mail'
+require_relative '../core_ext/file_utils'
+require_relative 'html'
+require_relative 'date_time'
+
+
+class BatchKit
+
+    module Helpers
+
+        # Defines a number of methods to help with generating email messages in
+        # both plain-text and HTML formats.
+        module Email
+
+            include Html
+
+            # Creates a new Mail message object that can be used to create and
+            # send an email.
+            #
+            # @param cfg [BatchKit::Config] A config object containing details of
+            #   an SMTP gateway for delivering the message. Defaults to the
+            #   config object defined by including BatchKit#Configurable.
+            def create_email(cfg = nil)
+                cfg = config if cfg.nil? && self.respond_to?(:config)
+                Mail.defaults do
+                    delivery_method :smtp, cfg.smtp
+                end
+
+                Mail.new(to: mail_list(cfg[:to]),
+                         cc: mail_list(cfg[:cc]),
+                         from: cfg[:email_from] || "#{self.job.job_class.name}@#{self.job.computer}",
+                         reply_to: mail_list(cfg[:reply_to]))
+            end
+
+
+            # Mail likes its recipient lists as a comma-separated list in a
+            # String. To make this easier to use, this helper method converts
+            # an array of values into sucn a string.
+            def mail_list(recips)
+                recips.is_a?(Array) ? recips.join(', ') : recips
+            end
+
+
+            # Creates an HTML formatted email, with a default set of styles.
+            #
+            # @param cfg [BatchKit::Config] A config object containing details of
+            #   an SMTP gateway for delivering the message. Defaults to the
+            #   config object defined by including BatchKit#Configurable.
+            # @param body_text [String] An optional string containing text to
+            #   add to the email body.
+            # @yield [Array<String>] an Array of strings to which body content
+            #   can be added.
+            def create_html_email(cfg = config, body_text = nil, &blk)
+                if cfg.is_a?(String) || cfg.is_a?(Array)
+                    body_text = cfg
+                    cfg = nil
+                end
+                msg = create_email(cfg)
+                body = create_html_document(body_text, &blk)
+                msg.html_part = Mail::Part.new do |part|
+                  part.content_type('text/html; charset=UTF-8')
+                  part.body(body.join("\n"))
+                end
+                msg
+            end
+
+
+            # Adds details of tasks run and their duration to an email.
+            #
+            # @param body [Array<String>] An array containing the lines of the
+            #   message body. Job execution details will be added as an HTML
+            #   table to this.
+            def add_job_details_to_email(body)
+                has_instances = self.job_run.task_runs.find{ |tr| tr.instance }
+                body << "<br>"
+                body << "<div class='separator'></div>"
+                body << "<p>"
+                body << "<p>Job execution details:</p>"
+                create_html_table(body, self.job_run.task_runs,
+                                  {name: :name, label: 'Task'},
+                                  {name: :instance, show: has_instances},
+                                  {name: :start_time, label: 'Start Time'},
+                                  {name: :end_time, label: 'End Time'},
+                                  {label: 'Duration', class: 'right',
+                                   value: lambda{ |tr| DateTime.display_duration(tr.elapsed) }})
+                body.slice!(-2..-1)
+                body << "<tr><th>#{self.job.name}</th>"
+                body << "<th>#{self.job_run.instance}</th>" if has_instances
+                body << "<th class='right'>#{self.job_run.start_time.strftime("%H:%M:%S")}</th>"
+                body << "<th class='right'></th>"
+                body << "<th class='right'>#{DateTime.display_duration(self.job_run.elapsed)}</th></tr>"
+                body << "</tbody>"
+                body << "</table>"
+                body << "<br>"
+            end
+
+
+            # Creates an email message containing details of the exception that
+            # caused this job to fail.
+            def create_failure_email(cfg = config)
+                msg = create_email(cfg)
+                to = cfg[:failure_email_to]
+                to = to.join(', ') if to.is_a?(Array)
+                cc = cfg[:failure_email_cc]
+                cc = cc.join(', ') if cc.is_a?(Array)
+                msg.to = to
+                msg.cc = cc
+                msg.subject = "#{self.job.name} job on #{self.job.computer} Failed!"
+
+                # Add details of the failed job and task runs
+                body = []
+                self.job.runs.each do |jr|
+                    ex = nil
+                    jr.task_runs.select{ |tr| tr.exception != nil }.each do |tr|
+                        ex = tr.exception
+                        body << "Job '#{jr.label}' has failed in task '#{tr.label}'."
+                        body << "\n#{ex.class.name}: #{ex.message}"
+                        body << "\nBacktrace:"
+                        body += ex.backtrace
+                        body << "\n"
+                    end
+                    if ex != jr.exception
+                        body << "Job '#{jr.label}' has failed."
+                        body << "\n#{jr.exception.class.name}: #{jr.exception.message}"
+                        body << "\nBacktrace:"
+                        body += jr.exception.backtrace
+                        body << "\n"
+                    end
+                end
+
+                # Add job log file as attachment (if it exists)
+                if self.respond_to?(:log) && self.log.log_file
+                    body << "See the attached log for details.\n"
+                    msg.add_file(self.log.log_file)
+                end
+                msg.body = body.join("\n")
+                msg
+            end
+
+
+            # Sends a failure email message in response to a job failure.
+            #
+            # @param recipients [String|Array] The recipient(s) to receive the
+            #   email. If no recipients are specified, the con
+            def send_failure_email(cfg = config, recipients = nil)
+                unless cfg.is_a?(Hash)
+                    recipients = cfg
+                    cfg = config
+                end
+                msg = create_failure_email(cfg)
+                if recipients
+                    # Override default recipients
+                    msg.to = recipients
+                    msg.cc = nil
+                end
+                msg.deliver!
+                log.detail "Failure email sent to #{recipient_count(msg)} recipients"
+            end
+
+
+            # Given a message, returns the number of recipients currently set.
+            #
+            # @param msg [Mail] A Mail message object.
+            def recipient_count(msg)
+                count = 0
+                count += msg.to.size if msg.to
+                count += msg.cc.size if msg.cc
+                count
+            end
+
+
+            # Saves the content of a message to a file.
+            #
+            # @param msg [Mail] The message whose content is to be saved.
+            # @param path [String] The path to the file to be created.
+            # @param options [Hash] An options hash; see FileUtils.archive for
+            #   details of supported option settings.
+            def save_msg_to_file(msg, path, options = {})
+                FileUtils.archive(path, options)
+                file = File.open(path, "w")
+                in_html = false
+                msg.html_part.to_s.each_line do |line|
+                    line.chomp!
+                    in_html ||= (line =~ /^<html/i)
+                    if in_html
+                        file.puts line
+                        file.puts "<title>#{msg.subject}</title>" if line =~ /<head>/
+                    end
+                end
+                file.close
+                log.detail "Saved email body to #{path}"
+            end
+
+        end
+
+    end
+
+end

data/lib/batch-kit/helpers/html.rb

@@ -0,0 +1,175 @@
+require_relative '../core_ext/numeric'
+require_relative '../core_ext/string'
+
+
+class BatchKit
+
+    module Helpers
+
+        # Defines a number of methods to help with generating simple HTML documents
+        module Html
+
+            # Creates a new HTML document with a pre-defined set of styles
+            def create_html_document(body_text = nil, opts = {})
+                if body_text.is_a?(Hash)
+                    opts = body_text
+                    body_text = nil
+                end
+
+                hdr = <<-EOS.gsub(/\s{20}/, '')
+                    <html>
+                    #{create_head_tag(opts)}
+                    <body>
+                EOS
+                body = [hdr]
+                body << body_text if body_text
+                yield body if block_given?
+                body << <<-EOS.gsub(/\s{20}/, '')
+                    </body>
+                    </html>
+                EOS
+            end
+
+
+            def create_head_tag(opts = {})
+                head_tag = <<-EOS.gsub(/^\w+\n$/, '')
+                    <head>
+                    <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=us-ascii">
+                    #{opts[:title] ? "<title>#{opts[:title]}</title>" : ''}
+                    #{create_style_tag(opts)}
+                    </head>
+                EOS
+            end
+
+
+            def create_style_tag(opts = {})
+                font = opts.fetch(:font, 'Calibri')
+                style_tag = <<-EOS
+                    <style>
+                        @font-face {font-family: #{font};}
+
+                        h1      {font-family: #{font}; font-size: 16pt;}
+                        h2      {font-family: #{font}; font-size: 14pt; margin: 1em 0em .2em;}
+                        h3      {font-family: #{font}; font-size: 12pt; margin: 1em 0em .2em;}
+                        body    {font-family: #{font}; font-size: 11pt;}
+                        p       {margin: .2em 0em;}
+                        table   {font-family: #{font}; font-size: 10pt;
+                                 line-height: 12pt; border-collapse: collapse;}
+                        th      {background-color: #00205B; color: white;
+                                 font-size: 11pt; font-weight: bold; text-align: left;
+                                 border: 1px solid #DDDDFF; padding: 1px 5px;}
+                        td      {border: 1px solid #DDDDFF; padding: 1px 5px;}
+
+                        .summary    {font-size: 13pt;}
+                        .red        {background-color: white; color: #FF0000;}
+                        .amber      {background-color: white; color: #FFA500;}
+                        .green      {background-color: white; color: #33A000;}
+                        .blue       {background-color: white; color: #0000A0;}
+                        .bold       {font-weight: bold;}
+                        .center     {text-align: center;}
+                        .right      {text-align: right;}
+                        .separator  {width: 200px; border-bottom: 1px gray solid;}
+                    </style>
+                    </head>
+                    <body>
+                EOS
+            end
+
+
+            # Creates an HTML table from +data+.
+            #
+            # @param body [Array] The HTML body to which this table will be
+            #   appended.
+            # @param data [Array|Hash] The data to be added to the table.
+            # @param cols [Array<Symbol|String|Hash>] An array of symbols,
+            #   strings, or Hashes. String and symbols output as-is, while the
+            #   hash can contain various options that control the display of
+            #   the column and the content below it, as follows:
+            #     - :name is the name of the property. It will be used to access
+            #       data values if +data+ is a Hash, and will be used as the
+            #       column header unless a :label property is passed.
+            #     - :label is the label to use as the column header.
+            #     - :class specifies a CSS class name to assign to each cell in
+            #       the column.
+            #     - :show is a boolean that determines whether the column is
+            #       output or suppressed.
+            #     - :prefix is any text that should appear before the content.
+            #     - :suffix is any text that should appear after the content.
+            def create_html_table(body, data, *cols)
+                cols.map!{ |col| col.is_a?(Symbol) || col.is_a?(String) ? {name: col.intern} : col }
+                body << "<table>"
+                body << "<thead><tr>"
+                add_table_cells(body,
+                                cols.map{ |col| (col[:label] || col[:name]).to_s.titleize },
+                                cols.map{ |col| {show: col.fetch(:show, true)} },
+                                :th)
+                body << "</tr></thead>"
+                body << "<tbody>"
+                data.each do |row|
+                    body << "<tr>"
+                    add_table_cells(body, row, cols)
+                    body << "</tr>"
+                end
+                body << "</tbody>"
+                body << "</table>"
+            end
+
+
+            # Adds a row of cells to a table.
+            #
+            # @param body [Array<String>] An array of lines containing the body
+            #   of the HTML message to which this table row should be added.
+            # @param row [Array, Hash, Object] An Array, Hash, or Object from
+            #   which a row of data shall be retrieved to populate the table.
+            # @param cols [Array<Hash>] An Array of Hashes, each containing
+            #   details for a single column. Each Hash can contain the following
+            #   options:
+            #     - :class: The CSS class with which to style the column cells.
+            #     - :show: A boolean value indicating whether the column should
+            #       be displayed or skipped.
+            #     - :prefix: Text to appear before the content of the cell.
+            #     - :suffix: Text to appear after the content of the cell.
+            #     - :value: A setting controlling how values are retrieved from
+            #       +row+. By default, this is by index, but this setting can
+            #       override that, and either supply a name or method to call
+            #       on +row+, or a Proc object to invoke on row.
+            # @param cell_type [Symbol] Either :td (the default) or :th.
+            def add_table_cells(body, row, cols, cell_type = :td)
+                cols.each_with_index do |col, i|
+                    cls = col[:class]
+                    show = col.fetch(:show, true)
+                    prefix = col.fetch(:prefix, '')
+                    suffix = col.fetch(:suffix, '')
+                    next if !show
+                    val = case
+                    when col[:value]
+                        col[:value].call(row)
+                    when row.is_a?(Array)
+                        row[i]
+                    when row.is_a?(Hash)
+                        row[col[:name]]
+                    when row.respond_to?(col[:name])
+                        row.send(col[:name])
+                    when row.respond_to?(:[])
+                        row[col[:name]]
+                    else
+                        row
+                    end
+                    case val
+                    when Numeric
+                        val = val.with_commas
+                        cls = 'right' unless cls
+                    when Date, Time, DateTime
+                        val = val.strftime('%H:%M:%S')
+                        cls = 'right' unless cls
+                    end
+                    td = %Q{<#{cell_type}#{cls ? " class='#{cls}'" : ''}>#{prefix}#{val}#{suffix}</#{cell_type}>}
+                    body << td
+                end
+            end
+
+        end
+
+    end
+
+end