Class: ActiveRecord::Associations::Association
Relationships & Source Files | |
Extension / Inclusion / Inheritance Descendants | |
Subclasses:
|
|
Inherits: | Object |
Defined in: | activerecord/lib/active_record/associations/association.rb |
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
- .new(owner, reflection) ⇒ Association constructor
Instance Attribute Summary
-
#collection? ⇒ Boolean
readonly
Whether the association represent a single record or a collection of records.
- #disable_joins readonly
-
#loaded? ⇒ Boolean
readonly
Has the target been already loaded?
- #options readonly
- #owner rw
- #reflection readonly
-
#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.
- #target rw
-
#target=(target)
rw
Sets the target of this association to
\target
, and the loaded flag totrue
. - #find_target? ⇒ Boolean readonly private
-
#foreign_key_present? ⇒ Boolean
readonly
private
Returns true if there is a foreign key present on the owner which references the target.
- #violates_strict_loading? ⇒ Boolean readonly private
Instance Method Summary
- #async_load_target
- #create(attributes = nil, &block)
- #create!(attributes = nil, &block)
- #extensions
- #initialize_attributes(record, except_from_scope_attributes = nil)
- #inversed_from(record)
- #inversed_from_queries(record)
-
#klass
Returns the class of the target.
-
#load_target
Loads the target if needed and returns it.
-
#loaded!
Asserts the target has been loaded setting the loaded flag to
true
. -
#marshal_dump
We can’t dump @reflection and @through_reflection since it contains the scope proc.
- #marshal_load(data)
-
#reload(force = false)
Reloads the target and returns
self
on success. -
#remove_inverse_instance(record)
Remove the inverse association, if possible.
-
#reset
Resets the loaded flag to
false
and sets the target tonil
. - #reset_negative_cache
- #reset_scope
- #scope
-
#set_inverse_instance(record)
Set the inverse association, if possible.
- #set_inverse_instance_from_queries(record)
- #set_strict_loading(record)
-
#association_scope
private
The scope for this association.
- #build_record(attributes) private
- #enqueue_destroy_association(options) private
-
#ensure_klass_exists!
private
Reader and writer methods call this so that consistent errors are presented when the association target class does not exist.
- #find_target(async: false) readonly private
-
#foreign_key_for?(record) ⇒ Boolean
private
Returns true if record contains the foreign_key.
- #inversable?(record) ⇒ Boolean private
- #inverse_association_for(record) private
-
#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.
-
#invertible_for?(record) ⇒ Boolean
private
Returns true if inverse association on the given record needs to be set.
- #matches_foreign_key?(record) ⇒ Boolean private
-
#raise_on_type_mismatch!(record)
private
Raises
::ActiveRecord::AssociationTypeMismatch
unlessrecord
is of the kind of the class of the associated objects. - #scope_for_create private
-
#skip_statement_cache?(scope) ⇒ Boolean
private
Returns true if statement cache should be skipped on the association reader.
- #skip_strict_loading(&block) private
-
#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.
-
#target_scope
private
Can be overridden (i.e. in
ThroughAssociation
) to merge in other scopes (i.e.
Constructor Details
.new(owner, reflection) ⇒ Association
# File 'activerecord/lib/active_record/associations/association.rb', line 41
def initialize(owner, reflection) reflection.check_validity! @owner, @reflection = owner, reflection @disable_joins = @reflection. [: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.
# 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.
# 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?
# 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 :, 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.
# 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
.
#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. .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.
# 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 ]#ensure_klass_exists! (private)
Reader and writer methods call this so that consistent errors are presented when the association target class does not exist.
# 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
# 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)
# 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.
# 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.
# 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.
# 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.
# 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
.
# 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
# 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)
# 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.
# 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) = "#{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, end end end
#reload(force = false)
Reloads the target and returns self
on success. The QueryCache is cleared if force
is true.
# 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
# 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
.
# File 'activerecord/lib/active_record/associations/association.rb', line 61
def reset @loaded = false @stale_state = nil end
#reset_negative_cache
[ GitHub ]#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
# 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.
# 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.
# 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)
# File 'activerecord/lib/active_record/associations/association.rb', line 312
def target_scope AssociationRelation.create(klass, self).merge!(klass.scope_for_association) end