[Treebase-guts] SF.net SVN: treebase:[324] trunk/treebase-core/src/main/perl/lib/CIPRES/ TreeBase

[<mjd...@us...>]

Revision: 324
          http://treebase.svn.sourceforge.net/treebase/?rev=324&view=rev
Author:   mjdominus
Date:     2009-11-25 05:58:49 +0000 (Wed, 25 Nov 2009)

Log Message:
-----------
lots more documentation

Modified Paths:
--------------
    trunk/treebase-core/src/main/perl/lib/CIPRES/TreeBase/TreeBaseObjects.pm
    trunk/treebase-core/src/main/perl/lib/CIPRES/TreeBase/VeryBadORM.pm

Modified: trunk/treebase-core/src/main/perl/lib/CIPRES/TreeBase/TreeBaseObjects.pm
===================================================================
--- trunk/treebase-core/src/main/perl/lib/CIPRES/TreeBase/TreeBaseObjects.pm	2009-11-25 04:21:49 UTC (rev 323)
+++ trunk/treebase-core/src/main/perl/lib/CIPRES/TreeBase/TreeBaseObjects.pm	2009-11-25 05:58:49 UTC (rev 324)
@@ -16,77 +16,6 @@
 on.
 
 
-=head1 OBJECT ATTRIBUTES
-
-In general, if a database object, represented by C<$X>, has an attribute named C<foo>, then 
-C< $X->foo > retrieves the value of the attribute.  If the attribute is a scalar, the value is
-returned as a Perl scalar; if the attribute is a reference to another database object, a
-Perl object is returned.
-
-Each object is assumed to correspond to a single table in the database.  If the object class is
-C<ObjectClass>, the corresponding table name is assumed to be C<objectclass>.  This can be
-overridden by defining the C<ObjectClass::table> method, which should return the correct table
-name.  
-
-Each object from class C<ObjectClass> is assumed to have a unique ID attribute which is stored
-in the table in a field whose name is returned by C<ObjectClass::id_attr>.  This defaults to
-C<objectclass_id> if the method is not overridden.
-
-C<ObjectClass::new(C<$id>)> will create an object with the specified ID number.  Objects are
-created lazily: the database is not consulted until some 
-
-We will consider a running example, a database which contains studies, trees, and matrices.
-Each tree and each matrix is contained in exactly one study, but each study may have multiple
-trees and matrices.
-
-Each tree contains zero or more treenodes, and each matrix contains zero or more matrixrows.
-
-Suppose the C<tree> table contains a field, C<study_id>, which contains the foreign key of the 
-
-=over
-
-=item %r_attr
-
-This hash specifies which other classes refer to the specifying class in a many-to-one relationship.
-For example:
-
- %Analysis::r_attr = ( 'analysissteps' => 'AnalysisStep' );
-
-Specifies that multiple AnalysisStep objects may refer to an invocant Analysis object, and that
-these AnalysisStep objects can be instantiated by calling the Analysis::analysissteps() method.
-
-=item %r2_attr
-
-This hash specifies associated objects which are linked to instances of the specifying class
-through an intersection table. For example:
-
- %Citation::r2_attr = (
-	'authors' => ['citation_author', 'Person', 'authors_person_id']
- );
-
-Specifies that associated instances of the Person class can be fetched by calling the 
-Citation::authors() method which will look in the citation_author table and instantiate
-Person objects passing the values in the authors_person_id column to the Person 
-constructor.
-
-=item %subobject
-
-This hash specifies associated classes which are identified by foreign keys in the table that is
-mapped onto the specifying class. For example:
-
- %PhyloTree::subobject = (
-	'rootnode' => 'PhyloTreeNode', 
-	'treetype' => 'TreeType'
- );
- 
-Specifies that an associated instance (one-to-one) of the PhyloTree's root node (instantiated
-as a PhyloTreeNode) and of the tree type (instantiates as a TreeType object) can be 
-created by calling the rootnode() and treetype() methods, respectively. Calls to those methods
-will look in phylotree.rootnode_id and phylotree.treetype_id in the row of the invocant object
-and create the right associated objects.
-
-=back
-
 =head1 PACKAGE METHODS
 
 =over

Modified: trunk/treebase-core/src/main/perl/lib/CIPRES/TreeBase/VeryBadORM.pm
===================================================================
--- trunk/treebase-core/src/main/perl/lib/CIPRES/TreeBase/VeryBadORM.pm	2009-11-25 04:21:49 UTC (rev 323)
+++ trunk/treebase-core/src/main/perl/lib/CIPRES/TreeBase/VeryBadORM.pm	2009-11-25 05:58:49 UTC (rev 324)
@@ -20,22 +20,117 @@
 This module maps relations in a relational database to objects in Perl.  It avoids all difficult
 implementation problems by providing only read-only access.
 
-=head1 PACKAGE VARIABLES
+=head1 OBJECT ATTRIBUTES
 
-=over
+In general, if a database object, represented by C<$X>, has an attribute named C<foo>,
+then C< $X->foo > or C< $x->get('foo') > retrieves the value of the attribute.  If the
+attribute is a scalar, the value is returned as a Perl scalar; if the attribute is a
+reference to another database object, a Perl object is returned.
 
-=item %dbh
+Each object is assumed to correspond to a single table in the database.  If the object
+class is C<ObjectClass>, the corresponding table name is assumed to be C<objectclass>.
+This can be overridden by defining the C<ObjectClass::table> method, which should return
+the correct table name.
 
-This hash holds cached database handles keyed on class names.  
+Each object from class C<ObjectClass> is assumed to have a unique ID attribute which is stored
+in the table in a field whose name is returned by C<ObjectClass::id_attr>.  This defaults to
+C<objectclass_id> if the method is not overridden.
 
-=item $DBH
+C<ObjectClass::new(C<$id>)> will create an object with the specified ID number.  Objects
+are created lazily: the database is not consulted until some other attribute of the object
+is read.
 
-Holds a singleton database handle
+Attributes are of four types.  The call C< $Object->foo > will be resolved in the
+following order:
 
+=over 4
+
+=item 1. Direct attributes. 
+
+If the object's table has a column whose name is exactly C<foo>, the value from that
+column will be returned directly.  SQL C<NULL> values are returned as Perl C<undef>.  
+
+Technical details: Whether an attribute name is considered a direct attribute is
+determined by the return value of the C<has_attr> method.  If C<has_attr> returns true,
+C<get_no_check> is called to produce the attribute value.  See the descriptions of those
+methods below for details.
+
+=item 2. Subobjects.
+
+If the object's table has a column whose name is C<foo_id>, its value is taken to be a
+foreign key, joining to a table named C<foo>.  The corresponding record is looked up in
+the joined table, and an object of class C<Foo> will be constructed and returned.
+
+Technical details: Whether an attribute is considered to be a subobject name is determined
+by the return value of the C<has_subobject> method.  The foreign key column name may be
+overridden by redefining the C<foreign_key> method.  The name of the instantiated class
+may be overridden by redefining the C<subobject_class> method.  The name of the joined
+table may be overridden by redefining the C<table> method for the instantiated class.  See
+the descriptions of those methods below for details.
+
 =back
 
-=head1 PACKAGE METHODS
+=item 3. Reverse subobjects.
 
+If the object's package contains an C<%r_attr> hash with key C<foo>, the value is taken to
+be a class that contains a foreign key linking to the invocant's table.  The tables are
+joined and all foreign objects linking to the invocant are returned.
+
+Technical details: An attribute name is considered to designate a reverse subobject when
+the C<has_r_attr> method returns true.  If so, the C<r_class> method is called to
+determine the class from which the subobjects will be instantiated, that class's C<table>
+method will determine the table joined, and that class's C<foreign_key> method will be
+called to determine the foreign key column for the join.  See the descriptions of those
+methods below for details.
+
+=item 4. Linked objects.
+
+If the invocant's package contains an C<%r2_attr> hash with key C<foo>, the value should be
+an array whose first element is the name of a link table that contains keys for both the
+invocant's table and a foreign table.  The three tables are joined, and the objects from
+the foreign table that link through to the invocant are returned.  The value
+C<$r2_attr{foo}> has the following format:
+
+	[ link table name,
+          class in which foreign objects are instantiated,
+          column of link table with foreign keys ]
+
+The third of these is optional; if omitted, the name returned by the foreign class's
+C<id_attr> method is used.
+
+Technical details: An attribute name is considered to designate a linked object when the
+C<has_r2_attr> method returns true.  The C<r2_table> method is called to determine the
+name of the link table.  The invocant's ID is looked up in the column of the link table
+named by the invocant's C<id_field> method, and the corresponding values of the column
+named by the C<r2_id_attr> method are gathered.  An object is allocated for each resulting
+foreign id, in the class named by the C<r2_class> method.  See the descriptions of those
+methods below for details.
+
+For example, consider the following tables:
+
+    study             study_author		person
+
+    study_id          study_id  person_id       person_id
+    1                 1         100             100
+    2                 2         101             101
+    3                 2         102             102
+    4                 2         103             103
+                      3         102
+                      4         101
+                      4         103
+
+Suppose that C<%study::r2_attr> contains:
+
+    authors => [ 'study_author', 'Person', 'person_id' ]
+
+The link table is C<study_author>, and the foreign table is C<person>.  Then 
+C< Study->new(4)->authors > will return C<Person> objects 101 and 103.
+
+
+=back
+
+=head1 CLASS METHODS
+
 =over
 
 =item set_db_connection()
@@ -54,30 +149,19 @@
 
 sub get_db_connection { my $class = shift; return $dbh{$class}; }
 
-=back
-
-=head1 INSTANCE METHODS
-
-=over
-
-=item prepare_cached()
-
-Prepares a query on the singleton database handle, returns statement handler.
-
-=cut
-
-sub prepare_cached {
+# Private; should remain undocumented
+sub _prepare_cached {
     my ($self, $q) = @_;
     return $DBH->prepare_cached($q);
 }
 
+=head1 INSTANCE METHODS
+
 =item new()
 
-Instantiates an instance of one of the classes defined in TreeBaseObjects. This constructor
-requires that the singleton database handle $CIPRES::TreeBase::VeryBadORM::DBH has been defined
-and that a valid ID is supplied as argument. Instantiated objects are cached in the private
-%cache hash as $cache{$class}{$id}. Returned objects are simply blessed hash references that 
-contain the ID as { 'id' => $id }
+Instantiates an instance of one of the classes defined in TreeBaseObjects. This
+constructor requires that the singleton database handle $CIPRES::TreeBase::VeryBadORM::DBH
+has been defined and that a valid ID is supplied as argument.
 
 =cut
 
@@ -97,20 +181,9 @@
     return $obj;
 }
 
-=item AUTOLOAD
-
-Provides the magical methods available in the child classes. It does this by checking which of
-has_attr(), has_subobject(), has_r_attr() or has_r2_attr() applies and invokes one of
-get_no_check(), get_subobject_no_check(), get_r_subobject_no_check() or get_r2_subobject_no_check()
-respectively. Croaks otherwise.
-
-=cut
-
 # Maybe add some caching here at some point
 #
-# This should dispatch off to ->get because the code in the
-# two places is almost the same and we've already had one bug
-# occur when they didn't stay in sync.  mjd 20091123
+# Do not document this; it's private
 sub AUTOLOAD {
     our $AUTOLOAD;
     my ($package, $method) = $AUTOLOAD =~ /(.*)::(.*)/;
@@ -121,9 +194,12 @@
 
 =item has_attr()
 
-Checks to see if the invocant's class defines the supplied attribute. It does this by calling
-attr_hash() and doing a lookup for the supplied attribute in the returned hash.
+Given an attribute name, check to see if the invocant's class has a direct attribute with
+that name, and return true or false.  
 
+By default, it looks for the attribute name as a key in the hash returned by the
+C<attr_hash()> method.
+
 =cut
 
 sub has_attr {
@@ -134,10 +210,12 @@
 
 =item has_r_attr()
 
-Checks to see if the invocant's class defines the supplied "reverse attribute" (see 
-L<TreeBaseObjects> for the description of the %r_attr hash). It does this by returning whatever
-is returned by r_class() whilst passing it the supplied "reverse attribute"'s name.
+Given an attribute name, check to see if the invocant's class has a reverse attribute with
+that name, and return true or false.
 
+By default, this just passes the attribute name to the C<r_class> method to see if an
+instantiating class is known for the reverse attribute.
+
 =cut
 
 sub has_r_attr {
@@ -148,11 +226,12 @@
 
 =item has_r2_attr()
 
-Checks to see if the invocant's class defines the supplied "reverse attribute through 
-intersection table" (see L<TreeBaseObjects> for the description of the %r2_attr hash). It does this 
-by returning whatever is returned by r2_class() whilst passing it the supplied "reverse 
-attribute through intersection table"'s name.
+Given an attribute name, check to see if the invocant's class has a link attribute with
+that name, and return true or false.
 
+By default, this just passes the attribute name to the C<r2_class> method to see if an
+instantiating class is known for the link attribute.
+
 =cut
 
 sub has_r2_attr {
@@ -163,10 +242,12 @@
 
 =item has_subobject()
 
-Checks to see if the invocant is associated with the supplied subobject. It does this by 
-first turning the subobject's name into a foreign key column (by calling foreign_key()) and then 
-checking whether that column is available as an attribute (by calling has_attr()).
+Given an attribute name, check to see if the invocant's class has a subobject attribute with
+that name, and return true or false.
 
+By default, this method first obtains the name of the foreign key field used for this
+attribute, and then checks to see if the invocant has a direct attribute with that name.
+
 =cut
 
 sub has_subobject {
@@ -177,8 +258,8 @@
 
 =item foreign_key()
 
-Turns the supplied argument into a foreign key column. It does this by lower casing the 
-argument string and appending '_id'.
+Given an attribute name, return the name of the field that stores foreign keys for that
+attribute.
 
 =cut
 
@@ -311,11 +392,10 @@
 
 =item get()
 
-Given an invocant and a supplied attribute name, returns the attribute value. What the attribute
-actually is, is decided by first checking has_attr(), has_subobject(), has_r_attr() and returns
-the output of either get_no_check(), get_subobject_no_check() or get_r_subobject_no_check() 
-respectively. B<This method is probably never used and therefore probably buggy.>
+Given an invocant and an attribute name, returns the attribute value. 
 
+See the section L<> for details of how attribute names are resolved.
+
 =cut
 
 sub get {
@@ -409,7 +489,7 @@
 #    $attr = uc $attr;
     my $q = $self->r2_subobject_query($attr);
     my $target_class = $self->r2_class($attr);
-    my $sth = $self->prepare_cached($q);
+    my $sth = $self->_prepare_cached($q);
     $sth->execute($self->id);
     my @results;
     while (my ($target_id) = $sth->fetchrow) {
@@ -464,6 +544,8 @@
 
 sub r2_id_attr {
     my ($self, $attr) = @_;
+# Would it make more sense to use $self->foreign_key($attr) as the fallback here?
+# 20091125 MJD
     $self->r2_attr_hash()->{$attr}->[2] || $self->r2_class($attr)->id_attr;
 }
 
@@ -544,18 +626,24 @@
 
 =item subobject_class()
 
-Returns the class name for the supplied attribute name.  The default is the name of the attribute,
-lowercase with initial capital.  This may be overridden by an entry in the C<%subobject> hash in the
-invocant's class.  For example, suppose there are C<Dessert> objects and C<Flavor> objects.  Suppose
-each C<Dessert> has a C<flavor> and an C<alternate_flavor> attribute, which are C<Flavor> objects.
-One could represent this by defining:
+Given an attribute name, return the name of the class that represents that attribute.
 
+The default version looks up the attribute name as a key in the hash C<%subobject>, and,
+returns the associated value, if there is one.
+
+If not, it converts the attribute name to all-lowercase, uppercases the first character,
+and uses the result.   For example, the default class for the C<potato> attribute is C<Potato>.
+
+For example, suppose there are C<Dessert> objects and C<Flavor> objects.  Suppose each
+C<Dessert> has a C<flavor> and an C<alternate_flavor> attribute, which are C<Flavor>
+objects.  One could represent this by defining:
+
     %Dessert::subobject = (flavor => 'Flavor',
                            alternate_flavor => 'Flavor',
                           );
 
-which says that whenever a C<Dessert>  object's C<flavor> or C<alternate_flavor> attributes are
-accessed, C<VeryBadORM> should instantiate them as C<Flavor> objects.
+which says that whenever a C<Dessert> object's C<flavor> or C<alternate_flavor> attributes
+are accessed, C<VeryBadORM> should instantiate them as C<Flavor> objects.
 
 But one could omit the first entry from the hash:
 
@@ -566,7 +654,6 @@
 One may, of course, override this method to implement any mapping of attribute to class names that
 is desired.
 
-
 =cut
 
 sub subobject_class { 


This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.