Class: ActiveRecord::Associations::Association
- Inherits:
-
Object
- Object
- ActiveRecord::Associations::Association
- Defined in:
- lib/active_record/associations/association.rb
Overview
Active Record Associations
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
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.
Direct Known Subclasses
Instance Attribute Summary collapse
-
#owner ⇒ Object
readonly
:nodoc:.
-
#reflection ⇒ Object
readonly
:nodoc:.
-
#target ⇒ Object
:nodoc:.
Instance Method Summary collapse
- #create(attributes = {}, &block) ⇒ Object
- #create!(attributes = {}, &block) ⇒ Object
- #extensions ⇒ Object
-
#initialize(owner, reflection) ⇒ Association
constructor
A new instance of Association.
-
#initialize_attributes(record, except_from_scope_attributes = nil) ⇒ Object
:nodoc:.
- #inversed_from(record) ⇒ Object (also: #inversed_from_queries)
-
#klass ⇒ Object
Returns the class of the target.
-
#load_target ⇒ Object
Loads the target if needed and returns it.
-
#loaded! ⇒ Object
Asserts the target has been loaded setting the loaded flag to
true
. -
#loaded? ⇒ Boolean
Has the target been already loaded?.
-
#marshal_dump ⇒ Object
We can’t dump @reflection and @through_reflection since it contains the scope proc.
- #marshal_load(data) ⇒ Object
-
#reload(force = false) ⇒ Object
Reloads the target and returns
self
on success. -
#remove_inverse_instance(record) ⇒ Object
Remove the inverse association, if possible.
-
#reset ⇒ Object
Resets the loaded flag to
false
and sets the target tonil
. - #reset_scope ⇒ Object
- #scope ⇒ Object
- #scoping(relation, &block) ⇒ Object
-
#set_inverse_instance(record) ⇒ Object
Set the inverse association, if possible.
- #set_inverse_instance_from_queries(record) ⇒ Object
-
#stale_target? ⇒ Boolean
The target is stale if the target no longer points to the record(s) that the relevant foreign_key(s) refers to.
Constructor Details
#initialize(owner, reflection) ⇒ Association
Returns a new instance of Association.
42 43 44 45 46 47 48 49 50 |
# File 'lib/active_record/associations/association.rb', line 42 def initialize(owner, reflection) reflection.check_validity! @owner, @reflection = owner, reflection @_scope = nil reset reset_scope end |
Instance Attribute Details
#owner ⇒ Object (readonly)
:nodoc:
38 39 40 |
# File 'lib/active_record/associations/association.rb', line 38 def owner @owner end |
#reflection ⇒ Object (readonly)
:nodoc:
38 39 40 |
# File 'lib/active_record/associations/association.rb', line 38 def reflection @reflection end |
#target ⇒ Object
:nodoc:
38 39 40 |
# File 'lib/active_record/associations/association.rb', line 38 def target @target end |
Instance Method Details
#create(attributes = {}, &block) ⇒ Object
191 192 193 |
# File 'lib/active_record/associations/association.rb', line 191 def create(attributes = {}, &block) _create_record(attributes, &block) end |
#create!(attributes = {}, &block) ⇒ Object
195 196 197 |
# File 'lib/active_record/associations/association.rb', line 195 def create!(attributes = {}, &block) _create_record(attributes, true, &block) end |
#extensions ⇒ Object
140 141 142 143 144 145 146 147 148 |
# File 'lib/active_record/associations/association.rb', line 140 def extensions extensions = klass.default_extensions | reflection.extensions if reflection.scope extensions |= reflection.scope_for(klass.unscoped, owner).extensions end extensions end |
#initialize_attributes(record, except_from_scope_attributes = nil) ⇒ Object
:nodoc:
181 182 183 184 185 186 187 188 189 |
# File 'lib/active_record/associations/association.rb', line 181 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 |
#inversed_from(record) ⇒ Object Also known as: inversed_from_queries
128 129 130 131 |
# File 'lib/active_record/associations/association.rb', line 128 def inversed_from(record) self.target = record @inversed = !!record end |
#klass ⇒ Object
Returns the class of the target. belongs_to polymorphic overrides this to look at the polymorphic_type field on the owner.
136 137 138 |
# File 'lib/active_record/associations/association.rb', line 136 def klass reflection.klass end |
#load_target ⇒ Object
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.
160 161 162 163 164 165 166 167 |
# File 'lib/active_record/associations/association.rb', line 160 def load_target @target = find_target if (@stale_state && stale_target?) || find_target? loaded! unless loaded? target rescue ActiveRecord::RecordNotFound reset end |
#loaded! ⇒ Object
Asserts the target has been loaded setting the loaded flag to true
.
76 77 78 79 80 |
# File 'lib/active_record/associations/association.rb', line 76 def loaded! @loaded = true @stale_state = stale_state @inversed = false end |
#loaded? ⇒ Boolean
Has the target been already loaded?
71 72 73 |
# File 'lib/active_record/associations/association.rb', line 71 def loaded? @loaded end |
#marshal_dump ⇒ Object
We can’t dump @reflection and @through_reflection since it contains the scope proc
170 171 172 173 |
# File 'lib/active_record/associations/association.rb', line 170 def marshal_dump ivars = (instance_variables - [:@reflection, :@through_reflection]).map { |name| [name, instance_variable_get(name)] } [@reflection.name, ivars] end |
#marshal_load(data) ⇒ Object
175 176 177 178 179 |
# File 'lib/active_record/associations/association.rb', line 175 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 |
#reload(force = false) ⇒ Object
Reloads the target and returns self
on success. The QueryCache is cleared if force
is true.
62 63 64 65 66 67 68 |
# File 'lib/active_record/associations/association.rb', line 62 def reload(force = false) klass.connection.clear_query_cache if force && klass reset reset_scope load_target self unless target.nil? end |
#remove_inverse_instance(record) ⇒ Object
Remove the inverse association, if possible
122 123 124 125 126 |
# File 'lib/active_record/associations/association.rb', line 122 def remove_inverse_instance(record) if inverse = inverse_association_for(record) inverse.inversed_from(nil) end end |
#reset ⇒ Object
Resets the loaded flag to false
and sets the target to nil
.
53 54 55 56 57 58 |
# File 'lib/active_record/associations/association.rb', line 53 def reset @loaded = false @target = nil @stale_state = nil @inversed = false end |
#reset_scope ⇒ Object
102 103 104 |
# File 'lib/active_record/associations/association.rb', line 102 def reset_scope @association_scope = nil end |
#scope ⇒ Object
98 99 100 |
# File 'lib/active_record/associations/association.rb', line 98 def scope @_scope&.spawn || target_scope.merge!(association_scope) end |
#scoping(relation, &block) ⇒ Object
199 200 201 202 203 204 |
# File 'lib/active_record/associations/association.rb', line 199 def scoping(relation, &block) @_scope = relation relation.scoping(&block) ensure @_scope = nil end |
#set_inverse_instance(record) ⇒ Object
Set the inverse association, if possible
107 108 109 110 111 112 |
# File 'lib/active_record/associations/association.rb', line 107 def set_inverse_instance(record) if inverse = inverse_association_for(record) inverse.inversed_from(owner) end record end |
#set_inverse_instance_from_queries(record) ⇒ Object
114 115 116 117 118 119 |
# File 'lib/active_record/associations/association.rb', line 114 def set_inverse_instance_from_queries(record) if inverse = inverse_association_for(record) inverse.inversed_from_queries(owner) end record end |
#stale_target? ⇒ Boolean
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.
88 89 90 |
# File 'lib/active_record/associations/association.rb', line 88 def stale_target? !@inversed && loaded? && @stale_state != stale_state end |