Module: Stannum::Entities::Associations

Included in:
Stannum::Entity
Defined in:
lib/stannum/entities/associations.rb

Overview

Methods for defining and accessing entity associations.

Defined Under Namespace

Modules: ClassMethods Classes: InvalidOptionError

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.apply(other) ⇒ Object

Generates Associations schema for the class.

Creates a new Stannum::Schema and sets it as the class’s :Associations constant. If the superclass is an entity class (and already defines its own Associations, includes the superclass Associations in the class Associations). Finally, includes the class Associations in the class.

Parameters:

  • other (Class) —

    the class to which attributes are added.



226
227
228
229
230
231
232
233
234
235
236
237
238
 
# File 'lib/stannum/entities/associations.rb', line 226

def apply(other)
  return unless other.is_a?(Class)

  return if entity_class?(other)

  other.const_set(:Associations, build_schema)

  if entity_class?(other.superclass)
    other::Associations.include(other.superclass::Associations)
  end

  other.include(other::Associations)
end

Instance Method Details

#assign_associations(associations) ⇒ Object

Updates the struct’s associations with the given values.

This method is used to update some (but not all) of the associations of the struct. For each key in the hash, it calls the corresponding writer method with the value for that association.

Any associations that are not in the given hash are unchanged, as are any properties that are not associations.

If the associations hash includes any keys that do not correspond to an association, the struct will raise an error.

Parameters:

  • associations (Hash) —

    The associations for the struct.

Raises:

  • ArgumentError if any key is not a valid association.

See Also:



287
288
289
290
291
292
293
 
# File 'lib/stannum/entities/associations.rb', line 287

def assign_associations(associations)
  unless associations.is_a?(Hash)
    raise ArgumentError, 'associations must be a Hash'
  end

  set_associations(associations, force: false)
end

#association_proxy_for(association) ⇒ Object 



296
297
298
299
 
# File 'lib/stannum/entities/associations.rb', line 296

def association_proxy_for(association)
  @association_proxies[association.name] ||=
    Stannum::Associations::Many::Proxy.new(association:, entity: self)
end

#associations ⇒ Hash<String, Object>

Collects the entity associations.

Returns:

  • (Hash<String, Object>) —

    the entity associations.



304
305
306
 
# File 'lib/stannum/entities/associations.rb', line 304

def associations
  @associations.dup
end

#associations=(associations) ⇒ Object

Replaces the entity’s associations with the given values.

This method is used to update all of the associations of the entity. For each association, the writer method is called with the value from the hash. Non-association properties are unchanged.

If the associations hash includes any keys that do not correspond to a valid association, the entity will raise an error.

Parameters:

  • associations (Hash) —

    the associations to assign to the entity.

Raises:

  • ArgumentError if any key is not a valid association.

See Also:

  • #assign_attributes


322
323
324
325
326
327
328
 
# File 'lib/stannum/entities/associations.rb', line 322

def associations=(associations)
  unless associations.is_a?(Hash)
    raise ArgumentError, 'associations must be a Hash'
  end

  set_associations(associations, force: true)
end

#initialize(**properties) ⇒ Object

Parameters:

  • properties (Hash) —

    the properties used to initialize the entity.



263
264
265
266
267
268
 
# File 'lib/stannum/entities/associations.rb', line 263

def initialize(**properties)
  @associations        = {}
  @association_proxies = {}

  super
end

#properties ⇒ Hash<String, Object>

Collects the entity properties.

Returns:

  • (Hash<String, Object>) —

    the entity properties.



331
332
333
 
# File 'lib/stannum/entities/associations.rb', line 331

def properties
  super.merge(associations)
end

#read_association(key, safe: true) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Retrieves the association value for the requested key.

If the :safe flag is set, will verify that the association name is valid (a non-empty String or Symbol) and that there is a defined association by that name. By default, :safe is set to true.

Parameters:

  • key (String, Symbol) —

    the key of the association to retrieve.

  • safe (Boolean) (defaults to: true) —

    if true, validates the association key.

Returns:

  • (Object) —

    the value of the requested association.



347
348
349
350
351
352
353
354
355
356
357
 
# File 'lib/stannum/entities/associations.rb', line 347

def read_association(key, safe: true)
  if safe
    tools.assertions.validate_name(key, as: 'association')

    unless self.class.associations.key?(key.to_s)
      raise ArgumentError, "unknown association #{key.inspect}"
    end
  end

  @associations[key.to_s]
end

#write_association(key, value, safe: true) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Assigns the association value for the requested key.

If the :safe flag is set, will verify that the association name is valid (a non-empty String or Symbol) and that there is a defined association by that name. By default, :safe is set to true.

Parameters:

  • key (String, Symbol) —

    the key of the association to assign.

  • value (Object) —

    the value to assign.

  • safe (Boolean) (defaults to: true) —

    if true, validates the association key.

Returns:

  • (Object) —

    the assigned value.



372
373
374
375
376
377
378
379
380
381
382
 
# File 'lib/stannum/entities/associations.rb', line 372

def write_association(key, value, safe: true)
  if safe
    tools.assertions.validate_name(key, as: 'association')

    unless self.class.associations.key?(key.to_s)
      raise ArgumentError, "unknown association #{key.inspect}"
    end
  end

  @associations[key.to_s] = value
end