X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FDBIx%2FClass%2FResultSource%2FMultipleTableInheritance.pm;h=9dceab69b551a97eff0190db3fb5219242b2ef5d;hb=ebcd7e950dc50fd9529d2d59acd1fb9fb72e3916;hp=a7cf79902f48c5b92ce6ed6d4b7812039527865f;hpb=146ec12072b06ff504e6b0b4004a98374d602cb8;p=dbsrgits%2FDBIx-Class-ResultSource-MultipleTableInheritance.git

diff --git a/lib/DBIx/Class/ResultSource/MultipleTableInheritance.pm b/lib/DBIx/Class/ResultSource/MultipleTableInheritance.pm
index a7cf799..9dceab6 100644
--- a/lib/DBIx/Class/ResultSource/MultipleTableInheritance.pm
+++ b/lib/DBIx/Class/ResultSource/MultipleTableInheritance.pm
@@ -15,6 +15,21 @@ our $VERSION = 0.01;
 
 __PACKAGE__->mk_group_accessors(simple => qw(parent_source additional_parents));
 
+# how this works:
+#
+# On construction, we hook $self->result_class->result_source_instance
+# if present to get the superclass' source object
+# 
+# When attached to a schema, we need to add sources to that schema with
+# appropriate relationships for the foreign keys so the concrete tables
+# get generated
+#
+# We also generate our own view definition using this class' concrete table
+# and the view for the superclass, and stored procedures for the insert,
+# update and delete operations on this view.
+#
+# deploying the postgres rules through SQLT may be a pain though.
+
 method new ($class: @args) {
   my $new = $class->next::method(@args);
   my $rc = $new->result_class;
@@ -131,14 +146,14 @@ method attach_additional_sources () {
     # have to use source name lookups rather than result class here
     # because we don't actually have a result class on the raw sources
     $table->add_relationship('parent', $parent->raw_source_name, \%pk_join);
-    $self->depends_on->{$parent->source_name} = 1;
+    $self->deploy_depends_on->{$parent->result_class} = 1;
   }
 
   foreach my $add (@{$self->additional_parents||[]}) {
     $table->add_relationship(
       'parent_'.$add->name, $add->source_name, \%pk_join
     );
-    $self->depends_on->{$add->source_name} = 1;
+    $self->deploy_depends_on->{$add->result_class} = 1;
   }
 
   # add every column that's actually a concrete part of us
@@ -261,7 +276,8 @@ BEGIN {
 
   *names_of = sub (@cols) { map $_->{name}, @cols };
 
-  *function_body = sub ($name, $args, $body_parts) {
+  *function_body = sub {
+    my ($name,$args,$body_parts) = @_;
     my $arglist = join(
       ', ',
         map "_${\$_->{name}} ${\uc($_->{data_type})}",
@@ -278,6 +294,23 @@ BEGIN {
       $function$ LANGUAGE plpgsql;
     };
   };
+  #*function_body = sub ($name,$args,$body_parts) {
+    #my $arglist = join(
+      #', ',
+        #map "_${\$_->{name}} ${\uc($_->{data_type})}",
+          #@$args
+    #);
+    #my $body = join("\n", '', map "          $_;", @$body_parts);
+    #return strip tt q{
+      #CREATE OR REPLACE FUNCTION [% name %]
+        #([% arglist %])
+        #RETURNS VOID AS $function$
+        #BEGIN
+          #[%- body %]
+        #END;
+      #$function$ LANGUAGE plpgsql;
+    #};
+  #};
 }
 
 BEGIN {
@@ -411,50 +444,33 @@ method view_definition () {
 
 __END__
 
-# how this works:
-#
-# On construction, we hook $self->result_class->result_source_instance
-# if present to get the superclass' source object
-# 
-# When attached to a schema, we need to add sources to that schema with
-# appropriate relationships for the foreign keys so the concrete tables
-# get generated
-#
-# We also generate our own view definition using this class' concrete table
-# and the view for the superclass, and stored procedures for the insert,
-# update and delete operations on this view.
-#
-# deploying the postgres rules through SQLT may be a pain though.
+=head1 NAME
 
-=encoding utf-8
+DBIx::Class::ResultSource::MultipleTableInheritance
+Use multiple tables to define your classes 
 
-=head1 NAME
+=head1 NOTICE
 
-DBIx::Class::ResultSource::MultipleTableInheritance -- Use multiple tables to define your classes 
+This only works with PostgreSQL for the moment.
 
 =head1 SYNOPSIS
 
-
     {
-        package MyApp::Schema::Result::Coffee;
+        package Cafe::Result::Coffee;
+
+        use strict;
+        use warnings;
+        use parent 'DBIx::Class::Core';
+        use aliased 'DBIx::Class::ResultSource::MultipleTableInheritance'
+            => 'MTI';
 
-        __PACKAGE__->table_class('DBIx::Class::ResultSource::MultipleTableInheritance');
+        __PACKAGE__->table_class(MTI);
         __PACKAGE__->table('coffee');
         __PACKAGE__->add_columns(
-          "id",
-          {
-            data_type => "integer",
-            default_value => "nextval('coffee_seq'::regclass)",
-            is_auto_increment => 1,
-            is_foreign_key => 1,
-            is_nullable => 0,
-            size => 4,
-          },
-          "flavor",
-          {
-            data_type => "text",
-            default_value => "good",
-          },
+            "id", { data_type => "integer" },
+            "flavor", {
+                data_type => "text",
+                default_value => "good" },
         );
 
         __PACKAGE__->set_primary_key("id");
@@ -463,19 +479,14 @@ DBIx::Class::ResultSource::MultipleTableInheritance -- Use multiple tables to de
     }
 
     {
-        package MyApp::Schema::Result::Sumatra;
+        package Cafe::Result::Sumatra;
 
-        use parent 'Coffee';
+        use parent 'Cafe::Result::Coffee';
 
         __PACKAGE__->table('sumatra');
 
-        __PACKAGE__->add_columns(
-          "aroma",
-          {
-            data_type => "text",
-            default_value => undef,
-            is_nullable => 0,
-          },
+        __PACKAGE__->add_columns( "aroma",
+            { data_type => "text" }
         );
 
         1;
@@ -483,32 +494,35 @@ DBIx::Class::ResultSource::MultipleTableInheritance -- Use multiple tables to de
     
     ...
 
-    my $schema = MyApp::Schema->connect($dsn);
-
-    my $cup = $schema->resultset('Sumatra')->new;
+    my $schema = Cafe->connect($dsn,$user,$pass);
 
-    print STDERR Dumper $cup->columns;
+    my $cup = $schema->resultset('Sumatra');
 
-        $VAR1 = 'id';
-        $VAR2 = 'flavor';
-        $VAR3 = 'aroma';
+    print STDERR Dwarn $cup->result_source->columns;
 
+        "id"
+        "flavor"
+        "aroma"
+        ..
 
+Inherit from this package and you can make a resultset class from a view, but
+that's more than a little bit misleading: the result is B<transparently
+writable>.
 
-Inherit from this package and you can make a resultset class from a view, but that's more than a little bit misleading: the result is B<transparentlt writable>.
-
-This is accomplished through the use of stored functions that map changes written to the view to changes to the underlying concrete tables.
+This is accomplished through the use of stored procedures that map changes
+written to the view to changes to the underlying concrete tables.
 
 =head1 WHY?
 
-In many applications, many classes are subclasses of others. Let's say you have this schema:
+In many applications, many classes are subclasses of others. Let's say you
+have this schema:
 
     # Conceptual domain model
     
     class User {
-            has id,
-            has name,
-            has password
+        has id,
+        has name,
+        has password
     }
 
     class Investor {
@@ -521,18 +535,20 @@ In many applications, many classes are subclasses of others. Let's say you have
 That's redundant. Hold on a sec...
 
     class User {
-            has id,
-            has name,
-            has password
+        has id,
+        has name,
+        has password
     }
 
-    class Investor isa User {
+    class Investor extends User {
         has dollars
     }
 
 Good idea, but how to put this into code?
 
-One far-too common and absolutely horrendous solution is to have a "checkbox" in your database: a nullable "investor" column, which entails a nullable "dollars" column, in the user table.
+One far-too common and absolutely horrendous solution is to have a "checkbox"
+in your database: a nullable "investor" column, which entails a nullable
+"dollars" column, in the user table.
 
     create table "user" (
         "id" integer not null primary key autoincrement,
@@ -544,7 +560,8 @@ One far-too common and absolutely horrendous solution is to have a "checkbox" in
 
 Let's not discuss that further.
 
-A second, better, solution is to break out the two tables into user and investor:
+A second, better, solution is to break out the two tables into user and
+investor:
 
     create table "user" (
         "id" integer not null primary key autoincrement,
@@ -557,7 +574,9 @@ A second, better, solution is to break out the two tables into user and investor
         "dollars" integer
     );
 
-So that investor's PK is just an FK to the user. We can clearly see the class hierarchy here, in which investor is a subclass of user. In DBIx::Class applications, this second strategy looks like:
+So that investor's PK is just an FK to the user. We can clearly see the class
+hierarchy here, in which investor is a subclass of user. In DBIx::Class
+applications, this second strategy looks like:
     
     my $user_rs = $schema->resultset('User');
     my $new_user = $user_rs->create(
@@ -572,11 +591,15 @@ So that investor's PK is just an FK to the user. We can clearly see the class hi
         dollars => $args->{dollars},
     );
 
-One can cope well with the second strategy, and it seems to be the most popular smart choice.
+One can cope well with the second strategy, and it seems to be the most popular
+smart choice.
 
 =head1 HOW?
 
-There is a third strategy implemented here. Make the database do more of the work. It'll save us some typing and it'll make for more expressive code. What if we could do this:
+There is a third strategy implemented here. Make the database do more of the
+work: hide the nasty bits so we don't have to handle them unless we really want
+to. It'll save us some typing and it'll make for more expressive code. What if
+we could do this:
 
     my $new_investor = $schema->resultset('Investor')->create(
         name => $args->{name},
@@ -584,9 +607,20 @@ There is a third strategy implemented here. Make the database do more of the wor
         dollars => $args->{dollars},
     );
     
-And have it Just Work? The user ( {name => $args->{name}, password => $args->{password} } ) should be created transparently, and the use of either user or investor in your code should require no special handling. Deleting and updating $new_investor should also delete or update the user row.
+And have it Just Work? The user...
 
-It does. User and investor are both views, their concrete tables abstracted away behind a set of rules and triggers. You would expect the above DBIC create statement to look like this in SQL:
+    {
+        name => $args->{name},
+        password => $args->{password},
+    }
+
+should be created behind the scenes, and the use of either user or investor
+in your code should require no special handling. Deleting and updating
+$new_investor should also delete or update the user row.
+
+It does. User and investor are both views, their concrete tables abstracted
+away behind a set of rules and triggers. You would expect the above DBIC
+create statement to look like this in SQL:
 
     INSERT INTO investor ("name","password","dollars") VALUES (...);
 
@@ -595,7 +629,8 @@ But using MTI, it is really this:
     INSERT INTO _user_table ("username","password") VALUES (...);
     INSERT INTO _investor_table ("id","dollars") VALUES (currval('_user_table_id_seq',...) );
 
-For deletes, the triggers fire in reverse, to preserve referential integrity (foreign key constraints). For instance:
+For deletes, the triggers fire in reverse, to preserve referential integrity
+(foreign key constraints). For instance:
 
    my $investor = $schema->resultset('Investor')->find({id => $args->{id}});
    $investor->delete;
@@ -606,11 +641,62 @@ Becomes:
     DELETE FROM _user_table WHERE ("id" = ?);
 
 
-    
+=head1 METHODS
+
+=over
+
+=item new
+
+
+MTI find the parents, if any, of your resultset class and adds them to the
+list of parent_sources for the table.
+
 
+=item add_additional_parents
 
 
+Continuing with coffee:
 
+    __PACKAGE__->result_source_instance->add_additional_parents(
+        qw/
+            MyApp::Schema::Result::Beverage
+            MyApp::Schema::Result::Liquid
+        /
+    );
+
+This just lets you manually add additional parents beyond the ones MTI finds.
+
+=item add_additional_parent
+
+    __PACKAGE__->result_source_instance->add_additional_parent(
+            MyApp::Schema::Result::Beverage
+    );
+
+You can also add just one.
+
+=item attach_additional_sources
+
+MTI takes the parents' sources and relationships, creates a new
+DBIx::Class::Table object from them, and registers this as a new, raw, source
+in the schema, e.g.,
+
+    use MyApp::Schema;
+
+    print STDERR map { "$_\n" } MyApp::Schema->sources;
+
+    # Coffee 
+    # Beverage
+    # Liquid
+    # Sumatra
+    # Raw::Sumatra
+
+Raw::Sumatra will be used to generate the view.
+
+=item view_definition
+
+This takes the raw table and generates the view (and stored procedures) you will use.
+
+=back
 
 =head1 AUTHOR
 
@@ -618,7 +704,12 @@ Matt S. Trout, E<lt>mst@shadowcatsystems.co.ukE<gt>
 
 =head2 CONTRIBUTORS
 
-Docs: Amiri Barksdale, E<lt>amiri@metalabel.comE<gt>
+Amiri Barksdale, E<lt>amiri@metalabel.comE<gt>
+
+=head1 COPYRIGHT
+
+Copyright (c) 2010 the DBIx::Class::ResultSource::MultipleTableInheritance
+L</AUTHOR> and L</CONTRIBUTORS> as listed above.
 
 =head1 LICENSE