copland 0.8.0

data/lib/copland/instantiator/identity.rb

@@ -0,0 +1,58 @@
+#--
+# =============================================================================
+# Copyright (c) 2004, Jamis Buck (jgb3@email.byu.edu)
+# All rights reserved.
+# 
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+# 
+#     * Redistributions of source code must retain the above copyright notice,
+#       this list of conditions and the following disclaimer.
+# 
+#     * Redistributions in binary form must reproduce the above copyright
+#       notice, this list of conditions and the following disclaimer in the
+#       documentation and/or other materials provided with the distribution.
+# 
+#     * The names of its contributors may not be used to endorse or promote
+#       products derived from this software without specific prior written
+#       permission.
+# 
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
+# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+# POSSIBILITY OF SUCH DAMAGE.
+# =============================================================================
+#++
+
+require 'copland/instantiator/abstract'
+
+module Copland
+  module Instantiator
+
+    # This trivial instantiator simply returns the definition that was given
+    # when it was created. Hence, it is a kind of "identity" operation. This
+    # kind of instantiator is only available programmatically--it cannot be
+    # specified in a descriptor file. It is used (for example) to back the
+    # "copland.Registry" service point by always returning the registry
+    # itself when the point is instantiated.
+    class Identity < Abstract
+
+      # Simply returns the definition data that was given when the instantiator
+      # was created.
+      def instantiate
+        definition
+      end
+
+      register_as "identity"
+
+    end
+
+  end
+end

data/lib/copland/instantiator/simple.rb

@@ -0,0 +1,68 @@
+#--
+# =============================================================================
+# Copyright (c) 2004, Jamis Buck (jgb3@email.byu.edu)
+# All rights reserved.
+# 
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+# 
+#     * Redistributions of source code must retain the above copyright notice,
+#       this list of conditions and the following disclaimer.
+# 
+#     * Redistributions in binary form must reproduce the above copyright
+#       notice, this list of conditions and the following disclaimer in the
+#       documentation and/or other materials provided with the distribution.
+# 
+#     * The names of its contributors may not be used to endorse or promote
+#       products derived from this software without specific prior written
+#       permission.
+# 
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
+# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+# POSSIBILITY OF SUCH DAMAGE.
+# =============================================================================
+#++
+
+require 'copland/utils'
+require 'copland/instantiator/abstract'
+require 'singleton'
+
+module Copland
+  module Instantiator
+
+    # A simple instantiator is used for instantiating a class. It does no other
+    # work than that.
+    class Simple < Abstract
+
+      # Takes the definition data that was given when the instantiator was
+      # created and treats it as the path to and name of the class to
+      # instantiate. This class is then instantiated and returned. This
+      # requires that the class have a no-argument constructor.
+      #
+      # If the class includes the Singleton module, then the singleton instance
+      # of the class will be returned.
+      def instantiate
+        unless @klass
+          @klass = Copland::get_class( definition )
+        end
+        if @klass.include?( Singleton )
+          @klass.instance
+        else
+          @klass.new
+        end
+      end
+
+      register_as "simple"
+
+    end
+
+  end
+end

data/lib/copland/interceptor-chain.rb

@@ -0,0 +1,166 @@
+#--
+# =============================================================================
+# Copyright (c) 2004, Jamis Buck (jgb3@email.byu.edu)
+# All rights reserved.
+# 
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+# 
+#     * Redistributions of source code must retain the above copyright notice,
+#       this list of conditions and the following disclaimer.
+# 
+#     * Redistributions in binary form must reproduce the above copyright
+#       notice, this list of conditions and the following disclaimer in the
+#       documentation and/or other materials provided with the distribution.
+# 
+#     * The names of its contributors may not be used to endorse or promote
+#       products derived from this software without specific prior written
+#       permission.
+# 
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
+# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+# POSSIBILITY OF SUCH DAMAGE.
+# =============================================================================
+#++
+
+require 'copland/errors'
+require 'copland/ordering'
+
+module Copland
+
+  # This module encapsulates the functionality for building interceptor chains.
+  module InterceptorChainBuilder
+
+    # The context of a method invocation.  This is used in an interceptor chain
+    # to encapsulate the elements of the current invocation.
+    # sym:   the name of the method being invoked
+    # args:  the argument list being passed to the method
+    # block: the reference to the block attached to the method invocation
+    InvocationContext = Struct.new( :sym, :args, :block )
+
+    # A single element in an interceptor chain.  Each interceptor object is
+    # wrapped in an instance of one of these.  Calling #process_next on a given
+    # chain element, invokes the #process method on the corresponding
+    # interceptor, with the next element in the chain being passed in.
+    class InterceptorChainElement
+
+      # Create a new InterceptorChainElement that wraps the given interceptor.
+      def initialize( interceptor )
+        @interceptor = interceptor
+      end
+
+      # Set the next element in the interceptor chain to the given object.  This
+      # must be either an InterceptorChainElement instance of a
+      # ProxyObjectChainElement instance.
+      def next=( next_obj )
+        @next_obj = next_obj
+      end
+
+      # Invokes the #process method of the interceptor encapsulated by this
+      # object, with the _next_ element in the chain being passed to it.
+      def process_next( context )
+        if @next_obj.nil?
+          raise CoplandError,
+            "[BUG] interceptor chain should always terminate with proxy"
+        end
+        @interceptor.process( @next_obj, context )
+      end
+
+    end
+
+    # Encapsulates the end of an interceptor chain, which is the actual object
+    # being effected.
+    class ProxyObjectChainElement
+
+      # Create a new ProxyObjectChainElement that wraps the given object.
+      def initialize( obj )
+        @obj = obj
+      end
+
+      # Invoke the method represented by the context on the wrapped object.
+      def process_next( context )
+        @obj.__send__( context.sym, *context.args, &context.block )
+      end
+
+    end
+
+    # This is just a trivial proxy class that is used to wrap a service
+    # before the interceptors are applied to it. This additional level of
+    # abstractions prevents the need for mangling the names of the service's
+    # methods, and also offers those applications that need it the ability
+    # to invoke methods of the service without going through the interceptors.
+    #
+    # The proxy will be decorated with dynamically appended methods by the
+    # InterceptorChainBuilder#build method.
+    class InterceptedServiceProxy
+
+      # Create a new InterceptedServiceProxy that wraps the given interceptor
+      # chain.
+      def initialize( chain )
+        @chain = chain
+      end
+
+    end
+
+    # This will apply the given interceptors to the given service by first
+    # ordering the interceptors based on their before and after preferences,
+    # and then dynamically modifying the service's methods so that the chain
+    # of interceptors sits in front of each of them.
+    #
+    # The modified service is returned.
+    def build( service, interceptors )
+      return service if interceptors.empty?
+
+      ordered_list = Orderer.order( interceptors )
+
+      chain = ProxyObjectChainElement.new( service )
+
+      ordered_list.reverse.each do |interceptor|
+        element = InterceptorChainElement.new( interceptor.instantiate )
+        element.next = chain
+        chain = element
+      end
+
+      # FIXME: should inherited methods of "Object" be interceptable?
+      methods_to_intercept = ( service.class.instance_methods( true ) -
+                               Object.instance_methods +
+                               service.class.instance_methods( false ) ).uniq
+
+      service = InterceptedServiceProxy.new( chain )
+      singleton = class << service; self; end
+
+      methods_to_intercept.each do |method|
+        next if method =~ /^__/
+
+        singleton.class_eval <<-EOF
+          def #{method}( *args, &block )
+            context = InvocationContext.new( :#{method}, args, block )
+            @chain.process_next( context )
+          end
+        EOF
+      end
+
+      # allow the interceptor to intercept methods not explicitly
+      # declared on the reciever.
+      singleton.class_eval <<-EOF
+        def method_missing( sym, *args, &block )
+          context = InvocationContext.new( sym, args, block )
+          @chain.process_next( context )
+        end
+      EOF
+
+      return service
+    end
+    module_function :build
+
+  end
+
+end

data/lib/copland/interceptor.rb

@@ -0,0 +1,139 @@
+#--
+# =============================================================================
+# Copyright (c) 2004, Jamis Buck (jgb3@email.byu.edu)
+# All rights reserved.
+# 
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+# 
+#     * Redistributions of source code must retain the above copyright notice,
+#       this list of conditions and the following disclaimer.
+# 
+#     * Redistributions in binary form must reproduce the above copyright
+#       notice, this list of conditions and the following disclaimer in the
+#       documentation and/or other materials provided with the distribution.
+# 
+#     * The names of its contributors may not be used to endorse or promote
+#       products derived from this software without specific prior written
+#       permission.
+# 
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
+# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+# POSSIBILITY OF SUCH DAMAGE.
+# =============================================================================
+#++
+
+require 'copland/errors'
+
+module Copland
+
+  # Represents an interceptor associated with a <em>service point</em>, not a
+  # _service_. When the service point with which this interceptor is associated
+  # is instantiated, the #instantiate method of this object will be invoked to
+  # obtain the actual interceptor instance.
+  #
+  # This wrapper object encapsulates the "before" and "after" lists, as well,
+  # which are used to determine the order in which the interceptors on the
+  # associated service point are invoked for each intercepted method call.
+  class Interceptor
+
+    # The service point with which this interceptor is associated.
+    attr_reader :owner
+
+    # The service point of the factory that will return the interceptor
+    # instance on demand.
+    attr_reader :point
+
+    # The array of interceptor service point _names_ (not services) that
+    # this interceptor should come before.
+    attr_reader :before
+
+    # The array of interceptor service point _names_ (not services) that
+    # this interceptor should come after.
+    attr_reader :after
+
+    # A hash of the constructor parameters that should be sent to the factory
+    # when instantiating the interceptor service. This attribute is the value
+    # of the hash <em>prior to processing by any schema</em>.
+    attr_reader :construction_parms
+
+    # Create a new interceptor on the given +owner+ service point, with the
+    # associated +definition+ map. The map _must_ include a value named
+    # "service", which should be the name of the service point of the factory
+    # that will be used to instantiate the interceptor when needed. If
+    # "before" or "after" exist, they are interpreted to be the "before" and
+    # "after" attributes of this interceptor. (If either of them are strings,
+    # they will be converted into an array of one element; otherwise, they
+    # should be arrays.)
+    #
+    # Any other elements in the +definition+ map will be used as constructor
+    # parameters.
+    def initialize( owner, definition )
+      @owner = owner
+
+      unless definition[ "service" ] 
+        raise MissingImplementationException,
+          "interceptor for #{owner.full_name} needs 'service' element"
+      end
+
+      @point = owner.find_service_point( definition[ "service" ] )
+
+      @before = [ *( definition[ "before" ] || [] ).dup ]
+      @after = [ *( definition[ "after" ] || [] ).dup ]
+
+      definition = definition.dup
+      definition.delete "service"
+      definition.delete "before"
+      definition.delete "after"
+
+      @construction_parms = definition
+
+      schema = point.schema
+      if schema.respond_to?( :validate )
+        schema.validate @point, @owner, @construction_parms
+      end
+    end
+
+    # Return an instance of the interceptor service that is wrapped by this
+    # object. This is done by invoking the #create_instance method on the
+    # factory service. If the factory service point has a schema associated
+    # with it, it will be used to pre-process the parameters.
+    def instantiate
+      @factory = @point.instance unless @factory
+
+      parms = @construction_parms
+      schema = @point.schema
+      if schema.respond_to?( :process )
+        parms = schema.process( point, owner, parms )
+      end
+
+      @factory.create_instance( @owner, parms )
+    end
+
+    # Returns +true+ if +self+ should be ordered before +interceptor+.
+    def before?( interceptor )
+      a = before.include?( interceptor.point.full_name )
+      b = interceptor.after.include?( point.full_name )
+
+      return a || b
+    end
+
+    # Returns +true+ if +self+ should be ordered after +interceptor+.
+    def after?( interceptor )
+      a = after.include?( interceptor.point.full_name )
+      b = interceptor.before.include?( point.full_name )
+
+      return a || b
+    end
+
+  end
+
+end

data/lib/copland/log-factory.rb

@@ -0,0 +1,206 @@
+#--
+# =============================================================================
+# Copyright (c) 2004, Jamis Buck (jgb3@email.byu.edu)
+# All rights reserved.
+# 
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+# 
+#     * Redistributions of source code must retain the above copyright notice,
+#       this list of conditions and the following disclaimer.
+# 
+#     * Redistributions in binary form must reproduce the above copyright
+#       notice, this list of conditions and the following disclaimer in the
+#       documentation and/or other materials provided with the distribution.
+# 
+#     * The names of its contributors may not be used to endorse or promote
+#       products derived from this software without specific prior written
+#       permission.
+# 
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
+# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+# POSSIBILITY OF SUCH DAMAGE.
+# =============================================================================
+#++
+
+require 'logger'
+require 'thread'
+require 'yaml'
+
+module Copland
+
+  # A factory class that returns Logger instances. The LogFactory is not
+  # a singleton for the same reason that Copland::Registry is not a 
+  # singleton--the allow multiple registries to exist simultaneously.
+  # Since each registry has its own logger factory, the logger factory
+  # must be separately instantiable.
+  class LogFactory
+
+    # The default name of the logger configuration file. This file will be used
+    # to read default properties for initializing logger objects.
+    DEFAULT_CONFIG_FILE = "./logger.yml"
+
+    # The default name of the log file to write to.
+    DEFAULT_LOG_FILENAME = "./copland.log"
+
+    # Translate names of levels to their actual values.
+    LEVEL_TRANSLATOR = {
+      "DEBUG" => Logger::DEBUG,
+      "INFO" => Logger::INFO,
+      "WARN" => Logger::WARN,
+      "ERROR" => Logger::ERROR,
+      "FATAL" => Logger::FATAL,
+      "UNKNOWN" => Logger::UNKNOWN
+    }
+
+    # The default (date) format string to use when logging.
+    attr_reader :default_format
+
+    # The default log level to use for logs that are created.
+    attr_reader :default_level
+
+    # The device that logs will write to.
+    attr_reader :device
+
+    # Create a new LogFactory using the given initialization parameters.
+    # The valid options are:
+    #
+    # * <tt>:config_file</tt>: the configuration file from which to read
+    #   logger configuration options.
+    # * <tt>:device</tt>: the device (pseudo-IO object) to write log
+    #   messages to. Either this, or <tt>:filename</tt> must be specified.
+    # * <tt>:filename</tt>: the filename of the log to write to.
+    # * <tt>:roll_age</tt>: the number of days before the log should be
+    #   rolled.
+    # * <tt>:roll_frequency</tt>: either 'daily', 'weekly', or 'monthly'.
+    # * <tt>:roll_size</tt>: the maximum size of a log file.
+    # * <tt>:default_format</tt>: the default date format string for the log.
+    # * <tt>:default_level</tt>: the default log level for the log.
+    # * <tt>:levels</tt>: a hash of patterns that map to a hash of 'level'
+    #   and 'format' keys, specifying the log level and date format for any
+    #   log whose name matches the key.
+    def initialize( opts={} )
+      opts[ :config_file ] ||= DEFAULT_CONFIG_FILE
+      read_config opts
+
+      if opts[ :device ]
+        @device = opts[ :device ]
+      else
+        filename = opts[ :filename ] || DEFAULT_LOG_FILENAME
+        roll_age = opts[ :roll_age ] || opts[ :roll_frequency ] || 0
+        roll_size = opts[ :roll_size ]
+        @device = Logger::LogDevice.new( filename,
+                      :shift_age => roll_age,
+                      :shift_size => roll_size )
+      end
+
+      @default_format = opts[ :default_format ]
+      @default_level = opts[ :default_level ]
+
+      @levels = Hash.new "level" => nil, "format" => nil 
+
+      ( opts[ :levels ] || Hash.new ).each_pair do |key, value|
+        key = Regexp.new( "^" + key.gsub( /\./, "\\." ).gsub( /\*/, ".*" ) )
+        value = { "level" => value } if value.is_a? String
+        @levels[ key ] = value
+      end
+
+      @loggers = Hash.new
+
+      @mutex = Mutex.new
+    end
+
+    # Read the configuration parameters from the logger configuration file.
+    # If the file does not exist or is not readable by the current user, this
+    # method does nothing.
+    def read_config( opts )
+      file = opts[ :config_file ]
+      if File.exist?( file ) && File.readable?( file )
+        config = YAML.load( File.read( file ) )
+        opts[ :default_format ] ||= config[ "default-format" ]
+        opts[ :default_level ] ||=
+          LEVEL_TRANSLATOR[ config[ "default-level" ] ] ||
+          config[ "default-level" ]
+        opts[ :filename ] ||= config[ "filename" ]
+        opts[ :roll_age ] ||= config[ "roll-age" ]
+        opts[ :roll_frequency ] ||= config[ "roll-frequency" ]
+        opts[ :roll_size ] ||= config[ "roll-size" ]
+        opts[ :levels ] ||= config[ "levels" ]
+      end
+    end
+    private :read_config
+
+    # Searches for a level definition hash that matches the given log
+    # name.
+    def find_definition( name )
+      best_match = { :length => 0, :value => Hash.new }
+
+      @levels.each_pair do |key, value|
+        length = key.to_s.length
+        if best_match[ :length ] < length && key === name
+          best_match[ :length ] = length
+          best_match[ :value ] = value
+        end
+      end
+
+      return best_match[ :value ]
+    end
+    private :find_definition
+
+    # Retrieves the logger with the given name. If no such log has been
+    # created, the log will be created and initialized. Otherwise, the
+    # log with the given name is returned.
+    def get( name )
+      # the common case first, outside the synchronize, for speed
+      return @loggers[ name ] if @loggers[ name ]
+
+      @mutex.synchronize do
+        # check again, inside the synchronize, to avoid race conditions
+        return @loggers[ name ] if @loggers[ name ]
+
+        definition = find_definition( name )
+
+        level = definition[ "level" ] || @default_level
+        format = definition[ "format" ] || @default_format
+
+        level = LEVEL_TRANSLATOR[ level ] || level
+
+        logger = Logger.new( @device )
+        logger.level = level if level
+        logger.datetime_format = format if format
+        logger.progname = name
+
+        @loggers[ name ] = logger
+        return logger
+      end
+    end
+
+    # Closes the logging device and makes this factory invalid for future
+    # accesses.
+    def close
+      @mutex.synchronize do
+        return if @closed
+
+        @device.close unless [ $stdout, $stderr ].include?( @device )
+
+        @loggers = nil
+        @closed = true
+      end
+    end
+
+    # Returns true if the factory has been closed.
+    def closed?
+      @closed
+    end
+
+  end
+
+end