X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FDBIx%2FClass%2FSchema.pm;h=3d63657ab3895d2d2cf331c64dcc63e529a2d962;hb=bf5ecff9ac30e6acfd912ce3c72ee86b73b775dc;hp=c84e0a709ff50a3df9cdd32c3bbcdab98dd904f9;hpb=8ef144fff4b1efed17257ac84c9e455adbd2fcbe;p=dbsrgits%2FDBIx-Class.git

diff --git a/lib/DBIx/Class/Schema.pm b/lib/DBIx/Class/Schema.pm
index c84e0a7..3d63657 100644
--- a/lib/DBIx/Class/Schema.pm
+++ b/lib/DBIx/Class/Schema.pm
@@ -18,29 +18,30 @@ DBIx::Class::Schema - composable schemas
 
 =head1 SYNOPSIS
 
-  package My::Schema;
+  package Library::Schema;
   use base qw/DBIx::Class::Schema/;
   
-  # load My::Schema::Foo, My::Schema::Bar, My::Schema::Baz
-  __PACKAGE__->load_classes(qw/Foo Bar Baz/);
+  # load Library::Schema::CD, Library::Schema::Book, Library::Schema::DVD
+  __PACKAGE__->load_classes(qw/CD Book DVD/);
 
-  package My::Schema::Foo;
+  package Library::Schema::CD;
   use base qw/DBIx::Class/;
-  __PACKAGE__->load_components(qw/PK::Auto::Pg Core/); # for example
-  __PACKAGE__->table('foo');
+  __PACKAGE__->load_components(qw/PK::Auto Core/); # for example
+  __PACKAGE__->table('cd');
 
-  my $schema1 = My::Schema->connect(
+  # Elsewhere in your code:
+  my $schema1 = Library::Schema->connect(
     $dsn,
     $user,
     $password,
-    $attrs
+    { AutoCommit => 0 },
   );
+  
+  my $schema2 = Library::Schema->connect($coderef_returning_dbh);
 
-  my $schema2 = My::Schema->connect( ... );
-
-  # fetch objects using My::Schema::Foo
-  my $resultset = $schema1->resultset('Foo')->search( ... );
-  my @objects = $schema2->resultset('Foo')->search( ... );
+  # fetch objects using Library::Schema::DVD
+  my $resultset = $schema1->resultset('DVD')->search( ... );
+  my @dvd_objects = $schema2->resultset('DVD')->search( ... );
 
 =head1 DESCRIPTION
 
@@ -54,11 +55,13 @@ particular which module inherits off which.
 
 =head1 METHODS
 
-=head2 register_class <moniker> <component_class>
+=head2 register_class
+
+=head3 Arguments: <moniker> <component_class>
 
 Registers a class which isa ResultSourceProxy; equivalent to calling
 
-  $schema->register_source($moniker, $class->result_source_instance);
+  $schema->register_source($moniker, $component_class->result_source_instance);
 
 =cut
 
@@ -67,7 +70,9 @@ sub register_class {
   $self->register_source($moniker => $to_register->result_source_instance);
 }
 
-=head2 register_source <moniker> <result source>
+=head2 register_source
+
+=head3 Arguments: <moniker> <result source>
 
 Registers the result source in the schema with the given moniker
 
@@ -88,7 +93,7 @@ sub register_source {
 
 =head2 class
 
-  my $class = $schema->class('Foo');
+  my $class = $schema->class('CD');
 
 Retrieves the result class name for a given result source
 
@@ -101,7 +106,7 @@ sub class {
 
 =head2 source
 
-  my $source = $schema->source('Foo');
+  my $source = $schema->source('Book');
 
 Returns the result source object for the registered name
 
@@ -131,7 +136,7 @@ sub sources { return keys %{shift->source_registrations}; }
 
 =head2 resultset
 
-  my $rs = $schema->resultset('Foo');
+  my $rs = $schema->resultset('DVD');
 
 Returns the resultset for the registered moniker
 
@@ -142,7 +147,9 @@ sub resultset {
   return $self->source($moniker)->resultset;
 }
 
-=head2  load_classes [<classes>, (<class>, <class>), {<namespace> => [<classes>]}]
+=head2 load_classes
+
+=head3 Arguments: @classes?, { $namespace => [ $class+ ] }+
 
 Uses L<Module::Find> to find all classes under the database class' namespace,
 or uses the classes you select.  Then it loads the component (using L<use>), 
@@ -183,46 +190,51 @@ sub load_classes {
     }
   } else {
     eval "require Module::Find;";
-    $class->throw_exception("No arguments to load_classes and couldn't load".
-      " Module::Find ($@)") if $@;
-    my @comp = map { substr $_, length "${class}::"  } Module::Find::findallmod($class);
+    $class->throw_exception(
+      "No arguments to load_classes and couldn't load Module::Find ($@)"
+    ) if $@;
+    my @comp = map { substr $_, length "${class}::"  }
+                 Module::Find::findallmod($class);
     $comps_for{$class} = \@comp;
   }
 
-  foreach my $prefix (keys %comps_for) {
-    foreach my $comp (@{$comps_for{$prefix}||[]}) {
-      my $comp_class = "${prefix}::${comp}";
-      eval "use $comp_class"; # If it fails, assume the user fixed it
-      if ($@) {
-        die $@ unless $@ =~ /Can't locate/;
+  my @to_register;
+  {
+    no warnings qw/redefine/;
+    local *Class::C3::reinitialize = sub { };
+    foreach my $prefix (keys %comps_for) {
+      foreach my $comp (@{$comps_for{$prefix}||[]}) {
+        my $comp_class = "${prefix}::${comp}";
+        eval "use $comp_class"; # If it fails, assume the user fixed it
+        if ($@) {
+	  $comp_class =~ s/::/\//g;
+          die $@ unless $@ =~ /Can't locate.+$comp_class\.pm\sin\s\@INC/;
+	  warn $@ if $@;
+        }
+        push(@to_register, [ $comp, $comp_class ]);
       }
-      $class->register_class($comp => $comp_class);
-      #  if $class->can('result_source_instance');
     }
   }
-}
+  Class::C3->reinitialize;
 
-=head2 compose_connection <target> <@db_info>
-
-This is the most important method in this class. it takes a target namespace,
-as well as dbh connection info, and creates a L<DBIx::Class::DB> class as
-well as subclasses for each of your database classes in this namespace, using
-this connection.
+  foreach my $to (@to_register) {
+    $class->register_class(@$to);
+    #  if $class->can('result_source_instance');
+  }
+}
 
-It will also setup a ->class method on the target class, which lets you
-resolve database classes based on the schema component name, for example
+=head2 compose_connection
 
-  MyApp::DB->class('Foo') # returns MyApp::DB::Foo, 
-                          # which ISA MyApp::Schema::Foo
+=head3 Arguments: $target_ns, @db_info
 
-This is the recommended API for accessing Schema generated classes, and 
-using it might give you instant advantages with future versions of DBIC.
+=head3 Return value: $new_schema
 
-WARNING: Loading components into Schema classes after compose_connection
-may not cause them to be seen by the classes in your target namespace due
-to the dispatch table approach used by Class::C3. If you do this you may find
-you need to call Class::C3->reinitialize() afterwards to get the behaviour
-you expect.
+Calls compose_namespace to the $target_ns, calls ->connection(@db_info) on
+the new schema, then injects the ResultSetProxy component and a
+resultset_instance classdata entry on all the new classes in order to support
+$target_ns::Class->search(...) method calls. Primarily useful when you have
+a specific need for classmethod access to a connection - in normal usage
+->connect is preferred.
 
 =cut
 
@@ -230,8 +242,9 @@ sub compose_connection {
   my ($self, $target, @info) = @_;
   my $base = 'DBIx::Class::ResultSetProxy';
   eval "require ${base};";
-  $self->throw_exception("No arguments to load_classes and couldn't load".
-      " ${base} ($@)") if $@;
+  $self->throw_exception
+    ("No arguments to load_classes and couldn't load ${base} ($@)")
+      if $@;
 
   if ($self eq $target) {
     # Pathological case, largely caused by the docs on early C::M::DBIC::Plain
@@ -247,6 +260,11 @@ sub compose_connection {
   }
 
   my $schema = $self->compose_namespace($target, $base);
+  {
+    no strict 'refs';
+    *{"${target}::schema"} = sub { $schema };
+  }
+
   $schema->connection(@info);
   foreach my $moniker ($schema->sources) {
     my $source = $schema->source($moniker);
@@ -259,24 +277,42 @@ sub compose_connection {
   return $schema;
 }
 
+=head2 compose_namespace
+
+=head3 Arguments: $target_ns, $additional_base_class?
+
+=head3 Return value: $new_schema
+
+For each result source in the schema, creates a class in the target
+namespace (e.g. $target_ns::CD, $target_ns::Artist) inheriting from the
+corresponding classes attached to the current schema and a result source
+to match attached to the new $schema object. If an additional base class is
+given, injects this immediately behind the corresponding classes from the
+current schema in the created classes' @ISA.
+
+=cut
+
 sub compose_namespace {
   my ($self, $target, $base) = @_;
   my %reg = %{ $self->source_registrations };
   my %target;
   my %map;
   my $schema = $self->clone;
-  foreach my $moniker ($schema->sources) {
-    my $source = $schema->source($moniker);
-    my $target_class = "${target}::${moniker}";
-    $self->inject_base(
-      $target_class => $source->result_class, ($base ? $base : ())
-    );
-    $source->result_class($target_class);
+  {
+    no warnings qw/redefine/;
+    local *Class::C3::reinitialize = sub { };
+    foreach my $moniker ($schema->sources) {
+      my $source = $schema->source($moniker);
+      my $target_class = "${target}::${moniker}";
+      $self->inject_base(
+        $target_class => $source->result_class, ($base ? $base : ())
+      );
+      $source->result_class($target_class);
+    }
   }
+  Class::C3->reinitialize();
   {
     no strict 'refs';
-    *{"${target}::schema"} =
-      sub { $schema };
     foreach my $meth (qw/class source resultset/) {
       *{"${target}::${meth}"} =
         sub { shift->schema->$meth(@_) };
@@ -285,7 +321,9 @@ sub compose_namespace {
   return $schema;
 }
 
-=head2 setup_connection_class <$target> <@info>
+=head2 setup_connection_class
+
+=head3 Arguments: <$target> <@info>
 
 Sets up a database connection class to inject between the schema
 and the subclasses the schema creates.
@@ -299,7 +337,9 @@ sub setup_connection_class {
   $target->connection(@info);
 }
 
-=head2 connection(@args)
+=head2 connection
+
+=head3 Arguments: (@args)
 
 Instantiates a new Storage object of type storage_type and passes the
 arguments to $storage->connect_info. Sets the connection in-place on
@@ -309,25 +349,156 @@ the schema.
 
 sub connection {
   my ($self, @info) = @_;
+  return $self if !@info && $self->storage;
   my $storage_class = $self->storage_type;
   $storage_class = 'DBIx::Class::Storage'.$storage_class
     if $storage_class =~ m/^::/;
   eval "require ${storage_class};";
-  $self->throw_exception("No arguments to load_classes and couldn't load".
-      " ${storage_class} ($@)") if $@;
+  $self->throw_exception(
+    "No arguments to load_classes and couldn't load ${storage_class} ($@)"
+  ) if $@;
   my $storage = $storage_class->new;
   $storage->connect_info(\@info);
   $self->storage($storage);
   return $self;
 }
 
-=head2 connect(@info)
+=head2 connect
+
+=head3 Arguments: (@info)
 
 Conveneience method, equivalent to $schema->clone->connection(@info)
 
 =cut
 
-sub connect { shift->clone->connection(@_) };
+sub connect { shift->clone->connection(@_) }
+
+=head2 txn_begin
+
+Begins a transaction (does nothing if AutoCommit is off).
+
+=cut
+
+sub txn_begin { shift->storage->txn_begin }
+
+=head2 txn_commit
+
+Commits the current transaction.
+
+=cut
+
+sub txn_commit { shift->storage->txn_commit }
+
+=head2 txn_rollback
+
+Rolls back the current transaction.
+
+=cut
+
+sub txn_rollback { shift->storage->txn_rollback }
+
+=head2 txn_do
+
+=head3 Arguments: $coderef, @coderef_args?
+
+Executes C<$coderef> with (optional) arguments C<@coderef_args>
+transactionally, returning its result (if any). If an exception is
+caught, a rollback is issued and the exception is rethrown. If the
+rollback fails, (i.e. throws an exception) an exception is thrown that
+includes a "Rollback failed" message.
+
+For example,
+
+  my $author_rs = $schema->resultset('Author')->find(1);
+
+  my $coderef = sub {
+    my ($author, @titles) = @_;
+
+    # If any one of these fails, the entire transaction fails
+    $author->create_related('books', {
+      title => $_
+    }) foreach (@titles);
+
+    return $author->books;
+  };
+
+  my $rs;
+  eval {
+    $rs = $schema->txn_do($coderef, $author_rs, qw/Night Day It/);
+  };
+
+  if ($@) {
+    my $error = $@;
+    if ($error =~ /Rollback failed/) {
+      die "something terrible has happened!";
+    } else {
+      deal_with_failed_transaction();
+    }
+  }
+
+Nested transactions work as expected (i.e. only the outermost
+transaction will issue a txn_commit on the Schema's storage), and
+txn_do() can be called in void, scalar and list context and it will
+behave as expected.
+
+=cut
+
+sub txn_do {
+  my ($self, $coderef, @args) = @_;
+
+  ref $self or $self->throw_exception
+    ('Cannot execute txn_do as a class method');
+  ref $coderef eq 'CODE' or $self->throw_exception
+    ('$coderef must be a CODE reference');
+
+  my (@return_values, $return_value);
+
+  $self->txn_begin; # If this throws an exception, no rollback is needed
+
+  my $wantarray = wantarray; # Need to save this since the context
+			     # inside the eval{} block is independent
+			     # of the context that called txn_do()
+
+  eval {
+    # Need to differentiate between scalar/list context to allow for
+    # returning a list in scalar context to get the size of the list
+
+    if ($wantarray) {
+      # list context
+      @return_values = $coderef->(@args);
+    } elsif (defined $wantarray) {
+      # scalar context
+      $return_value = $coderef->(@args);
+    } else {
+      # void context
+      $coderef->(@args);
+    }
+    $self->txn_commit;
+  };
+
+  if ($@) {
+    my $error = $@;
+
+    eval {
+      $self->txn_rollback;
+    };
+
+    if ($@) {
+      my $rollback_error = $@;
+      my $exception_class = "DBIx::Class::Storage::NESTED_ROLLBACK_EXCEPTION";
+      $self->throw_exception($error)  # propagate nested rollback
+	if $rollback_error =~ /$exception_class/;
+
+      $self->throw_exception(
+        "Transaction aborted: $error. Rollback failed: ${rollback_error}"
+      );
+    } else {
+      $self->throw_exception($error); # txn failed but rollback succeeded
+    }
+  }
+
+  return $wantarray ? @return_values : $return_value;
+}
 
 =head2 clone
 
@@ -347,18 +518,20 @@ sub clone {
   return $clone;
 }
 
-=item populate($moniker, \@data);
+=head2 populate
+
+=head3 Arguments: ($moniker, \@data);
 
 Populates the source registered with the given moniker with the supplied data.
 @data should be a list of listrefs, the first containing column names, the
 second matching values - i.e.
 
-$schema->populate('Foo', [
-  [ qw/foo_id foo_string/ ],
-  [ 1, 'One' ],
-  [ 2, 'Two' ],
-  ...
-]);
+  $schema->populate('Artist', [
+    [ qw/artistid name/ ],
+    [ 1, 'Popular Band' ],
+    [ 2, 'Indie Band' ],
+    ...
+  ]);
 
 =cut
 
@@ -366,14 +539,16 @@ sub populate {
   my ($self, $name, $data) = @_;
   my $rs = $self->resultset($name);
   my @names = @{shift(@$data)};
+  my @created;
   foreach my $item (@$data) {
     my %create;
     @create{@names} = @$item;
-    $rs->create(\%create);
+    push(@created, $rs->create(\%create));
   }
+  return @created;
 }
 
-=item throw_exception
+=head2 throw_exception
 
 Defaults to using Carp::Clan to report errors from user perspective.
 
@@ -384,6 +559,21 @@ sub throw_exception {
   croak @_;
 }
 
+=head2 deploy (EXPERIMENTAL)
+
+Attempts to deploy the schema to the current storage using SQL::Translator.
+
+Note that this feature is currently EXPERIMENTAL and may not work correctly
+across all databases, or fully handle complex relationships.
+
+=cut
+
+sub deploy {
+  my ($self, $sqltargs) = @_;
+  $self->throw_exception("Can't deploy without storage") unless $self->storage;
+  $self->storage->deploy($self, undef, $sqltargs);
+}
+
 1;
 
 =head1 AUTHORS