Home
In jPos, the transaction manager component takes care of driving the transaction. To do so, it relies on smaller units called participants. Participants are components through which the transaction flow may pass. Thus, the jPos transaction manager implementation design enhances code reuse and componentization. The transaction manager provides also some routing functionalities thanks to the org.jpos.transaction.GroupSelector interface. Transaction manager is configured via a dedicated XML configuration. See jPOS programmer's guide §10 for more details.
The way a transaction is processed may vary, depending on many criteria. For instance, the transaction type (activation, payment, cancellation ...) may change the way the transaction should be processed. Also, further in the processing, you may have to choose between different processing paths depending on many criteria : card's validity check result, acquirer response (acceptation, reject), ...
When wondering how to efficiently work on transaction manager configuration, and thinking about a process allowing to work incrementally on it so that it can easily be communicated to other people (maybe more business oriented people), one can not simply answer : edit transaction manager's XML configuration and it's done.
Having a graphical view would be much more talkative. Besides, a graphical representation (say a diagram state representation for instance) is easier to communicate to non developer people. Editing a workflow in an UML editor is a solution, but edition work needs to be done twice. And what if the workflow often changes ? This is not a very responsive process, with the risk to loose informations. Eventually, it would be nice if we were able to generate a graphical view on the fly (and at will) straight from the XML transaction manager configuration itself.
Thinking of a graphical representation as a state diagram along its states and transitions, there would be the transaction participants as states . But what about transitions? Nothing in a transaction manager configuration formally identifies transitions between a participant and a group. But, taking a further look at §10.8 of jPOS programmer's guide, the configuration sample clearly shows that some properties are used for this purpose and hold a transition function. In this sample, we can see properties which gives a list of groups to pass through, depending on the message type (0100, 0200,...). Obviously, theses properties can be used as transitions.
...
<participant class="org.jpos.my.Switch" logger="Q2">
< !--
If MTI is 0100, route to the following participants groups :
- Authorization,
- Response,
- Log
-- >
<property name="0100" value="Authorization Response Log" />
< !--
If MTI is 0200, route to the following participants groups :
- Financial,
- 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>
...
Keeping all of this in mind, a specific Eclipse plugin has been written which at this point provides :
- conversion of a transaction manager configuration into a directed graph model,
- reduction of the previously generated directed graph,
- graphical view of the reduced graph in a dedicated Eclipse editor,
- image export of Eclipse view (JPG, PNG),
- GraphViz format export (DOT) for enhanced rendering
- keep the transaction participants as atomic as possible,
- clearly identify transitions properties. In order for the plugin to work, those properties should be formally marked with a special attribute named selectCriterion , whose value should briefly describe the transition,
- avoid circular references
File /deploy/20_txnmgr.xml
<!DOCTYPE SYSTEM [ <!ENTITY Financial SYSTEM "Financial.inc"> ]> <txnmgr name="kdoTxn" logger="Q2" class="org.jpos.transaction.TransactionManager"> <participant class="org.jpos.my.Switch" logger="Q2"> <property name="0200" value="Financial Response Log" selectCriterion="incoming message 0200" /> <property name="0100" value="Authorization Response Log" selectCriterion="incoming message 0100" /> <property name="0220" value="Notification Response Log" selectCriterion="incoming message 0220" /> <property name="0221" value="Notification Response Log" selectCriterion="incoming message 0221" /> <property name="0420" value="Reversal Response Log" selectCriterion="incoming message 0420" /> <property name="0421" value="Reversal Response Log" selectCriterion="incoming message 0421" /> <property name="0500" value="BatchManagement Response Log" selectCriterion="incoming message 0500" /> <property name="0800" value="NetworkManagement Response Log" selectCriterion="incoming message 0800" /> </participant> &Financial; </txnmgr>
File /deploy/Financial.inc
<group name="Financial"> <participant class="org.jpos.jposext.jposworkflow.sample.participant.CheckRequiredFields"> <property name="fields" value="0,3,4,17,49,32,41,43,37,PAN,AMOUNT" /> <property name="ok" value="Financial_Suite1" selectCriterion="checked" /> <property name="nok" value="" selectCriterion="unchecked" /> </participant> </group> <group name="Financial_Suite1"> <participant class="org.jpos.jposext.jposworkflow.sample.participant.CheckCurrency"> <property name="ok" value="Financial_Suite2" selectCriterion="checked" /> <property name="nok" value="" selectCriterion="unchecked" /> </participant> </group> <group name="Financial_Suite2"> <participant class="org.jpos.jposext.jposworkflow.sample.participant.FinancialProcessingSuite" /> </group>
After right-clicking configuration file 20_txnmgr.xml in the Eclipse Package Explorer view, menu items jPos Workflow -> view ... should show up.
Left-clicking one menu item should open a jPos Workflow view with a graphical representation of the selected configuration :
About this view :
- if somewhere in the transaction manager configuration, a non yet declared participant/group is referenced, its icon shows up in red color,
- transition informations can be seen by mouse over on information icons; if you have use context management annotations on your participant classes, thse informations also show up,
- double-clicking on a participant node may open the Java source of the associated participant class (provided it exists in your project),
- right clicking on jPos Workflow view, you may be able to export the graph as a DOT file (GraphViz format).
As the number of nodes and transitions may grow quickly, the Eclipse GEF graph layout at some point may become hardly readable; consider then using the DOT export function for a further GraphViz rendering.
Here is the generated DOT source after such export :
digraph "JPos Workflow Eclipse Plugin DOT Export" {
node [shape="box" peripheries="1" style="filled" color="#000000" fillcolor="#FFFFCE" fontname="Arial" fontsize="10"]
n1 [label="Switch"]
n23 [label="Log:<undefined>"]
n22 [label="Response:<undefined>"]
FINAL [label="" shape="circle" peripheries="2" style="filled" color="#000000" fillcolor="#000000"]
n21 [label="Reversal:<undefined>"]
n3 [label="CheckCurrency"]
n2 [label="CheckRequiredFields"]
n9 [label="Notification:<undefined>"]
n6 [label="NetworkManagement:<undefined>"]
INITIAL [label="" shape="circle" peripheries="1" style="filled" color="#000000" fillcolor="#000000"]
n24 [label="Authorization:<undefined>"]
n15 [label="BatchManagement:<undefined>"]
edge [fontname="Arial" fontsize="8" dir="forward" arrowhead="normal"]
n3 -> n22 [label=""]
n22 -> n23 [label=""]
n6 -> n22 [label=""]
n1 -> n9 [label="incoming message 0221"]
n15 -> n22 [label=""]
n21 -> n22 [label=""]
n9 -> n22 [label=""]
n1 -> n21 [label="incoming message 0420"]
n1 -> n6 [label="incoming message 0800"]
n1 -> n15 [label="incoming message 0500"]
n23 -> FINAL [label=""]
n1 -> n24 [label="incoming message 0100"]
n24 -> n22 [label=""]
INITIAL -> n1 [label=""]
n1 -> n2 [label="incoming message 0200"]
n2 -> n3 [label=""]
}
and here is GraphViz rendering of this DOT source :
You may install the Eclipse GraphViz plugin for rendering inside your Eclipse IDE.
When jPos transaction manager configuration is growing, jPos users naturally tend to extract participants into external entities. From a user point of view, doing so eases the configuration reading and maintenance.
When a jPos transaction manager configuration becomes consequent and the number of different possible paths is exponentially growing, the plugin execution time may increase, and may even become unacceptable.
It then becomes necessary to go for a "divide to rule" approach and identify in this big/all-mixed-up configuration if some parts could be identified as subflows and extracted into external entities.
The plugin approach of a subflow is :
- a subflow should be seen as a set of participant groups, with one group identified as the subflow entry point,
- when the subflow job is done, it simply stops, implicitely giving the control back to its parent flow,
- a subflow shouldn't reference a group of its parent flow; still, it may at some point give the control to another subflow by reference this latter's entrypoint group.
For the plugin to correctly handle external entities as subflows, your configuration should be respectful of the following rules.
There's a tight connection between :
- the external entity name (i.e.
Financial.inc), - the entity reference name (i.e.
&Financial;), - the subflow entry point group name (i.e.
<group name="Financial">)
- choose a subflow-name for your subflow,
- ensure your external entity file is subflow-name with a
.incfile extension, - in your external entity file, ensure your entry point group is named subflow-name,
This is more a design advice than a real rule. Implicitely means here that when the subflow is done, it shouldn't reference a group of its parent flow, but should simply stops.
In case you have a GroupSelector with one transition that should do nothing but return to the parent flow, just let this transition value empty. Here is an example with group Financial_Suite1 and its transition nok :
<group name="Financial_Suite1"> <participant class="org.jpos.jposext.jposworkflow.sample.participant.CheckCurrency"> <property name="ok" value="Financial_Suite2" selectCriterion="checked" /> <property name="nok" value="" selectCriterion="unchecked" /> </participant> </group>
Another strategy is : for each subflow, get a dedicated group (name it your-subflow-nameEndPoint), wrapping a generic TransactionParticipant (not GroupSelector) that barely does nothing, and get your subflow participants redirect to it when there's nothing more to be done.
The Eclipse plugin provides now two modes.
When choosing the view graph (entity refs as subflows) menu item, the plugin will parse the transaction manager configuration and convert it into a(some) graph(s), considering all external entity references as subflows, and therefore converting them in independent (well not that much independent really) graphs. Computations times should then improve.
When the main graph is showed in Eclipse editor, clicking on any nodes referencing a subflow will open a further Eclipse editor in wich the associated subflow graph will be shown. And so on ... You can then navigate from parents to childs flows.
Note that on a subflow opening, context management informations available at this particular point of the parent flow are inherited by the subflow graph.
When choosing the view graph (expanded) menu item, external entity references will be expanded when parsing the transaction manager configuration. Therefore no subflows will be identified, graph should show up in one Eclipse editor only.
Context management annotations are intented to be used on participant classes (implementing jPos TransactionParticipant or GroupSelector interfaces). In a few words, these annotations are a way to specify which context attributes a participant may set while being processed.
If your participant classes use such annotations, the plugin detects it and extracts context management specifications from them.
More information available on the context management annotations project wiki page.
Mousing over a transition edge, it lists the context attributes set by parent node when this transition has been selected.
Mousing over a ok transition binding source node CheckRequiredFields to target node CheckCurrency :
Mousing over a simple participant node of the flow, the plugin lists the available context attributes at that particular point of the flow : depending on the path that leads to that point, some context attributes presence may be guaranteed (
mark), and some others may be or may not be present (
mark).
Mousing over a CheckCurrency participant node :
Now, as the graph is reduced (common branches of the original graph tree are merged as much as possible), looking to the end of the workflow of our switch transaction manager configuration above, we can see just one Response participant with a transition to one Log participant. That's because this part is common to every processing (authorization, notification, financial, reversal, ...). Looking back at the beginning of the flow, the authorization processing may put some particular attributes in the context whereas the notification processing may put some others. And maybe they also both share some commons attributes in the process.
Mousing over the late transition of the workflow, plugin shows not only the common attributes guaranteed to be set in the context, but also the ones that may be set somewhere in the parent branches. Special marks distinguish guaranteed attributes from non-guaranteed ones.
Mousing over the Response participant :
Such info may reveal helpful at development phase, when one of your participant need to get one attribute from the context, and you want to make sure this attribute is set at that particular point of the flow.
- jpos-workflow-commons : a common library providing jPos transaction manager configuration to graph(s) conversion facilities; actually used by this Eclipse plugin; can surely be used to create an IntelliJ IDEA plugin using its open graph API,
- jpos-workflow-cli : an alternative to this Eclipse plugin. Implemented as a jPos CLI command, it converts a jPos transaction manager configuration to DOT graph(s) you can further vizualize through graphviz or convert to other formats (SVG, ...),
- context-mgmt-annotation : annotations for context management