Tutorial – Writing a gateway the jPOS way

I get to see dozens of third party jPOS gateway implementations just using 5% of jPOS capabilities.

People download jPOS just to use the ISO-8583 packing/unpacking and sometimes they don’t even get to use the channels, multiplexers, servers, transaction manager. I see developers trying to stay away from Q2 probably because they don’t know it, but it’s quite simple to use.

So I wrote a little tutorial, http://jpos.org/doc/tutorials/jpos-gateway.pdf that walks you through the process of installing jPOS and writing a production grade gateway capable of processing thousands of transactions per second.

The tutorial has two parts, first you get it running (takes about 5 minutes), then the second part explains why that very simple configuration works.

The second part has plenty of links to the jPOS programmer’s guide documentation (freely available), while it’s just a couple pages, understanding it and following the links may take some more time and may raise some questions that we’ll be happy to answer.

Investor’s Dilemma : How do I Handle Unlicensed Copies of AGPL Software in a Portfolio Company

Every once in a while we receive a request from an investor or private equity firm who, in the process of conducting due-diligence on an existing or established potential portfolio company, encounters an unlicensed copy of jPOS. Often the company has released a commercial product which incorporates this unlicensed software. Investors want to know, how should we proceed and what are the responsibilities of the company vis-à-vis the license and source code?

The easiest and first answer is of course, the company should purchase a license and not rely on pirated software to conduct their business. The more subtle question is what does it imply when a start-up is willing to pirate software which is intended to be reasonably priced and positioned to benefit the authors and the overall Fintech software community as a whole?

Isn’t it risky to partner with a company that disregards good business practices, either because of bad faith or negligence?

If it were me, I’d invest somewhere else!

jPOS-EE BinLog module

jPOS-EE has a new binlog module, a general purpose binary log that can be used as a reliable event store.

The jPOS BinLog has the following features:

  • multiple readers and writers can be used from the same JVM
  • multiple readers and writers can be used from different JVMs

Here is a sample Writer:

File dir = new File("/tmp/binlog");
try (BinLogWriter bl = new BinLogWriter(dir)) {
    bl.add( ... ); // byte array
    bl.add( ... ); // byte array
    bl.add( ... ); // byte array
}

and a sample Reader:

File dir = new File("/tmp/binlog");
try (BinLogReader bl = new BinLogReader(dir)) {
    while (bl.hasNext()) {
        byte[] b = bl.next().get();
        // do something with the byte[]
    }
} 

The BinLogReader implements an Iterator<BinLog.Entry>. Each BinLog.Entry has two main methods:

  • BinLog.Rer ref()
  • byte[] get()

While iterating over a BinLog, it might make sense to persistently store its BinLog.Ref in order to be able to restart the iterator at a given point if required (this is useful if using the BinLog to implement a Store and Forward.

The BinLogReader has two constructors:

  • BinLogReader(File dir)
  • BinLogReader(File dir, BinLog.Ref ref)

the latter can be used to restart the iterator at a given reference point obtained from a previous run.

In addition to the standard hasNext() method required by the Iterator implementation, BinLogReader also has a hasNext(long millis) method that waits a given number of milliseconds once it reaches the end of the log, attempting to wait for a new entry to be available.

The goal behind the BinLog implementation is to have a future proof file format easy to read from any language, 10 years down the road. We found that the Mastercard simple IPM file format, that’s basically a two-byte message length followed by the message itself was suitable for that. The payload on each record can be ISO-8583 (like Mastercard), JSON, FSDMsg based, Protocol buffers or whatever format the user choose.

But that format isn’t crash proof. If a system crashes while a record is being written to disk, the file can get easily corrupted. So we picked some ideas from Square’s tape project that implements a highly crash proof on-disk persistent circular queue using a very small header. Tape is great and we encourage you to consider it instead of this binlog for some use cases, but we didn’t want a circular queue, we wanted a place to securely store events for audit or store and forward purposes, and we also wanted to be able to access the same binlog from multiple JVMs with access to the same file-system, so we had to write our own.

The on-disk file format looks like this:

Format:
256 bytes Header
... Data
... Data

Header format (256 bytes):
4 bytes header length
2 bytes version
2 bytes Status (00=open, 01=closed)
8 bytes Last element position
4 bytes this log number
4 bytes next log number
232 bytes reserved

Element:
4 bytes Data length
...     Data

Each record has a length prefix (four bytes in network byte order) followed by its data. The header has a fixed length of 256 bytes but we found useful to make it look like a regular record too by providing its length at the very beginning. An implementation in any language reading a jPOS binlog can just be programmed to skip the first record.

At any given time (usually at end of day), a process can request a cut-over by calling the BinLogWriter.cutover() method in that case, all writers and readers will close the current file and move to the next one (Readers can choose to not-follow to the next file, for example while producing daily extracts).

In order to achieve file crash resilience, each write does the following:

  • Lock the file
  • Write the record’s length and data
  • Sync to disc
  • Write the last element position to the header
  • Sync to disc
  • Unlock the file

In an MBP with SDRAM we’ve managed to achieve approximately 6000 writes per second. On an iMac with regular disk the numbers go down to approximately 1500 writes per second for regular ISO-8583 message lengths (500..1000 bytes per record).

Due to the fact that the header is small enough to fit in an operating system block, the second write where we place the last element position happens to be atomic. While this works OK for readers and writers reading the file from different JVMs, that’s not the case for readers and writers running on the same JVM, even if they use a different file descriptor to open the file, the operating system stack has early access to the header that under high concurrency can lead to garbage values, that’s the reason the code synchronizes on a mutex object at specific places.

Supporting CLI commands

The binlog CLI command is a subsystem that currently have two commands:

  • monitor (to visually monitor a binlog)
  • cutover (to force a cutover)
  • exit (builtin command)

binlog accepts a parameter with the binlog’s path, i.e: binlog /tmp/binlog

So a cutover can be triggered from cron using the following command:

q2 --command="binlog /tmp/binlog; cutover; exit; shutdown --force"

jPOS 2.0.10 has been released

jPOS 2.0.10 has been released, new development version is now 2.1.0-SNAPSHOT

This release upgrades JLine to 3.0.0, adds new CLI commands and subsystems, upgrades Gradle to 3.1.0, allows license to be read from external file and removes double-logging in PADChannel. The main reason for this small release is to flush small enhancements before we make some bigger changes to the TransactionManager with improved audit logging (those are already available in 2.1.0-SNAPSHOT). It also updates the copyright year to 2017 and changes the copyright owner to the new entity jPOS Software SRL.

Starting with this release we’ll move to semantic versioning, so next release is going to be 2.1.0 and requires a full clean build of your projects in order to make sure some of the API changes don’t break your system.

see ChangeLog for details.

Q2 User Interface (aka ‘QI’)

I’m happy to share some new stuff we have in jPOS-EE that we call “QI” (short for Q2 UI).

TL;DR: go to jpos.org/jpos using user admin and password test in order to see what I’m talking about. If you like it, keep reading, otherwise please ignore this message.

QI uses the Vaadin framework that we found very useful for our company’s web development and graphics design skillset (basically no skills). It allows us to create nice reusable web/mobile-friendly applications from Java in a highly modular way.

If you monitor @jposcommits you might have noticed a few new jPOS-EE components, like:

  • qi-core
  • qi-eeuser
  • qi-sysconfig

(see jPOS-EE/modules)

The main goal of the project is to have a bunch of reusable little QI modules (for instance, qi-minigl is coming) that you can use to put together very easily to administrate your jPOS application.

As the rest of the Q2 system, it uses an XML configuration file that gives you a top level control of your particular application, including centralised role-based permissions to access the different parts of the system.

<xml-config name="QI" logger="Q2">
    <title>jPOS QI</title>
    <locale>en-US</locale>
    <menubar>
        <menu name="System" icon="COG" style="icon-cog" action="system" />
        <menu name="Accounting"  action="accounting" />
    </menubar>

    <sidebar id="info">
        <section name="Info"/>
        <option name="Info" action="info"/>
    </sidebar>

    <sidebar id="system">
        <section name="System"/>
        <option name="Info" action="info"/>
        <option name="Log" action="log"/>
        <option name="Exception log" action="exceptions"/>
        <option name="Users" action="users"/>
        <option name="Roles" action="roles"/>
        <option name="Permissions" action="permissions"/>
        <option name="SysConfig" action="sysconfig"/>
        <option name="Audit Log" action="syslog"/>
        <option name="Revision History" action="revision_history"/>
    </sidebar>
    ...
    ...
</xml-config>

There you can see the top level menu that triggers two different sidebars. When we hit for example ‘Log’ it brings us to the ‘log’ action that is defined like this:

<view route="log" class="org.jpos.qi.system.LogListenerView" perm="sysadmin" sidebar="system" >
    <property name="name" value="logger.Q2.buffered"/>
    <property name="entityName" value="log"/>
</view>

If you hit the ‘info’ action, you get a tabbed pane, the tabbed pane is defined like this:

<view route="info" class="org.jpos.qi.views.TabView" perm="login" sidebar="system">
    <view caption="About" class="org.jpos.qi.system.AboutView" perm="login"/>
    <view caption="Memory" route="memory" 
        class="org.jpos.qi.system.MemoryUsageView" perm="login"/>
    <view caption="Sysmon" route="sysmon" 
        class="org.jpos.qi.system.ObjectView" perm="sysadmin" repeat="1000"
         clearScreen="true">
     <object class="org.jpos.util.SystemMonitor"/>
    </view>
    <view caption="Uptime" route="uptime" class="org.jpos.qi.system.ProcessView" perm="sysadmin" repeat="1000"
      clearScreen="true">
      <script>uptime</script>
    </view>
    <view caption="Date" route="date" class="org.jpos.qi.system.ObjectView" 
        perm="login" repeat="1000"
          clearScreen="true">
      <object class="java.util.Date"/>
    </view>
</view>

I suggest you take a look at how a simple view is implemented, for example the About view:

public class AboutView extends VerticalLayout implements View {
    public AboutView() {
        super();
        Label html = new Label(Q2.getVersionString());
        html.setContentMode(ContentMode.PREFORMATTED);
        setMargin(true);
        addComponent(html);
    }
    public void enter(ViewChangeListener.ViewChangeEvent event) { }
}

Some others like ObjectView or ProcessView are interesting, ObjectView can view any object and refresh it regularly, that’s how the ‘Date’ tab is implemented with a very simple XML configuration:

 <view caption="Date" route="date" class="org.jpos.qi.system.ObjectView" 
        perm="login" repeat="1000"
       clearScreen="true">
     <object class="java.util.Date"/>
 </view>

The ObjectView implementation is very simple (see code here) but behind the scenes QI uses web sockets (courtesy of a pre-configured Atmosphere setup) to refresh it.

If you go see the log and you telnet to us.jpos.org on port 9000 (that has an open XMLChannel with an auto-responder) you can see how smooth it is.

If you like this stuff you can clone the qitest project that demonstrate how to use QI in your own application.

Your feedback and contributions are greatly appreciated. If you really want to use this stuff, we’ll be happy to walk you through the setup and help with questions for undocumented features (we’ll be adding documentation to the jPOS-EE manual as time permits). The easiest way to do that is here on the list, or better yet, in the jPOS Slack (we are usually around from 1600 to 2000 GMT – see http://jpos.org/resources to get an invite)

jPOS 2.0.8 has been released

jPOS 2.0.8 has been released, new development version is now 2.0.9-SNAPSHOT

see ChangeLog for details.

This release includes the former jPOS-EE SSH module that can be enabled by calling Q2 with the --ssh switch.

This requires a file cfg/authorized_keys and defaults to port 2222. After starting the SSH service, one can:

ssh -p 2222 admin@localhost

and get a Q2 CLI prompt.

See q2 --help for details.

SpaceLogListener

In 2.0.4 we’ve added a SpaceLogListener that can be used to write log output in an asynchronous way.

It works with a companion LoggerService that pull entries from the Space and actually log them.

The configuration is very simple, here is an example:

00_logger.xml

<logger name="Q2" class="org.jpos.q2.qbean.LoggerAdaptor">
  <log-listener class="org.jpos.util.SpaceLogListener">
    <property name="queue" value="logger.q2" />
    <property name="space" value="tspace:default" />
    <property name="frozen" value="true" />
  </log-listener>
</logger>

01_logger_daemon.xml

(this is basically your old 00_logger.xml, synchronously writing to disk)

<logger name="DAEMON" class="org.jpos.q2.qbean.LoggerAdaptor">
    <log-listener class="org.jpos.util.DailyLogListener">
        <property name="window" value="86400" />
        <property name="prefix" value="log/q2" />
        <property name="suffix" value=".log"/>
        <property name="date-format" value="-yyyy-MM-dd-HH"/>
        <property name="compression-format" value="gzip"/> 
    </log-listener>
</logger>

02_logger_service.xml

<logger-service class="org.jpos.q2.qbean.LoggerService" logger="DAEMON">
    <property name="queue" value="logger.q2" />
    <property name="space" value="tspace:default" />
</logger-service>

The logger service pulls entries from logger.q2 space queue and uses the second logger as its output (we arbitrarily called it DAEMON).

The SpaceLogListener can send to the Space the original “Live” (so to speak) LogEvent, or create a Frozen one (see the frozen property). When set to true, log filters (i.e. the ProtectedLogFilter) has to be applied before the SpaceLogListener, otherwise, it won’t work on the frozen LogEvent.

A FrozenLogEvent is Serializable, so we are not limited to TSpace, one can use the ReplicatedSpace in order to implement a very simple central logging.