+__END__
+
+=pod
+
+=encoding utf8
+
+=head1 NAME
+
+SL::DB - Database access class for all RDB objects
+
+=head1 FUNCTIONS
+
+=over 4
+
+=item C<create $domain, $type>
+
+Registers the database information with Rose, creates a cached
+connection and executes initial SQL statements. Those can include
+setting the time & date format to the user's preferences.
+
+=item C<dbi_connect $dsn, $login, $password, $options>
+
+Forwards the call to L<SL::DBConnect/connect> which connects to the
+database. This indirection allows L<SL::DBConnect/connect> to route
+the calls through L<DBIx::Log4Perl> if this is enabled in the
+configuration.
+
+=item C<with_transaction $code_ref, @args>
+
+Executes C<$code_ref> with parameters C<@args> within a transaction,
+starting one only if none is currently active. Example:
+
+ return $self->db->with_transaction(sub {
+ # do stuff with $self
+ });
+
+There are two big differences between C<with_transaction> and
+L<Rose::DB/do_transaction>: the handling of an already-running
+transaction and the handling of return values.
+
+The first difference revolves around when a transaction is started and
+committed/rolled back. Rose's C<do_transaction> will always start one,
+then execute the code reference and commit afterwards (or roll back if
+an exception occurs).
+
+This prevents the caller from combining several pieces of code using
+C<do_transaction> reliably as results committed by an inner
+transaction will be permanent even if the outer transaction is rolled
+back.
+
+Therefore our C<with_transaction> works differently: it will only
+start a transaction if no transaction is currently active on the
+database connection.
+
+The second big difference to L<Rose::DB/do_transaction> is the
+handling of returned values. Basically our C<with_transaction> will
+return the values that the code reference C<$code_ref> returns (or
+C<undef> if the transaction was rolled back). Rose's C<do_transaction>
+on the other hand will only return a value signaling the transaction's
+status.
+
+In more detail:
+
+=over 2
+
+=item * If a transaction is already active then C<with_transaction>
+will simply return the result of calling C<$code_ref> as-is preserving
+context.
+
+=item * If no transaction is started then C<$code_ref> will be wrapped
+in one. C<with_transaction>'s return value depends on the result of
+that transaction. If the it succeeds then the return value of
+C<$code_ref> will be returned preserving context. Otherwise C<undef>
+will be returned in scalar context and an empty list in list context.
+
+=back
+
+So if you want to differentiate between "transaction failed" and
+"succeeded" then your C<$code_ref> should never return C<undef>
+itself.
+
+=back
+
+=head1 BUGS
+
+Nothing here yet.
+
+=head1 AUTHOR
+
+Moritz Bunkus E<lt>m.bunkus@linet-services.deE<gt>
+
+=cut