Added GroupSelector + minor edits

doc/src/asciidoc/ch09/abort_participant.asc

@@ -1,6 +1,6 @@
 == AbortParticipant
 
-Imagine you have a list of participants that conform a transaction, for example:
+Imagine you have a list of participants that define a transaction, for example:
 
 * +ValidateMessage+ (sanity checks)
 * +FetchData+ (i.e. get Terminal/Merchant info from database)

doc/src/asciidoc/ch09/group_selector.asc

@@ -0,0 +1,141 @@
+== GroupSelector
+
+Having a configuration like this: 
+[source,xml]
+------
+  <txnmgr ...>
+   <participant A />
+   <participant B />
+   <participant C />
+   <participant D />
+   ...
+  </txnmgr>
+------
+
+may be good for some small applications, but you risk ending up having to
+configure multiple transaction managers for different classes of transactions
+(e.g., network management, authorization, draft capture, etc.) or add
+complexity to participants in order to operate or do nothing depending
+in the transation type.
+
+In order to simplify the TransactionManager configuration, we've added a very
+simple interface called +GroupSelector+: 
+
+[source,java]
+-------------
+
+    public interface GroupSelector extends TransactionParticipant {
+        public String select (long id, Serializable context);
+    }
+
+-------------
+
+A participant implementing the +GroupSelector+ interface can modify the flow of
+a transaction by returning a space-separated list of group names (or can
+specify 'null' to signify no action). 
+
+Our Q2-based TransactionManager reference implementation supports this
+interface and lets you design your own configuration file with a structure
+like this: 
+
+[source,xml]
+------------
+
+  <txnmgr ...>
+   <participant A />
+   <participant B />
+   ...
+   ...
+   <group name="GroupA">
+    <participant A />
+    <participant B />
+    <participant C />
+   </group>
+   <group name="GroupB">
+    <participant J />
+    <participant K />
+    <participant L />
+   </group>
+   <group name="GroupC">
+    <participant X />
+    <participant Y />
+    <participant Z />
+   </group>
+   ...
+   ...
+  </txnmgr>
+------------
+
+.Sample GroupSelector implementation
+====
+[source,java]
+----
+
+    public class Switch implements GroupSelector {
+        public int  prepare (long id, Serializable context) {
+            return PREPARED | READONLY | NO_JOIN;
+        }
+        public void commit   (long id, Serializable context) { }
+        public void abort    (long id, Serializable context) { }
+        public String select (long id, Serializable context) {
+            try {
+                ISOMsg m = (ISOMsg) ((Context)context).get (ISOMSG);
+                String groups = cfg.get (m.getMTI(), null);
+                return groups;
+            } catch (Exception e) {
+                warn (e);
+                return null;
+            }
+        }
+    }
+
+----
+====
+
+By using the +Switch+ presented in the previous example, you can write a
+TransactionManager configuration file like this: 
+
+[source,xml]
+----
+   ...
+   ...
+   <participant class="org.jpos.my.Switch" logger="Q2">
+    <property name="0100" value="Authorization Response Log" />
+    <property name="0200" value="Financial Response Log" />
+    <property name="0220" value="Notification Response Log" />
+    <property name="0221" value="Notification Response Log" />
+    <property name="0420" value="Reversal Response Log" />
+    <property name="0421" value="Reversal Response Log" />
+    <property name="0500" value="BatchManagement Response Log" />
+    <property name="0421" value="Reversal Response Log" />
+    <property name="0800" value="NetworkManagement Response Log" />
+   </participant>
+   ...
+   ...
+   <group name="Financial">
+    <participant class="com.my.company.CheckRequiredFields">
+     <property name="fields" value="0,3,4,17,49,32,41,43,37,PAN,AMOUNT" />
+    </participant>
+    <participant class="com.my.company.CheckCurrency" />
+    ...
+    ...
+   </group>
+
+   <group name="Reversal">
+    ...
+    ...
+   </group>
+   ...
+   ...
+
+----
+
+Using the previous approach, the application can be designed using small
+reusable participants. 
+
+
+We have found it very useful to have very small participants to peform tasks
+like: Debug the context; introduce Delays (during testing); Open  and Close 
+O/R mapping sessions, etc. 
+
+

doc/src/asciidoc/ch09/transaction_manager.asc

@@ -1,4 +1,4 @@
-== TransactionManager
+== TransactionManager implementation
 
 The +TransactionManager+ is a jPOS Service that monitors a Space queue waiting
 for transactions to be processed. These transactions are expected to be
@@ -210,6 +210,9 @@ sessions. In order to place a cap on the number of in-flight transactions
 to avoid exhausting resources (for example a JDBC pool), this
 `max-active-sessions` property can be set. The default is 0.
 
+* *call-selector-on-abort* +
+
+
 [TIP]
 =====
 If you're _pausing_ your transactions, please read the previous paragraph

doc/src/asciidoc/master.asc

@@ -80,6 +80,7 @@ include::ch09/context.asc[]
 include::ch09/context_recovery.asc[]
 include::ch09/assembly_line.asc[]
 include::ch09/abort_participant.asc[]
+include::ch09/group_selector.asc[]
 include::ch09/transaction_manager.asc[]
 
 //include::ch02.asciidoc[]