Include this module to classes to make them managable by Og.

Contents
Methods
Included Modules
Public Class methods
included(base)

[ show source ]

    # File lib/og/model.rb, line 18
18:   def self.included(base)
19:     # If the after_enchant callback is defined, call it 
20:     # to allow for some customization. Have a look at cacheable
21:     # for an example.
22: 
23:     if base.respond_to?(:after_enchant)
24:       base.after_enchant(base)
25:     end
26:   end
Public Instance methods
assign(values, options = {})

Alias for #assign_attributes

assign_attributes(values, options = {})
This method is also aliased as assign

[ show source ]

     # File lib/og/model.rb, line 146
146:   def assign_attributes(values, options = {})
147:     AttributeUtils.populate_object(self, values, options)
148:     return self
149:   end
assign_attributes(values, options = {})

[ show source ]

     # File lib/og/model.rb, line 228
228:     def assign_attributes(values, options = {})
229:       AttributeUtils.populate_object(self.new, values, options)
230:     end
aupdate(*attrs)

Alias for #update_attributes

create(*args) {|obj| ...}

[ show source ]

     # File lib/og/model.rb, line 199
199:     def create(*args)
200:       obj = self.new(*args)
201:       yield(obj) if block_given?
202:       ogmanager.with_store do |s|
203:         s.save(obj)
204:       end
205:       return obj
206:     end
create_with(hash)

An alternative creation helper, does not call the initialize method when there are mandatory elements.

[ show source ]

     # File lib/og/model.rb, line 211
211:     def create_with(hash)
212:       obj = nil
213:       arity = self.method(:initialize).arity
214:       
215:       if arity > 0 || arity < -1
216:         obj = self.allocate
217:       else
218:         obj = self.new
219:       end
220:       
221:       obj.assign_with(hash)
222:       ogmanager.with_store do |s|
223:         s.save(obj)
224:       end
225:       return obj
226:     end
delete(cascade = true)

Delete this model instance from the store.

This method is also aliased as delete!

[ show source ]

     # File lib/og/model.rb, line 126
126:   def delete(cascade = true)
127:     self.class.ogmanager.with_store do |s|
128:       s.delete(self, self.class, cascade)
129:     end
130:   end
delete!(cascade = true)

Alias for #delete

force_save!(options = nil)

Force saving of the objects, even if the validations don’t pass.

[ show source ]

    # File lib/og/model.rb, line 41
41:   def force_save!(options = nil)
42:     self.class.ogmanager.with_store do |s|
43:       s.force_save!(self, options)
44:     end
45:   end
insert()

Insert the object in the store.

[ show source ]

    # File lib/og/model.rb, line 49
49:   def insert
50:     self.class.ogmanager.with_store do |s|
51:       s.insert(self)
52:     end
53:   end
instance_attribute_set(a, val)

Set attribute (like instance_variable_set)

Example

a = Article[oid] a.instance_attribute_set :accepted, true

[ show source ]

     # File lib/og/model.rb, line 110
110:   def instance_attribute_set(a, val)
111:     instance_variable_set "@#{a}", val
112:     update_attribute(a.to_sym)
113:   end
load(pk)

Load an instance of this Model class using the primary key. If the class defines a text key, this string key may optionally be used!

[ show source ]

     # File lib/og/model.rb, line 237
237:     def load(pk)
238:       # gmosx: leave the checks in this order (optimized)
239:       if pk.to_i == 0 and (key = ann(:self, :text_key)) 
240:         # A string is passed as pk, try to use it as a 
241:         # tesxt key too.
242:         send("find_by_#{key}", pk)
243:       else
244:         # A valid pk is always > 0
245:         ogmanager.with_store do |s|
246:           s.load(pk, self)
247:         end
248:       end
249:     end
og_quote(obj)

[ show source ]

     # File lib/og/model.rb, line 189
189:   def og_quote(obj)
190:     self.class.ogmanager.with_store do |s|
191:       s.quote(obj)
192:     end
193:   end
properties_to_hash()

Returns a symbol => value hash of the object’s properties.

[ show source ]

     # File lib/og/model.rb, line 155
155:   def properties_to_hash
156:     hash = {}
157:     for sym, prop in self.class.properties
158:       hash[sym] = instance_variable_get("@#{sym}")
159:     end
160:   end
reload()

Reload this model instance from the store.

This method is also aliased as reload!

[ show source ]

     # File lib/og/model.rb, line 117
117:   def reload
118:     self.class.ogmanager.with_store do |s|
119:       s.reload(self, self.pk)
120:     end
121:   end
reload!()

Alias for #reload

save(options = nil)

Persist the object.

This method is also aliased as save! validate_and_save

[ show source ]

    # File lib/og/model.rb, line 30
30:   def save(options = nil)
31:     self.class.ogmanager.with_store do |s|
32:       s.save(self, options)
33:     end
34:   end
save!(options = nil)

Alias for #save

save_building_collections(options = nil)

Save all building collections. Transparently called when saving an object, allows efficient object relationship setup. Example:

a = Article.new a.categories << c1 a.categories << c2 a.tags << t1 a.tags << t2 a.save

[ show source ]

     # File lib/og/model.rb, line 178
178:   def save_building_collections(options = nil)
179:     if @pending_building_collections
180:       for rel in self.class.relations
181:         next unless rel.class.ann(:self, :collection)
182:         collection = send(rel.name.to_s)
183:         collection.save_building_members
184:       end
185:       @pending_building_collections = false
186:     end
187:   end
saved?()

Is this object saved in the store?

This method is also aliased as serialized?

[ show source ]

     # File lib/og/model.rb, line 141
141:   def saved?
142:     not @oid.nil?
143:   end
serialized?()

Alias for #saved?

set_attribute(attrs = {})

Alias for #set_attributes

set_attributes(attrs = {})

Set attributes (update + save).

Examples

a = Article[oid] a.set_attributes :accepted => true, :update_time => Time.now a.set_attribute :accepted => true

This method is also aliased as set_attribute

[ show source ]

     # File lib/og/model.rb, line 95
 95:   def set_attributes(attrs = {})
 96:     for a, val in attrs
 97:       instance_variable_set "@#{a}", val  
 98:     end
 99:     update_attributes(*attrs.keys)
100:   end
supdate(set)

Alias for #update_by_sql

transaction(&block)

[ show source ]

     # File lib/og/model.rb, line 133
133:   def transaction(&block)
134:     self.class.ogmanager.with_store do |s|
135:       s.transaction(&block)
136:     end
137:   end
update(set, options = nil)

Update the representation of this class in the store.

[ show source ]

     # File lib/og/model.rb, line 256
256:     def update(set, options = nil)
257:       ogmanager.with_store do |s|
258:         s.update_by_sql(self, set, options)
259:       end
260:     end
update(options = nil)

Update an existing object in the store.

[ show source ]

    # File lib/og/model.rb, line 57
57:   def update(options = nil)
58:     self.class.ogmanager.with_store do |s|
59:       s.update(self, options)
60:     end
61:   end
update_attribute(*attrs)

Alias for #update_attributes

update_attributes(*attrs)
This method is also aliased as update_attribute aupdate update_properties update_property

[ show source ]

    # File lib/og/model.rb, line 63
63:   def update_attributes(*attrs)
64:     self.class.ogmanager.with_store do |s|
65:       s.update(self, :only => attrs)
66:     end
67:   end
update_by_sql(set)
This method is also aliased as update_sql supdate

[ show source ]

    # File lib/og/model.rb, line 74
74:   def update_by_sql(set)
75:     self.class.ogmanager.with_store do |s|
76:       s.update_by_sql(self, set)
77:     end
78:   end
update_properties(*attrs)

Alias for #update_attributes

update_property(*attrs)

Alias for #update_attributes

update_sql(set)

Alias for #update_by_sql

validate_and_save(options = nil)

Alias for #save

Query methods.
Public Instance methods
find(options = {}, &block)

Find a specific instance of this class according to the given conditions.

Unlike the lower level store.find method it accepts Strings and Arrays instead of an option hash.

Examples

User.find :condition => "name LIKE ‘g%’", :order => ‘name ASC’ User.find :where => "name LIKE ‘g%’", :order => ‘name ASC’ User.find :sql => "WHERE name LIKE ‘g%’ ORDER BY name ASC" User.find :condition => [ ‘name LIKE ?’, ‘g%’ ], :order => ‘name ASC’, :limit => 10 User.find "name LIKE ‘g%’" User.find "WHERE name LIKE ‘g%’ LIMIT 10" User.find [ ‘name LIKE ?’, ‘g%’ ]

[ show source ]

     # File lib/og/model.rb, line 280
280:     def find(options = {}, &block)
281:       options = resolve_non_hash_options(options)
282:       
283:       ez_resolve_options(options, &block) if block_given?
284:       
285:       if find_options = self.ann(:self, :find_options)
286:         options = find_options.dup.update(options)
287:       end
288: 
289:       options[:class] = self
290:       options.merge! schema_options
291: 
292:       ogmanager.with_store do |s|
293:         s.find(options)
294:       end
295:     end
find_one(options = {}, &block)

Find a single instance of this class.

[ show source ]

     # File lib/og/model.rb, line 300
300:     def find_one(options = {}, &block)
301:       options = resolve_non_hash_options(options)
302:       
303:       ez_resolve_options(options, &block) if block_given?
304:       
305:       if find_options = self.ann(:self, :find_options)
306:         options = find_options.dup.update(options)
307:       end
308: 
309:       options[:class] = self
310:       options.merge! schema_options
311: 
312:       ogmanager.with_store do |s|
313:         s.find_one(options)
314:       end
315:     end
query_by_example(example)

Query the database for an model that matches the example. The example is a hash populated with the property values to search for.

The provided property values are joined with AND to build the actual query.

Article.query_by_example :title => ‘IBM%’, :hits => 2 Article.find_with_properties :title => ‘IBM%’, :hits => 2

[ show source ]

     # File lib/og/model.rb, line 345
345:     def query_by_example(example)
346:       condition = []
347:       example.each do |k, v|
348:         next if v.nil?
349:         if v.is_a? String and v =~ /%/
350:           condition << "#{k} LIKE #{Og.quote(v)}"
351:         else
352:           condition << "#{k} = #{Og.quote(v)}"
353:         end
354:       end
355:       
356:       condition = condition.join(' AND ')
357: 
358:       options = { 
359:         :condition => condition, 
360:         :class => self,
361:       }
362:       
363:       options.merge! schema_options
364: 
365:       ogmanager.with_store do |s|
366:         s.find(options)
367:       end
368:     end
select(sql)

Select an object using an sql query.

[ show source ]

     # File lib/og/model.rb, line 321
321:     def select(sql)
322:       ogmanager.with_store do |s|
323:         s.select(sql, self)
324:       end
325:     end
select_one(sql)

Select one instance using an sql query.

[ show source ]

     # File lib/og/model.rb, line 329
329:     def select_one(sql)
330:       ogmanager.with_store do |s|
331:         s.select_one(sql, self)
332:       end
333:     end
Aggregations / Calculations
Public Instance methods
aggregate(term, options = {})

Perform a general aggregation/calculation.

[ show source ]

     # File lib/og/model.rb, line 376
376:     def aggregate(term, options = {})
377:       options[:class] = self
378:       ogmanager.with_store do |s|
379:         s.calculate(term, options)
380:       end
381:     end
average(avg, options = {})

Find the average of a property. Pass a :group option to return an aggregation.

[ show source ]

     # File lib/og/model.rb, line 412
412:     def average(avg, options = {})
413:       options[:field] = avg
414:       calculate("AVG(#{avg})", options)
415:     end
count(options = {})

Perform a count query.

[ show source ]

     # File lib/og/model.rb, line 386
386:     def count(options = {})
387:       options[:field] = '*'
388:       calculate('COUNT(*)', options).to_i
389:     end
maximum(max, options = {})

Find the maximum of a property. Pass a :group option to return an aggregation.

[ show source ]

     # File lib/og/model.rb, line 403
403:     def maximum(max, options = {})
404:       options[:field] = max
405:       calculate("MAX(#{max})", options)
406:     end
minimum(min, options = {})

Find the minimum of a property. Pass a :group option to return an aggregation.

[ show source ]

     # File lib/og/model.rb, line 394
394:     def minimum(min, options = {})
395:       options[:field] = min
396:       calculate("MIN(#{min})", options)
397:     end
summarize(sum, options = {})

Find the sum of a property. Pass a :group option to return an aggregation.

[ show source ]

     # File lib/og/model.rb, line 421
421:     def summarize(sum, options = {})
422:       options[:field] = sum
423:       calculate("SUM(#{sum})", options)
424:     end
Delete/Destroy methods.
Public Instance methods
delete(obj_or_pk, cascade = true)

Delete an instance of this Model class using the actual instance or the primary key.

[ show source ]

     # File lib/og/model.rb, line 432
432:     def delete(obj_or_pk, cascade = true)
433:       ogmanager.with_store do |s|
434:         s.delete(obj_or_pk, self, cascade)
435:       end
436:     end
delete_all()

Delete all objects of this Model class.

[ show source ]

     # File lib/og/model.rb, line 444
444:     def delete_all
445:       ogmanager.with_store do |s|
446:         s.delete_all(self)
447:       end
448:     end
destroy()

[ show source ]

     # File lib/og/model.rb, line 450
450:     def destroy
451:       ogmanager.with_store do |s|
452:         s.send(:destroy, self)
453:       end
454:     end
each_schema_child()

[ show source ]

     # File lib/og/model.rb, line 505
505:     def each_schema_child
506:       return
507:     end
escape(str)

[ show source ]

     # File lib/og/model.rb, line 456
456:     def escape(str)
457:       ogmanager.with_store do |s|
458:         s.escape(str)
459:       end
460:     end
ez_condition(options = {}, &block)

Returns a Condition for this object.

[ show source ]

     # File lib/og/model.rb, line 698
698:     def ez_condition(options = {}, &block)
699:       options[:table_name] ||= table()
700:       Caboose::EZ::Condition.new(options, &block)
701:     end
ez_resolve_options(options) {|*conditions| ...}

Resolve ez options, ie options provided using the Ruby query language.

[ show source ]

     # File lib/og/model.rb, line 679
679:     def ez_resolve_options(options, &block)
680:       klass = self.name.downcase.to_sym       
681:       # conditions on self first
682:       # conditions = [ez_condition(:outer => outer_mapping[klass], :inner => inner_mapping[klass])] 
683:       conditions = [ez_condition()]
684: 
685:       # options[:include].uniq.each do |assoc| 
686:       #   conditions << reflect_on_association(assoc).klass.ez_condition(:outer => outer_mapping[assoc], :inner => inner_mapping[assoc])
687:       # end
688:       
689:       yield *conditions
690:       
691:       condition = Caboose::EZ::Condition.new
692:       conditions.each { |c| condition << c }
693:       options[:condition] = condition.to_sql
694:     end
find_by_(match, args, &block)

[ show source ]

     # File lib/og/model.rb, line 628
628:     def find_by_(match, args, &block)
629:       finder(match, args, &block)
630:     end
find_or_create_by_(match, args) {|obj| ...}

[ show source ]

     # File lib/og/model.rb, line 632
632:     def find_or_create_by_(match, args, &block)
633:       obj = finder(match, args)
634:       
635:       unless obj
636:         attrs = match.captures.last.split('_and_')
637:         obj = self.create do |obj|
638:           attrs.zip(args).map do |name, value|
639:             obj.instance_variable_set "@#{name}", value
640:           end
641:         end
642:         yield(obj) if block_given?
643:       end
644:       
645:       return obj
646:     end
finder(match, args)

Helper method for dynamic finders. Finds the object dynamically parsed method name is after.

[ show source ]

     # File lib/og/model.rb, line 706
706:     def finder(match, args)
707:       finder = (match.captures.first == 'all_by' ? :find : :find_one)
708:       
709:       attrs = match.captures.last.split('_and_')
710:       
711:       options = (ann(:find_options) || {}).dup
712:       options = args.pop if args.last.is_a?(Hash)
713:       
714:       relations_map = {}
715:       relations.each {|r| relations_map[r.name.to_s] = r }
716: 
717:       ret = nil
718:       ogmanager.with_store do |store|
719:       
720:         condition = attrs.zip(args).map do |name, value|
721:           if relation = relations_map[name]
722:             field_name = relation.foreign_key
723:             value = value.send(relation.target_class.primary_key)
724:             value = store.quote(value)
725:               
726:           elsif name =~ /^(#{relations_map.keys.join('|')})_(.*)$/
727:             r = relations_map[$1]
728:             tc = r.target_class
729:             if tc.serializable_attributes.include?($2.to_sym)
730:               field_name = r.foreign_key
731:               value = "(SELECT #{tc.primary_key} FROM #{tc::OGTABLE} WHERE #{$2} = '#{value}')"
732:             end
733:           else
734:             anno = ann(name.to_sym)
735:             field_name = anno[:field] || anno[:name] || name.to_sym
736:             value = store.quote(value)
737:           end
738:           
739:           options["#{name}_op".to_sym] ||= 'IN' if value.is_a?(Array)
740:           
741:           %|#{field_name} #{options.delete("#{name}_op".to_sym) || '='} #{value}|
742:         end.join(' AND ')
743: 
744:         options.merge!(
745:           :class => self,
746:           :condition => condition
747:         )
748: 
749:         ret = store.send(finder, options)
750:       end
751:       
752:       return ret
753:     end
get_scope()

Get the scope.

[ show source ]

     # File lib/og/model.rb, line 593
593:     def get_scope
594:       Thread.current["#{self}_scope"]
595:     end
method_missing(sym, *args, &block)

Handles dynamic finders. Handles methods such as:

class User 

  attr_accessor :name, String
  attr_accessor :age, Fixnum

end

User.find_by_name(‘tml’) User.find_by_name_and_age(‘tml’, 3) User.find_all_by_name_and_age(‘tml’, 3) User.find_all_by_name_and_age(‘tml’, 3, :name_op => ‘LIKE’, :age_op => ’>’, :limit => 4) User.find_or_create_by_name_and_age(‘tml’, 3)

[ show source ]

     # File lib/og/model.rb, line 618
618:     def method_missing(sym, *args, &block)
619:       if match = /find_(all_by|by)_([_a-zA-Z]\w*)/.match(sym.to_s)
620:         return find_by_(match, args, &block)
621:       elsif match = /find_or_create_by_([_a-zA-Z]\w*)/.match(sym.to_s)
622:         return find_or_create_by_(match, args, &block)
623:       else
624:         super
625:       end
626:     end
polymorphic_parent?()

Is this model a polymorphic parent?

[ show source ]

     # File lib/og/model.rb, line 551
551:     def polymorphic_parent?
552:       self.to_s == self.ann(:self, :polymorphic).to_s
553:     end
primary_key()

Returns the primary key for this class.

[ show source ]

     # File lib/og/model.rb, line 470
470:     def primary_key
471:       Model.resolve_primary_key(self)
472:     end
resolve_non_hash_options(options)

Resolve String/Array options.

[ show source ]

     # File lib/og/model.rb, line 655
655:     def resolve_non_hash_options(options)      
656:       if options.is_a? String
657:         if options =~ /^WHERE/i
658:           # pass the string as sql.
659:           return { :sql => options }
660:         else
661:           # pass the string as a condition.
662:           return { :condition => options }
663:         end
664:       elsif options.is_a? Array
665:         # pass the array as condition (prepared statement style
666:         # parsing/quoting.
667:         return { :condition => options }
668:       end
669:       
670:       return options
671:     end
resolve_remote_relations()

Returns an array of all relations formed by other og managed classes with the class of this object.

This is needed by the PostgreSQL foreign key constraints system.

[ show source ]

     # File lib/og/model.rb, line 567
567:     def resolve_remote_relations
568:       klass = self
569:       manager = klass.ogmanager
570:       relations = Array.new
571:       manager.managed_classes.each do |managed_class|
572:         next if managed_class == klass
573:         managed_class.relations.each do |rel|
574:           relations << rel if rel.target_class == klass
575:         end
576:       end
577:       relations
578:     end
schema_inheritance?()

[ show source ]

     # File lib/og/model.rb, line 493
493:     def schema_inheritance?
494:       false
495:     end
schema_inheritance_child?()

[ show source ]

     # File lib/og/model.rb, line 497
497:     def schema_inheritance_child?
498:       false
499:     end
schema_inheritance_root?()

[ show source ]

     # File lib/og/model.rb, line 501
501:     def schema_inheritance_root?
502:       false
503:     end
schema_inheritance_root_class()

[ show source ]

     # File lib/og/model.rb, line 519
519:     def schema_inheritance_root_class
520:       return table_class
521:     end
schema_options()

[ show source ]

     # File lib/og/model.rb, line 489
489:     def schema_options
490:       {}
491:     end
set_find_options(options)

Set the default find options for this model.

[ show source ]

     # File lib/og/model.rb, line 476
476:     def set_find_options(options)
477:       ann :self, :find_options => options
478:     end
set_order(order_str)

Set the default order option for this model.

[ show source ]

     # File lib/og/model.rb, line 525
525:     def set_order(order_str)
526:       unless ann(:self, :find_options)
527:         ann(:self, :find_options => { :order => order_str })
528:       else
529:         ann!(:self, :find_options).update(:order => order_str)
530:       end
531:     end
set_primary_key(pk, pkclass = Fixnum)

Set the primary key.

[ show source ]

     # File lib/og/model.rb, line 544
544:     def set_primary_key(pk, pkclass = Fixnum)
545:       self.ann(pk, :primary_key => true)
546: #     self.ann!(pk)[:class] ||= pkclass # gmosx, WHAT is this?
547:     end
set_schema_inheritance()

Enable schema inheritance for this Model class. The Single Table Inheritance pattern is used.

[ show source ]

     # File lib/og/model.rb, line 484
484:     def set_schema_inheritance
485:       include Og::SchemaInheritanceBase
486:     end
set_scope(options)

Define a scope for the following og method invocations on this managed class. The scope options are stored in a thread variable.

At the moment the scope is only considered in find queries.

[ show source ]

     # File lib/og/model.rb, line 587
587:     def set_scope(options)
588:       Thread.current["#{self}_scope"] = options
589:     end
set_sql_table(table)

Set a custom table name.

[ show source ]

     # File lib/og/model.rb, line 537
537:     def set_sql_table(table)
538:       ann :self, :sql_table => table.to_s
539:     end
table_class()

+

[ show source ]

     # File lib/og/model.rb, line 512
512:     def table_class
513:       self
514:     end
transaction(&block)

[ show source ]

     # File lib/og/model.rb, line 462
462:     def transaction(&block)
463:       ogmanager.with_store do |s|
464:         s.transaction(&block)
465:       end
466:     end
with_scope(options) {|| ...}

Execute some Og methods in a scope.

[ show source ]

     # File lib/og/model.rb, line 599
599:     def with_scope(options)
600:       set_scope(options)
601:       yield
602:       set_scope(nil)
603:     end