work on Configuration section

doc/src/asciidoc/ch09/transaction_manager.asc

@@ -35,6 +35,29 @@ transaction manager appropriately sets before calling a participant, but *never
 ever* in member variables.  
 ===========
 
+=== TM use of spaces
+
+The TransactionManager uses 3 different spaces for operation.
+
+We see in the previous diagram that the producer (depicted as 'client' in the
+image) places entries in a Space, to be consumed by the TransactionManager.
+
+This can be the general purpose _default_ space (`tspace:default`), but in 
+high demanding environments, it is possible to define a separate space,
+defined as `input-space`.
+
+Internally, it also needs a transient space to keep track of the in-flight
+transactions. Again, if not specified, the TransactionManager will use
+`tspace:default`, but it is possible to configure a separate space for
+that using the `space` property in the XML configuration file.
+
+For recovery purposes, a persistent space (defined with the property
+`persistent-space`) is required, i.e.: `je:XXXX` (being XXXX the name
+of the space). But taking snapshots to disk reduces the TM speed by
+probably an order of magnitude, and many applications that use the
+TransactionManager doesn't take advantage of its recovery features, 
+this space defaults to an internal space.
+
 === Configuration
 
 The TransactionManager is implemented by +org.jpos.transaction.TransactionManager+
@@ -83,6 +106,55 @@ This is the Space-based _queue_ where the TM looks for transactions to be proces
 As described above, these transactions are actually +Serializable+ objects, typically
 an instance of +org.jpos.transaction.Context+. This is a mandatary property.
 
+* *input-space* +
+This is the Space where the TransactionManager's sessions wait for transactions
+to be queued. It defaults to the default space returned by `SpaceFactory.getSpace()`
+that is currently set to `tspace:default`, but can vary.
+
 * *space* +
+Space used by the TransactionManager to handle in-flight transactions. The TM uses
+a Space-based circular queue. This Space also uses the system's default, but
+in high load systems it is reasonable to consider using a unique space for
+each TransactionManager.
+
++ *persistent-space* +
+If the application takes advantage of crash recovery features, a persistent
+space has to be defined. It can be any persistent space, such as `jdbm` or
+the more robust `je` based spaces (i.e. `je:mytm:/path/to/mytm`).
+
++ *recover* +
+When the TransactionManager starts, it checks the persistent space for 
+in-flight transactions from a previous run. If this feature is not being
+used, it is recommended to set `recover` to false (although it doesn't hurt
+to keep it on in most situations).
+
++ *debug* +
+If true, the TransactionManager log a small report after each transaction
+indicating which participants took place. The log looks like this:
 
+[source,xml]
+------------
+<log realm="org.jpos.transaction.TransactionManager" at="Sun Feb 12 22:47:39 UYST 2012.725" lifespan="23ms">
+  <debug>
+    txnmgr-1:2
+            prepare: org.jpos.jcard.PrepareContext NO_JOIN
+            prepare: org.jpos.jcard.CheckVersion READONLY NO_JOIN
+            prepare: org.jpos.transaction.Open READONLY NO_JOIN
+            prepare: org.jpos.jcard.Switch READONLY NO_JOIN
+      groupSelector: notsupported prepareresponse close sendresponse
+            prepare: org.jpos.jcard.NotSupported NO_JOIN
+            prepare: org.jpos.jcard.PrepareResponse NO_JOIN
+            prepare: org.jpos.transaction.Close READONLY
+            prepare: org.jpos.jcard.SendResponse READONLY
+            prepare: org.jpos.jcard.ProtectDebugInfo READONLY
+            prepare: org.jpos.transaction.Debug READONLY
+             commit: org.jpos.transaction.Close
+             commit: org.jpos.jcard.SendResponse
+             commit: org.jpos.jcard.ProtectDebugInfo
+             commit: org.jpos.transaction.Debug
+    head=3, tail=3, outstanding=0, active-sessions=2/2, tps=0, peak=0, 
+    avg=0.00, elapsed=22ms
+  </debug>
+</log>
+------------