restful_serializer 0.1.3 → 0.1.4

data/lib/restful/serializer.rb

@@ -1,23 +1,49 @@
 # This file is part of restful_serializer.  Copyright 2011 Joshua Partlow.  This is free software, see the LICENSE file for details.
-require 'deep_merge'
+require 'forwardable'
 
 module Restful
 
+  # Enables local generation of named_routes with preset arguments:
+  #
+  # * :api_prefix
+  # * :default_url_options
+  #
+  # Used by Serializer and Association to customize urls for their WebService.
+  class UrlFactory
+    attr_accessor :api_prefix, :default_url_options
+
+    def initialize(options)
+      self.api_prefix = options[:api_prefix]
+      self.default_url_options = options[:default_url_options] || {}
+    end
+
+    # Url.for but with UrlFactory's options slipped in.
+    def create(options)
+      create_options = {:api_prefix => api_prefix}.merge(options).deep_merge(:named_route_options => default_url_options)
+      Url.for(create_options)
+    end
+  end
+
   # Used to construct and attempt to call named routes by providing resource
   # strings out of which a named route method name will be constructed:
   #
   # Options:
   #
+  # * :api_prefix => if we are constructing an url helper from a collection of
+  #   resource names, prepend it with this prefix
   # * :resources => a symbol, string or array of same describing segments of
   #   the helper method name.  e.g. [:user, :comments] => user_comments (to
   #   which _url will be appended...)
-  # * :method => overrides the use of :resources and :prefix
-  # * :args => any arguments to be passed to the named_route when it is called
-  #
+  # * :method => overrides the use of :resources and :api_prefix
+  # * :named_route_options => any additional options to be passed to the
+  #   named_route when it is called (:id or :host for instance)
+  #   
   # = Example
   #
-  #   Url.for(:resources => [:user, :comments], :args => 1)
-  #   # => send("#{Restful.api_prefix}_user_comments_url", 1)
+  #   Url.for(:api_prefix => :foo_service, :resources => [:user, :comments],
+  #     :named_route_options => {:id => 1})
+  #
+  #   # => send("foo_service_user_comments_url", {:id => 1})
   #   # which if it exists is likely to return something like:
   #   # "http://example.com/user/1/comments"
   #
@@ -29,10 +55,11 @@ module Restful
 
     class << self
    
-      # Sets ActionController::UrlWriter.default_url_options from Restful.default_url_options.
-      # Attempting to do this during Rails initialization results in botched routing, presumably
-      # because of how ActionController::UrlWriter initializes when you include it into a class.
-      # So this method is called lazily. 
+      # Sets ActionController::UrlWriter.default_url_options from
+      # Restful.default_url_options.  Attempting to do this during Rails
+      # initialization results in botched routing, presumably because of how
+      # ActionController::UrlWriter initializes when you include it into a
+      # class.  So this method is called lazily. 
       def initialize_default_url_options
         unless @@initialized
           self.default_url_options = Restful.default_url_options
@@ -53,7 +80,7 @@ module Restful
 
     def to_s
       url_for = [options[:method], 'url'] if options.include?(:method)
-      url_for ||= [Restful.api_prefix, options[:resources], 'url'].flatten.compact
+      url_for ||= [options[:api_prefix], options[:resources], 'url'].flatten.compact
       url_for = url_for.join('_').downcase
       send(url_for, *Array(options[:args])) if respond_to?(url_for) 
     end
@@ -85,33 +112,50 @@ module Restful
     end
   end
 
+  # New instances of Serializer handle the actual conversion of a model subject into
+  # a hash of resource attributes.
+  #
+  # = Configuration
+  #
+  # There are four levels of configuration.
+  #
+  # 1. The subject's base_class configuration (if different than it's own class configuration)
+  # 2. The subject's class configuration
+  # 3. Any additional parameters passed into the initialization of the Serializer.  
+  # 4. Any configuration performed when the Restful::Configuration::Resource is yielded
+  #    to a passed block in initialization.
+  #
+  # One through three are successively deep_merged.  Four allows for complete redefinition.
   class Serializer
-    attr_accessor :subject, :base_klass, :klass, :options, :shallow
- 
-    def initialize(subject, *args)
+    extend Forwardable
+
+    attr_accessor :subject, :base_klass, :klass, :options, :configure_block
+    attr_accessor :web_service, :resource_configuration, :url_factory
+
+    def_delegators :@web_service, :api_prefix, :default_url_options
+    def_delegator :@resource_configuration, :associations, :resource_associations
+    def_delegators :@resource_configuration, :serialization, :url_for, :no_inherited_options, :shallow, :name_method
+
+    def initialize(subject, web_service, options = {}, &block)
       self.subject = subject
+      self.web_service = web_service || Restful::Configuration::WebService.new('__stub__')
+      raise(ArgumentError, "No web service configuration set.  Received: #{web_service.inspect})") unless web_service.kind_of?(Restful::Configuration::WebService)
 
       self.base_klass = subject.class.base_class.name.demodulize.underscore if subject.class.respond_to?(:base_class)
       self.klass = subject.class.name.demodulize.underscore
 
-      passed_options = (args.pop || {}).symbolize_keys
+      self.options = (options || {}).symbolize_keys
       if subject.kind_of?(Array)
-        # preserve options as is to be passed to array members
-        self.options = passed_options
+        # preserve configure block to pass to array members 
+        self.configure_block = block
       else
-        deeply_merge = passed_options.delete(:deep_merge)
-        base_options = Restful.model_configuration_for(base_klass) || {}
-        class_options = Restful.model_configuration_for(klass) || {}
-        self.options = (klass == base_klass || class_options[:no_inherited_options]) ? 
-          class_options : 
-          base_options.merge(class_options)
-        self.options.merge!(passed_options)
-        self.options.deep_merge(deeply_merge) if deeply_merge
+        _configure(&block)
       end
-
-      self.shallow = options[:shallow]
+    
+      self.url_factory = UrlFactory.new(:api_prefix => api_prefix, :default_url_options => default_url_options)
     end
-  
+ 
+    # Encode as a resource hash. 
     def serialize
       case 
         when subject.respond_to?(:attribute_names) then _serialize_active_record
@@ -121,27 +165,26 @@ module Restful
     end
 
     def active_record_serialization_options
-      ar_options = (options[:serialization] || {}).clone
+      ar_options = serialization.to_hash(:ignore_empty => true)
       ar_options.delete(:include) if shallow 
       return ar_options
     end
 
     def name
-      name_method = options[:name] || :name
       subject.send(name_method) if subject.respond_to?(name_method)
     end
 
     def associations
       unless @associations
-        @associations = case options[:associations]
+        @associations = case resource_associations
           when Array,Hash
-            options[:associations].map do |name,assoc|
-              Association.new(subject, klass, (assoc.nil? ? name : assoc), name)
+            resource_associations.map do |name,assoc|
+              Association.new(subject, klass, (assoc.nil? ? name : assoc), url_factory, name)
             end
           when nil
             []
           else
-            [Association.new(subject, klass, options[:associations])]
+            [Association.new(subject, klass, resource_associations, url_factory)]
         end
       end
       return @associations
@@ -149,15 +192,48 @@ module Restful
 
     def href 
       unless @href
-        @href = Url.for(:method => options[:url_for], :args => subject.id) if options.include?(:url_for)
-        @href = Url.for(:resources => klass, :args => subject.id) unless @href
-        @href = Url.for(:resources => base_klass, :args => subject.id) unless @href || base_klass == klass
+        @href = url_factory.create(:method => url_for, :args => subject.id) if url_for
+        @href = url_factory.create(:resources => klass, :args => subject.id) unless @href
+        @href = url_factory.create(:resources => base_klass, :args => subject.id) unless @href || base_klass == klass
       end
       return @href
     end
 
     private
 
+    def base_configuration
+      unless @base_configuration
+        @base_configuration = web_service.resource_configuration_for(base_klass) if web_service
+        @base_configuration ||= Restful::Configuration::Resource.new
+      end
+      return @base_configuration
+    end
+
+    def class_configuration
+      unless @class_configuration
+        @class_configuration = web_service.resource_configuration_for(klass) if web_service
+        @class_configuration ||= Restful::Configuration::Resource.new
+      end
+      return @class_configuration
+    end
+
+    def passed_configuration
+      return @passed_configuration ||= Restful::Configuration::Resource.new(options)
+    end
+
+    def _configure(&block)
+      self.resource_configuration = 
+        (klass == base_klass || class_configuration.no_inherited_options) ? 
+          class_configuration.deep_clone :
+          base_configuration.deep_merge!(class_configuration)
+
+      self.resource_configuration = resource_configuration.deep_merge!(passed_configuration)
+
+      yield(resource_configuration) if block_given?
+
+      return resource_configuration
+    end
+
     def _serialize_active_record
       restful = DeepHash[
         klass => ActiveRecord::Serialization::Serializer.new(subject, active_record_serialization_options).serializable_record
@@ -174,8 +250,8 @@ module Restful
     def _serialize_array
       restful = subject.map do |e|
         array_options = options.clone
-        array_options.merge!(:shallow => true) unless array_options.include?(:shallow)
-        Serializer.new(e, array_options).serialize
+        array_options = { :shallow => true }.merge(array_options)
+        Serializer.new(e, web_service, array_options, &configure_block).serialize
       end 
       return restful 
     end
@@ -183,12 +259,13 @@ module Restful
 
   # Handle for information about an ActiveRecord association.
   class Association
-    attr_accessor :name, :association_name, :association, :subject, :subject_klass
+    attr_accessor :name, :association_name, :association, :subject, :subject_klass, :url_factory
     
-    def initialize(subject, subject_klass, association_name, name = nil)
+    def initialize(subject, subject_klass, association_name, url_factory, name = nil)
       self.subject = subject
       self.subject_klass = subject_klass
       self.association_name = association_name
+      self.url_factory = url_factory
       self.name = name || association_name
       self.association = subject.class.reflect_on_association(association_name)
     end
@@ -199,7 +276,7 @@ module Restful
 
     def href
       if singular?
-        href = Url.for(:resources => association_name, :args => subject.send(association.name).id)
+        href = url_factory.create(:resources => association_name, :args => subject.send(association.name).id)
       else
         href = collective_href
       end
@@ -208,8 +285,8 @@ module Restful
 
     def collective_href
       # try url_for nested resources first
-      unless href = Url.for(:resources => [subject_klass, association_name], :args => subject.id)
-        href = Url.for(:resources => association_name)
+      unless href = url_factory.create(:resources => [subject_klass, association_name], :args => subject.id)
+        href = url_factory.create(:resources => association_name)
       end
       return href 
     end

data/lib/restful/version.rb

@@ -1,3 +1,3 @@
 module Restful
-  VERSION = "0.1.3"
+  VERSION = "0.1.4"
 end

data/lib/restful.rb

@@ -5,27 +5,7 @@
 #
 # It produces a hash of reference, object and href information for an
 # ActiveRecord instance or association.  Output is highly configurable both
-# through Rails initialization and method calls.
-#
-# = Options
-#
-# The following options may be set in the Restful.model_configuration hash on a
-# per model class basis.
-#
-# * :name => method to call on an instance to produce a human meaningful
-#   reference for the instance.  Defaults to :name.
-# * :serialization => options to be passed to
-#   ActiveRecord::Serialization::Serializer to configure serialization of the
-#   ActiveRecord instance itself.  See ActiveRecord::Serialization.to_json
-# * :url_for => if the named_route helper method cannot be guessed from normal
-#   Rails restful syntax, it may be overriden here.
-# * :associations => you may include href references to the instance's associations
-# * :shallow => if you are serializing an association, by default member
-#   includes and association references are stripped.  Set this to false to
-#   traverse deeply.
-# * :no_inherited_options => normally a subclass inherits and overrides its
-#   base class settings.  Setting this to true prevents this so that only the
-#   options specifically set for the class will be used.  Default false.
+# through Rails initialization and during method calls.
 #
 # = Usage
 #
@@ -54,114 +34,157 @@
 #     end 
 #   end
 #
-#   Restful.model_configuration = {
-#     :person => {
+#   Restful.default_url_options(:host => 'www.example.com')
+#   Restful.register_web_service(:books) do |config|
+#
+#     config.register_resource(:person,
 #       :serialization => { :except => [:secrets] }
-#       :associations => :books,
-#     }
-#     :book => {
-#       :name => :title,
-#       :associations => :person,
-#     }
-#   }
-#
-#   bob = Person.new(:first_name => 'Bob', :last_name => 'Smith', :age => 41, :secrets => 'untold')
-#   bob.restful
+#       :associations => :books
+#     )
+#
+#     config.register_resource(:book,
+#       :name_method => :title,
+#       :associations => :person
+#     )
+#
+#   end 
+#
+#   bob = Person.new(:first_name => 'Bob', :last_name => 'Smith', :age => 41,
+#     :secrets => 'untold')
+#   bob.restful(:books)
 #   # => { 
 #   #   'name' => 'Bob Smith'
 #   #   'person' => { 
 #   #      'id' => 1,
 #   #      'first_name' => 'Bob',
 #   #      'last_name' => 'Bob',
-#   #      'age' : 17,
+#   #      'age' => 17,
 #   #   },
 #   #   'href' => 'http://www.example.com/web_service/people/1' }
 #   #   'books_href' => 'http://www.example.com/web_service/people/1/books' }
 #   # }
 #
-# Options may be overridden at call time, by default this overwrite the passed options completely:
+# Options may be adjusted at call time.
+#
+# If options are passed in as a hash then they will be merged into the class's
+# registered resource configuration (using the +deep_merge+ gem).  
 #  
-#   bob = Person.new(:first_name => 'Bob', :last_name => 'Smith', :age => 41, :secrets => 'untold')
-#   bob.restful(:serialization => { :except => [:id] })
+#   bob = Person.new(:first_name => 'Bob', :last_name => 'Smith', :age => 41,
+#     :secrets => 'untold')
+#   bob.restful(:books, :serialization => { :except => [:id] })
 #   # => { 
 #   #   'name' => 'Bob Smith'
 #   #   'person' => { 
 #   #      'first_name' => 'Bob',
 #   #      'last_name' => 'Bob',
-#   #      'age' : 17,
-#   #      'secrets' : 'untold',
+#   #      'age' => 17,
 #   #   },
 #   #   'href' => 'http://www.example.com/web_service/people/1' }
 #   #   'books_href' => 'http://www.example.com/web_service/people/1/books' }
 #   # }
 #
-# To perform a deep merge of options instead, place the options to be deeply merged
-# inside a :deep_merge hash:
+# For more fine grained control, the final configuration object is exposed
+# if a block is given to the restful call:
+#
+#   bob = Person.new(:first_name => 'Bob', :last_name => 'Smith', :age => 41,
+#     :secrets => 'untold')
+#   bob.restful(:books, :serialization => { :except => [:id] }) do |configure|
 #
-#   bob = Person.new(:first_name => 'Bob', :last_name => 'Smith', :age => 41, :secrets => 'untold')
-#   bob.restful(:deep_merge => { :serialization => { :except => [:id] } })
+#     pp configure.serialization.except
+#     # => [ :secrets, :id ]
+#
+#     configure.serializtion.except = :id
+#
+#   end
 #   # => { 
 #   #   'name' => 'Bob Smith'
 #   #   'person' => { 
 #   #      'first_name' => 'Bob',
 #   #      'last_name' => 'Bob',
-#   #      'age' : 17,
+#   #      'age' => 17,
+#   #      'secrets' => 'untold',
 #   #   },
 #   #   'href' => 'http://www.example.com/web_service/people/1' }
 #   #   'books_href' => 'http://www.example.com/web_service/people/1/books' }
 #   # }
 #
-# These two techniques can be combined, but overwriting will occur prior to a deep merge...
-#
-# (There is a trap in how deep merge handles this.  If the above :except values had
-# not been configured as arrays, then deep merge would have overwritten rather than merging
-# them.  This could probably be adjusted with a closer look into the deep_merge docs.)
+# These two techniques can be combined.
 module Restful
-  # Requiring Serializer (and hence action_controller for UrlWriter) was interferring with
-  # route generation somehow, so instead we are letting it autoload if used.
   autoload :Serializer, 'restful/serializer'
-
-  # Route prefix for api calls.
-  mattr_accessor :api_prefix
+  autoload :Configuration, 'restful/configuration'
 
   # Default url options for ActionController::UrlWriter.
   # (Generally you must provide {:host => 'example.com'})
   mattr_accessor :default_url_options
   self.default_url_options = {}
 
-  # Hash for configuration Restful models.
-  mattr_accessor :model_configuration
-  self.model_configuration = {}
+  # Hash of registered Restful::Configuration::WebService configurations. 
+  mattr_accessor :registered_web_services
+  self.registered_web_services = {}
 
-  def self.model_configuration=(options)
-    @@model_configuration = options.symbolize_keys
-  end
+  class << self
 
-  def self.model_configuration_for(key)
-    config = case key 
-      when Symbol
-        model_configuration[key]
-      when String
-        model_configuration[key.to_sym]
-      when Class
-        model_configuration[key.name.underscore.to_sym]
-      else
-        model_configuration[key.class.name.underscore.to_sym]
+    # Configured the specified web service.
+    def register_web_service(name, options = {}, &block)
+      @@registered_web_services[symbolized_web_service_name(name)] = new_ws = Restful::Configuration::WebService.register(name, options, &block)
+      return new_ws
     end
-    return Marshal.load(Marshal.dump(config)) || {} # deep clone or empty
-  end
 
-  module Extensions
-    def restful(*args)
-      Restful::Serializer.new(self, *args).serialize
+    # Retrieve configuration for the specified web service. 
+    def web_service_configuration(key)
+      ws = @@registered_web_services[symbolized_web_service_name(key)]
+      if ws.default_url_options.empty? && !default_url_options.empty?
+        ws.default_url_options = default_url_options.dup
+      end if ws
+      return ws
+    end
+
+    def symbolized_web_service_name(name)
+      return if name.nil?
+      name.to_s.downcase.gsub(/[^\w]+/,'_').to_sym
+    end
+
+    def clear
+      self.default_url_options = {}
+      self.registered_web_services = {}
     end
   end
 
-  module AssociationExtensions
-    def restful(*args)
-      Restful::Serializer.new(self, *args).serialize
+  module Extensions
+
+    # Restfully serialize an activerecord object, association or a plain array
+    # of activerecord objects.  The web service name must be specified as
+    # registered via Restful.register_web_service, unless there is only one
+    # registered service.
+    #
+    # A final hash of options will be passed on to the serializer for configuration.
+    #
+    # If a block is given, the serializer's Restful::Configuration::Resource
+    # configuration object will be exposed for fine grained configuration.
+    def restful(*args, &block)
+      options = args.extract_options!
+      web_service_name = args.shift
+      web_service = Restful.web_service_configuration(web_service_name)
+      web_service ||= Restful.registered_web_services.values.first if Restful.registered_web_services.size == 1
+      Restful::Serializer.new(self, web_service, options, &block).serialize
     end
   end
 end
+
+# Rails 2.3 Hash is extended with :deep_merge and :deep_merge! already, and route
+# generation requires these versions.  We're using the +deep_merge+ gem's versions,
+# and need to setup aliases to ensure that Rails versions remain available while
+# we are still able to access the gem's versions.
+Hash.class_eval do
+  alias_method :rails_deep_merge, :deep_merge
+  alias_method :rails_deep_merge!, :deep_merge!
+  require 'deep_merge'
+  alias_method :_rs_deep_merge, :deep_merge
+  alias_method :_rs_deep_merge!, :deep_merge!
+  alias_method :deep_merge, :rails_deep_merge
+  alias_method :deep_merge!, :rails_deep_merge!
+end
+
 ActiveRecord::Base.send(:include, Restful::Extensions)
-ActiveRecord::Associations::AssociationProxy.send(:include, Restful::AssociationExtensions)
+ActiveRecord::Associations::AssociationProxy.send(:include, Restful::Extensions)
+Array.send(:include, Restful::Extensions)