NAME

       UR::Context::Transaction - API for software transactions

SYNOPSIS

         my $o = Some::Obj->create(foo => 1);
         print "o's foo is ",$o->foo,"\n";  # prints 1

         my $t = UR::Context::Transaction->begin();

         $o->foo(4);

         print "In transaction, o's foo is ",$o->foo,"\n";  # prints 4

         if (&should_we_commit()) {
             $t->commit();
             print "Transaction committed, o's foo is ",$o->foo,"\n";  # prints 4

         } else {
             $t->rollback();
             print "Transaction rollback, o's foo is ",$o->foo,"\n";  # prints 1
         }

DESCRIPTION

       UR::Context::Transaction instances represent in-memory transactions as a diff of the
       contents of the object cache in the Process context.  Transactions are nestable.  Their
       instances exist in the object cache and  are subject to the same scoping rules as other
       UR-based objects, meaning that they do not disappear mearly because the lexical variable
       they're assigned to goes out of scope.  They must be explicitly disposed of via the commit
       or rollback methods.

INHERITANCE

       UR::Context::Transaction is a subclass of UR::Context

CONSTRUCTOR

       begin
             $t = UR::Context::Transaction->begin();

           Creates a new software transaction context to track changes to UR-based objects.  As
           all activity to objects occurs in some kind of transaction context, the newly created
           transaction exists within whatever context was current before the call to begin().

METHODS

       commit
             $t->commit();

           Causes all objects with changes to save those changes back to the underlying context.

       rollback
             $t->rollback();

           Causes all objects with changes to have those changes reverted to their state when the
           transaction began.  Classes with properties whose meta-property is_transactional => 0
           are not tracked within a transaction and will not be reverted.

       delete
             $t->delete();

           delete() is a synomym for rollback

       has_changes
             $bool = $t->has_changes();

           Returns true if any UR-based objects have changes within the transaction.

       get_changes
             @changes = $t->get_changes();

           Return a list or UR::Change objects representing changes within the transaction.

CLASS METHODS

       eval
             UR::Context::Transaction::eval BLOCK

           Executes the BLOCK (with no arguments) wrapped by a software transaction and a
           CORE::eval.  If the BLOCK dies then the exception is caught and the software
           transaction is rolled back.

       do
             UR::Context::Transaction::do BLOCK

           Executes the BLOCK (with no arguments) wrapped by a software transaction and a
           CORE::eval.  If the BLOCK returns a true value and does not die then the software
           transaction is committed.  If the BLOCK returns false or dies then the software
           transaction is rolled back.

           If the BLOCK throws an exception, it will be caught, the software transaction rolled
           back, and the exception will be re-thrown with die().

SEE ALSO

       UR::Context