batch-kit 0.3

data/lib/batch-kit/logging/java_util_logger.rb

@@ -0,0 +1,87 @@
+require 'java'
+
+
+class BatchKit
+
+    module Logging
+
+        class JavaLogFacade
+
+            LEVEL_MAP = {
+                :error => Java::JavaUtilLogging::Level::SEVERE,
+                :warning => Java::JavaUtilLogging::Level::WARNING,
+                :info => Java::JavaUtilLogging::Level::INFO,
+                :config => Java::JavaUtilLogging::Level::CONFIG,
+                :detail => Java::JavaUtilLogging::Level::FINE,
+                :trace => Java::JavaUtilLogging::Level::FINER,
+                :debug => Java::JavaUtilLogging::Level::FINEST
+            }
+
+            # @return The path to any log file used with this logger
+            attr_reader :log_file
+
+
+            def initialize(logger)
+                @java_logger = logger
+            end
+
+
+            def level
+                LEVEL_MAP.invert[@java_logger.getLevel()]
+            end
+
+
+            def level=(level)
+                @java_logger.setLevel(LEVEL_MAP[level])
+            end
+
+
+            # Adds a FileHandler to capture output from this logger to a log file.
+            def log_file=(log_path)
+                @java_logger.getHandlers().each do |h|
+                    if h.is_a?(Java::JavaUtilLogging::FileHandler)
+                        @java_logger.removeHandler(h)
+                        h.close()
+                    end
+                end
+                @log_file = log_path
+                if log_path
+                    # Java logger does not follow changes in working directory via Dir.chdir
+                    log_path = File.absolute_path(log_path)
+                    FileUtils.mkdir_p(File.dirname(log_path))
+                    fh = Java::JavaUtilLogging::FileHandler.new(log_path, true)
+                    if defined?(Console::JavaUtilLogger)
+                        fmt = Console::JavaUtilLogger::RubyFormatter.new('[%1$tF %1$tT]  %4$-6s  %5$s', -1)
+                        fmt.level_labels[Java::JavaUtilLogging::Level::FINE] = 'DETAIL'
+                        fmt.level_labels[Java::JavaUtilLogging::Level::FINER] = 'TRACE'
+                    else
+                        fmt = Java::JavaUtilLogging::SimpleFormatter.new
+                    end
+                    fh.setFormatter(fmt)
+                    self.addHandler(fh)
+                end
+            end
+
+
+            BatchKit::Logging::LEVELS.each do |lvl|
+                java_mthd = LEVEL_MAP[lvl].getName().downcase.intern
+                class_eval <<-EOD
+                    def #{lvl}(msg)
+                        @java_logger.#{java_mthd}(msg.to_s)
+                    end
+                EOD
+            end
+
+            alias_method :warn, :warning
+
+
+            def method_missing(mthd, *args)
+                @java_logger.send(mthd, *args)
+            end
+
+        end
+
+    end
+
+end
+

data/lib/batch-kit/logging/log4r_logger.rb

@@ -0,0 +1,71 @@
+require 'log4r'
+require 'log4r/configurator'
+
+Log4r::Configurator.custom_levels(*BatchKit::Logging::LEVELS.reverse.map{ |l| l.to_s.upcase })
+
+
+
+class BatchKit
+
+    module Logging
+
+        class Log4rFacade
+
+            def initialize(logger)
+                @log4r_logger = logger
+            end
+
+
+            def level
+                Log4r::LNAMES[@log4r_logger.level].downcase.intern
+            end
+
+
+            def level=(lvl)
+                @log4r_logger.level = Log4r::LNAMES.index(lvl.to_s.upcase)
+            end
+
+
+            def log_file
+                out_name = "#{self.name}_file"
+                fo = @log4r_logger.outputters.find{ |o| o.name == out_name }
+                fo && fo.filename
+            end
+
+
+            def log_file=(log_path)
+                out_name = "#{self.name}_file"
+                if outputter = Log4r::Outputter[out_name]
+                    outputter.close
+                    @log4r_logger.remove out_name
+                end
+                if log_path
+                    FileUtils.mkdir_p(File.dirname(log_path))
+                    formatter = Log4r::PatternFormatter.new(pattern: '[%d] %-6l %x %M\r')
+                    outputter = Log4r::FileOutputter.new(out_name, filename: log_path,
+                                                         trunc: false, formatter: formatter)
+                    @log4r_logger.add out_name
+                end
+            end
+
+
+            BatchKit::Logging::LEVELS.each do |lvl|
+                class_eval <<-EOD
+                    def #{lvl}(msg)
+                        @log4r_logger.#{lvl}(msg)
+                    end
+                EOD
+            end
+
+            alias_method :warn, :warning
+
+
+            def method_missing(mthd, *args)
+                @log4r_logger.send(mthd, *args)
+            end
+
+        end
+
+    end
+
+end

data/lib/batch-kit/logging/null_logger.rb

@@ -0,0 +1,35 @@
+class BatchKit
+
+    module Logging
+
+        # Implements a NULL logger, i.e. a logger that throws away log messages.
+        # This logger should be used when no logging is desired.
+        class NullLogger
+
+
+            def self.instance
+                @instance ||= self.new
+            end
+
+
+            def log_level=(level)
+            end
+
+
+            LEVELS.each do |level|
+                define_method level do |*args|
+                    log_msg(level, *args)
+                end
+            end
+
+            alias_method :warn, :warning
+
+
+            def log_msg(level, msg)
+            end
+
+        end
+
+    end
+
+end

data/lib/batch-kit/logging/stdout_logger.rb

@@ -0,0 +1,96 @@
+class BatchKit
+
+    module Logging
+
+        class StdOutLogger
+
+            def self.logger(name)
+                @loggers ||= {}
+                @loggers[name] ||= self.new(name)
+            end
+
+
+            # @return [String] The name of this logger
+            attr_reader :name
+            # @return [Symbol] The current level at which logging is set
+            attr_accessor :level
+            # @return [String] The log file path, if any
+            attr_reader :log_file
+
+            # Width at which to split lines
+            attr_accessor :width
+            # Amount by which to indent lines
+            attr_accessor :indent
+
+
+            def initialize(name, level = :detail)
+                @name = name
+                @level = level
+                @indent = 8
+                @width = Console.width if use_console?
+            end
+
+
+            LEVELS.each do |level|
+                define_method level do |*args|
+                    log_msg(level, *args)
+                end
+            end
+
+            alias_method :warn, :warning
+
+
+            def log_file=(log_path, options = {})
+                @log_file.close if @log_file
+                if log_path
+                    append = options.fetch(:append, true)
+                    @log_file = File.new(log_path, append ? 'a' : 'w')
+                end
+            end
+
+
+            def log_msg(level, *args)
+                return if LEVELS.index(level) > LEVELS.index(@level)
+                lvl = level.to_s.upcase
+                msg = args.join(' ')
+                spacer = LEVELS.index(level) >= LEVELS.index(:config) ? '  ' : ''
+                fmt_msg = "%-6s  %s%s" % [lvl, spacer, msg]
+                if use_console?
+                    color = case level
+                    when :error then :red
+                    when :warning then :yellow
+                    when :info then :white
+                    when :config then :cyan
+                    when :detail then :light_gray
+                    else :dark_gray
+                    end
+
+                    indent = @indent || 0
+                    indent += 2 if indent > 0 && [:config, :detail, :trace, :debug].include?(level)
+
+                    msg = @width ? Console.wrap_text(msg, @width - indent) : [msg]
+                    msg = msg.each_with_index.map do |line, i|
+                        "%-6s  %s%s" % [[lvl][i], spacer, line]
+                    end.join("\n")
+                    Console.puts msg, color
+                else
+                    STDOUT.puts fmt_msg
+                end
+                if @log_file
+                    @log_file.puts Time.now.strftime('[%F %T] ') + fmt_msg
+                end
+            end
+
+
+            def use_console?
+                unless @use_console
+                    @use_console = defined?(::Console)
+                end
+                @use_console
+            end
+
+        end
+
+    end
+
+end

data/lib/batch-kit/resources.rb

@@ -0,0 +1,191 @@
+require 'set'
+require_relative 'events'
+
+
+class BatchKit
+
+    # Defines a manager for resource types, such as database connections etc.
+    # Resource types are registered with this class, which then adds acquisition
+    # methods to the ResourceHelper module. These acquisition methods add the
+    # acquired objects to a collection managed by the objects of the class that
+    # includes the ResourceHelper, and modify the returned resource objects so
+    # that they automatically de-register themselves if they are disposed of
+    # explicitly.
+    class ResourceManager
+
+        class << self
+
+            # Returns an unbound method object that represents the method that
+            # should be called to dispose of +rsrc+.
+            def disposal_method(rsrc)
+                disp_mthd = resource_types[rsrc.class] || resource_types.find{ |rt, _| rt === rsrc }.last rescue nil
+                disp_mthd or raise ArgumentError, "No registered resource class matches '#{rsrc.class}'"
+            end
+
+
+            # Register a resource type for automated resource management.
+            #
+            # @param rsrc_cls [Class] The class of resource to be managed. This
+            #   must be the type of the object that will be returned when an
+            #   instance of this resource is acquired.
+            # @param helper_mthd [Symbol] The name of the resource acquisition
+            #   helper method that should be added to the ResourceHelper module.
+            # @param options [Hash] An options class.
+            # @option options [Symbol] :acquisition_method For cases where an
+            #   existing method can be called directly on the +rsrc_cls+ to
+            #   obtain a resource (rather than passing in a block containing
+            #   resource acquisition steps), the name of that method. Defaults
+            #   to :open.
+            # @option options [Symbol] :disposal_method The name of the method
+            #   to be called on the resource to dispose of it. Defaults to
+            #   :close.
+            def register(rsrc_cls, helper_mthd, options = {}, &body)
+                if ResourceHelper.method_defined?(helper_mthd)
+                    raise ArgumentError, "Resource acquisition method #{helper_mthd} is already registered"
+                end
+                unless body
+                    open_mthd = options.fetch(:acquisition_method, :open)
+                    body = lambda{ |*args| rsrc_cls.send(open_mthd, *args) }
+                end
+                disp_mthd = options.fetch(:disposal_method, :close)
+
+                if rsrc_cls.method_defined?(disp_mthd)
+                    if (m = resource_types[rsrc_cls]) && m.name != disp_mthd
+                        raise ArgumentError, "Resource class #{rsrc_cls} has already been registered" +
+                            " with a different disposal method (##{m.name})"
+                    else
+                        resource_types[rsrc_cls] = rsrc_cls.instance_method(disp_mthd)
+                    end
+                else
+                    raise ArgumentError, "No method named '#{disp_mthd}' is defined on #{rsrc_cls}"
+                end
+
+                # Define the helper method on the ResourceHelper module. This is
+                # necessary (as opposed to just calling the block from the
+                # acquisition methd) in order to ensure that self etc are set
+                # correctly
+                ResourceHelper.class_eval{ define_method(helper_mthd, &body) }
+
+                # Now wrap an aspect around the method to handle the tracking of
+                # resources acquired, and event notifications
+                add_aspect(rsrc_cls, helper_mthd, disp_mthd)
+                Events.publish(self, 'resource.registered', rsrc_cls, helper_mthd)
+            end
+
+
+            private
+
+
+            def resource_types
+                @resource_types ||= {}
+            end
+
+
+            # Define the helper method to acquire a resource, publish events about
+            # the resource lifecycle, and track the usage of the resource to
+            # ensure we know about unreleased resources and can clean then up at
+            # the appropriate time when the owning object is done with them.
+            def add_aspect(rsrc_cls, helper_mthd, disp_mthd)
+                mthd = ResourceHelper.instance_method(helper_mthd)
+                ResourceHelper.class_eval do
+                    define_method helper_mthd do |*args|
+                        if Events.publish(rsrc_cls, 'resource.pre_acquire', *args)
+                            result = nil
+                            begin
+                                result = mthd.bind(self).call(*args)
+                                unless rsrc_cls === result
+                                    raise ArgumentError, "Returned resource is of type #{
+                                        result.class.name}, not #{rsrc_cls}"
+                                end
+                                # Override disposal method on this acquired instance
+                                # to call #dispose_resource instead
+                                defn = self
+                                result.define_singleton_method(disp_mthd) do
+                                    defn.dispose_resource(self)
+                                end
+                                add_resource(result)
+                                Events.publish(rsrc_cls, 'resource.acquired', result)
+                                result
+                            rescue Exception => ex
+                                Events.publish(rsrc_cls, 'resource.acquisition_failed', ex)
+                                raise
+                            end
+                        end
+                    end
+                end
+            end
+
+        end
+
+    end
+
+
+
+    # A module that can be included in a class to provide resource acquisition
+    # with automated resource cleanup.
+    #
+    # Resources acquired via this module are tracked, and can be disposed of
+    # when no longer needed via a call to the #cleanup_resources method.
+    #
+    # The benefits of including and using ResourceHelper module:
+    # - Resource acquisition can be setup to use a common configuration process,
+    #   such as obtaining connection details from a shared configuration file.
+    # - All resources obtained by an object can be freed when the object is
+    #   done with them by calling the #cleanup_resources.
+    module ResourceHelper
+
+        # Register a resource for later clean-up
+        def add_resource(rsrc)
+            # Ensure we know how to dispose of this resource
+            ResourceManager.disposal_method(rsrc)
+            (@__resources__ ||= Set.new) << rsrc
+        end
+
+
+        # Dispose of a resource.
+        #
+        # This method will be called automatically whenever a resource is closed
+        # manually (via a call to the resources normal disposal method, e.g.
+        # #close), or when #cleanup_resources is used to tidy-up all managed
+        # resources.
+        def dispose_resource(rsrc)
+            disp_mthd = ResourceManager.disposal_method(rsrc)
+            @__resources__.delete(rsrc)
+            if Events.publish(rsrc, 'resource.pre-disposal')
+                begin
+                    disp_mthd.bind(rsrc).call
+                    Events.publish(rsrc, 'resource.disposed')
+                rescue Exception => ex
+                    Events.publish(rsrc, 'resource.disposal-failed', ex)
+                    raise
+                end
+            end
+        end
+
+
+        # Dispose of all resources managed by this object.
+        def cleanup_resources
+            if @__resources__
+                @__resources__.clone.reverse_each do |rsrc|
+                    dispose_resource(rsrc)
+                end
+                @__resources__ = nil
+            end
+        end
+
+
+        # Add automatic disposal of resources on completion of job if included
+        # into a job.
+        def self.included(cls)
+            if (defined?(BatchKit::Job) && BatchKit::Job == cls) ||
+                (defined?(BatchKit::ActsAsJob) && cls.include?(BatchKit::ActsAsJob))
+                Events.subscribe(BatchKit::Job::Run, 'post-execute') do |run, job_obj, ok|
+                    job_obj.cleanup_resources
+                end
+            end
+        end
+
+    end
+
+end
+