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_attr
s defined for klass
. Used
internally.
DBBackedClass.refs(klass)
Return all hashed_ref
s defined for klass
. Used
internally.
DBBackedClass.backrefs(klass)
Return all hashed_backref
s 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) }
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
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.