copland 0.8.0

data/lib/copland/impl/startup.rb

@@ -0,0 +1,116 @@
+#--
+# =============================================================================
+# 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/ordering'
+
+module Copland
+  module Implementation
+
+    # This wraps a single service as a client to the Startup service.
+    # It provides the necessary #before? and #after? abstractions required
+    # by the Orderer module (which is used by Startup to order the
+    # clients before starting them).
+    class StartupClient
+
+      # The service point that is wrapped by this object.
+      attr_reader :point
+
+      # The array of names of service points that should start after this
+      # service point.
+      attr_reader :before
+
+      # The array of names of service points that should start before this
+      # service point.
+      attr_reader :after
+
+      # Instantiate a new client that wraps the given service point, and
+      # its before and after lists. These lists should be arrays of the
+      # <em>full names</em> of other services.
+      def initialize( point, before, after )
+        @point = point
+        @before = before
+        @after = after
+      end
+
+      # Returns +true+ if +self+ should be started before +e+.
+      def before?( e )
+        @before.include?( e.point.full_name ) ||
+        e.after.include?( point.full_name )
+      end
+
+      # Returns +true+ if +self+ should be after before +e+.
+      def after?( e )
+        @after.include?( e.point.full_name ) ||
+        e.before.include?( point.full_name )
+      end
+    end
+
+    # This class is accessed via the singleton system service
+    # <tt>copland.Startup</tt>. It listens to the registry, and when it
+    # receives notification that the registry has been initialized, it will
+    # start all (enabled) services listed in the <tt>copland.Startup</tt>
+    # configuration point.
+    class Startup
+
+      # Setter for the clients collection
+      attr_writer :clients
+
+      # Setter for the instantiating registry
+      attr_writer :registry
+
+      # Invoked by Copland when the registry has been initialized. This allows
+      # the service to then instantiate each of its registered services in
+      # turn, in the order they were requested.
+      def start
+        list = []
+        @clients.each do |client|
+          enabled = client.fetch( 'enabled', true )
+          if enabled
+            service_name = client['service']
+            before = [ *( client['before'] || [] ) ] 
+            after = [ *( client['after'] || [] ) ]
+
+            list << StartupClient.new(
+              @registry.service_point( service_name ),
+              before, after )
+          end
+        end
+
+        list = Orderer.order( list )
+        list.each { |client| client.point.instance }
+      end
+
+    end
+
+  end
+end

data/lib/copland/impl/symbol-source-manager.rb

@@ -0,0 +1,131 @@
+#--
+# =============================================================================
+# 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/ordering'
+require 'copland/utils'
+
+module Copland
+  module Implementation
+
+    # A utility class for representing a single symbol source definition.
+    # It is used only during the construction of a SymbolSourceManager class,
+    # when the ordering of the sources must be ascertained.
+    class SymbolSourceDefinition
+
+      # The name of the symbol source.
+      attr_accessor :name
+
+      # The symbol source itself, either a service a directly-instantiated
+      # object.
+      attr_accessor :source
+
+      # The array of sources that this source should be ordered before.
+      attr_accessor :before
+
+      # The array of sources that this source should be ordered after.
+      attr_accessor :after
+
+      # Create a new SymbolSourceDefinition from the given definition.
+      # The definition should match the schema for the SymbolSources
+      # configuration point, although no checking is done here.
+      def initialize( definition )
+        @name = definition[ 'name' ]
+
+        source = definition[ 'source' ]
+        if source.is_a?( String )
+          @source = Copland::get_class( source ).new
+        else
+          @source = source
+        end
+
+        @before = definition[ 'before' ] || []
+        @after = definition[ 'after' ] || []
+      end
+
+      # Return +true+ if the given source should be ordered after # +self+.
+      def before?( source )
+        @before.include?( source.name ) ||
+          source.after.include?( @name )
+      end
+
+      # Return +true+ if the given source should be ordered before # +self+.
+      def after?( source )
+        @after.include?( source.name ) ||
+          source.before.include?( @name )
+      end
+    end
+
+    # The implementation of the SymbolSourceManager service. It forms the
+    # central repository of all symbols in Copland, and which clients may
+    # query the values of any defined symbols.
+    class SymbolSourceManager
+
+      # A unique value, used for identifying whether or not a value was found
+      # in a symbol source.
+      NOT_FOUND = Object.new
+
+      # Create a new SymbolSourceManager, using the given array of source
+      # definitions.
+      def initialize( sources )
+        @sources = sources.map { |entry| SymbolSourceDefinition.new( entry ) }
+        @sources = Copland::Orderer.order( @sources ).map { |v| v.source }
+      end
+      
+      # Returns +true+ if the source contains a symbol with the given name.
+      def has_symbol?( name )
+        found = @sources.find { |source| source.has_symbol?( name ) }
+        return !found.nil?
+      end
+
+      # Returns the value of the given symbol, or the value of +default+ if no
+      # such symbol exists in source.
+      def lookup( name, default=nil )
+        @sources.each do |source|
+          value = source.lookup( name, NOT_FOUND )
+          if value != NOT_FOUND
+            return value
+          end
+        end
+
+        return default
+      end
+
+      # A convenience method that just delegates to #lookup.
+      def []( name )
+        lookup( name )
+      end
+
+    end
+
+  end
+end

data/lib/copland/impl/symbol-source.rb

@@ -0,0 +1,63 @@
+#--
+# =============================================================================
+# 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.
+# =============================================================================
+#++
+
+module Copland
+  module Implementation
+
+    # The default SymbolSource implementation, used by both the
+    # ApplicationDefaults and FactoryDefaults implementations.
+    class SymbolSource
+
+      # The map configuration point that backs this service.
+      attr_accessor :defaults
+
+      # Returns +true+ if the source contains a symbol with the given name.
+      def has_symbol?( name )
+        defaults.has_key?( name )
+      end
+
+      # Returns the value of the given symbol, or the value of +default+ if no
+      # such symbol exists in source.
+      def lookup( name, default=nil )
+        defaults.fetch( name, default )
+      end
+
+      # A convenience method that just delegates to #lookup.
+      def []( name )
+        lookup( name )
+      end
+
+    end
+
+  end
+end

data/lib/copland/instantiator.rb

@@ -0,0 +1,38 @@
+#--
+# =============================================================================
+# 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'
+
+require 'copland/instantiator/simple'
+require 'copland/instantiator/complex'
+require 'copland/instantiator/identity'

data/lib/copland/instantiator/abstract.rb

@@ -0,0 +1,91 @@
+#--
+# =============================================================================
+# 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/class-factory'
+
+module Copland
+  module Instantiator
+
+    # The name of the ClassFactory pool associated with instantiators.
+    POOL_NAME = "instantiator"
+
+    begin
+      factory = Copland::ClassFactory.instance
+      factory.create_pool( POOL_NAME )
+    end
+
+    # The ancestor class of all instantiators. It provides functionality
+    # common to all instantiators.
+    class Abstract
+
+      # The service point that this instantiator is intended to, well,
+      # instantiate.
+      attr_reader :point
+
+      # The definition data for this instantiator. Each subclass may choose to
+      # interpret this property differently.
+      attr_reader :definition
+
+      # Create a new instantiator using the given service point and
+      # definition data.
+      def initialize( point, definition )
+        @point = point
+        @definition = definition
+      end
+
+      # Raises a NotImplementedError. Subclasses must override this
+      # method and provide functionality for instantiating a service point.
+      def instantiate
+        raise NotImplementedError
+      end
+
+      # Does nothing.
+      def validate!
+      end
+
+      # A convenience method for registering +self+ with the ClassFactory
+      # under the given name. This will also add a +name+ method to the
+      # class, which will return the value of the +name+ parameter.
+      def self.register_as( name )
+        class_eval <<-EOF
+          def name
+            #{name.inspect}
+          end
+        EOF
+        Copland::ClassFactory.instance.register( POOL_NAME, name, self )
+      end
+
+    end
+
+  end
+end

data/lib/copland/instantiator/complex.rb

@@ -0,0 +1,96 @@
+#--
+# =============================================================================
+# 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/instantiator/abstract'
+
+module Copland
+  module Instantiator
+
+    # The Complex instantiator is a more sophisticated way of instantiating
+    # services. It provides for the wiring of dependencies into the new service
+    # "automatically" (based on specified dependencies). This instantiator is
+    # what allows Copland to claim support for "dependency injection."
+    class Complex < Abstract
+
+      register_as "complex"
+
+      # The hash of parameters to pass to the instantiating factory.
+      attr_reader :construction_parms
+
+      # The service point of the factory to use to instantiate the service.
+      attr_reader :factory_point
+
+      # Create a new Complex instantiator for the given service point, using
+      # the given +definition+ hash.
+      def initialize( point, definition )
+        super point, definition
+
+        @factory_id = definition[ "factory" ] || "copland.BuilderFactory"
+        @factory_id = @factory_id.value if @factory_id.respond_to?( :value )
+
+        @construction_parms = definition.dup
+        @construction_parms.delete "factory"
+      end
+
+      # Validates the parameters to this instantiator by running them through
+      # the schema of the associated factory service point (if any).
+      def validate!
+        @factory_point = point.find_service_point( @factory_id )
+
+        schema = @factory_point.schema
+        if schema.respond_to?( :validate )
+          schema.validate @factory_point, point, construction_parms
+        end
+      end
+
+      # Create a new instance of the service via the factory service. The
+      # constructor parameters are passed through the factory's schema
+      # (if any) before passing them to the factory's +create_instance+
+      # method.
+      def instantiate
+        @factory = @factory_point.instance unless @factory
+
+        parms = @construction_parms
+        schema = @factory_point.schema
+        if schema.respond_to?( :process )
+          parms = schema.process( @factory_point, point, parms )
+        end
+        
+        @factory.create_instance( point, parms )
+      end
+
+    end
+
+  end
+end