copland 0.8.0

data/lib/copland/impl/builder-factory.rb

@@ -0,0 +1,112 @@
+#--
+# =============================================================================
+# 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'
+require 'singleton'
+
+module Copland
+  module Implementation
+
+    # This is the implementation of the BuilderFactory service. It constructs
+    # service implementations and wires services together automatically, as
+    # determined by their dependencies in the configuration files.
+    class BuilderFactory
+
+      # This is the list of patterns that are recognized as "setter" methods.
+      # These are used when determining how to set properties.
+      SETTERS = [ "%s=", "set_%s" ]
+      
+      # This is the factory method used to construct new services. Based
+      # on the +parms+ argument, the new service is instantiated, initialized,
+      # and returned.
+      def create_instance( point, parms )
+        ensure_log( point )
+
+        klass = Copland::get_class( parms['class'] )
+
+        args = ( parms['parameters'] || [] )
+
+        if klass.include?( Singleton )
+          if args.length > 0
+            raise CoplandException,
+              "Singleton instances cannot have constructor parameters"
+          end
+          obj = klass.instance
+        else
+          obj = klass.new( *args )
+        end
+
+        if parms['properties']
+          parms['properties'].each_pair do |name, value|
+            catch( :property_set ) do
+              SETTERS.each do |pattern|
+                setter = pattern % name
+                if obj.respond_to?( setter )
+                  obj.__send__( setter, value )
+                  throw :property_set
+                end
+              end
+
+              @log.warn "no setter for #{name.inspect} found on " +
+                        "#{klass} (#{point.full_name})"
+              obj.instance_variable_set "@#{name}".intern, value
+            end
+          end
+        end
+
+        if parms['invoke']
+          parms['invoke'].each_pair do |name, value|
+            obj.__send__( name, *( value || [] ) )
+          end
+        end
+
+        initialize_method = parms[ 'initialize-method' ] ||
+          "initialize_service"
+
+        if obj.respond_to?( initialize_method )
+          obj.__send__( initialize_method )
+        end
+
+        return obj
+      end
+
+      def ensure_log( point )
+        return if @log
+        @log = point.owner.registry.logs.get( "copland.BuilderFactory" )
+      end
+
+    end
+
+  end
+end

data/lib/copland/impl/copland-config.yml

@@ -0,0 +1 @@
+yaml-package-file: package.yml

data/lib/copland/impl/include-exclude.rb

@@ -0,0 +1,140 @@
+#--
+# =============================================================================
+# 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
+  module Implementation
+
+    # A simple structure for representing a single include/exclude pattern.
+    IncludeExcludePattern = Struct.new( :name, :comparitor, :arity )
+
+    # A module encapsulating the factory end of a service with include/exclude
+    # functionality. Such functionality involves a schema with include and
+    # exclude elements, each of which must be an array of method names that
+    # should be included or excluded. See the IncludeExclude module for more
+    # info.
+    module IncludeExcludeFactory
+
+      # This is the regular expression for parsing elements in an include or
+      # exclude array.
+      PATTERN = /^
+                 (.*?)        (?# this matches the method name pattern)
+                 (?:          (?# begin optional arity section)
+                   \(         (?# begin parenthesized section)
+                     ([<=>])? (?# optional comparator character)
+                     (\d+)    (?# arity specification)
+                   \)         (?# end parenthesized section)
+                 )?           (?# end optional arity section)
+                 $/x
+
+      # This is a utility function for converting an array of strings
+      # representing method name patterns, into an array of
+      # IncludeExcludePattern instances.
+      def build_map( array )
+        ( array || [] ).map do |pattern|
+          unless pattern =~ PATTERN
+            raise CoplandException,
+              "invalid logging interceptor method pattern: #{pattern.inspect}"
+          end
+
+          name = $1
+          comparitor = $2
+          arity = ( $3 || -1 ).to_i
+
+          comparitor ||= ">" if arity < 0
+          comparitor ||= "="
+            
+          IncludeExcludePattern.new( Regexp.new( "^" + name + "$" ),
+                                     comparitor,
+                                     arity )
+        end
+      end
+
+    end
+
+    # This module encapsulates the service end of a service with
+    # include/exclude functionality.
+    module IncludeExclude
+
+      # Returns +false+ if the given context object "matches" any of the
+      # exclude patterns without matching any of the include patterns.
+      # The context object must respond to the <tt>:sym</tt> and
+      # <tt>:args</tt> messages, where <tt>:sym</tt> is a symbol identifying
+      # the method being matched, and <tt>:args</tt> is an array of
+      # arguments that will be sent to that method.
+      def match( context )
+        match = true
+
+        @excludes.each do |pattern|
+          if match_pattern( context, pattern )
+            match = false
+            break
+          end
+        end
+
+        unless match
+          @includes.each do |pattern|
+            if match_pattern( context, pattern )
+              match = true
+              break
+            end
+          end
+        end
+
+        return match
+      end
+      private :match
+
+      # Returns +true+ if the given context matches the given pattern, and
+      # +false+ otherwise.
+      def match_pattern( context, pattern )
+        if context.sym.to_s =~ pattern.name
+          case pattern.comparitor
+            when "<"
+              return context.args.length < pattern.arity
+            when ">"
+              return context.args.length > pattern.arity
+            when "="
+              return context.args.length == pattern.arity
+          end
+        end
+
+        return false
+      end
+      private :match_pattern
+
+    end
+
+  end
+end

data/lib/copland/impl/logging-interceptor.rb

@@ -0,0 +1,106 @@
+#--
+# =============================================================================
+# 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/impl/include-exclude'
+
+module Copland
+  module Implementation
+
+    # This is the implementation of the service factory that provides
+    # instances of logging interceptors. It includes the IncludeExcludeFactory
+    # functionality.
+    class LoggingInterceptorFactory
+      include IncludeExcludeFactory
+
+      # Returns a new LoggingInterceptor instance, initialized with the given
+      # parameters.
+      def create_instance( point, parms )
+        includes = build_map( parms[ "include" ] )
+        excludes = build_map( parms[ "exclude" ] )
+
+        return LoggingInterceptor.new( point, includes, excludes )
+      end
+
+    end
+
+    # A LoggingInterceptor is an interceptor object that logs method
+    # invocations and exceptions. It includes the IncludeExclude functionality.
+    class LoggingInterceptor
+      include IncludeExclude
+
+      # The log used by this interceptor to log messages.
+      attr_reader :log
+
+      # The array of patterns of methods to log.
+      attr_reader :includes
+
+      # The array of patterns of methods to _not_ log.
+      attr_reader :excludes
+
+      # Create a new LoggingInterceptor for the given service point, with the
+      # given list of include and exclude patterns. The logger object will be
+      # created as well, named with the service point's full name.
+      def initialize( point, includes, excludes )
+        @log = point.owner.registry.logs.get( point.full_name )
+        @includes = includes
+        @excludes = excludes
+      end
+
+      # Processes a method invocation context. If the current log has debugging
+      # activated, and the requested method is not excluded by the
+      # interceptor's exclude and include patterns, then a message will be
+      # written for the method's invocation, its return code, and any exception
+      # that is thrown.
+      def process( chain, context )
+        if @log.debug? && match( context )
+          args = context.args.map { |i| i.inspect } .join( ', ' )
+          @log.debug "#{context.sym}( #{args} )"
+
+          begin
+            result = chain.process_next( context )
+          rescue Exception => e
+            @log.debug "#{context.sym} raised #{e.message.inspect} (#{e.class})"
+            raise
+          end
+
+          @log.debug "#{context.sym} => #{result.inspect}"
+          return result
+        else
+          return chain.process_next( context )
+        end
+      end
+
+    end
+
+  end
+end

data/lib/copland/impl/package.yml

@@ -0,0 +1,217 @@
+---
+id: copland
+description: >-
+  The copland package is the standard package defined by the Copland
+  distribution. It includes the core services and interceptors, such as the
+  BuilderFactory and the LoggingInterceptor.
+
+configuration-points:
+
+  SymbolSources:
+    type: list
+    description: >-
+      This is a list of services or objects that can be queried to provide
+      symbols. Packages may contribute additional symbol sources to this
+      list. Additionally, the sources may be given an explicit order in
+      which they will be queried for symbols, allowing some sources to take
+      precendence over others.
+    schema:
+      definition:
+        source:
+          type: any
+          required: true
+          description: >-
+            The implementor of the symbol source that is being contributed.
+            It must be the name of a class, or an instance of a service.
+        name:
+          type: string
+          description: >-
+            The name given to this symbol source. This allows it to be
+            referenced in other sources' before and after lists.
+        before:
+          type: array
+          description: >-
+            A list of symbol sources to be queried after this source.
+        after:
+          type: array
+          description: >-
+            A list of symbol sources to be queried before this source.
+
+  FactoryDefaults:
+    type: map
+    description: >-
+      This symbol source configuration point allows packages to define "factory
+      defaults" for various substitution symbols that they export.
+
+  ApplicationDefaults:
+    type: map
+    description: >-
+      This symbol source configuration point allows packages to override
+      factory default values (see the FactoryDefaults configuration point).
+
+  Startup:
+    type: list
+    description: >-
+      This is the data source for the Startup service. This allows services
+      to register themselves to be automatically started when the registry
+      has finished initializing. Services may also register their preferred
+      ordering for startup.
+    schema:
+      name: ClientDefinition
+      definition:
+        service:
+          type: string
+          required: true
+          description: The (full) name of the client service.
+        enabled:
+          type: boolean
+          description: Whether or not the service should be notified.
+        before:
+          type: array
+          description: >-
+            A list of other service names that should be notified after this
+            service.
+        after:
+          type: array
+          description: >-
+            A list of other service names that should be notified before this
+            service.
+
+service-points:
+
+  FactoryDefaults:
+    model: singleton
+    description: >-
+      The service point that provides access to the FactoryDefaults
+      configuration point.
+    implementor:
+      class: copland/impl/symbol-source/Copland::Implementation::SymbolSource
+      properties:
+        defaults: !!configuration FactoryDefaults
+
+  ApplicationDefaults:
+    model: singleton
+    description: >-
+      The service point that provides access to the ApplicationDefaults
+      configuration point.
+    implementor:
+      class: copland/impl/symbol-source/Copland::Implementation::SymbolSource
+      properties:
+        defaults: !!configuration ApplicationDefaults
+
+  SymbolSourceManager:
+    model: singleton
+    description: >-
+      The service that manages all contributed symbol sources, and which may be
+      queried to obtain values known by any of them.
+    implementor:
+      class: copland/impl/symbol-source-manager/Copland::Implementation::SymbolSourceManager
+      parameters:
+      - !!configuration SymbolSources
+
+  BuilderFactory:
+    implementor:
+      copland/impl/builder-factory/Copland::Implementation::BuilderFactory
+    model: singleton
+    description: >-
+      Used to construct a service from a class name and optional constructor
+      parameters and properties.
+    schema:
+      definition:
+        class:
+          required: true
+          type: string
+          description: >-
+            The path description of the class to instantiate. This takes the
+            form "path/to/file/Full::Class::Name". Then, "require" will be
+            invoked on the "path/to/file" portion, and the class itself will
+            then be resolved. If the class includes the Singleton module,
+            the singleton instance will be correctly resolved; in this case,
+            it is an error to specify construction parameters.
+        parameters:
+          type: array
+          description: >-
+            A list of values that should be passed (in order) to the
+            constructor of the class. It is illegal to specify this value if
+            the class includes the Singleton module.
+        properties:
+          type: hash
+          description: >-
+            A hash of property-name/value pairs that describe the properties
+            to set on the instantiated object. Assignment occurs as follows:
+            first, a setter is searched for, either "name=" or "set_name".
+            If one is found, it is used to set the property. If no such
+            setter exists, the property is set directly using
+            "instance_variable_set".
+        invoke:
+          type: hash
+          description: >-
+            A hash of method-name/parameter pairs, where the value of each
+            pair is an array of parameters to pass to the method. These
+            methods will be invoked in no particular order, after all
+            properties have been assigned.
+        initialize-method:
+          type: string
+          description: >-
+            This describes the name of the method to invoke when the service
+            has been completely instantiated (and all properties wired into
+            it). This defaults to "initialize_service". If the method does not
+            exist, then nothing is invoked.
+
+  LoggingInterceptor:
+    implementor:
+      copland/impl/logging-interceptor/Copland::Implementation::LoggingInterceptorFactory
+    description: >-
+      An interceptor that adds logging to a service.  Log entries are created
+      for all method calls (on enter and exit) and for any raised exceptions.
+      By default, all methods implemented by the service are included for
+      logging, and may only be excluded by using the 'exclude' element.
+      Anything matching any of the exclusion patterns will not be logged,
+      unless it also matches an 'include' pattern.
+    model: singleton
+    schema:
+      name: IncludeExcludeSchema
+      description: >-
+        This is a schema that may be used by any service that wishes to
+        incorporate "include/exclude" functionality into itself.
+      definition:
+        include:
+          type: array
+          description: >-
+            A list of special expressions that define which methods are
+            included in the operation. These expressions take the format
+            "pattern" (where pattern in a regular expression that should
+            match the method's name), or "pattern(arity)", where arity is
+            either a positive integer (indicating that only methods
+            with that arity match), or a positive integer preceded by a
+            comparison operator (<, =, or >).
+        exclude:
+          type: array
+          description: >-
+            A list of special expressions that define which methods are
+            excluded from the operation. The format for these expressions
+            is described under the 'include' element.
+
+  Startup:
+    model: singleton
+    description: >-
+      This is a service that will be automatically instantiated when the
+      registry is initialized. Once invoked, it inspects the Startup
+      configuration point to determine which other services to load. These
+      clients will be ordered based on their 'before' and 'after'
+      preferences, and then all enabled services will be started.
+    implementor:
+      class: copland/impl/startup/Copland::Implementation::Startup
+      properties:
+        clients: !!configuration Startup
+        registry: !!service Registry
+
+contributions:
+
+  SymbolSources:
+    - name: FactoryDefaults
+      source: !!service FactoryDefaults
+      after:
+      - ApplicationDefaults
+    - name: ApplicationDefaults
+      source: !!service ApplicationDefaults