copland 0.8.0

data/lib/copland/configuration/yaml/service-point.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/service-point'
+require 'copland/configuration/errors'
+require 'copland/configuration/yaml/implementor'
+require 'copland/configuration/yaml/interceptor'
+require 'copland/configuration/yaml/listener'
+require 'copland/configuration/yaml/schema'
+require 'copland/configuration/yaml/utils'
+
+module Copland
+  module Configuration
+    module YAML
+
+      # This is the delgate that is responsible for processing the input
+      # describing a service point.
+      class ServicePointProcessor
+        include TypeValidator
+
+        # Create a new ServicePointProcessor that feeds into the given
+        # package instance. The +options+ parameter is given to every new
+        # service point as it is created.
+        def initialize( package, options={} )
+          @package = package
+          @options = options
+          @implementor = ImplementorProcessor.new
+          @interceptor = InterceptorProcessor.new
+          @listener = ListenerProcessor.new
+          @schema = SchemaParser.new
+        end
+
+        # The list of valid keys that may exist on the input.
+        VALID_KEYS = [ "description", "model", "implementor",
+                       "interceptors", "listen-to", "schema" ]
+
+        # The list of required keys that must exist on the input.
+        REQUIRED_KEYS = [ "implementor" ]
+
+        # Create a new service point with the given name and populate it with
+        # data as described by the +doc+ parameter. The new service point is 
+        # returned.
+        def process( name, doc )
+          ensure_element_type "service-point", doc, Hash
+          validate_elements doc
+
+          point = ServicePoint.new( @package, name, @options )
+          doc.each_pair do |key, value|
+            case key
+              when "description"
+                point.description = value
+
+              when "model"
+                point.use_service_model value
+
+              when "implementor"
+                @implementor.process( point, value )
+
+              when "interceptors"
+                ensure_element_type "interceptors", value, Array
+                value.each do |definition|
+                  @interceptor.process( point, definition )
+                end
+
+              when "listen-to"
+                ensure_element_type "listen-to", value, Array
+                value.each do |definition|
+                  @listener.process( point, definition )
+                end
+
+              when "schema"
+                point.schema = @schema.process( point, value )
+
+              else
+                raise CoplandBug, "[BUG] invalid key discovered too late: #{key.inspect}"
+            end
+          end
+
+          return point
+        end
+
+      end
+
+    end
+  end
+end

data/lib/copland/configuration/yaml/utils.rb

@@ -0,0 +1,82 @@
+#--
+# =============================================================================
+# 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/configuration/errors'
+
+module Copland
+  module Configuration
+    module YAML
+
+      # This module implements type validation routines that are used by most
+      # of the classes in the Copland::Configuration::YAML module.
+      module TypeValidator
+
+        # Ensures that the given +element+ (identified by the given +name+) is
+        # indeed an instance of the given +klass+. If it is not, a ParserError
+        # is raised.
+        def ensure_element_type( name, element, klass )
+          unless element.is_a?( klass )
+            raise ParserError,
+              "#{name.inspect} must be of type #{klass}, " +
+              "not #{element.class}",
+              caller[1..-1]
+          end
+        end
+
+        # This requires that the +VALID_KEYS+ and +REQUIRED_KEYS+ constants have
+        # been set in the including class. Then, it tests to see if the given
+        # +hash+ includes any values other than those that are defined in
+        # +VALID_KEYS+, or whether any keys in +REQUIRED_KEYS+ are missing from
+        # +hash+. If either condition is true, a ParserError is raised. If
+        # +path+ is given, it describes the location of the element (for error
+        # reporting).
+        def validate_elements( hash, path="" )
+          path = " at #{path}" if path
+          invalid_keys = hash.keys - self.class::VALID_KEYS
+          unless invalid_keys.empty?
+            raise ParserError,
+              "invalid elements(s)#{path}: #{invalid_keys.inspect}"
+          end
+
+          missing_keys = self.class::REQUIRED_KEYS - hash.keys
+          unless missing_keys.empty?
+            raise ParserError,
+              "missing element(s)#{path}: #{missing_keys.inspect}"
+          end
+        end
+
+      end
+
+    end
+  end
+end

data/lib/copland/default-schema-processor.rb

@@ -0,0 +1,144 @@
+#--
+# =============================================================================
+# 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/utils'
+
+module Copland
+
+  # The DefaultSchemaProcessor is the default processor class used for
+  # processing (validating and pre-processing) schema elements.
+  class DefaultSchemaProcessor
+
+    # Validates the given +data+ against the given +schema+. +owner+ is the
+    # object associated with the schema, and +client" is the object associated
+    # with the data. If +path+ is given, it specifies the path up to the
+    # current schema element (for error reporting purposes).
+    #
+    # If this method returns, then the validation succeeded. Otherwise, it will
+    # raise a ValidationException.
+    def validate( owner, client, schema, data, path="/" )
+      return unless schema.definition
+      schema_keys = schema.definition.keys
+      data = data.value if data.respond_to?( :type_id )
+      data_keys = data.keys
+
+      extra_keys = data_keys - schema_keys
+      unless extra_keys.empty?
+        validation_error owner, client, path,
+          "illegal parameter(s) #{extra_keys.inspect}"
+      end
+
+      schema.definition.each_pair do |key, subschema|
+        subpath = path + ( path[-1] == ?/ ? "" : "/" ) + key
+
+        if data[key]
+          validate_type owner,
+            client,
+            subschema.type,
+            data[key],
+            subpath
+
+          subschema.validate owner,
+            client,
+            data[key],
+            subpath
+
+        elsif subschema.required
+          validation_error owner, client, path,
+            "required parameter #{key.inspect} missing"
+        end
+      end
+    end
+
+    # Pre-processes the +data+, possibly in conjuction with the +schema+. The
+    # parameters are identical to those given for #validate. The default
+    # implementation simply calls Copland::translate_value on the +data+,
+    # using +client+ as the reference value.
+    #
+    # The primary purpose of this call is to convert/translate values to their
+    # actual types, like "!!service service.name" values.
+    def process( owner, client, schema, data, path="/" )
+      return Copland::translate_value( client.owner.registry,
+        client.owner,
+        client,
+        data )
+    end
+
+    # Used internally to ensure that the given +data+ element is of the
+    # +type+ specified. If it isn't, a ValidationException is raised.
+    def validate_type( owner, client, type, data, path )
+      return unless type && type != "any"
+
+      if data.respond_to?( :type_id )
+        type_id = data.type_id
+      else
+        case data
+          when String then type_id = "string"
+          when Integer then type_id = "integer"
+          when Float then type_id = "real"
+          when Hash then type_id = "hash"
+          when Array then type_id = "array"
+          when Symbol then type_id = "symbol"
+          when true, false then type_id = "boolean"
+          else
+            type_id = "unknown (#{data.class})"
+        end
+      end
+
+      if type_id == "hash" && type == "array"
+        # special case: the data is an array, but the type in the schema is a
+        # hash. This should be interpreted to mean that the hash is the
+        # subschema for each element of the array.
+        return
+      end
+
+      unless type_id == type
+        validation_error owner, client, path,
+          "expected type #{type}, got #{type_id}"
+      end
+    end
+    private :validate_type
+
+    # A convenience method for raising ValidationException errors.
+    def validation_error( owner, client, path, msg )
+      raise ValidationException,
+        "at #{path} in #{owner.full_name} for #{client.full_name}: " +
+        msg,
+        caller[1..-1]
+    end
+    private :validation_error
+
+  end
+
+end

data/lib/copland/errors.rb

@@ -0,0 +1,82 @@
+#--
+# =============================================================================
+# 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
+
+  # The base exception class for all Copland errors.
+  class CoplandException < StandardError; end
+
+  # This specialized exception is used for reporting "bug" conditions.
+  class CoplandBug < CoplandException; end
+
+  # Used when reporting the absense of a package that was requested.
+  class PackageNotFound < CoplandException; end
+
+  # Used when reporting the absense of a service point that was requested.
+  class ServicePointNotFound < CoplandException; end
+
+  # Used when reporting the absense of a configuration point that was
+  # requested.
+  class ConfigurationPointNotFound < CoplandException; end
+
+  # Used when reporting the absense of a schema that was requested.
+  class SchemaNotFound < CoplandException; end
+
+  # Used when an ordering (of interceptors, or autoload services) could not be
+  # honored due to conflicting ordering preferences.
+  class OrderingException < CoplandException; end
+
+  # Used when reporting the invocation of a disallowed operation.
+  class DisallowedOperationException < CoplandException; end
+
+  # Used when reporting the absense of a pool (in the ClassFactory) that was
+  # requested.
+  class NoSuchPoolException < CoplandException; end
+
+  # Used when reporting the absense of a class that was requested via the
+  # ClassFactory.
+  class NoSuchRegisteredClassException < CoplandException; end
+
+  # Used when a package is added to the registry and a package with the same
+  # name already exists.
+  class DuplicatePackageError < CoplandException; end
+
+  # Used when a service point (or similar entity) is defined without an
+  # implementation (ie, instantiator, or some such).
+  class MissingImplementationException < CoplandException; end
+
+  # Used when a validation fails, such as validating parameter data against a
+  # schema.
+  class ValidationException < CoplandException; end
+
+end

data/lib/copland/event-producer.rb

@@ -0,0 +1,95 @@
+#--
+# =============================================================================
+# 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
+
+  # Any service implementation that wishes to be able to alert other services
+  # of events may mixin this module. If it does not, it may still be used as an
+  # event producer as long as it implements:
+  #
+  # # The #add_listener method
+  # # A notification method that invokes some listener method on each listener,
+  #   which method must be called "on_#{event_name}" and must accept the
+  #   producer as the first argument.
+  module EventProducer
+
+    # Add the given listener to this producer's list of listeners. A listener
+    # may be added multiple times.
+    def add_listener( listener )
+      ( @listeners ||= [] ).push listener
+      self
+    end
+
+    # Remove the given listener from the producer's list of listeners. If the
+    # listener does not exist in the listener list, nothing happens. If it
+    # exists more than once, only the first instance is removed.
+    def remove_listener( listener )
+      @listeners.delete listener if @listeners
+      self
+    end
+
+    # Iterates over each listener in the list. It first makes a copy of the
+    # list and then iterates over the copy, so it essentially iterates over
+    # a snapshot of the listener list. This makes its behavior deterministic
+    # when dealing with multiple threads of control.
+    def each_listener
+      return unless @listeners
+      @listeners.dup.each do |listener|
+        yield listener
+      end
+      self
+    end
+
+    # Signals the listeners that some event has occurred. The +event+ method
+    # should be either a String or a Symbol. Each listener is then queried
+    # to see if they respond to a method called "on_#{event}", and if they
+    # do, they are sent that message, along with the producer and the argument
+    # list. If they don't respond to "on_#{event}", they are then asked if
+    # they respond to "on_any_event", if they do, they are sent that message,
+    # along with the producer, the event, and the argument list.
+    def fire_event( event, *args )
+      method = "on_#{event.to_s}"
+      general_method = "on_any_event"
+      each_listener do |listener|
+        if listener.respond_to?( method )
+          listener.__send__( method, self, *args )
+        elsif listener.respond_to?( general_method )
+          listener.__send__( general_method, self, event, *args )
+        end
+      end
+      self
+    end
+
+  end
+
+end