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.
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.
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.
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.
See sample.rb in the sample directory.
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.
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_nameThis 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) }DBBackedClass#attributesThis simply returns a hash of attributes for this class. It's used internally on occassion.
DBBackedClass#refsThis simply returns a hash of references for this class. It's used internally on occassion.
DBBackedClass#backrefsThis simply returns a hash of back references for this class. It's used internally on occassion.
DBBackedClass#primary_key_nameDBBackedClass#sanitizeOccassionally 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#parseBoolA 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_sFormat the contents of this object as a String.
DBBackedClass#flushFlush 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.