vendor/rails/activerecord/lib/active_record/associations/association_proxy.rb

   1 module ActiveRecord
   2   module Associations
   3     # This is the root class of all association proxies:
   4     #
   5     #   AssociationProxy
   6     #     BelongsToAssociation
   7     #       HasOneAssociation
   8     #     BelongsToPolymorphicAssociation
   9     #     AssociationCollection
  10     #       HasAndBelongsToManyAssociation
  11     #       HasManyAssociation
  12     #         HasManyThroughAssociation
  13     #            HasOneThroughAssociation
  14     #
  15     # Association proxies in Active Record are middlemen between the object that
  16     # holds the association, known as the <tt>@owner</tt>, and the actual associated
  17     # object, known as the <tt>@target</tt>. The kind of association any proxy is
  18     # about is available in <tt>@reflection</tt>. That's an instance of the class
  19     # ActiveRecord::Reflection::AssociationReflection.
  20     #
  21     # For example, given
  22     #
  23     #   class Blog < ActiveRecord::Base
  24     #     has_many :posts
  25     #   end
  26     #
  27     #   blog = Blog.find(:first)
  28     #
  29     # the association proxy in <tt>blog.posts</tt> has the object in +blog+ as
  30     # <tt>@owner</tt>, the collection of its posts as <tt>@target</tt>, and
  31     # the <tt>@reflection</tt> object represents a <tt>:has_many</tt> macro.
  32     #
  33     # This class has most of the basic instance methods removed, and delegates
  34     # unknown methods to <tt>@target</tt> via <tt>method_missing</tt>. As a
  35     # corner case, it even removes the +class+ method and that's why you get
  36     #
  37     #   blog.posts.class # => Array
  38     #
  39     # though the object behind <tt>blog.posts</tt> is not an Array, but an
  40     # ActiveRecord::Associations::HasManyAssociation.
  41     #
  42     # The <tt>@target</tt> object is not \loaded until needed. For example,
  43     #
  44     #   blog.posts.count
  45     #
  46     # is computed directly through SQL and does not trigger by itself the
  47     # instantiation of the actual post records.
  48     class AssociationProxy #:nodoc:
  49       alias_method :proxy_respond_to?, :respond_to?
  50       alias_method :proxy_extend, :extend
  51       delegate :to_param, :to => :proxy_target
  52       instance_methods.each { |m| undef_method m unless m =~ /(^__|^nil\?$|^send$|proxy_|^object_id$)/ }
  53
  54       def initialize(owner, reflection)
  55         @owner, @reflection = owner, reflection
  56         Array(reflection.options[:extend]).each { |ext| proxy_extend(ext) }
  57         reset
  58       end
  59
  60       # Returns the owner of the proxy.
  61       def proxy_owner
  62         @owner
  63       end
  64
  65       # Returns the reflection object that represents the association handled
  66       # by the proxy.
  67       def proxy_reflection
  68         @reflection
  69       end
  70
  71       # Returns the \target of the proxy, same as +target+.
  72       def proxy_target
  73         @target
  74       end
  75
  76       # Does the proxy or its \target respond to +symbol+?
  77       def respond_to?(*args)
  78         proxy_respond_to?(*args) || (load_target && @target.respond_to?(*args))
  79       end
  80
  81       # Forwards <tt>===</tt> explicitly to the \target because the instance method
  82       # removal above doesn't catch it. Loads the \target if needed.
  83       def ===(other)
  84         load_target
  85         other === @target
  86       end
  87
  88       # Returns the name of the table of the related class:
  89       #
  90       #   post.comments.aliased_table_name # => "comments"
  91       #
  92       def aliased_table_name
  93         @reflection.klass.table_name
  94       end
  95
  96       # Returns the SQL string that corresponds to the <tt>:conditions</tt>
  97       # option of the macro, if given, or +nil+ otherwise.
  98       def conditions
  99         @conditions ||= interpolate_sql(@reflection.sanitized_conditions) if @reflection.sanitized_conditions
 100       end
 101       alias :sql_conditions :conditions
 102
 103       # Resets the \loaded flag to +false+ and sets the \target to +nil+.
 104       def reset
 105         @loaded = false
 106         @target = nil
 107       end
 108
 109       # Reloads the \target and returns +self+ on success.
 110       def reload
 111         reset
 112         load_target
 113         self unless @target.nil?
 114       end
 115
 116       # Has the \target been already \loaded?
 117       def loaded?
 118         @loaded
 119       end
 120
 121       # Asserts the \target has been loaded setting the \loaded flag to +true+.
 122       def loaded
 123         @loaded = true
 124       end
 125
 126       # Returns the target of this proxy, same as +proxy_target+.
 127       def target
 128         @target
 129       end
 130
 131       # Sets the target of this proxy to <tt>\target</tt>, and the \loaded flag to +true+.
 132       def target=(target)
 133         @target = target
 134         loaded
 135       end
 136
 137       # Forwards the call to the target. Loads the \target if needed.
 138       def inspect
 139         load_target
 140         @target.inspect
 141       end
 142
 143       def send(method, *args)
 144         if proxy_respond_to?(method)
 145           super
 146         else
 147           load_target
 148           @target.send(method, *args)
 149         end
 150       end
 151
 152       protected
 153         # Does the association have a <tt>:dependent</tt> option?
 154         def dependent?
 155           @reflection.options[:dependent]
 156         end
 157
 158         # Returns a string with the IDs of +records+ joined with a comma, quoted
 159         # if needed. The result is ready to be inserted into a SQL IN clause.
 160         #
 161         #   quoted_record_ids(records) # => "23,56,58,67"
 162         #
 163         def quoted_record_ids(records)
 164           records.map { |record| record.quoted_id }.join(',')
 165         end
 166
 167         def interpolate_sql(sql, record = nil)
 168           @owner.send(:interpolate_sql, sql, record)
 169         end
 170
 171         # Forwards the call to the reflection class.
 172         def sanitize_sql(sql)
 173           @reflection.klass.send(:sanitize_sql, sql)
 174         end
 175
 176         # Assigns the ID of the owner to the corresponding foreign key in +record+.
 177         # If the association is polymorphic the type of the owner is also set.
 178         def set_belongs_to_association_for(record)
 179           if @reflection.options[:as]
 180             record["#{@reflection.options[:as]}_id"]   = @owner.id unless @owner.new_record?
 181             record["#{@reflection.options[:as]}_type"] = @owner.class.base_class.name.to_s
 182           else
 183             record[@reflection.primary_key_name] = @owner.id unless @owner.new_record?
 184           end
 185         end
 186
 187         # Merges into +options+ the ones coming from the reflection.
 188         def merge_options_from_reflection!(options)
 189           options.reverse_merge!(
 190             :group   => @reflection.options[:group],
 191             :limit   => @reflection.options[:limit],
 192             :offset  => @reflection.options[:offset],
 193             :joins   => @reflection.options[:joins],
 194             :include => @reflection.options[:include],
 195             :select  => @reflection.options[:select],
 196             :readonly  => @reflection.options[:readonly]
 197           )
 198         end
 199
 200         # Forwards +with_scope+ to the reflection.
 201         def with_scope(*args, &block)
 202           @reflection.klass.send :with_scope, *args, &block
 203         end
 204
 205       private
 206         # Forwards any missing method call to the \target.
 207         def method_missing(method, *args)
 208           if load_target
 209             raise NoMethodError unless @target.respond_to?(method)
 210
 211             if block_given?
 212               @target.send(method, *args)  { |*block_args| yield(*block_args) }
 213             else
 214               @target.send(method, *args)
 215             end
 216           end
 217         end
 218
 219         # Loads the \target if needed and returns it.
 220         #
 221         # This method is abstract in the sense that it relies on +find_target+,
 222         # which is expected to be provided by descendants.
 223         #
 224         # If the \target is already \loaded it is just returned. Thus, you can call
 225         # +load_target+ unconditionally to get the \target.
 226         #
 227         # ActiveRecord::RecordNotFound is rescued within the method, and it is
 228         # not reraised. The proxy is \reset and +nil+ is the return value.
 229         def load_target
 230           return nil unless defined?(@loaded)
 231
 232           if !loaded? and (!@owner.new_record? || foreign_key_present)
 233             @target = find_target
 234           end
 235
 236           @loaded = true
 237           @target
 238         rescue ActiveRecord::RecordNotFound
 239           reset
 240         end
 241
 242         # Can be overwritten by associations that might have the foreign key
 243         # available for an association without having the object itself (and
 244         # still being a new record). Currently, only +belongs_to+ presents
 245         # this scenario (both vanilla and polymorphic).
 246         def foreign_key_present
 247           false
 248         end
 249
 250         # Raises ActiveRecord::AssociationTypeMismatch unless +record+ is of
 251         # the kind of the class of the associated objects. Meant to be used as
 252         # a sanity check when you are about to assign an associated record.
 253         def raise_on_type_mismatch(record)
 254           unless record.is_a?(@reflection.klass) || record.is_a?(@reflection.class_name.constantize)
 255             message = "#{@reflection.class_name}(##{@reflection.klass.object_id}) expected, got #{record.class}(##{record.class.object_id})"
 256             raise ActiveRecord::AssociationTypeMismatch, message
 257           end
 258         end
 259
 260         # Array#flatten has problems with recursive arrays. Going one level
 261         # deeper solves the majority of the problems.
 262         def flatten_deeper(array)
 263           array.collect { |element| (element.respond_to?(:flatten) && !element.is_a?(Hash)) ? element.flatten : element }.flatten
 264         end
 265
 266         # Returns the ID of the owner, quoted if needed.
 267         def owner_quoted_id
 268           @owner.quoted_id
 269         end
 270     end
 271   end
 272 end