Further refining Instance vs. Class provider opts

Based on feedback concerning the prior commit, this commit seeks to
further insulate the change of behavior to downstream implementors.

1) I added discussion and documentation about the change
2) I updated the tests accordingly
3) I added fall-back behavior in case someone inherited from
   OIA::Provider but did not initialize with `super`

The method documentation for `OAI::Provider::Base#provider_context`
highlights the entirity of this change:

> The traditional interaction of a Provider has been to:
>
> 1. Assign attributes to the Provider class
> 2. Instantiate the Provider class
> 3. Call response instance methods for theProvider which pass
>    the Provider class and not the instance.
>
> The above behavior continues unless you initialize the Provider with
> `{ :provider_context => :instance_based }`. If you do that, then the
>
> Provider behavior will be:
>
> 1. Assign attributes to Provider class
> 2. Instantiate the Provider class
> 3. Call response instance methods for theProvider which pass an
>    instance of the Provider to those response objects.
>    a. The instance will mirror all of the assigned Provider class
>       attributes, but allows for overriding and extending on a
>       case by case basis.
>
> (Dear reader, please note the second behavior is something most
> of us would've assumed to be the case, but for historic now lost
> reasons is not the case.)

Author: jeremyf

lib/oai/provider.rb

@@ -139,6 +139,35 @@
 #
 # Special thanks to Jose Hales-Garcia for this solution.
 #
+# ### Leverage the Provider instance
+#
+# The traditional implementation of the OAI::Provider would pass the OAI::Provider
+# class to the different resposnes. This made it hard to inject context into a
+# common provider. Consider that we might have different request headers that
+# change the scope of the OAI::Provider queries.
+#
+# ```ruby
+# class InstanceProvider
+#   def initialize(options = {})
+#     super({ :provider_context => :instance_based })
+#     @controller = options.fetch(:controller)
+#   end
+#   attr_reader :controller
+# end
+#
+# class OaiController < ApplicationController
+#   def index
+#     provider = InstanceProvider.new({ :controller => self })
+#     request_body =  provider.process_request(oai_params.to_h)
+#     render :body => request_body, :content_type => 'text/xml'
+#   end
+# ```
+#
+# In the above example, the underlying response object will now receive an
+# instance of the InstanceProvider. Without the `super({ :provider_context => :instance_based })`
+# the response objects would have received the class InstanceProvider as the
+# given provider.
+#
 # ## Supporting custom metadata formats
 #
 # See {OAI::MetadataFormat} for details.
@@ -240,10 +269,9 @@ module OAI::Provider
   class Base
     include OAI::Provider
 
-    OAI_PMH_ATTRIBUTES = [:name, :url, :prefix, :email, :delete_support, :granularity, :model, :identifier, :description]
     class << self
       attr_reader :formats
-      attr_accessor(*OAI_PMH_ATTRIBUTES)
+      attr_accessor :name, :url, :prefix, :email, :delete_support, :granularity, :model, :identifier, :description
 
       def register_format(format)
         @formats ||= {}
@@ -298,19 +326,43 @@ def inherited(klass)
       :instance_based => :instance_based
     }
 
-    def initialize(provider_context = :class_based)
+    def initialize(options = {})
+      provider_context = options.fetch(:provider_context) { :class_based }
       @provider_context = PROVIDER_CONTEXTS.fetch(provider_context)
-      OAI_PMH_ATTRIBUTES.each do |attr|
-        instance_variable_set("@#{attr}", self.class.public_send(attr))
-      end
     end
-    attr_accessor(*OAI_PMH_ATTRIBUTES)
 
+    # @note These are the accessor methods on the class. If you need to overwrite
+    # them on the instance level you can do that. However, an instance of this
+    # class won't be used unless you initialize with:
+    # { :provider_context => :instance_based }
+    attr_writer :name, :url, :prefix, :email, :delete_support, :granularity, :model, :identifier, :description
+
+    # The traditional interaction of a Provider has been to:
+    #
+    # 1) Assign attributes to the Provider class
+    # 2) Instantiate the Provider class
+    # 3) Call response instance methods for theProvider which pass
+    #    the Provider class and not the instance.
+    #
+    # The above behavior continues unless you initialize the Provider with
+    # { :provider_context => :instance_based }. If you do that, then the
+    # Provider behavior will be:
+    #
+    # 1) Assign attributes to Provider class
+    # 2) Instantiate the Provider class
+    # 3) Call response instance methods for theProvider which pass an
+    #    instance of the Provider to those response objects.
+    #    a) The instance will mirror all of the assigned Provider class
+    #       attributes, but allows for overriding and extending on a
+    #       case by case basis.
+    # (Dear reader, please note the second behavior is something most
+    # of us would've assumed to be the case, but for historic now lost
+    # reasons is not the case.)
     def provider_context
-      if @provider_context == :class_based
-        self.class
-      else
+      if @provider_context == :instance_based
         self
+      else
+        self.class
       end
     end
 
@@ -326,6 +378,42 @@ def formats
       self.class.formats
     end
 
+    def name
+      @name || self.class.name
+    end
+
+    def url
+      @url || self.class.url
+    end
+
+    def prefix
+      @prefix || self.class.prefix
+    end
+
+    def email
+      @email || self.class.email
+    end
+
+    def delete_support
+      @delete_support || self.class.delete_support
+    end
+
+    def granularity
+      @granularity || self.class.granularity
+    end
+
+    def model
+      @model || self.class.model
+    end
+
+    def identifier
+      @identifier || self.class.identifier
+    end
+
+    def description
+      @description || self.class.description
+    end
+
     # Equivalent to '&verb=Identify', returns information about the repository
     def identify(options = {})
       Response::Identify.new(provider_context, options).to_xml
@@ -370,7 +458,7 @@ def process_request(params = {})
       begin
 
         # Allow the request to pass in a url
-        provider_context.url = params['url'] ? params.delete('url') : self.class.url
+        provider_context.url = params['url'] ? params.delete('url') : self.url
 
         verb = params.delete('verb') || params.delete(:verb)
 

test/provider/tc_instance_provider.rb

@@ -13,7 +13,7 @@ class TestInstanceProvider < Test::Unit::TestCase
   # response object.
   def test_instance_used_in_responses
     @url_path = "/stringy-mc-string-face"
-    @instance_provider = InstanceProvider.new(:instance_based, @url_path)
+    @instance_provider = InstanceProvider.new({ :provider_context => :instance_based, :url_path => @url_path })
 
     xml = @instance_provider.identify
     doc =  REXML::Document.new(xml)
@@ -22,7 +22,16 @@ def test_instance_used_in_responses
 
   def test_class_used_in_responses
     @url_path = "/stringy-mc-string-face"
-    @instance_provider = InstanceProvider.new(:class_based, @url_path)
+    @instance_provider = InstanceProvider.new({ :provider_context => :class_based, :url_path => @url_path })
+
+    xml = @instance_provider.identify
+    doc =  REXML::Document.new(xml)
+    assert_equal "http://localhost", doc.elements["OAI-PMH/Identify/baseURL"].text
+  end
+
+  def test_by_default_class_used_in_responses
+    @url_path = "/stringy-mc-string-face"
+    @instance_provider = InstanceProvider.new({ :url_path => @url_path })
 
     xml = @instance_provider.identify
     doc =  REXML::Document.new(xml)

test/provider/test_helper_provider.rb

@@ -50,9 +50,9 @@ class InstanceProvider < Provider::Base
   repository_url 'http://localhost'
   source_model SimpleModel.new
 
-  def initialize(context_provider, url_path)
-    super(context_provider)
-    @url_path = url_path
+  def initialize(options = {})
+    super
+    @url_path = options.fetch(:url_path)
   end
   attr_reader :url_path