copland 0.8.0

data/lib/copland/models.rb

@@ -0,0 +1,39 @@
+#--
+# =============================================================================
+# 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/models/abstract'
+require 'copland/models/prototype'
+require 'copland/models/prototype-deferred'
+require 'copland/models/singleton'
+require 'copland/models/singleton-deferred'
+require 'copland/models/threaded'

data/lib/copland/models/abstract.rb

@@ -0,0 +1,78 @@
+#--
+# =============================================================================
+# 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 ServiceModel
+  
+    # This is the name of the pool in the ClassFactory that the
+    # ServiceModel classes will use.
+    POOL_NAME = "model"
+
+    begin
+      factory = Copland::ClassFactory.instance
+      factory.create_pool POOL_NAME
+    end
+
+    # This is the parent class of all service model implementations.
+    class AbstractServiceModel
+
+      # This is the service point that this model protects.
+      attr_reader :service_point
+
+      # Create a new service model around the given service point.
+      def initialize( service_point )
+        @service_point = service_point
+      end
+
+      # Raises a NotImplementedException. Subclasses must override this method.
+      def instance( &block )
+        raise NotImplementedException
+      end
+
+      # A convenience method for allowing subclasses to register themselves
+      # with the ClassFactory.
+      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/models/prototype-deferred.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/models/abstract'
+require 'copland/models/proxy'
+
+module Copland
+
+  module ServiceModel
+
+    # This is the "deferred instantiation" variety of the
+    # PrototypeServiceModel. Instead of immediately instantiating the service
+    # point, it instead wraps the service point in a new Proxy instance and
+    # returns that.
+    class PrototypeDeferredServiceModel < AbstractServiceModel
+
+      # Returns a new Proxy instance that wraps the service point.
+      def instance( &block )
+        Proxy.new( @service_point, &block )
+      end
+
+      register_as "prototype-deferred"
+
+    end
+
+  end
+
+end

data/lib/copland/models/prototype.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/models/abstract'
+
+module Copland
+
+  module ServiceModel
+
+    # This is the most trivial of all service models. It simply calls the
+    # ServicePoint#instantiate method of the service point it protects.
+    # In this way, the service point becomes a prototype (or template)
+    # for instantiation.
+    class PrototypeServiceModel < AbstractServiceModel
+
+      # Invokes ServicePoint#instantiate on the model's protected
+      # service point.
+      def instance( &block )
+        @service_point.instantiate( &block )
+      end
+
+      register_as "prototype"
+
+    end
+
+  end
+
+end

data/lib/copland/models/proxy.rb

@@ -0,0 +1,100 @@
+#--
+# =============================================================================
+# 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 'thread'
+
+module Copland
+  module ServiceModel
+
+    # A proxy class to aid in deferred instantiation of service points. This is
+    # used primarily by the "deferred" service models.
+    class Proxy
+
+      # Create a new proxy that wraps the given service point.
+      def initialize( service_point, &init )
+        @service_point = service_point
+        @mutex = Mutex.new
+        @init = init
+      end
+
+      # Attempts to invoke the given message on the service. If the service has
+      # not yet been instantiated, it will be instantiated and stored.
+      def method_missing( sym, *args, &block )
+        unless @instance || @instantiation_failed
+          @mutex.synchronize do
+            unless @instance || @instantiation_failed
+              begin
+                @instance = @service_point.instantiate( &@init )
+              rescue Exception
+                @instantiation_failed = true
+                raise
+              end
+            end
+          end
+        end
+
+        unless @instantiation_failed
+          @instance.__send__ sym, *args, &block
+        else
+          # just return nil... this way, a failed instantiation won't barf
+          # more than once... I hope...
+        end
+      end
+
+      # Override some "standard" methods so that they are routed to the
+      # service instead of to the proxy.
+      [ "is_a?", "respond_to?", "to_s", "to_str",
+        "to_i", "to_int", "to_io", "===", "==", "=~",
+        "send" ].each do |method|
+      #begin
+        class_eval <<-EOF
+          def #{method}( *args, &block )
+            unless @instantiation_failed
+              method_missing '#{method}', *args, &block
+            else
+              super
+            end
+          end
+        EOF
+      end
+
+      def inspect
+        "#<#{self.class.name}:#{"0x%08x"%self.id}:" +
+        "service_point=>#{@service_point.full_name}:" +
+        "instantiated=>#{@instance ? true : false}>"
+      end
+
+    end
+
+  end
+end

data/lib/copland/models/singleton-deferred.rb

@@ -0,0 +1,59 @@
+#--
+# =============================================================================
+# 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/models/singleton'
+require 'copland/models/proxy'
+
+module Copland
+
+  module ServiceModel
+
+    # This is the deferred variety of the Singleton service model. Instead of
+    # immediately instantiating the service point when requested to, it instead
+    # wraps the service point in a Proxy object, which will cause the service
+    # point to be instantiated as soon as a method is invoked on the Proxy.
+    # Then, the proxy will forward all subsequent calls to the service itself.
+    class SingletonDeferredServiceModel < SingletonServiceModel
+
+      # Creates an instance of Proxy that encapsulates the service point.
+      def new_instance( &init )
+        @instance = Proxy.new( @service_point, &init )
+      end
+      
+      register_as "singleton-deferred"
+
+    end
+
+  end
+
+end

data/lib/copland/models/singleton.rb

@@ -0,0 +1,77 @@
+#--
+# =============================================================================
+# 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/models/abstract'
+require 'thread'
+
+module Copland
+
+  module ServiceModel
+
+    # This service model enforces a singleton constraint on the service point
+    # it protects. That is to say, whenever the #instance method of this
+    # model is called, it will always return the same instance of the service
+    # point.
+    class SingletonServiceModel < AbstractServiceModel
+
+      # Create a new SingletonServiceModel on the given service point.
+      def initialize( service_point )
+        super
+        @mutex = Mutex.new
+      end
+
+      # Return the singleton instance of the service point. This is
+      # thread safe.
+      def instance( &init )
+        return @instance if @instance
+
+        @mutex.synchronize do
+          return @instance if @instance
+          new_instance( &init )
+          return @instance
+        end
+      end
+
+      # Creates a new instance of the service point.
+      def new_instance( &init )
+        @instance = @service_point.instantiate( &init )
+      end
+      private :new_instance
+      
+      register_as "singleton"
+
+    end
+
+  end
+
+end