copland 0.8.0

data/lib/copland/schema.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 'copland/utils'
+
+module Copland
+
+  # This class represents a single node in a schema "tree". The entire tree is
+  # the actual schema, where it is recursively defined using instances of this
+  # class.
+  class Schema
+
+    # The children nodes of this schema node. If +nil+, then this is a leaf
+    # node.
+    attr_reader :definition
+
+    # The optional description of this schema.
+    attr_reader :description
+
+    # The path description that identifies the class to use when processing
+    # this schema.
+    attr_reader :processor_path
+
+    # The optional name of this schema.
+    attr_reader :name
+
+    # Whether or not this node is required.
+    attr_reader :required
+
+    # The type of this node. If +nil+, then it may be of any type.
+    attr_reader :type
+
+    # The owning package of this schema.
+    attr_accessor :owner
+
+    # The schema that this schema extends.
+    attr_accessor :extends
+    
+    # Create a new schema node with the given name, processor class,
+    # description, required-flag, type, and definition. If processor is +nil+,
+    # then the DefaultSchemaProcessor class will be used.
+    def initialize( name, processor, description,
+                    required, type, definition,
+                    extends )
+    #begin
+      @definition, @description, @name = definition, description, name
+      @processor_path, @required, @type = processor, required, type
+      @extends = extends
+    end
+
+    # Returns the fully-qualified name of this schema, but only if the schema
+    # has both a name and an owning package. Otherwise, it returns +nil+.
+    def full_name
+      if @owner && @name
+        @owner.name + "." + @name
+      end
+    end
+
+    # Validate the given data against this schema node. The +owner+ is the
+    # service point (or configuration point) that the schema is being
+    # processed for, and the +client+ is the service point (or configuration
+    # point) that the +data+ is being processed for. If +path+ is given, it
+    # represents the path through the schema leading to this node. If
+    # processor is given, then it should be used to process this node as long
+    # as it is of the same type as this node's processor.
+    def validate( owner, client, data, path="/", processor=nil )
+      # always make sure the schema has been fixated before we try to validate
+      # anything with it.
+      fixate!
+
+      processor = get_processor( processor )
+
+      if processor.respond_to?( :validate )
+        if data.is_a?( Array ) ||
+          ( data.respond_to?( :type_id ) && data.type_id == "array" )
+        # then
+          data = data.value if data.respond_to?( :type_id )
+          index = 0
+          data.each do |item|
+            processor.validate( owner, client, self, item, "#{path}[#{index}]" )
+            index += 1
+          end
+        else
+          processor.validate( owner, client, self, data, path )
+        end
+      end
+    end
+
+    # Preprocess the given data against this schema node. The +owner+ is the
+    # service point (or configuration point) that the schema is being
+    # processed for, and the +client+ is the service point (or configuration
+    # point) that the +data+ is being processed for. If +path+ is given, it
+    # represents the path through the schema leading to this node. If
+    # processor is given, then it should be used to process this node as long
+    # as it is of the same type as this node's processor.
+    #
+    # The preprocessed data is returned.
+    def process( owner, client, data, path="/", processor=nil )
+      processor = get_processor( processor )
+
+      if processor.respond_to?( :process )
+        return processor.process( owner, client, self, data, path )
+      end
+
+      return data
+    end
+
+    # Returns the processor instance for this node. If +default+ is given, it
+    # will be used if either this instance's processor is +nil+, or if this
+    # instance's processor is of the same type as +default+. If both +default+
+    # and this instance's processor are +nil+, then an instance of the
+    # DefaultSchemaProcessor will be returned.
+    def get_processor( default )
+      return default if default && @processor_path.nil?
+
+      unless @processor_class
+        @processor_path ||=
+          "copland/default-schema-processor/Copland::DefaultSchemaProcessor"
+
+        @processor_file, @processor_class =
+          Copland::get_class_ref_parts( @processor_path )
+      end
+
+      return default if default && default.class.name == @processor_class
+
+      @processor ||= Copland::get_class( @processor_path ).new
+      return @processor
+    end
+    private :get_processor
+
+    # Fixate the schema by recursively processing each subschema. If any
+    # subschema is actually a string, it is replaced by the schema with
+    # that name.
+    def fixate!
+      extend Fixated
+
+      if @extends
+        new_definition = @owner.find_schema( @extends ).definition.dup
+        new_definition.update @definition if @definition
+        @definition = new_definition
+      end
+
+      if @definition.is_a?( String )
+        @definition = @owner.find_schema( @definition ).definition
+      elsif @definition.is_a?( Hash )
+        @definition.each_key do |key|
+          value = @definition[ key ]
+          if value.is_a?( String )
+            @definition[ key ] = @owner.find_schema( value )
+          else
+            value.fixate!
+          end
+        end
+      end
+    end
+
+    # Returns false.
+    def fixated?
+      false
+    end
+
+    # Used to extend a schema that has been fixated. This makes the #fixate!
+    # method do nothing.
+    module Fixated
+      def fixate!
+        # does nothing
+      end
+
+      def fixated?
+        true
+      end
+    end
+
+  end
+
+end

data/lib/copland/service-point.rb

@@ -0,0 +1,282 @@
+#--
+# =============================================================================
+# 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'
+require 'copland/errors'
+require 'copland/interceptor'
+require 'copland/interceptor-chain'
+require 'copland/models'
+require 'copland/utils'
+
+module Copland
+
+  # A "service point" is the definition of a service. Just as a class describes
+  # an object, a service point describes a service. Just as an object is the
+  # instantiation of a class, so is a service the instantiation of a service
+  # point.
+  #
+  # A service point consists of an "instantiator" (which describes _how_ the
+  # service is to be instantiated) and a service model (which describes _when_
+  # the service is to be instantiated). Optionally, a service point may also
+  # have _interceptors_ (which act as filters on the methods of a service),
+  # _event producers_ (which send events to the service) and a _schema_
+  # (which is only useful for factory services, and describes what the format
+  # of the parameters that the factory understands).
+  class ServicePoint
+
+    # This is the service model that will be used when no other has been
+    # specified, and no other default was given in the options when the
+    # service point was created.
+    DEFAULT_SERVICE_MODEL = "singleton-deferred"
+
+    # The package the owns this service point.
+    attr_reader :owner
+
+    # The unqualified name of this service point.
+    attr_reader :name
+
+    # An array of service points that instances of this service point will
+    # listen to for events.
+    attr_reader :event_producers
+
+    # An array of Interceptor objects that should be instantiated when this
+    # service is instantiated.
+    attr_reader :interceptors
+
+    # An (optional) description of this service point.
+    attr_accessor :description
+
+    # The instantiator that will be used to instantiate this service point.
+    # (When a service point is first created, this is +nil+, and the service
+    # point cannot be instantiated until an instantiator is specified.)
+    attr_accessor :instantiator
+
+    # The (optional) schema specification that identifies the valid parameters
+    # that can be given to an instance of this service point. This only applies
+    # when the service point describes a factory service, in which case the
+    # schema will be used to validate and preprocess the parameters that are
+    # passed to the factory when a new instance is required.
+    attr_accessor :schema
+
+    # Create a new service point, contained by the +owner+ package. The only
+    # recognized option currently is <tt>:default_service_model</tt>, which
+    # is used to identify the service model to use when no other service model
+    # has been specified.
+    def initialize( owner, name, opts={} )
+      @owner = owner
+      @name = name
+
+      use_service_model opts[ :default_service_model ] || DEFAULT_SERVICE_MODEL
+
+      @event_producers = []
+      @interceptors = []
+    end
+
+    # Returns the fully-qualified name of this service point, which will be the
+    # name of the package and the name of the service point, separated by a
+    # dot.
+    def full_name
+      owner.name + "." + name
+    end
+
+    # Return the service model instance that will be used to regulate the
+    # instantiation of this service point.
+    def service_model
+      @model
+    end
+
+    # Specify the name of service model to use for this service point. An
+    # instance of the corresponding service model will be looked up in the
+    # class factory.
+    def use_service_model( service_model_name )
+      @model =
+        Copland::ClassFactory.instance.get(
+          Copland::ServiceModel::POOL_NAME,
+          service_model_name,
+          self )
+    end
+
+    # Add the given service point as an event producer for this service point.
+    def add_event_producer( producer )
+      ( @event_producers << producer ).uniq!
+    end
+
+    # Add the given Interceptor object to this service point, to be
+    # instantiated and applied when a new service is created.
+    def add_interceptor( interceptor )
+      ( @interceptors << interceptor ).uniq!
+    end
+
+    # Returns the instance returned by the service model. This is the
+    # preferred way of instantiating a service point, since it takes advantage
+    # of the regulatory services offered by the service model.
+    #
+    # If a block is given, it will be used to do one-time initialization of
+    # the new service.
+    def instance( &block )
+      @model.instance( &block )
+    end
+
+    # Directly instantiates the service point. This also applies the
+    # interceptors and sends out notifications that the service has been
+    # instantiated.
+    #
+    # This should never be called except by service model instances. If you
+    # need to programmatically instantiate a service point, you should use the
+    # #instance method; otherwise the service model will be bypassed.
+    def instantiate( &init )
+      service = @instantiator.instantiate
+
+      service.instance_eval &init if init
+
+      # the service is registered with each of its event producers before
+      # the interceptors are added, thus enabling the event notifications to
+      # bypass the interceptor layer
+      @event_producers.each do |producer|
+        producer.instance.add_listener service
+      end
+
+      # Construct the interceptor layer around the service
+      service = InterceptorChainBuilder.build( service, @interceptors )
+
+      # TODO: lifecycle notifications: "service_instantiated"
+
+      return service
+    end
+
+    # Searches for (and instantiates) the service with the given name in the
+    # registry, giving preference to services in this service point's package
+    # (i.e., when an unqualified service name is given). If a block is
+    # specified, it will be invoked when the package and service point name
+    # have been resolved, allowing more than just services to be returned by
+    # this method.
+    def find_service( name, &block )
+      Copland::get_possibly_local_service( owner.registry,
+        owner, name, &block )
+    end
+
+    # Searches for the service point with the given name, giving preference to
+    # service points within this service point's package (i.e., when an
+    # unqualified service point name is given). If an invalid package name is
+    # given, this will raise a PackageNotFound exception. If the named
+    # service point does not exist, this will raise a ServicePointNotFound
+    # exception. Otherwise, it will return the requested service point.
+    def find_service_point( name )
+      point = find_service( name ) do |pkg, id|
+        raise PackageNotFound, name unless pkg
+        pkg.service_point( id )
+      end
+
+      raise ServicePointNotFound, name unless point
+
+      return point
+    end
+
+    # Adds a "pending" (i.e., unvalidated) interceptor definition to this
+    # service point. This method is only valid before the service point has
+    # been fixated (see #fixate!). The +definition+ parameter should be a hash
+    # that contains the definition of the interceptor. The Interceptor itself
+    # will be instantiated when the service point is fixated.
+    def add_pending_interceptor( definition )
+      ( @pending_interceptors ||= [] ).push definition
+    end
+
+    # Fixates the service point. After calling this, #add_pending_interceptor
+    # becomes illegal to call.
+    #
+    # Fixating a service point will cause its instantiator to be validated
+    # (via the #validate! method of the corresponding instantiator). Also, any
+    # pending interceptors will be processed and added to the service point.
+    # Then, if the schema value that was associated with this service point is
+    # a string value, then it is treated as a reference to an "external"
+    # schema, which is then looked up.
+    def fixate!
+      extend Fixated
+
+      if @schema.is_a?( String )
+        @schema = @owner.find_schema( @schema )
+      elsif !@schema.nil?
+        @schema.fixate!
+      end
+
+      instantiator.validate!
+
+      if @pending_interceptors
+        @pending_interceptors.each do |definition|
+          interceptor = Interceptor.new( self, definition )
+          add_interceptor interceptor
+        end
+
+        remove_instance_variable :@pending_interceptors
+      end
+
+      # do lazy evaluation of the actual event producer services, so that
+      # no one is actually instantiated until needed.
+      @event_producers.map! do |name|
+        find_service_point( name )
+      end
+    end
+
+    # Returns +false+. Once the service point has been fixated, this method
+    # will be overridden with a method that returns +true+. (See the
+    # Fixated module).
+    def fixated?
+      false
+    end
+
+    # When a service point is fixated, it will extend this module. This
+    # causes certain operations on the service point to become illegal, or
+    # to do nothing.
+    module Fixated
+
+      # Raises DisallowedOperationException.
+      def add_pending_interceptor( *args )
+        raise DisallowedOperationException, 
+          "cannot add pending interceptors to a fixated service point"
+      end
+
+      # Does nothing.
+      def fixate!
+        # does nothing
+      end
+
+      # Returns +true+.
+      def fixated?
+        true
+      end
+
+    end
+
+  end
+
+end