module IDEquality

Description

IDEquality simply provides a convenient mechanism for comparing two DBBackedClass instances. If they are of the same class and they have the same record ID, then they should be the same instance.

class DBBackedArray

Description

DBBackedArray isn't DB backed necessarily, but contains a collection of objects that are meant to be. It's really an array that may be declared to be writeable or readonly. If it's readonly, then attempts to insert elements will raise an exception. This is used by DBBackedClass for hashed_backref.

Class Methods

DBBackedArray.new(writeable, &block)

Construct a new DBBackedArray which is writeable as dictated by the writeable flag. If it is writeable, then block will be called with the new element upon insertion. This is typically used so that when a new element is inserted, it is flushed to the database.

Instance Methods

DBBackedArray#<<(val)

Insert val into the DBBackedArray and call the block passed to the constructor with val as a parameter. This will raise an exception if the DBBackedArray is readonly.

class DBBackedClass

Synopsis

See sample.rb in the sample directory.

Description

This is the base class for all database backed classes. It contains some useful methods for instances as well as some class methods which allow for extension of subclasses based on a simple run-time declarations (similar to the attr family. It's a bit messy as I didn't really know what I was doing at the time and I should probably clean things up now that I know the proper way to do things. Nevertheless it works pretty well though each subclass takes up a tiny bit of extra memory in a class-variable for the declared attributes.

You will probably never use this class's methods directly.

Class Methods

DBBackedClass.new(accessor, record_id = -1, hash = nil)

Construct a new instance of the DBBackedClass with DBIAccessor accessor whose record ID is record_id which defaults to -1 indicating a new instance and with properties contained in hash a hash of name to values similar to what one would get back from DBIAccessor#selexec.

Instantiating this class directly isn't very useful. You want subclasses.

DBBackedClass.register(klass)

This registers klass. Basically it sets up some hashes to default values for the event where attributes weren't declared. Invoked by the constructor.

DBBackedClass.attributes(klass)

Return all hashed_attrs defined for klass. Used internally.

DBBackedClass.refs(klass)

Return all hashed_refs defined for klass. Used internally.

DBBackedClass.backrefs(klass)

Return all hashed_backrefs defined for klass. Used internally.

DBBackedClass.hashed_attr(symbol, key, datatype, writeable)

Define an attribute for a subclass of DBBackedClass. This is used similar to the popular attr_reader, attr_accessor, attr, etc.

Example usage:

class DumbClass < DBBackedClass
  hashed_attr :record_id, 'record_id', 'i', false
end

foo = DumbClass.new(accessor,23)
foo.record_id == 23

bar = DumbClass.new(accessor)
bar.record_id == -1

This says that DumbClass has a single hashed attribute accessed with the record_id method which will return the value of the record_id field in this particular record, casting it to an Integer. It is not writeable.

DBBackedClass.hashed_ref(symbol, key, klass, writeable)

This is similar to DBBackedClass.hashed_attr only it's used to define a method that will return an instance of another DBBackedClass subclass referenced by a foreign key in the database.

Example:

class DumbClass < DBBackedClass
  hashed_attr :record_id, 'record_id', 'i', false
  hashed_ref :person, 'people_id', Person, true
end

foo = DumbClass.new(accessor,23)
foo.record_id == 23

foo.person.type == Person

This says we want a method person which will lookup a Person from the Person table whose record_id field matches the value of the people_id field in this record (a many to one or one to one mapping). We can change the value of person with foo.person = newguy where newguy is some new Person. Note that this does not delete the old Person as other records may still be referencing it. It only changes this record to reference newguy.

DBBackedClass.hashed_backref(symbol, key, klass, writeable)

This is similar to DBBackedClass.hashed_ref only it's for when another table has records which refer back to this record (a one to many or one to one mapping). So for example, if our trusty DumbClass had phone numbers associated with it now, we might declare it like:

class DumbClass < DBBackedClass
  hashed_attr :record_id, 'record_id', 'i', false
  hashed_ref :person, 'people_id', Person, true
  hashed_backref :phones, 'dumb_id', Phone, false
end

foo = DumbClass.new(accessor,23)

This says that in the Phone table, there are records whose dumb_id field may match our record ID. When we call foo.phones we'll get back an array of Phone instances which point to this DumbClass instance. The array is not writeable, so we can't add new phones. I guess we can delete them, but that's a bug and won't really affect the persistent data.

DBBackedClass.primary_key_name

This returns the primary key name for this class in the database. In theory, your databases could then have a primary key named other than 'record_id' though I'm pretty sloppy about it and in practice it's probably not really a safe thing to rely. In the future I'll be better, I promise.

DBBackedClass.count(accessor, modifier=nil)

Count the number of instances this class has in the database. Where may be an optional WHERE clause.

DBBackedClass.fetchAll(accessor,modifier=nil)

Use accessor to fetch all instances of this class from the class's table. Optionally, you can specify a where class like WHERE foo='bar' which will limit the result set.

Actually used a lot like

DumbClass.fetchAll(accessor).each { |dumb_inst| blah_blah(dumb_inst) }

Instance Methods

DBBackedClass#attributes

This simply returns a hash of attributes for this class. It's used internally on occassion.

DBBackedClass#refs

This simply returns a hash of references for this class. It's used internally on occassion.

DBBackedClass#backrefs

This simply returns a hash of back references for this class. It's used internally on occassion.

DBBackedClass#primary_key_name

See DBBackedClass.primary_key_name

DBBackedClass#sanitize

Occassionally it may be necessary to go through and sanitize the data contained in the object's hash before writing out to the database. This is particularly true when the object has a boolean field and we've set it manually (through the hash) to be 'true' or 'false' whereas many databases use 1 or 0. This will force an update in the hash table. It's really only necessary if code external to the class directly manipulates the hash table.

DBBackedClass#parseBool

A method to parse a boolean value from a string which may be 'true', 'false', '0', '1', or nil (false).

DBBackedClass#parseDate(str)

Parse a date from a string.

DBBackedClass#parseTime(str)

Parse a time from a string.

DBBackedClass#to_s

Format the contents of this object as a String.

DBBackedClass#flush

Flush this to the backing database. Any references and backrefs will also be flushed if they've been loaded.

DBBackedClass#fetchRef(refname)

Referenced objects aren't fetched automatically, only upon being referenced through the accessor method. At this point, this method is called and the object is fectched.

DBBackedClass#fetchBackrefs(refname)

This is similar to DBBackedClass#fetchRef but for backrefs.