The TransactionManager (also called _TM_ in this document) is just another Q2
Service, but it is such an important component in most jPOS based applications
that it stands out, deserving its own chapter.

jPOS is typically used to implement mission-critical applications that
have to carefully deal with error conditions.

When you access a web page and a transient network error occurs,
you just hit the *reload* button on your browser. By contrast, a complex 
financial transaction involves a lot of activities such as contacting remote 
hosts, notifying risk management systems, placing holds in cardholder's credit
accounts, database logging, etc. 

So, if something goes wrong or your system just dies due to a power failure,
it's more complicated than simply hitting the *reload* button: you have to reverse 
the impact of whatever actions had been taken up to the failure point.

The +org.jpos.transaction+ package - along with the Q2-based *TransactionManager*
implementation - provides a framework and set of components that can assist dealing
with the previous scenario. This combination also fosters code reuse and 
_componentization_.

[NOTE]
======
This doesn't mean a jPOS based application needs to use the TransactionManager.
It's proven, it's fast, it's reliable, we are aware of use cases where the TM is used to
process millions of transactions per day, we @jposconsulting use it in most of 
our applications, but it's up to you to use it or not.
======

The key class is the 
link:http://jpos.org/doc/javadoc/org/jpos/transaction/TransactionParticipant.html[TransactionParticipant]
that exposes the following interface:

[source,java]
-------------

    public interface TransactionParticipant extends TransactionConstants {
        public int  prepare (long id, Serializable context);
        public void commit  (long id, Serializable context);
        public void abort   (long id, Serializable context);
    }


   // the TransactionConstants interface provides the following definitions:
  
    public interface TransactionConstants {
        public static final int ABORTED  = 0;
        public static final int PREPARED = 1;
        public static final int RETRY    = 2;
        public static final int PAUSE    = 4;
        public static final int NO_JOIN  = 0x40;
        public static final int READONLY = 0x80;
    }

-------------

[NOTE]
======
As of jPOS 2.1.0 the `commit` and `abort` methods have default
implementations so they don't have to be called in situations
where `prepare` returns the `NO_JOIN` modifier.
======

The TransactionManager implementation _drives_ the transaction by calling all of its 
participants' +prepare+ method. If all of them return +PREPARED+ (indicating that
they are ready to proceed with the transaction), then the transaction moves
to the _COMMITTING_ phase, at which point the TransactionManager will call all of the 
participants' +commit+ method.

If one of the participants' +prepare+ method returns +ABORTED+, then the transaction
moves into an _ABORTING_ phase, and all the participants previously called to get
prepared will get a call to their +abort+ method.

