Merge pull request #1017 from bf4/registerable_adapters

Make Adapters registerable so they are not namespace-constrained

Author: joaomdmoura

.gitignore

@@ -4,6 +4,7 @@
 .config
 .yardoc
 Gemfile.lock
+Gemfile.local
 InstalledFiles
 _yardoc
 coverage

.rubocop.yml

@@ -8,6 +8,39 @@ AllCops:
   DisplayCopNames: true
   DisplayStyleGuide: true
 
+Style/IndentationConsistency:
+  Exclude:
+    - lib/active_model/serializer/adapter/flatten_json.rb
+    - lib/active_model/serializer/adapter/fragment_cache.rb
+    - lib/active_model/serializer/adapter/json.rb
+    - lib/active_model/serializer/adapter/json/fragment_cache.rb
+    - lib/active_model/serializer/adapter/json_api.rb
+    - lib/active_model/serializer/adapter/json_api/fragment_cache.rb
+    - lib/active_model/serializer/adapter/json_api/pagination_links.rb
+    - lib/active_model/serializer/adapter/null.rb
+
+Style/IndentationWidth:
+  Exclude:
+    - lib/active_model/serializer/adapter/flatten_json.rb
+    - lib/active_model/serializer/adapter/fragment_cache.rb
+    - lib/active_model/serializer/adapter/json.rb
+    - lib/active_model/serializer/adapter/json/fragment_cache.rb
+    - lib/active_model/serializer/adapter/json_api.rb
+    - lib/active_model/serializer/adapter/json_api/fragment_cache.rb
+    - lib/active_model/serializer/adapter/json_api/pagination_links.rb
+    - lib/active_model/serializer/adapter/null.rb
+
+Style/AccessModifierIndentation:
+  Exclude:
+    - lib/active_model/serializer/adapter/flatten_json.rb
+    - lib/active_model/serializer/adapter/fragment_cache.rb
+    - lib/active_model/serializer/adapter/json.rb
+    - lib/active_model/serializer/adapter/json/fragment_cache.rb
+    - lib/active_model/serializer/adapter/json_api.rb
+    - lib/active_model/serializer/adapter/json_api/fragment_cache.rb
+    - lib/active_model/serializer/adapter/json_api/pagination_links.rb
+    - lib/active_model/serializer/adapter/null.rb
+
 Lint/NestedMethodDefinition:
   Enabled: false
   Exclude:

.simplecov

@@ -8,7 +8,7 @@
   when 'jruby', 'rbx'
     96.0
   else
-    98.3
+    98.1
   end
 }.to_f.round(2)
 # rubocop:disable Style/DoubleNegation

Gemfile

@@ -1,4 +1,8 @@
 source 'https://rubygems.org'
+#
+# Add a Gemfile.local to locally bundle gems outside of version control
+local_gemfile = File.join(File.expand_path('..', __FILE__), 'Gemfile.local')
+eval_gemfile local_gemfile if File.readable?(local_gemfile)
 
 # Specify your gem's dependencies in active_model_serializers.gemspec
 gemspec

docs/general/adapters.md

@@ -32,7 +32,7 @@ resources in the `"included"` member when the resource names are included in the
 
 ## Choosing an adapter
 
-If you want to use a different adapter, such as JsonApi, you can change this in an initializer:
+If you want to use a specify a default adapter, such as JsonApi, you can change this in an initializer:
 
 ```ruby
 ActiveModel::Serializer.config.adapter = ActiveModel::Serializer::Adapter::JsonApi
@@ -44,8 +44,59 @@ or
 ActiveModel::Serializer.config.adapter = :json_api
 ```
 
-If you want to have a root key in your responses you should use the Json adapter, instead of the default FlattenJson:
+If you want to have a root key for each resource in your responses, you should use the Json or
+JsonApi adapters instead of the default FlattenJson:
 
 ```ruby
 ActiveModel::Serializer.config.adapter = :json
 ```
+
+## Advanced adapter configuration
+
+### Registering an adapter
+
+The default adapter can be configured, as above, to use any class given to it.
+
+An adapter may also be specified, e.g. when rendering, as a class or as a symbol.
+If a symbol, then the adapter must be, e.g. `:great_example`,
+`ActiveModel::Serializer::Adapter::GreatExample`, or registered.
+
+There are two ways to register an adapter:
+
+1) The simplest, is to subclass `ActiveModel::Serializer::Adapter`, e.g. the below will
+register the `Example::UsefulAdapter` as `:useful_adapter`.
+
+```ruby
+module Example
+  class UsefulAdapter < ActiveModel::Serializer::Adapter
+  end
+end
+```
+
+You'll notice that the name it registers is the class name underscored, not the full namespace.
+
+Under the covers, when the `ActiveModel::Serializer::Adapter` is subclassed, it registers
+the subclass as `register(:useful_adapter, Example::UsefulAdapter)`
+
+2) Any class can be registered as an adapter by calling `register` directly on the
+`ActiveModel::Serializer::Adapter` class. e.g., the below registers `MyAdapter` as
+`:special_adapter`.
+
+```ruby
+class MyAdapter; end
+ActiveModel::Serializer::Adapter.register(:special_adapter, MyAdapter)
+```
+
+### Looking up an adapter
+
+| `ActiveModel::Serializer::Adapter.adapter_map` | A Hash of all known adapters { adapter_name => adapter_class } |
+| `ActiveModel::Serializer::Adapter.adapters`    | A (sorted) Array of all known adapter_names |
+| `ActiveModel::Serializer::Adapter.lookup(name_or_klass)` |  The adapter_class, else raises an `ActiveModel::Serializer::Adapter::UnknownAdapter` error |
+| `ActiveModel::Serializer::Adapter.adapter_class(adapter)` | delegates to `ActiveModel::Serializer::Adapter.lookup(adapter)` |
+| `ActiveModel::Serializer.adapter` | a convenience method for `ActiveModel::Serializer::Adapter.lookup(config.adapter)` |
+
+The registered adapter name is always a String, but may be looked up as a Symbol or String.
+Helpfully, the Symbol or String is underscored, so that `get(:my_adapter)` and `get("MyAdapter")`
+may both be used.
+
+For more information, see [the Adapter class on GitHub](https://github.com/rails-api/active_model_serializers/blob/master/lib/active_model/serializer/adapter.rb)

lib/active_model/serializable_resource.rb

@@ -76,7 +76,7 @@ def serializer?
     private
 
     ActiveModelSerializers.silence_warnings do
-    attr_reader :resource, :adapter_opts, :serializer_opts
+      attr_reader :resource, :adapter_opts, :serializer_opts
     end
   end
 end

lib/active_model/serializer.rb

@@ -94,19 +94,9 @@ def self.serializer_for(resource, options = {})
       end
     end
 
+    # @see ActiveModel::Serializer::Adapter.lookup
     def self.adapter
-      adapter_class = case config.adapter
-                      when Symbol
-                        ActiveModel::Serializer::Adapter.adapter_class(config.adapter)
-                      when Class
-                        config.adapter
-                      end
-      unless adapter_class
-        valid_adapters = Adapter.constants.map { |klass| ":#{klass.to_s.downcase}" }
-        raise ArgumentError, "Unknown adapter: #{config.adapter}. Valid adapters are: #{valid_adapters}"
-      end
-
-      adapter_class
+      ActiveModel::Serializer::Adapter.lookup(config.adapter)
     end
 
     def self.root_name

lib/active_model/serializer/adapter.rb

@@ -1,22 +1,83 @@
 module ActiveModel
   class Serializer
     class Adapter
+      UnknownAdapterError = Class.new(ArgumentError)
+      ADAPTER_MAP = {}
+      private_constant :ADAPTER_MAP if defined?(private_constant)
       extend ActiveSupport::Autoload
-      require 'active_model/serializer/adapter/json'
-      require 'active_model/serializer/adapter/json_api'
-      autoload :FlattenJson
-      autoload :Null
       autoload :FragmentCache
+      autoload :Json
+      autoload :JsonApi
+      autoload :Null
+      autoload :FlattenJson
 
       def self.create(resource, options = {})
         override = options.delete(:adapter)
         klass = override ? adapter_class(override) : ActiveModel::Serializer.adapter
         klass.new(resource, options)
       end
 
+      # @see ActiveModel::Serializer::Adapter.lookup
       def self.adapter_class(adapter)
-        adapter_name = adapter.to_s.classify.sub('API', 'Api')
-        "ActiveModel::Serializer::Adapter::#{adapter_name}".safe_constantize
+        ActiveModel::Serializer::Adapter.lookup(adapter)
+      end
+
+      # Only the Adapter class has these methods.
+      # None of the sublasses have them.
+      class << ActiveModel::Serializer::Adapter
+        # @return Hash<adapter_name, adapter_class>
+        def adapter_map
+          ADAPTER_MAP
+        end
+
+        # @return [Array<Symbol>] list of adapter names
+        def adapters
+          adapter_map.keys.sort
+        end
+
+        # Adds an adapter 'klass' with 'name' to the 'adapter_map'
+        # Names are stringified and underscored
+        # @param [Symbol, String] name of the registered adapter
+        # @param [Class] klass - adapter class itself
+        # @example
+        #     AMS::Adapter.register(:my_adapter, MyAdapter)
+        def register(name, klass)
+          adapter_map.update(name.to_s.underscore => klass)
+          self
+        end
+
+        # @param  adapter [String, Symbol, Class] name to fetch adapter by
+        # @return [ActiveModel::Serializer::Adapter] subclass of Adapter
+        # @raise  [UnknownAdapterError]
+        def lookup(adapter)
+          # 1. return if is a class
+          return adapter if adapter.is_a?(Class)
+          adapter_name = adapter.to_s.underscore
+          # 2. return if registered
+          adapter_map.fetch(adapter_name) {
+            # 3. try to find adapter class from environment
+            adapter_class = find_by_name(adapter_name)
+            register(adapter_name, adapter_class)
+            adapter_class
+          }
+        rescue NameError, ArgumentError => e
+          failure_message =
+            "NameError: #{e.message}. Unknown adapter: #{adapter.inspect}. Valid adapters are: #{adapters}"
+          raise UnknownAdapterError, failure_message, e.backtrace
+        end
+
+        # @api private
+        def find_by_name(adapter_name)
+          adapter_name = adapter_name.to_s.classify.tr('API', 'Api')
+          ActiveModel::Serializer::Adapter.const_get(adapter_name.to_sym) or # rubocop:disable Style/AndOr
+            fail UnknownAdapterError
+        end
+        private :find_by_name
+      end
+
+      # Automatically register adapters when subclassing
+      def self.inherited(subclass)
+        ActiveModel::Serializer::Adapter.register(subclass.to_s.demodulize, subclass)
       end
 
       attr_reader :serializer

lib/active_model/serializer/adapter/flatten_json.rb

@@ -1,7 +1,4 @@
-module ActiveModel
-  class Serializer
-    class Adapter
-      class FlattenJson < Json
+class ActiveModel::Serializer::Adapter::FlattenJson < ActiveModel::Serializer::Adapter::Json
         def serializable_hash(options = {})
           super
           @result
@@ -13,7 +10,4 @@ def serializable_hash(options = {})
         def include_meta(json)
           json
         end
-      end
-    end
-  end
 end

lib/active_model/serializer/adapter/fragment_cache.rb

@@ -1,7 +1,4 @@
-module ActiveModel
-  class Serializer
-    class Adapter
-      class FragmentCache
+class ActiveModel::Serializer::Adapter::FragmentCache
         attr_reader :serializer
 
         def initialize(adapter, serializer, options)
@@ -75,7 +72,4 @@ def fragment_serializer(name, klass)
         def to_valid_const_name(name)
           name.gsub('::', '_')
         end
-      end
-    end
-  end
 end