Contents

ISO 8583 ........................................................................................................................................................ 2 Message Type ISO 8583 ................................................................................................................................ 2 Message Type Indicator ........................................................................................................................ 2 ISO 8583 version ................................................................................................................................... 3 Message Class ....................................................................................................................................... 3 Message Function ................................................................................................................................. 4 Message Origin ..................................................................................................................................... 4 Examples of Message Type Indicator.................................................................................................... 5 Bitmap ........................................................................................................................................................... 5 How to Calculate Bitmap ...................................................................................................................... 6 Data Element ................................................................................................................................................ 8 JPOS............................................................................................................................................................... 9 JPOS Components ......................................................................................................................................... 9 1. Create Data Elements (DE) types XML .............................................................................................. 9 2. ISOComponent ................................................................................................................................ 10 3. ISOPackager .................................................................................................................................... 11 4. ISOMsg ............................................................................................................................................ 12 5. ISOChannel ...................................................................................................................................... 14 6. Filters............................................................................................................................................... 14 7. NameRegistrar ................................................................................................................................ 14 8. ISOServer And ISOMUX ................................................................................................................... 15 9. ISOFieldPackagers ........................................................................................................................... 16 10. ISOSource ...................................................................................................................................... 16 11. SystemMonitor ............................................................................................................................. 16 12. Logger............................................................................................................................................ 16 13. ChannelAdaptor ............................................................................................................................ 17 14. QMUX ............................................................................................................................................ 18 15. QServer ......................................................................................................................................... 19 16. TransactionManager ..................................................................................................................... 19

JPOS Deploy Directory Elements in JPOS-EE ............................................................................................... 21 Sample Server-Client Simulator Example ................................................................................................... 22

ISO 8583
ISO 8583 is an international standard for financial transactions. It is a standard or protocol has long been used by banks to bridge the communication, the presence of a communication standard like this then it is possible to still do the transaction between related parties though using the system or different programming languages. The use of ISO 8583 can be seen clearly in the EDC machines. In addition to the EDC, the use of ISO 8583 is also widely applied to the communication between banks or between Switcher with Biller.

Message Type ISO 8583

ISO 8583 is actually divided into 3 parts: 1. Message Header, it can be used as an early marker of a message. 2. Application Data, these are the core of ISO 8583. All formats and message definitions contained in this section. 3. Message Trailer, can be used as a marker of the end of a message. In some cases, sometimes in every message we just found the use of Message Header or Trailer only. Use Message Header and Message Trailer are entirely up to each interested party and this information there should be written clearly on the technical specification document was discussed and agreed upon by either parties or more. Because the Message Header and Message Trailer only used as a marker only, so now let's talk about what is contained in the Application Data is ISO 8583. Application Data is also divided into sections more or less as follows. 1. MTI (Message Type Indicator): It is a 4-digit code that is used as a marker of the beginning of the main ISO 8583 message. 2. Bitmap: It is 8 bytes of data binaries or 16 digit hexadecimal values that is used as marker bits or data elements which are active. (16 digits here is the standard length of the Primary Bitmap only). 3. DE (Data Element): It is the bits that contain the actual information on the transaction itself.

Message Type Indicator

MTI consists of 4 digit code that is used as the primary initial ISO 8583 message itself. MTI is itself divided into as shown below. 1. 2. 3. 4. First Digit ISO 8583 version Second Digit Message Class Third Digit Function of the Message Fourth Digit Who began the communication

As a simple example, MTI 0110 can be explained as follows:

For more details, let us now enter into the discussion of each component contained in the MTI.

ISO 8583 version

The first digit of the MTI is used as a marker of ISO 8583 version used. While the version contained in ISO 8583 are as follows:

Message Class
The second digit of the MTI is used for what purpose was the message in its entirety. And the code or standard values used to populate the second digit can be seen in the below table.

Message Function
The third digit of the MTI is used to define the function of a message does it request, response or advice. And the code or standard value used to fill the third digit can be seen in the below table:

Message Origin
The last digit of the MTI is used to define where the message originated (sender location). And the code or standard value used to fill this digit can be seen in the below table:

Examples of Message Type Indicator

After knowing each component found in MTI, now let's look at some examples of MTI that standard used as the table below (though not all MTI implementation of ISO 8583 has the same meaning and the meaning):

Bitmap
The second component of the Application Data contained in ISO 8583 is a Bitmap. Bitmap is a component that has a length of 16 characters (or more, depending on whether the Secondary or Tertiary Bitmap active or not) in hexadecimal, and values contained in this bitmap be used to represent a field or Data Element is active or not. An ISO 8583 more or less the message must have a bitmap commonly referred to as the Primary Bitmap, which indicates that the Data Element 1 to 64 active. While Secondary Bitmap appear if Data Element 65 to 128 active, as well as for Tertiary / Third Bitmap used if Data Element 129 to 192 active though rarely a message to use Bitmap Tertiary. This bitmap 8 bytes of data can be binary or 16 character hexadecimal 0-9, AF in ASCII or EBCDIC character, a field or Data Element will be active if the value is TRUE bitmap (marked with a value of 1). As for the field or Data Element is not active, it will be worth FALSE (marked with a value of 0 [zero]) on the bitmap.

How to Calculate Bitmap

To calculating a Bitmap there are some important points that should always be remembered when they want to read or create a Bitmap. The key points to note are:There are 3 kinds of Bitmap, namely:1. Primary Bitmap: All ISO 8583 message must have this. Field or Data Element is active is 1-64. 2. Secondary Bitmap: It is used if the field or current Data Element is 65-128. The characteristic of the Secondary Bitmap is the first bit of the bitmap PRIMARY definitely worth the 1 or TRUE. 3. Tertiary / Third Bitmap, is used if the field is active or Data Element is 129-192. The identity of the Tertiary / Third Bitmap is the active field or Data Element to 65. The entire field or Data Element that WILL NOT ACTIVE VALUE 0 (ZERO / FALSE) AND FOR THE ACTIVE BE WORTH 1 (TRUE) Bitmap can contain 8 bytes of binary data, or 16 hexadecimal characters (0-9 and A-F) in ASCII or EBCDIC (see the explanation of the following information). To determine where the field or Data Element is active, we have to convert the hexadecimal value to binary. If the first message is active only Primary Bitmap only, then the length is 64 bits Bitmap. Where the Primary Bitmap = 8 Byte or 64 Bit (Note 1 byte = 8 bits). If the Secondary Bitmap active, then the length will be 128 bit or it could be called a 32 character hexadecimal. See below conversion table which will make as a reference to determine the field or Data Element which is active

All the equipment is ready, now what if we have a Bitmap like this 5030004100010000? Data Element Field or what is to be active? To calculate it, now solve 16 digits Bitmap into each 2-digit and 1 digit hexadecimal convert each into a binary value as below:

The series Bitmap in Binary

From the table above, we've been able to move on the field or Data Element whichever is active. And because the Bitmap above us see no Secondary Bitmap then we will check from field 1 to 64. And the end result of the field or the current Data Element is as follows:

How to find or identify the Secondary Bitmap? The easiest way is identifying its first digit after the 4 digit MTI (the first character of the bitmap), when converted to binary digits beginning its definitely worth 1 (TRUE) and if its value is 1 (TRUE) Bitmap so long to be taken is 32 characters for the purposes of notice or data Element field is active. For example, now let's add some fields or Data Element we have seen above becomes as follows:

Sample Data Element With Secondary Bitmap After knowing the Data Element is active, now let's convert it into a Bitmap to fill the 0 (zero) for the Data Element is not active, and 1 (one) for the Data Element is active. And its results to be approximately as follow: Now of binary values that we get, convert a hexadecimal value and we will get more value for less Bitmap results will be as shown below:

Data Element
Data Element is actually an entire core of the message contained in the ISO 8583, due to the Data Element is the information content of transactions carried out will actually be sent over the network using the ISO 8583 protocol. There are 128 Data Element in the standard ISO 8583 version 1987, while in the next version of the ISO 8583 version 1993 up to 192. Data Element can be assumed as a set of boxes as much as 128 or 192 pieces (depending on the version of ISO 8583 is used it), that each box has ARTI and FORMAT specified by the ISO 8583 standard. And so easy, look at the ISO 8583 Data Element can be described as shown below:

Representation of a Data Element Example Each Data Element has a data format are allowed for each content (such as numeric, binary or else it) and has the data length specified (either variable or fixed). While the format of data contained in the Data Element is presented in the table below:

Format Data in Data Element In addition to data format, each Data Element can have a data length can be determined fixed (permanent) or a variable. If the length of the Data Element determined variables, the Data Element shall be preceded by an indication of how long the data followed by the first and the truth. While the variable length format specified by the ISO 8583 standard can be seen in the table below:

JPOS
The JPOS supports multiple protocols commonly used in the implementation of ISO 8583.

JPOS internal representation of an ISO-8583 message is usually an ISOMsg object (or an

ISOMsg's subclass). In order to use JPOS there are some basic components we need to know are: Creating Data Elements types XML file or class file ISOComponent ISOPackager ISOChannel ISOServer and ISOMUX ISOMsg ISOFieldPackager

JPOS Components
1. Create Data Elements (DE) types XML
We need to tell JPOS how our DE will be formatted or packaged. We need to put all DE types whichever is needed for our application in an xml file. Structure of xml tags: <isofield id="[field id]" name="[field name]" length="[max field length]" class="[org.jpos.iso.IF_*]" pad="true|false"> </isofield> For example:DE type to MTI <isofield id="0" length="4" name="MESSAGE TYPE INDICATOR" class="org.jpos.iso.IFA_NUMERIC"/>

DE type to transaction the amount <isofield id="4" length="12" name="AMOUNT, TRANSACTION" class="org.jpos.iso.IFA_NUMERIC"/> The XML tag contains following attributes: id: the DE number length: the max/fixed length of the DE name: the name or description class: this define the type of the DE, which in this case represent by the JPOS class. For example:IFA_NUMERIC: Numeric Left padder with zeros. IFA_BITMAP: For ISO Bitmap IFA_LLCHAR: ASCII variable length CHAR 2 digit length info IFA_LLLCHAR: ASCII variable length CHAR 3 digit length info So this XML will be used for build (pack) ISO Message or parse (unpack) ISO Message. We need the XML data schema (genericpackager.dtd) to be put on same directory with xml file created above.

2. ISOComponent
ISOMsg, ISOField, ISOBitMapField, ISOBinaryField and any custom field type that you may implement are subclasses of ISOComponent. Let's have a look at ISOComponent's methods. public abstract class ISOComponent implements Cloneable { public void set (ISOComponent c) throws ISOException; public void unset (int fldno) throws ISOException; public ISOComponent getComposite(); public Object getKey() throws ISOException; public Object getValue() throws ISOException; public byte[] getBytes() throws ISOException; public int getMaxField(); public Hashtable getChildren(); public abstract void setFieldNumber (int fieldNumber); public abstract void setValue(Object obj) throws ISOException; public abstract byte[] pack() throws ISOException; public abstract int unpack(byte[] b) throws ISOException; public abstract void dump (PrintStream p, String indent); // new in jPOS 2.0+ public abstract void pack (OutputStream out) throws IOException, ISOException; public abstract void unpack (InputStream in) throws IOException, ISOException; } We have many situations where some methods are not applicable, (i.e. getChildren() has no meaning in a leaf field, same goes for methods such as getMaxField()) but as a general rule,

using the same super class for ISOMsg and ISOFields is a nice thing, you can easily assign an ISOMsg as a field of an outter ISOMsg.

3. ISOPackager
Packager or ISOPackager library is used as the definition of the length and data type of each Data Element that will be used in communications. GenericPackager uses an XML config file to describe the layout of an ISOMessage. These ids will be used to create ISOField associated to fieldId within ISOMsg. Sample XML file structure:<!DOCTYPE isopackager SYSTEM "genericpackager.dtd"> <!-- ISO 8583:1993 (ASCII) field descriptions for GenericPackager --> <isopackager> <isofield id="0" length="4" name="Message Type Indicator" class="org.jpos.iso.IFA_NUMERIC"/> <isofield id="1" length="16" name="Bitmap" class="org.jpos.iso.IFA_BITMAP"/> <isofield id="2" length="19" name="Primary Account number" class="org.jpos.iso.IFA_LLNUM"/> . .. <isofield id="128" length="8" name="Message authentication code field" class="org.jpos.iso.IFA_BINARY"/> </ isopackager > Besides using xml file, packager can also be configured through java file with the provisions we have to ISOBasePackager extends class like this: public class CustomPackager extends ISOBasePackager { public CustomPackager() { setFieldPackager(new ISOFieldPackager[]{ /*000*/new IFA_NUMERIC(4, "Message Type Indicator"), /*001*/ new IFA_BITMAP(16, "BIT MAP"),

/*002*/ new IFA_LLNUM(19, "PAN - PRIMARY ACCOUNT NUMBER"), /*003*/ new IFA_NUMERIC(6, "PROCESSING CODE"), .. /*126*/ new IFA_LLLCHAR(999, "RESERVED PRIVATE USE"), /*127*/ new IFA_LLLCHAR(999, "RESERVED PRIVATE USE"), /*128*/ new IFA_LLLCHAR(999, "MAC 2") }); } } While its usage is as follows: // to packager of type xml ISOPackager packager = new GenericPackager("sample.xml"); // to packager of type class ISOPackager packager = new CustomPackager();

4. ISOMsg
Financial transaction is communication between 2 systems through socket connection. After connection established, each system can send message in ISO 8583 format which commonly will be request and the other system will response.

Class jPOS ISOMsg the library is at the heart of the message that we send, and we will receive data.
It is used to pack and unpack the data. We need to fill in the data element values specified in the

class ISOMsg as follows.

// Create ISO Message ISOMsg isoMsg = new ISOMsg(); isoMsg.setMTI("0200"); isoMsg.set(3, "201234"); isoMsg.set(4, "10000"); isoMsg.set(7, "1107221830"); isoMsg.set(11, "123456"); isoMsg.set(44, "A5DFGR"); isoMsg.set(105, "ABCDEFGHIJ 1234567890"); Otherwise we can set like below isoMsg.set (new ISOField (0, "0800")); //setMTI method of ISOMsg can also be set with field number (it is always zero) and field value. isoMsg.set (new ISOField (3, "201234")); etc. Here we are just calling ISOComponent.set (ISOComponent) method. ISOComponents have two useful methods called public abstract byte[] pack() throws ISOException; public abstract int unpack(byte[] b) throws ISOException;

pack returns a byte[] with the binary image of a given component (can be just a field or the whole ISOMsg) and unpack does the opposite, returning the number of consumed bytes. JPOS uses yet another pattern called Peer pattern that allows a given ISOComponent to be packed and unpacked by a peer class, plugged at runtime. So ISOMsg has a method called public void setPackager (ISOPackager p); where one can assign a given packager to an ISOMsg. GenericPackager packager = new GenericPackager("basic.xml"); isoMsg.setPackager(packager); byte[] binaryImage = isoMsg.pack(); // to pack In order to unpack this binary image you may write code like this: isoMsg.setPackager (packager); isoMsg.unpack (binaryImage); // to unpack For our examples, the data element list: #3 Processing code n 6 #4 Transaction amount n 12 #7 Transmission date & time n 10 #11 Systems trace audit number n 6 #44 Additional response data an ..25 #105 Reserved for ISO use ans 999 After packing we will get below response. 0200B220000000100000000000000080000020123400000001000011072218301 2345606A5DFGR021ABCDEFGHIJ 1234567890 Similarly if we provide above result to unpack method we will get all the ISOField values and MTI. Bitmaps is field that contains information about which data element is presence or absence. Based on the variant it could be 16 hexadecimal characters. >> Refer PackISOMessage.java file for pack and UnpackISOMessage.java for unpacking of ISOMsg Meanwhile, to send data on a server, we can wrap the object ISORequest ISOMsg into ISORequest object and sends it to the queue method (ISORequest isoRequest) on ISOMUX class like the example below: How to send a message through ISORequest. ISORequest req = new ISORequest(networkReq); //where networkReq is object of Type ISOMsg isoMux.queue(req);

And to get a response from the server, we can use the method GetResponse (Integer TIMEOUT) of class ISORequest like the code below. How to take ISORequest response through: ISOMsg reply = req.getResponse(50*1000); if (reply != null) { System.out.println("Req ["+new String(networkReq.pack()) + "]"); System.out.println("Res ["+new String(reply.pack()) + "]"); }

5. ISOChannel
Class ISOChannel or Channel at jPOS library is used to encapsulate the implementation details of the protocols used by each vendor. Besides ISOChannel is also used to transmit and receive ISOMsg object. Some Channel is supported by the library JPOS, among others are ASCIIChannel, BCDChannel, NACChannel, XMLChannel, ServerChannel etc. Channels are used to communicate data as a client and server application. ISOChannel is used to send and receive ISOMsg objects. It leverages the peer pattern where its peer is an ISOPackager instance. It has send and receives methods as well as means to set and get a peer packager. >> Refer ChannelServer.java and ChannelClient.java files. Here client will connect to server and sends ISOMsg. But it will not receive any message from server.

6. Filters
Whenever we add a filter (be it incoming, outgoing, or both) to a FilteredChannel, all messages sent or received by that channel are passed through that filter. For example assume that we created a sample Delay filter. DelayFilter just applies a given delay to all traffic being sent or received by a given channel. It can be used to simulate remote host delays. >> Refer ClientWithDelayFilter.java file

7. NameRegistrar
Allow runtime binding of jPOS's components (ISOChannels, Logger, MUXes, ISOServer, etc). org.jpos.util.NameRegistrar is a very simple singleton class that can be used to register and locate jPOS components. It's nothing but a simple well known Map where one can easily find components by an arbitrary name. To register a ISOServer ISOServer server = new ISOServer(..); NameRegistrar.register("SERVER-NAME", server); We can get a reference to server with code like this: try{ ISOServer serverInstance = (ISOServer) NameRegistrar.get("SERVER-NAME"); } catch (NameRegistrar.NotFoundeException e) { }

8. ISOServer And ISOMUX

In normal java application we use ServerSocket class as the implementation of a server and Socket class as the implementation of a client, the library jPOS ISOServer we can use the class as an implementation of the server and client class ISOMUX as its implementation. In order for the message that we send to the server are not confused with another message, then when we do the initialization method override the ISOMUX getKey (ISOMsg isoMsg) like the example below: ISOServer listens in a given port for incoming connections; it takes care of accepting them and passing control to an underlying ISOChannel implementation. Proper Use of ISOMUX: ISOMUX isoMux = new ISOMUX(channel) { @Override protected String getKey(ISOMsg m) throws ISOException { return super.getKey(m); } }; // run ISOMux new Thread(isoMux).start(); As for how to use the class ISOServer are as follows: ISOServer server = new ISOServer(portNumber, channel, null); new Thread(server).start(); Third argument of ISOServer's constructor is an optional ThreadPool. If we pass a null parameter there, a new ThreadPool is created for you, which defaults to 100 threads. (new ThreadPool (1,100)). We can add an ISORequestListener to ISOServer that will take care of actually processing the incoming messages. Let's modify our little Test program to answer our messages. Our Test class JPosServer has to implement ISORequestListener. public class JPosServer implements ISORequestListener { ... ... public boolean process (ISOSource source, ISOMsg m) { try { m.setResponseMTI (); m.set (39, "00"); source.send (m); } catch (ISOException e) { e.printStackTrace(); } catch (IOException e) { e.printStackTrace(); } return true; } ... ... } Now we have to assign this request listener to our server, with the following instruction:

server.addISORequestListener(new JPosServer()); ISOServer uses a ThreadPool in order to be able to accept multiple connections at the same time. Every socket connection is handled by a single thread. If our request listener implementation takes too long to reply, new messages arriving over that session will have to wait for their response. To solve this problem, our ISORequestListener implementation should have its own thread pool, so its process(...) method will just queue requests to be processed by a peer thread. Channel and Packager name should be same in both client and Server side. Otherwise server unable to receive messages sent from client side. >> Refer JposServer.java and JposClient.java files

9. ISOFieldPackagers
ISOFieldPackager classes are used in class attributes of isofield tag definition of DE elements. Some examples are below. IF_CHAR Fixed length alphanumeric (ASCII) IFE_CHAR Fixed length alphanumeric (EBCDIC) IFA_NUMERIC Fixed length numeric (ASCII) IFE_NUMERIC Fixed length numeric (EBCDIC) IFB_NUMERIC Fixed length numeric (BCD) IFB_LLNUM Variable length numeric (BCD, maxlength=99) IFB_LLLNUM Variable length numeric (BCD, maxlength=999) ... ... ... ..

10. ISOSource
Source for an ISORequest (where to send a reply). By using the send method we will process the ISOMsg object.

11. SystemMonitor
org.jpos.util.SystemMonitor is a very simple class that periodically logs useful information such as the number of running threads, memory usage, etc. Using SystemMonitor is very easy. We simply have to instantiate it with code like this: ... ... new SystemMonitor (60*60*1000, yourLogger, "system-monitor"); ... ... If we are using Q2 (revision greater than r2581), the default configuration deploys a SystemMonitor for us with file 99_sysmon.xml located in deploy folder.

12. Logger
The main difference between our logger sub-system and other logger sub-systems out there is that we deal with live objects. A LogEvent holds live objects that can be handled by the

LogListeners, for example to protect sensitive information (PCI requirement) or to act on special conditions (i.e. e-mailing an Operator on an Exception). While other logger subsystems are mostly "line oriented", jPOS' is mostly "transaction oriented". A jPOS LogEvent is likely to carry information for the whole transaction making it very suitable for audit and debugging purposes. jPOS's logger subsystem is very easy to extend, so one can easily plug in other logger engines (such as Log4j, commons logging or the new JDK's 1.4 logging stuff). Logger is implemented by the following main classes:

1. 2. 3. 4.

Logger - Main logger class LogListener - Listens to log events LogSource - A log event producer has to implement LogSource LogEvent - The Log Event

13. ChannelAdaptor
It is used to configure a standard client ISOChannel and it takes care of keeping it connected to a remote host. In addition to that, ChannelAdaptor's communication with other components is performed through a Space based interface, which brings into play the ability to have more than one channel connected to a given host, as well as the ability to distribute channels across multiple Q2 machines in a cluster. ChannelAdaptor was designed to operate with QMUX, the new-generation space-based multiplexer intended to replace ISOMUX. If we look at a ChannelAdaptor configuration, it looks like this: <channel-adaptor name='sample-channel-adaptor' class="org.jpos.q2.iso.ChannelAdaptor" logger="Q2"> <channel class="org.jpos.iso.channel.ASCIIChannel" logger="Q2" packager="org.jpos.iso.packager.GenericPackager" header="ISO016000055"> <property name="host" value="192.168.0.1" /> <property name="port" value="1234" /> <property name="packager-config" value="cfg/iso87ascii.xml" /> </channel> <in>sample-send</in> <out>sample-receive</out> <reconnect-delay>5000</reconnect-delay> <space>transient:default</space> </channel-adaptor> NOTE: in and out are seen from the ChannelAdaptor's standpoint. Input to the ChannelAdaptor means something that have to be actually sent through the underlying ISOChannel. The key here are these '<in>' and '<out>' elements. The ChannelAdaptor reads its 'in' queue (from the space, defined below) and places all received messages in the 'out' queue. That's where the QMUX fits in, <mux class="org.jpos.q2.iso.QMUX" logger="Q2" name="mymux"> <in>sample-receive</in> <out>sample-send</out> </mux>

QMUX implements MUX (please note MUX is an interface, different than ISOMUX which is an implementation). You can locate "mymux" using the NameRegistrar, and you can then call: ISOMsg response = qmux.request (myRequest, timeout); There are a few advantages of this strategy, namely, you can have more than one channel associated with a given mux, and you can start a new channel, and then stop the old one, all at runtime. If you have configured a ready indicator in the qmux config, the qmux has an isConnected method that tells you if the underling channel is connected. <?xml version="1.0" ?> <mux class="org.jpos.q2.iso.QMUX" logger="Q2" name="Test-mux"> <in>A-receive</in> <out>A-send</out> <ready>ABC.ready</ready> <!-- needs to be adptor name + .ready--> <unhandled>incomm-unhandled</unhandled> </mux> Snippet of channel xml <channel-adaptor name='ABC' .... > .... <in>A-send</in> <out>A-receive</out> <reconnect-delay>10000</reconnect-delay> </channel-adaptor>

14. QMUX
QMUX is a modern, very simple yet powerful Q2 component designed to replace ISOMUX. It closely adheres to the Q2 framework design where components can be added and removed on the fly. The main difference between ISOMUX and QMUX is that the latter uses the Space in order to communicate with the underlying channels; this strategy brings into play a whole new set of deployment options, including the ability to multiplex several channels for redundancy/load-balancing. These channels dont even have to run on the same machine. They can use distributed/remote space implementations. A QMUX configuration looks like this: <mux class="org.jpos.q2.iso.QMUX" logger="Q2" name="mymux"> <in>sample-receive</in> <out>sample-send</out> </mux> The "in" and "out" queue names must be interchanged compare to channel adapter settings. To handle incoming messages that don't match an outgoing request (i.e. late responses, network management messages originated by a remote server, etc.). The old ISOMUX had a request listener for that, but in Q2, with clusters, redundancy and scalability in mind, we

use the space instead. You can configure an optional unhandled queue, and QMUX will place all arriving messages that don't match any pending request in that queue. The configuration looks like this: <mux class="org.jpos.q2.iso.QMUX" logger="Q2" name="mymux"> <in>sample-receive</in> <out>sample-send</out> <unhandled>mymux.unhandled</unhandled> </mux> A separate process can be used to pull messages out of the mymux.unhandled queue for further processing. In order to match responses with their original requests, QMUX uses a constructed key which defaults to the matching response MTI plus data element 41 (terminal ID) and data element 11 (Serial Trace Audit Number).

15. QServer
QServer is a simple service that wraps an ISOServer. The configuration looks like this: <?xml version="1.0" ?> <server class="org.jpos.q2.iso.QServer" logger="Q2" name="simulator_10000"> <attr name="port" type="java.lang.Integer">10000</attr> <channel class="org.jpos.iso.channel.XMLChannel" logger="Q2" packager="org.jpos.iso.packager.XMLPackager"> </channel> <request-listener class="org.jpos.bsh.BSHRequestListener" logger="Q2"> <property name="source" value="cfg/serversimulator.bsh" /> </request-listener> </server> QServer uses a ThreadPool to handle incoming connections. The default limits for the ThreadPool are 1(minSessions) and 100 (maxSessions), but you can easily change that by adding the following attributes to your configuration : <attr name="minSessions" type="java.lang.Integer">10</attr> <attr name="maxSessions" type="java.lang.Integer">250</attr>

16. TransactionManager
jPOS is typically used to implement mission-critical applications that have to deal carefully with error conditions. The TransactionManager implementation takes care of 'driving' the transaction by calling all of the participants' prepare methods. If all of them return 'PREPARED', then the transaction moves to the committing phase, at which point the TransactionManager will call all of the participants' commit methods. If one of the participants' prepare methods were to return ABORTED, then the transaction would move into an aborting phase, and all the participants' abort methods would get called. Sample TransactionManager configuration: <txnmgr name="txnmgr" logger="Q2" class="org.jpos.transaction.TransactionManager"> <property name="space" value="transient:default"/> <property name="queue" value="txnmgr"/> <property name="max-sessions" value="100"/>

<property name="debug" value="true"/> <participant class="com.mycompany.tm.DemoParticipantOne" logger="Q2" realm="dummy-processor1"/> <participant class="com.mycompany.tm.DemoParticipantTwo" logger="Q2" realm="dummy-processor2"/> <participant class="com.mycompany.tm.DemoParticipantThree" logger="Q2" realm="dummy-processor3"/> <participant class="org.jpos.transaction.Debug" logger="Q2" realm="debug"/> </txnmgr> Where Space Space used to inject transactions into this transaction manager. Queue Queue name where the transaction manager pulls for new messages to be processed (sp.in(queue)). Sessions Number of transactions that can be processed simultaneously. Persistent space This TransactionManager reference implementation uses a persistent space to store a snapshot of ongoing transactions for recovery procedures. This persistent space has to be unique (see note). DemoParticipantOne, DemoParticipantTwo and DemoParticipantThree are participant classes involved in Transaction management. Integration with ISORequestListener It is extremely easy to integrate this TransactionManager framework with our ISORequestListeners. Here is how a process can be implemented: // Constants defined elsewhere ... public static final String REQUEST = "REQUEST"; public static final String ISOSOURCE = "ISOSOURCE"; public boolean process (ISOSource source, ISOMsg m) { Context ctx = new Context (); ctx.put (REQUEST, m); ctx.tput (ISOSOURCE, source); (1) sp.out (cfg.get "queue", ctx, cfg.getLong ("timeout")); (2) return true; } (1) Please note ISOSource is a live object. Therefore, it makes no sense to store it in our persistent snapshot for recovery. Instead, we use the transient map of our custom context (as described above). (2) Hands off the request to the TransactionManager. ISORequestListener is free to return. The transaction manager then pulls that context out of the queue, processes it, and uses the ISOSource reference in order to send a response back to the client. For example: <?xml version="1.0" encoding="UTF-8"?> <server class="org.jpos.q2.iso.QServer" logger="Q2" name="dummy-server"> <attr name="port" type="java.lang.Integer">5000</attr> <channel class="org.jpos.iso.channel.XMLChannel" logger="Q2" packager="org.jpos.iso.packager.XMLPackager"> </channel>

<request-listener class="com.mycompany.SendToTM"> <property name="space" value="transient:default"/> <property name="queue" value="txnmgr"/> <property name="timeout" value="12000"/> </request-listener> </server> public class MyISORequestListener extends Log implements ISORequestListener, Configurable { private String q; protected Space<String, Context> sp; @Override public boolean process(ISOSource source, ISOMsg m) { ISOMsg responseISOMsg = null; QMUX mux = null; try { Context c = new Context(); c.put("MyRequest", m); sp.out(q,c,10000); ISOMsg reply = (ISOMsg) m.clone(); reply.setMTI("1810"); reply.set(39, "00"); try{ source.send(reply); } catch (IOException e) { e.printStackTrace(); } } catch (Exception ex) { ex.printStackTrace(); } return true; } @Override public void setConfiguration(Configuration arg0) throws ConfigurationException { sp = SpaceFactory.getSpace (arg0.get ("space")); q= arg0.get ("queue"); } }

JPOS Deploy Directory Elements in JPOS-EE

The significance and operational workings of each of the items contained in the deploy subdirectory at one of our client sites running a jPOS-based Acquirer implementation. These XML-based system components represent the key touchpoints of the jPOS application as implemented. They are the critical control points, so the more you know of their workings, the more capable you will be in terms of support and tuning of a jPOS application.

The lists of those components suggest us to type of functionality we can define in a jPOS application. Heres the list: 00_logger.xml This file governs how system information (e.g., system start, stop; channel connect, disconnect; protected transaction breakout) is placed into files in the log sub-directory. Implementation Notes: Logger is specified as q2 (so current log is q2.log and previous generations are q2.log.1, q2.log.2, etc.). ProtectedLogListener ensures sensitive fields in logs are protected or wiped. RotateLogListener defines how many copies to keep, as well as maximum log size in seconds (see window) or bytes. On cycle, q2.log becomes q2.log.1, the previous q2.log.1 becomes q2.log.2, the previous q2.log.89 becomes q2.log.90, and the previous q2.log.90 is eliminated. This facility is enabled via the applications use of the log4j logging service. [For further info, see http://logging.apache.org/log4j/docs/index.html.] Removal of 00_logger from directory will disable logging but not impact transaction processing. However, the q2.log is instrumental to any attempt at troubleshooting and is a key component of continuous improvement efforts. 99_sysmon.xml Summary: Presence of this item in the deploy directory results in the executing application log placing diagnostic (see XML tag <SystemMonitor>) information into q2.log at intervals specified by the sleeptime parameter. Information includes memory usage, thread summary and a review of the name registrar. These entries are important debugging and troubleshooting devices. For more deploy directory elements refer http://www.andyorrock.com/2007/03/recently_i_wrot.html

Sample Server-Client Simulator Example

Consider a sample client server simulator application using jposs-ee. Download jposs-ee sample projects and extract. 1. Create a java project 2. Copy modules folder, build.properties, devel.properties and build.xml file from extracted folder to new created folder. 3. Copy clientsimulator, commons and serversimulator folder from <ExtractedFolder>/opt folder into project 4. Execute build.xml for setting target as run. 5. We will see swing applet with some result. Lets take a look at the serversimulator/deploy directory. We find a Qbean descriptor called 05_serversimulator.xml . Q2 manages Qbeans with its container. Q2 is like a club house

that only allows Qbeans, to hang out at the VIP section and if anyone needs to talk to a Qbean, they need to check with the NameRegistrar to see if the Qbean is available. The request listener being used here is the org.jpos.bsh.BSHRequestListener class. It points to the cfg/serversimulator.bsh file. The content of 05_serversimulator.xml file tells that it will be server start on port 10000 and waiting for request from client. Serveris configured with BSHRequestListener listener and whenever it will receive the request it will respond the request with response present in cfg/serversimulator.bsh file. Next, we can take a look at the clientsimulator/deploy directory. This directory contains four files. They are: 10_clientsimulator_channel.xml 20_clientsimulator_mux.xml 25_clientsimulator_ui.xml 30_clientsimulator.xml The numbers in front of the file name tells Q2 the order in which the Qbean descriptors should be loaded. The 10_clientsimulator_channel.xml file contains the channel information which are type of channel, the host, the port and the packager. You should be able to see where this is going buy now. The 20_clientsimulator_mux.xml file contains the MUX configuration. The recommended MUX implementation in the JPOS world is the QMUX. The MUX uses the channel to send and receive ISO Messages. The 25_clientsimulator_ui.xml file is basically the swing app you see when you execute ant run command under the jposee directory. The last file 30_clientsimualtor.xml, is the client simulator. It uses all the other qbeans to send/receive messages to/from the server simulator. The request content to be fetched from echo_s files present under clientsimulator/cfg folder. TestRunner.java and TestCase.java will provide input to the QMUX by reading data from echo_s file. When we run ant build we see the result in an applet window and all the logger entries will be present in log file present under build/log/q2.log file