Module: DataMapper::Resource

Included Modules

DataMapper::Serialize, DataMapper::Timestamp, DataMapper::Types

Attributes

Instance Attributes

collection [RW] public

+————— Instance methods.

Public Visibility

Public Class Method Summary

descendants

Return all classes that include the DataMapper::Resource module.

descendents

For backward compatibility.

included(model)

When Resource is included in a class this method makes sure it gets all the methods.

Public Instance Method Summary

#attribute_dirty?(name)

Checks if the attribute is dirty.

#attribute_get(name)

returns the value of the attribute.

#attribute_loaded?(name)

Checks if the attribute has been loaded.

#attribute_set(name, value)

sets the value of the attribute and marks the attribute as dirty if it has been changed so that it may be saved.

#attributes=(values_hash)

Mass assign of attributes.

#child_associations
#destroy

destroy the instance, remove it from the repository.

#dirty?

Checks if the class is dirty.

#dirty_attributes

set of attributes that have been marked dirty.

#eql?(other)

Compares if its the same object or if attributes are equal.

#id

default id method to return the resource id when there is a single key, and the model was defined with a primary key named something other than id.

#inspect

Inspection of the class name and the attributes.

#key

FIXME: should this take a repository_name argument.

#loaded_attributes

fetches all the names of the attributes that have been loaded, even if they are lazy but have been called.

#new_record?

Checks if the model has been saved.

#parent_associations
#pretty_print(pp)

TODO docs.

#readonly!
#readonly?
#reload

Reload association and all child association.

#reload_attributes(*attributes)

Relad all the attributes.

#repository

Returns

<Repository>:the respository this resource belongs to in the context of a collection OR in the class’s context.
#save

save the instance to the data-store.

#shadow_attribute_get(name)
#transaction(&block)

Produce a new Transaction for the class of this Resource.

#update_attributes(hash, *update_only)

Updates attributes and saves model.

Public Instance Methods Included from DataMapper::Serialize

to_csv, to_json, to_xml, to_yaml

Public Class Method Details

descendants

public descendants

Return all classes that include the DataMapper::Resource module

Returns

Set:a set containing the including classes

Example

  Class Foo
    include DataMapper::Resource
  end

  DataMapper.Resource.decendents[1].type == Foo
[View source] 


42
43
44
45
46
# File 'dm-core/lib/dm-core/resource.rb', line 42

def self.descendants


  @@descendants
end

descendents

public descendents

For backward compatibility

[View source] 


46
47
48
49
50
# File 'dm-core/lib/dm-core/resource.rb', line 46

def self.descendents


  self.descendants
end

included

public included(model)

When Resource is included in a class this method makes sure it gets all the methods

[View source] 


22
23
24
25
# File 'dm-core/lib/dm-core/resource.rb', line 22

def self.included(model)
  model.extend ClassMethods
  @@descendants << model
end

Public Instance Method Details

attribute_dirty?

public attribute_dirty?(name)

Checks if the attribute is dirty

Parameters

name<Symbol>:name of attribute

Returns

True:returns if attribute is dirty

—

[View source] 


359
360
361
362
# File 'dm-core/lib/dm-core/resource.rb', line 359

def attribute_dirty?(name)
  property = self.class.properties(repository.name)[name]
  dirty_attributes.include?(property)
end

attribute_get

public attribute_get(name)

returns the value of the attribute. Do not read from instance variables directly, but use this method. This method handels the lazy loading the attribute and returning of defaults if nessesary.

Parameters

name<Symbol>:name attribute to lookup

Returns

<Types>:the value stored at that given attribute, nil if none, and default if necessary

Example

  Class Foo
    include DataMapper::Resource

    property :first_name, String
    property :last_name, String

    def full_name
      "#{attribute_get(:first_name)} #{attribute_get(:last_name)}"
    end

    def name_for_address_book
      "#{last_name}, #{first_name}"
    end
  end
[View source] 


85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
# File 'dm-core/lib/dm-core/resource.rb', line 85

def attribute_get(name)
  property  = self.class.properties(repository.name)[name]
  ivar_name = property.instance_variable_name

  unless new_record? || instance_variable_defined?(ivar_name)



    property.lazy? ? lazy_load(name) : lazy_load(self.class.properties(repository.name).reject {|p| instance_variable_defined?(p.instance_variable_name) || p.lazy? })
  end

  value = instance_variable_get(ivar_name)

  if value.nil? && new_record? && !property.options[:default].nil?



    value = property.default_for(self)
  end

  property.custom? ? property.type.load(value, property) : value
end

attribute_loaded?

public attribute_loaded?(name)

Checks if the attribute has been loaded

Example

  class Foo
    include DataMapper::Resource
    property :name, String
    property :description, Text, :lazy => false
  end

  Foo.new.attribute_loaded?(:description) # will return false

—

[View source] 


296
297
298
299
# File 'dm-core/lib/dm-core/resource.rb', line 296

def attribute_loaded?(name)
  property = self.class.properties(repository.name)[name]
  instance_variable_defined?(property.instance_variable_name)
end

attribute_set

public attribute_set(name, value)

sets the value of the attribute and marks the attribute as dirty if it has been changed so that it may be saved. Do not set from instance variables directly, but use this method. This method handels the lazy loading the property and returning of defaults if nessesary.

Parameters

name<Symbol>:name attribute to set
value<Type>:value to store at that location

Returns

<Types>:the value stored at that given attribute, nil if none, and default if necessary

Example

  Class Foo
    include DataMapper::Resource

    property :first_name, String
    property :last_name, String

    def full_name(name)
      name = name.split(' ')
      attribute_set(:first_name, name[0])
      attribute_set(:last_name, name[1])
    end

    def name_from_address_book(name)
      name = name.split(', ')
      first_name = name[1]
      last_name = name[0]
    end
  end
[View source] 


139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
# File 'dm-core/lib/dm-core/resource.rb', line 139

def attribute_set(name, value)
  property  = self.class.properties(repository.name)[name]
  ivar_name = property.instance_variable_name

  old_value = instance_variable_get(ivar_name)
  new_value = property.custom? ? property.type.dump(value, property) : property.typecast(value)

  # skip setting the attribute if the new value equals the old
  # value, or if the new value is nil, and the property does not
  # allow nil values
  return if new_value == old_value || (new_value.nil? && !property.nullable?)

  if property.lock?



    instance_variable_set("@shadow_#{name}", old_value)
  end

  dirty_attributes << property

  instance_variable_set(ivar_name, new_value)
end

attributes

public attributes=(values_hash)

Mass assign of attributes

Parameters

value_hash <Hash[<Symbol>]>::

—

[View source] 


434
435
436
437
438
439
440
441
442
443
444
445
446
# File 'dm-core/lib/dm-core/resource.rb', line 434

def attributes=(values_hash)
  values_hash.each_pair do |k,v|
    setter = "#{k.to_s.sub(/\?\z/, '')}="
    # We check #public_methods and not Class#public_method_defined? to
    # account for singleton methods.
    if public_methods.include?(setter)



      send(setter, v)
    end
  end
end

child_associations

public child_associations
[View source] 


218
219
220
221
222
# File 'dm-core/lib/dm-core/resource.rb', line 218

def child_associations


  @child_associations ||= []
end

destroy

public destroy

destroy the instance, remove it from the repository

Returns

<True, False>:results of the destruction

—

[View source] 


278
279
280
281
282
# File 'dm-core/lib/dm-core/resource.rb', line 278

def destroy


  repository.destroy(self)
end

dirty?

public dirty?

Checks if the class is dirty

Returns

True:returns if class is dirty

—

[View source] 


345
346
347
348
349
# File 'dm-core/lib/dm-core/resource.rb', line 345

def dirty?


  dirty_attributes.any?
end

dirty_attributes

public dirty_attributes

set of attributes that have been marked dirty

Returns

Set:attributes that have been marked dirty

—

[View source] 


334
335
336
337
338
# File 'dm-core/lib/dm-core/resource.rb', line 334

def dirty_attributes


  @dirty_attributes ||= Set.new
end

eql?

public eql?(other)

Compares if its the same object or if attributes are equal

Parameters

other<Object>:Object to compare to

Returns

<True>:the outcome of the comparison as a boolean
[View source] 


170
171
172
173
174
# File 'dm-core/lib/dm-core/resource.rb', line 170

def eql?(other)
  return true if object_id == other.object_id
  return false unless self.class === other
  attributes == other.attributes
end

id

public id

default id method to return the resource id when there is a single key, and the model was defined with a primary key named something other than id

Returns

<Array[Key], Key> key or keys

—

[View source] 


235
236
237
238
239
240
# File 'dm-core/lib/dm-core/resource.rb', line 235

def id


  key = self.key
  key.first if key.size == 1
end

inspect

public inspect

Inspection of the class name and the attributes

Returns

<String>:with the class name, attributes with their values

Example

>> Foo.new

> #<Foo name=nil updated_at=nil created_at=nil id=nil>

[View source] 


190
191
192
193
194
195
# File 'dm-core/lib/dm-core/resource.rb', line 190

def inspect


  attrs = attributes.inject([]) {|s,(k,v)| s << "#{k}=#{v.inspect}"}
  "#<#{self.class.name} #{attrs.join(" ")}>"
end

key

public key

FIXME: should this take a repository_name argument

[View source] 


241
242
243
244
245
246
247
248
249
250
# File 'dm-core/lib/dm-core/resource.rb', line 241

def key


  key = []
  self.class.key(repository.name).each do |property|
    value = instance_variable_get(property.instance_variable_name)
    key << value
  end
  key
end

loaded_attributes

public loaded_attributes

fetches all the names of the attributes that have been loaded, even if they are lazy but have been called

Returns

Array[<Symbol>]:names of attributes that have been loaded

Example

  class Foo
    include DataMapper::Resource
    property :name, String
    property :description, Text, :lazy => false
  end

  Foo.new.loaded_attributes # returns [:name]

—

[View source] 


319
320
321
322
323
324
325
326
327
# File 'dm-core/lib/dm-core/resource.rb', line 319

def loaded_attributes


  names = []
  self.class.properties(repository.name).each do |property|
    names << property.name if instance_variable_defined?(property.instance_variable_name)
  end
  names
end

new_record?

public new_record?

Checks if the model has been saved

Returns

True:status if the model is new

—

[View source] 


404
405
406
407
408
# File 'dm-core/lib/dm-core/resource.rb', line 404

def new_record?


  !defined?(@new_record) || @new_record
end

parent_associations

public parent_associations
[View source] 


222
223
224
225
226
# File 'dm-core/lib/dm-core/resource.rb', line 222

def parent_associations


  @parent_associations ||= []
end

pretty_print

public pretty_print(pp)

TODO docs

[View source] 


196
197
198
199
200
201
202
203
204
205
206
# File 'dm-core/lib/dm-core/resource.rb', line 196

def pretty_print(pp)
  attrs = attributes.inject([]) {|s,(k,v)| s << [k,v]}
  pp.group(1, "#<#{self.class.name}", ">") do
    pp.breakable
    pp.seplist(attrs) do |k_v|
      pp.text k_v[0].to_s
      pp.text " = "
      pp.pp k_v[1]
    end
  end
end

readonly!

public readonly!
[View source] 


250
251
252
253
254
# File 'dm-core/lib/dm-core/resource.rb', line 250

def readonly!


  @readonly = true
end

readonly?

public readonly?
[View source] 


254
255
256
257
258
# File 'dm-core/lib/dm-core/resource.rb', line 254

def readonly?


  @readonly == true
end

reload

public reload

Reload association and all child association

Returns

self:returns the class itself

—

[View source] 


375
376
377
378
379
380
381
# File 'dm-core/lib/dm-core/resource.rb', line 375

def reload


  @collection.reload(:fields => loaded_attributes)
  (parent_associations + child_associations).each { |association| association.reload! }
  self
end

reload_attributes

public reload_attributes(*attributes)

Relad all the attributes

Parameters

*attributes<Array[<Symbol>]>:name of attribute

Returns

self:returns the class itself

—

[View source] 


392
393
394
395
# File 'dm-core/lib/dm-core/resource.rb', line 392

def reload_attributes(*attributes)
  @collection.reload(:fields => attributes)
  self
end

repository

public repository

Returns

<Repository>:the respository this resource belongs to in the context of a collection OR in the class’s context
[View source] 


214
215
216
217
218
# File 'dm-core/lib/dm-core/resource.rb', line 214

def repository


  @collection ? @collection.repository : self.class.repository
end

save

public save

save the instance to the data-store

Returns

<True, False>:results of the save

Meta Tags

See Also:

DataMapper::Repository#save --
[View source] 


267
268
269
270
271
# File 'dm-core/lib/dm-core/resource.rb', line 267

def save


  new_record? ? create : update
end

shadow_attribute_get

public shadow_attribute_get(name)
[View source] 


364
365
366
# File 'dm-core/lib/dm-core/resource.rb', line 364

def shadow_attribute_get(name)
  instance_variable_get("@shadow_#{name}")
end

transaction

public transaction(&block)

Produce a new Transaction for the class of this Resource

Returns

<DataMapper::Adapters::Transaction>:a new DataMapper::Adapters::Transaction with all DataMapper::Repositories of the class of this DataMapper::Resource added.

Meta Tags

[View source] 


473
474
475
# File 'dm-core/lib/dm-core/resource.rb', line 473

def transaction(&block)
  self.class.transaction(&block)
end

update_attributes

public update_attributes(hash, *update_only)

Updates attributes and saves model

Parameters

attributes<Hash> Attributes to be updated keys<Symbol, String, Array> keys of Hash to update (others won’t be updated)

Returns

<TrueClass, FalseClass> if model got saved or not

Meta Tags

[View source] 


456
457
458
459
460
461
# File 'dm-core/lib/dm-core/resource.rb', line 456

def update_attributes(hash, *update_only)
  raise 'Update takes a hash as first parameter' unless hash.is_a?(Hash)
  loop_thru = update_only.empty? ? hash.keys : update_only
  loop_thru.each {|attr|  send("#{attr}=", hash[attr])}
  save
end

Protected Visibility

Protected Instance Methods Included from DataMapper::Serialize

to_xml_document, xml_element_name