configuration_service 2.0.4 → 2.0.5

data/lib/configuration_service/provider_registry.rb

@@ -5,44 +5,48 @@ module ConfigurationService
   unless defined?(ProviderRegistry)
 
     ##
-    # A singleton registry of uniquely identified service provider classes
+    # A singleton registry of configuration service providers
     #
-    # Provider classes are registered and looked up by unique string identifier.
+    # @!method self.instance
+    #   The singleton registry instance
+    #
+    #   @return [ConfigurationService::ProviderRegistry] singleton instance
     #
     class ProviderRegistry
 
       include Singleton
 
-        def initialize ## :nodoc:
-          @providers = {}
-        end
-
         ##
-        # Register a +provider+ identified by the string +identifier+
+        # Register a configuration service provider
         #
-        # The +provider+ should be a class with a keyword argument
-        # constructor.
+        # @param [String] identifier
+        #   unique identifier for the configuration service provider
+        # @param [Class] provider
+        #   the configuration service provider class
         #
         def register(identifier, provider)
           @providers[identifier] = provider
         end
 
         ##
-        # Return the +provider+ identified by the string +identifier+
+        # Look up a configuration service provider
         #
-        # The +provider+ must already have been registered with #register,
-        # and should be a class with a keyword argument constructor.
+        # @param [String] identifier
+        #   the unique identifier for the configuration service provider.
+        #   The provider must already have been registered with {#register}.
         #
-        # Returns +nil+ if no provider has been registered with the given
-        # +identifier+.
+        # @return [Class] the configuration service provider class
+        # @return [nil] if no provider has been registered with the given +identifier+
         #
         def lookup(identifier)
           @providers[identifier]
         end
 
-        ##
-        # Return the singleton registry instance
-        # :singleton-method: instance
+        # @private
+        def initialize
+          @providers = {}
+        end
+
     end
 
   end

data/lib/configuration_service/test/orchestration_provider.rb

@@ -6,45 +6,34 @@ module ConfigurationService
   module Test
 
     ##
-    # Abstract Orchestrator provider
+    # @abstract
+    #   It is a base provider for the test {ConfigurationService::Test::Orchestrator}.
     #
-    # Extend this class if you want your test orchestration provider to
-    # constrain your implementation's interface to work as a configuration
-    # service provider. If you have no intention of plugging your
-    # implementation into ConfigurationService::Base, build your own test
-    # orchestration provider from scratch, using Orchestrator as a guide.
+    #   Extend this class if you want your test orchestration provider toconstrain your implementation's interface
+    #   to work as a configuration service provider.
+    #   If you have no intention of plugging your implementation into {ConfigurationService::Base},
+    #   build your own test orchestration provider from scratch, using {ConfigurationService::Test::Orchestrator}
+    #   and {ConfigurationService::Test::StubOrchestrationProvider} as a guide.
     #
-    # Extensions should implement:
+    #   Extensions should implement:
     #
-    # * #service_provider_id
-    # * #service_provider_configuration
-    # * #service_provider
-    # * #broken_service_provider
-    # * #token_for
-    # * #delete_configuration
+    #   * {#service_provider_id}
+    #   * {#service_provider_configuration}
+    #   * {#service_provider}
+    #   * {#broken_service_provider}
+    #   * {#token_for}
+    #   * {#delete_configuration}
     #
     class OrchestrationProvider
 
-      ##
-      # * +:requesting_configurations+
-      # * +:publishing_configurations+
-      # * +:nothing+ (if possible, provide credentials that don't allow
-      #   operations on the configuration +identifier+)
       ACTIVITY_ROLE_MAP = {
         :requesting_configurations => :consumer,
         :publishing_configurations => :publisher,
-        :nothing => :none
+        :nothing => :none # if possible, provide credentials that don't allow operations on the configuration identifier
       } unless defined?(ACTIVITY_ROLE_MAP)
-      ##
-      # * +:consumer+
-      # * +:publisher+
-      # * +:none+
-      #
       ROLES = ACTIVITY_ROLE_MAP.values unless defined?(ROLES)
 
       ##
-      # Returns a new Orchestrator provider
-      #
       # The provider is always initialized with the same configuration +identifier+
       #
       def initialize
@@ -52,48 +41,98 @@ module ConfigurationService
       end
 
       ##
-      # Returns the string identifier of the service provider
+      # The registered identifier of the service provider under test
       #
-      # This should be the +identifier+ with which the service provider
-      # registers into the ProviderRegistry.
+      # @return [String] the +identifier+ with which the service provider is registered
+      #                  into the {ConfigurationService::ProviderRegistry}
       #
       def service_provider_id
         raise NotImplementedError, "#{self.class} must implement service_provider_id"
       end
 
       ##
-      # Return configuration for the service provider
+      # The configuration for the service provider under test
       #
-      # The configuration should be a dictionary of keyword arguments that can
-      # be passed to the constructor of the service provider class.
+      # @return [Hash] dictionary of keyword arguments that can be passed to the constructor of the service provider class
       #
-      def service_provider_configuration # :doc:
+      def service_provider_configuration
         raise NotImplementedError, "#{self.class} must implement service_provider_configuration"
       end
 
       ##
-      # See Orchestrator#authorize
+      # The service provider under test
+      #
+      # @return [Object] a provider to be plugged into {ConfigurationService::Base}
+      #
+      def service_provider
+        raise NotImplementedError, "#{self.class} must implement service_provider"
+      end
+
+      ##
+      # A broken service provider
+      #
+      # @return [Object] a provider to be plugged into {ConfigurationService::Base}.
+      #                  The service provider's +publish_configuration+ and +request_configuration+ methods
+      #                  must raise an {ConfigurationService::Error} other than {ConfigurationService::AuthorizationError}.
+      #
+      def broken_service_provider
+        raise NotImplementedError, "#{self.class} must implement broken_service_provider"
+      end
+
+      ##
+      # Delete configuration data
+      #
+      # Deleting non-existent configuration should not produce an error.
+      # The +@identifier+ instance variable may be used to identify the configuration to delete,
+      # but +@token+ should not be used, because it may not be sufficiently authorized.
+      #
+      # @return [nil] always
+      #
+      def delete_configuration
+        raise NotImplementedError, "#{self.class} must implement delete_configuration"
+      end
+
+      ##
+      # Provide a token that authorizes a role
+      #
+      # Valid roles are:
+      #
+      # * +:consumer+
+      # * +:publisher+
+      # * +:nothing+
+      #
+      # Note that a token should be returned for +:nothing+, but the token should
+      # not be authorized to consume or publish to the +identifier+.
+      #
+      # @return [String] a token
+      #
+      def token_for(role)
+        raise NotImplementedError, "#{self.class} must implement token_for(role)"
+      end
+
+      ##
+      # @see ConfigurationService::Test::Orchestrator#authorize
       #
       def authorize(role)
         @token = token_for(role)
       end
 
       ##
-      # See Orchestrator#deauthorize
+      # @see ConfigurationService::Test::Orchestrator#deauthorize
       #
       def deauthorize
         @token = nil
       end
 
       ##
-      # See Orchestrator#given_metadata
+      # @see ConfigurationService::Test::Orchestrator#given_metadata
       #
       def given_metadata
         @metadata = {"version" => "1.0"}
       end
 
       ##
-      # See Orchestrator#given_existing_configuration
+      # @see ConfigurationService::Test::Orchestrator#given_existing_configuration
       #
       def given_existing_configuration
         authorized_as(:publisher) do
@@ -102,14 +141,14 @@ module ConfigurationService
       end
 
       ##
-      # See Orchestrator#given_invalid_configuration
+      # @see ConfigurationService::Test::Orchestrator#given_invalid_configuration
       #
       def given_invalid_configuration
         @configuration = "This should be an object!"
       end
 
       ##
-      # See Orchestrator#given_missing_configuration
+      # @see ConfigurationService::Test::Orchestrator#given_missing_configuration
       #
       def given_missing_configuration
         authorized_as(:publisher) do
@@ -119,23 +158,30 @@ module ConfigurationService
       end
 
       ##
-      # See Orchestrator#existing_configuration
+      # @see ConfigurationService::Test::Orchestrator#existing_configuration
       #
       def existing_configuration
         @existing_configuration.data
       end
 
       ##
-      # See Orchestrator#existing_revision
+      # @see ConfigurationService::Test::Orchestrator#existing_revision
       #
       def existing_revision
         @existing_configuration.revision
       end
 
       ##
-      # Perform a consuming operation against the service under test
+      # Request configuration
+      #
+      # Request configuration from the configuration service.
+      # This exercises the configuration service provider under test through the configuration service API.
+      #
+      # The response from the service is wrapped in a test {ConfigurationService::Test::response}.
+      #
+      # @return [ConfigurationService::Test::Response]
       #
-      # The response from the service is wrapped in a test Response.
+      # @see ConfigurationService::Base#request_configuration
       #
       def request_configuration
         wrap_response do
@@ -144,9 +190,16 @@ module ConfigurationService
       end
 
       ##
-      # Perform a publishing operation against the service under test
+      # Publish configuration
       #
-      # The response from the service is wrapped in a test Response.
+      # Publish configuration through the configuration service.
+      # This exercises the configuration service provider under test through the configuration service API.
+      #
+      # The response from the service is wrapped in a test {ConfigurationService::Test::response}.
+      #
+      # @return [ConfigurationService::Test::Response]
+      #
+      # @see ConfigurationService::Base#publish_configuration
       #
       def publish_configuration
         wrap_response do
@@ -159,73 +212,30 @@ module ConfigurationService
       end
 
       ##
-      # Arrange for the next publication or consuming operation to fail
+      # Arrange for the next publish or request operation to fail
+      #
+      # This is done by using a {#broken_service_provider} to service the next operation.
       #
-      # This is done by using a #broken_service_provider to service the
-      # next operation.
+      # @return [nil]
       #
       def fail_next_request
         @fail_next = true
       end
 
-      private
-
-        ##
-        # Return a ConfigurationService::Base provider
-        #
-        # The provider should use a consistent +identifier+.
-        #
-        def service_provider # :doc:
-          raise NotImplementedError, "#{self.class} must implement service_provider"
-        end
-
-        ##
-        # Return a broken ConfigurationService::Base provider
-        #
-        # The provider's #publish_configuration and #request_configuration
-        # methods must raise an Error other than AuthorizationError.
-        #
-        def broken_service_provider # :doc:
-          raise NotImplementedError, "#{self.class} must implement broken_service_provider"
-        end
-
-        ##
-        # Delete the configuration identified by the consistent +identifier+
-        #
-        # Deleting non-existent configuration should not produce an error.
-        #
-        def delete_configuration # :doc:
-          raise NotImplementedError, "#{self.class} must implement delete_configuration"
-        end
-
-        ##
-        # Return a token that authorizes +role+
-        #
-        # Valid roles are:
-        #
-        # * +:consumer+
-        # * +:publisher+
-        # * +:nothing+
-        #
-        # Note that a token should be returned for +:nothing+, but the token should
-        # not be authorized to consume or publish to the +identifier+.
-        #
-        def token_for(role) # :doc:
-          raise NotImplementedError, "#{self.class} must implement token_for(role)"
+      ##
+      # Mark a cucumber step as pending
+      #
+      # @raise [Cucumber::Pending] always
+      #
+      def pending(message = nil)
+        if message
+          raise Cucumber::Pending, message
+        else
+          raise Cucumber::Pending
         end
+      end
 
-        ##
-        # Raise a Cucumber::Pending exception
-        #
-        # This allows incomplete implementations to mark features as pending
-        #
-        def pending(message = nil) # :doc:
-          if message
-            raise Cucumber::Pending, message
-          else
-            raise Cucumber::Pending
-          end
-        end
+      private
 
         def configuration
           @configuration ||= {"verbose" => true}

data/lib/configuration_service/test/orchestration_provider_registry.rb

@@ -8,40 +8,46 @@ module ConfigurationService
     unless defined?(OrchestrationProviderRegistry)
 
       ##
-      # Singleton registry of Orchestrator providers
+      # Singleton registry of test orchestration providers
+      #
+      # @!method self.instance
+      #   The singleton registry instance
+      #
+      #   @return [ConfigurationService::Test::OrchestrationProviderRegistry] singleton instance
       #
       class OrchestrationProviderRegistry
         include Singleton
 
-        def initialize ## :nodoc:
-          @providers = {}
-        end
-
         ##
-        # Register a +provider+ identified by the string +identifier+
+        # Register a test orchestration provider
         #
-        # The +provider+ should be a class with a default (nullary) constructor.
+        # @param [String] identifier
+        #   unique identifier for the test orchestration provider
+        # @param [Class] provider
+        #   the test orchestration provider class (which should have a default/nullary constructor)
         #
         def register(identifier, provider)
           @providers[identifier] = provider
         end
 
         ##
-        # Return the +provider+ identified by the string +identifier+
+        # Look up a test orchestration provider
         #
-        # The +provider+ must already have been registered with #register,
-        # and should be a class with a default (nullary) constructor.
+        # @param [String] identifier
+        #   the unique identifier for the test orchestration provider.
+        #   The provider must already have been registered with {#register}.
         #
-        # Returns +nil+ if no provider has been registered with the given
-        # +identifier+.
+        # @return [Class] the test orchestration provider class
+        # @return [nil] if no provider has been registered with the given +identifier+
         #
         def lookup(identifier)
           @providers[identifier]
         end
 
-        ##
-        # Return the singleton registry instance
-        # :singleton-method: instance
+        # @private
+        def initialize
+          @providers = {}
+        end
 
       end