123456789_123456789_123456789_123456789_123456789_

Class: ActiveRecord::Associations::Association

Do not use. This class is for internal use only.

Overview

This is the root class of all associations (‘+ Foo’ signifies an included module Foo):

Association
  SingularAssociation
    HasOneAssociation + ForeignAssociation
      HasOneThroughAssociation + ThroughAssociation
    BelongsToAssociation
      BelongsToPolymorphicAssociation
  CollectionAssociation
    HasManyAssociation + ForeignAssociation
      HasManyThroughAssociation + ThroughAssociation

::ActiveRecord::Associations in Active Record are middlemen between the object that holds the association, known as the #owner, and the associated result set, known as the #target. Association metadata is available in #reflection, which is an instance of ::ActiveRecord::Reflection::AssociationReflection.

For example, given

class Blog < ActiveRecord::Base
  has_many :posts
end

blog = Blog.first

The association of blog.posts has the object blog as its #owner, the collection of its posts as #target, and the #reflection object represents a :has_many macro.

Class Method Summary

Instance Attribute Summary

Instance Method Summary

Constructor Details

.new(owner, reflection) ⇒ Association

[ GitHub ]

  
# File 'activerecord/lib/active_record/associations/association.rb', line 41

def initialize(owner, reflection)
  reflection.check_validity!

  @owner, @reflection = owner, reflection
  @disable_joins = @reflection.options[:disable_joins] || false

  reset
  reset_scope

  @skip_strict_loading = nil
end

Instance Attribute Details

#collection?Boolean (readonly)

Whether the association represent a single record or a collection of records.

[ GitHub ]

  
# File 'activerecord/lib/active_record/associations/association.rb', line 237

def collection?
  false
end

#disable_joins (readonly)

[ GitHub ]

  
# File 'activerecord/lib/active_record/associations/association.rb', line 37

attr_reader :reflection, :disable_joins

#find_target?Boolean (readonly, private)

[ GitHub ]

  
# File 'activerecord/lib/active_record/associations/association.rb', line 320

def find_target?
  !loaded? && (!owner.new_record? || foreign_key_present?) && klass
end

#foreign_key_present?Boolean (readonly, private)

Returns true if there is a foreign key present on the owner which references the target. This is used to determine whether we can load the target if the owner is currently a new record (and therefore without a key). If the owner is a new record then foreign_key must be present in order to load target.

Currently implemented by belongs_to (vanilla and polymorphic) and has_one/has_many :through associations which go through a belongs_to.

[ GitHub ]

  
# File 'activerecord/lib/active_record/associations/association.rb', line 332

def foreign_key_present?
  false
end

#loaded?Boolean (readonly)

Has the target been already loaded?

[ GitHub ]

  
# File 'activerecord/lib/active_record/associations/association.rb', line 81

def loaded?
  @loaded
end

#options (readonly)

[ GitHub ]

  
# File 'activerecord/lib/active_record/associations/association.rb', line 39

delegate :options, to: :reflection

#owner (rw)

[ GitHub ]

  
# File 'activerecord/lib/active_record/associations/association.rb', line 36

attr_accessor :owner

#reflection (readonly)

[ GitHub ]

  
# File 'activerecord/lib/active_record/associations/association.rb', line 37

attr_reader :reflection, :disable_joins

#stale_target?Boolean (readonly)

The target is stale if the target no longer points to the record(s) that the relevant foreign_key(s) refers to. If stale, the association accessor method on the owner will reload the target. It’s up to subclasses to implement the stale_state method if relevant.

Note that if the target has not been loaded, it is not considered stale.

[ GitHub ]

  
# File 'activerecord/lib/active_record/associations/association.rb', line 97

def stale_target?
  loaded? && @stale_state != stale_state
end

#target (rw)

[ GitHub ]

  
# File 'activerecord/lib/active_record/associations/association.rb', line 53

def target
  if @target.is_a?(Promise)
    @target = @target.value
  end
  @target
end

#target=(target) (rw)

Sets the target of this association to \target, and the loaded flag to true.

[ GitHub ]

  
# File 'activerecord/lib/active_record/associations/association.rb', line 102

def target=(target)
  @target = target
  loaded!
end

#violates_strict_loading?Boolean (readonly, private)

[ GitHub ]

  
# File 'activerecord/lib/active_record/associations/association.rb', line 284

def violates_strict_loading?
  return if @skip_strict_loading

  return unless owner.validation_context.nil?

  return reflection.strict_loading? if reflection.options.key?(:strict_loading)

  owner.strict_loading? && !owner.strict_loading_n_plus_one_only?
end

Instance Method Details

#association_scope (private)

The scope for this association.

Note that the association_scope is merged into the target_scope only when the scope method is called. This is because at that point the call may be surrounded by scope.scoping { … } or unscoped { … } etc, which affects the scope which actually gets built.

[ GitHub ]

  
# File 'activerecord/lib/active_record/associations/association.rb', line 300

def association_scope
  if klass
    @association_scope ||= if disable_joins
      DisableJoinsAssociationScope.scope(self)
    else
      AssociationScope.scope(self)
    end
  end
end

#async_load_target

[ GitHub ]

  
# File 'activerecord/lib/active_record/associations/association.rb', line 198

def async_load_target # :nodoc:
  @target = find_target(async: true) if (@stale_state && stale_target?) || find_target?

  loaded! unless loaded?
  nil
end

#build_record(attributes) (private)

[ GitHub ]

  
# File 'activerecord/lib/active_record/associations/association.rb', line 383

def build_record(attributes)
  reflection.build_association(attributes) do |record|
    initialize_attributes(record, attributes)
    yield(record) if block_given?
  end
end

#create(attributes = nil, &block)

[ GitHub ]

  
# File 'activerecord/lib/active_record/associations/association.rb', line 227

def create(attributes = nil, &block)
  _create_record(attributes, &block)
end

#create!(attributes = nil, &block)

[ GitHub ]

  
# File 'activerecord/lib/active_record/associations/association.rb', line 231

def create!(attributes = nil, &block)
  _create_record(attributes, true, &block)
end

#enqueue_destroy_association(options) (private)

[ GitHub ]

  
# File 'activerecord/lib/active_record/associations/association.rb', line 398

def enqueue_destroy_association(options)
  job_class = owner.class.destroy_association_async_job

  if job_class
    owner._after_commit_jobs.push([job_class, options])
  end
end

#ensure_klass_exists! (private)

Reader and writer methods call this so that consistent errors are presented when the association target class does not exist.

[ GitHub ]

  
# File 'activerecord/lib/active_record/associations/association.rb', line 244

def ensure_klass_exists!
  klass
end

#extensions

[ GitHub ]

  
# File 'activerecord/lib/active_record/associations/association.rb', line 169

def extensions
  extensions = klass.default_extensions | reflection.extensions

  if reflection.scope
    extensions |= reflection.scope_for(klass.unscoped, owner).extensions
  end

  extensions
end

#find_target(async: false) (readonly, private)

[ GitHub ]

  
# File 'activerecord/lib/active_record/associations/association.rb', line 248

def find_target(async: false)
  if violates_strict_loading?
    Base.strict_loading_violation!(owner: owner.class, reflection: reflection)
  end

  scope = self.scope
  if skip_statement_cache?(scope)
    if async
      return scope.load_async.then(&:to_a)
    else
      return scope.to_a
    end
  end

  sc = reflection.association_scope_cache(klass, owner) do |params|
    as = AssociationScope.create { params.bind }
    target_scope.merge!(as.scope(self))
  end

  binds = AssociationScope.get_bind_values(owner, reflection.chain)
  klass.with_connection do |c|
    sc.execute(binds, c, async: async) do |record|
      set_inverse_instance(record)
      set_strict_loading(record)
    end
  end
end

#foreign_key_for?(record) ⇒ Boolean (private)

Returns true if record contains the foreign_key

[ GitHub ]

  
# File 'activerecord/lib/active_record/associations/association.rb', line 370

def foreign_key_for?(record)
  foreign_key = Array(reflection.foreign_key)
  foreign_key.all? { |key| record._has_attribute?(key) }
end

#initialize_attributes(record, except_from_scope_attributes = nil)

[ GitHub ]

  
# File 'activerecord/lib/active_record/associations/association.rb', line 217

def initialize_attributes(record, except_from_scope_attributes = nil) # :nodoc:
  except_from_scope_attributes ||= {}
  skip_assign = [reflection.foreign_key, reflection.type].compact
  assigned_keys = record.changed_attribute_names_to_save
  assigned_keys += except_from_scope_attributes.keys.map(&:to_s)
  attributes = scope_for_create.except!(*(assigned_keys - skip_assign))
  record.send(:_assign_attributes, attributes) if attributes.any?
  set_inverse_instance(record)
end

#inversable?(record) ⇒ Boolean (private)

[ GitHub ]

  
# File 'activerecord/lib/active_record/associations/association.rb', line 406

def inversable?(record)
  record &&
    ((!record.persisted? || !owner.persisted?) || matches_foreign_key?(record))
end

#inverse_association_for(record) (private)

[ GitHub ]

  
# File 'activerecord/lib/active_record/associations/association.rb', line 350

def inverse_association_for(record)
  if invertible_for?(record)
    record.association(inverse_reflection_for(record).name)
  end
end

#inverse_reflection_for(record) (private)

Can be redefined by subclasses, notably polymorphic belongs_to The record parameter is necessary to support polymorphic inverses as we must check for the association in the specific class of the record.

[ GitHub ]

  
# File 'activerecord/lib/active_record/associations/association.rb', line 359

def inverse_reflection_for(record)
  reflection.inverse_of
end

#inversed_from(record)

[ GitHub ]

  
# File 'activerecord/lib/active_record/associations/association.rb', line 153

def inversed_from(record)
  self.target = record
end

#inversed_from_queries(record)

[ GitHub ]

  
# File 'activerecord/lib/active_record/associations/association.rb', line 157

def inversed_from_queries(record)
  if inversable?(record)
    self.target = record
  end
end

#invertible_for?(record) ⇒ Boolean (private)

Returns true if inverse association on the given record needs to be set. This method is redefined by subclasses.

[ GitHub ]

  
# File 'activerecord/lib/active_record/associations/association.rb', line 365

def invertible_for?(record)
  foreign_key_for?(record) && inverse_reflection_for(record)
end

#klass

Returns the class of the target. belongs_to polymorphic overrides this to look at the polymorphic_type field on the owner.

[ GitHub ]

  
# File 'activerecord/lib/active_record/associations/association.rb', line 165

def klass
  reflection.klass
end

#load_target

Loads the target if needed and returns it.

This method is abstract in the sense that it relies on #find_target, which is expected to be provided by descendants.

If the target is already loaded it is just returned. Thus, you can call load_target unconditionally to get the target.

::ActiveRecord::RecordNotFound is rescued within the method, and it is not reraised. The proxy is reset and nil is the return value.

[ GitHub ]

  
# File 'activerecord/lib/active_record/associations/association.rb', line 189

def load_target
  @target = find_target(async: false) if (@stale_state && stale_target?) || find_target?

  loaded! unless loaded?
  target
rescue ActiveRecord::RecordNotFound
  reset
end

#loaded!

Asserts the target has been loaded setting the loaded flag to true.

[ GitHub ]

  
# File 'activerecord/lib/active_record/associations/association.rb', line 86

def loaded!
  @loaded = true
  @stale_state = stale_state
end

#marshal_dump

We can’t dump @reflection and @through_reflection since it contains the scope proc

[ GitHub ]

  
# File 'activerecord/lib/active_record/associations/association.rb', line 206

def marshal_dump
  ivars = (instance_variables - [:@reflection, :@through_reflection]).map { |name| [name, instance_variable_get(name)] }
  [@reflection.name, ivars]
end

#marshal_load(data)

[ GitHub ]

  
# File 'activerecord/lib/active_record/associations/association.rb', line 211

def marshal_load(data)
  reflection_name, ivars = data
  ivars.each { |name, val| instance_variable_set(name, val) }
  @reflection = @owner.class._reflect_on_association(reflection_name)
end

#matches_foreign_key?(record) ⇒ Boolean (private)

[ GitHub ]

  
# File 'activerecord/lib/active_record/associations/association.rb', line 411

def matches_foreign_key?(record)
  if foreign_key_for?(record)
    record.read_attribute(reflection.foreign_key) == owner.id ||
      (foreign_key_for?(owner) && owner.read_attribute(reflection.foreign_key) == record.id)
  else
    owner.read_attribute(reflection.foreign_key) == record.id
  end
end

#raise_on_type_mismatch!(record) (private)

Raises ::ActiveRecord::AssociationTypeMismatch unless record is of the kind of the class of the associated objects. Meant to be used as a safety check when you are about to assign an associated record.

[ GitHub ]

  
# File 'activerecord/lib/active_record/associations/association.rb', line 339

def raise_on_type_mismatch!(record)
  unless record.is_a?(reflection.klass)
    fresh_class = reflection.class_name.safe_constantize
    unless fresh_class && record.is_a?(fresh_class)
      message = "#{reflection.class_name}(##{reflection.klass.object_id}) expected, "\
        "got #{record.inspect} which is an instance of #{record.class}(##{record.class.object_id})"
      raise ActiveRecord::AssociationTypeMismatch, message
    end
  end
end

#reload(force = false)

Reloads the target and returns self on success. The QueryCache is cleared if force is true.

[ GitHub ]

  
# File 'activerecord/lib/active_record/associations/association.rb', line 72

def reload(force = false)
  klass.connection_pool.clear_query_cache if force && klass
  reset
  reset_scope
  load_target
  self unless target.nil?
end

#remove_inverse_instance(record)

Remove the inverse association, if possible

[ GitHub ]

  
# File 'activerecord/lib/active_record/associations/association.rb', line 147

def remove_inverse_instance(record)
  if inverse = inverse_association_for(record)
    inverse.inversed_from(nil)
  end
end

#reset

Resets the loaded flag to false and sets the target to nil.

[ GitHub ]

  
# File 'activerecord/lib/active_record/associations/association.rb', line 61

def reset
  @loaded = false
  @stale_state = nil
end

#reset_negative_cache

[ GitHub ]

  
# File 'activerecord/lib/active_record/associations/association.rb', line 66

def reset_negative_cache # :nodoc:
  reset if loaded? && target.nil?
end

#reset_scope

[ GitHub ]

  
# File 'activerecord/lib/active_record/associations/association.rb', line 119

def reset_scope
  @association_scope = nil
end

#scope

[ GitHub ]

  
# File 'activerecord/lib/active_record/associations/association.rb', line 107

def scope
  if disable_joins
    DisableJoinsAssociationScope.create.scope(self)
  elsif (scope = klass.current_scope) && scope.try(:proxy_association) == self
    scope.spawn
  elsif scope = klass.global_current_scope
    target_scope.merge!(association_scope).merge!(scope)
  else
    target_scope.merge!(association_scope)
  end
end

#scope_for_create (private)

[ GitHub ]

  
# File 'activerecord/lib/active_record/associations/association.rb', line 316

def scope_for_create
  scope.scope_for_create
end

#set_inverse_instance(record)

Set the inverse association, if possible

[ GitHub ]

  
# File 'activerecord/lib/active_record/associations/association.rb', line 132

def set_inverse_instance(record)
  if inverse = inverse_association_for(record)
    inverse.inversed_from(owner)
  end
  record
end

#set_inverse_instance_from_queries(record)

[ GitHub ]

  
# File 'activerecord/lib/active_record/associations/association.rb', line 139

def set_inverse_instance_from_queries(record)
  if inverse = inverse_association_for(record)
    inverse.inversed_from_queries(owner)
  end
  record
end

#set_strict_loading(record)

[ GitHub ]

  
# File 'activerecord/lib/active_record/associations/association.rb', line 123

def set_strict_loading(record)
  if owner.strict_loading_n_plus_one_only? && reflection.macro == :has_many
    record.strict_loading!
  else
    record.strict_loading!(false, mode: owner.strict_loading_mode)
  end
end

#skip_statement_cache?(scope) ⇒ Boolean (private)

Returns true if statement cache should be skipped on the association reader.

[ GitHub ]

  
# File 'activerecord/lib/active_record/associations/association.rb', line 391

def skip_statement_cache?(scope)
  reflection.has_scope? ||
    scope.eager_loading? ||
    klass.scope_attributes? ||
    reflection.source_reflection.active_record.default_scopes.any?
end

#skip_strict_loading(&block) (private)

[ GitHub ]

  
# File 'activerecord/lib/active_record/associations/association.rb', line 276

def skip_strict_loading(&block)
  skip_strict_loading_was = @skip_strict_loading
  @skip_strict_loading = true
  yield
ensure
  @skip_strict_loading = skip_strict_loading_was
end

#stale_state (private)

This should be implemented to return the values of the relevant key(s) on the owner, so that when stale_state is different from the value stored on the last find_target, the target is stale.

This is only relevant to certain associations, which is why it returns nil by default.

[ GitHub ]

  
# File 'activerecord/lib/active_record/associations/association.rb', line 380

def stale_state
end

#target_scope (private)

Can be overridden (i.e. in ThroughAssociation) to merge in other scopes (i.e. the through association’s scope)

[ GitHub ]

  
# File 'activerecord/lib/active_record/associations/association.rb', line 312

def target_scope
  AssociationRelation.create(klass, self).merge!(klass.scope_for_association)
end