In addition to the must-have buy-it-now jPOS Programmer's Guide, I've been working in a new document, the jPOS Project Guide. I thought it would be a good idea to share the source code of that document, which uses DITA, so may be we can learn DITA together by editing this document. You can find it in the new 'jpos6/doc' directory (r2834) This is an experiment, the document will be there for a couple of months, if there are no significant contributions from the community, I will remove it and continue working alone which gives me more flexibility. If that happens, the PDF version will continue to be available, though. Patches and additions are welcome!

When we started to log messages using a very simple XML format a long time ago, and then created the XMLPackager to support that message format, we never thought that this was going to be so heavily used, we frequently find ISO-8583 interchanges based on this format, implemented in different languages by different vendors in different countries. I've recently been involved in the deployment of an ISO/Bridge system at a financial institution in one African country connected to another institution at another African country. When I asked for the ISO-8583 specs in order to configure ISO/Bridge, I was surprised to see that the specs where XML based, and basically our spec. I hope we start seeing this with the jPOS CMF soon. The existing format looks like this:

Starting in jPOS 1.6.5 r2817, you can optionally use:

   0800
   000001
   301

Or any combination, i.e:

   301  

This is particularly useful in some implementations that use XML content as part of the ISO-8583 payload, in the past, we had to expand it using XML entities such as < and > that where not nice looking in the logs. With the new addition, we can:

  301
  < ?xml version='1.0' encoding='UTF-8' ?>
     29110001
        I love XML tags  

(you have to add a CDATA block around your inner XML) At response time, we wanted to make it as backward compatible as possible, so we only use this mode if we detect that the field content is XML.

Quick cross-post just to tell that I can assert this is quite true:

"Alejandro has told me the same thing – that when he does projects not related to OLS, he misses our documentation and attention to detail."

Andy's "Master Project Workbook" is a time saver, everything is there. Everything. Original post here.

About a year ago I've blogged about jCard and jPTS (the jPOS-EE based Card Management System / Stored Value Engine and the jPOS Transaction Switch). As part of the project, we defined what we called our IMF (internal message format) based on the ISO-8583 v2003 standard. After several deployments and mapping exercises to different source (SS) and destination stations (DS), we believe that this extra message normalization layer was a good thing to do. We get to see jPOS based systems connected to other jPOS based systems all the time, which is a good thing and makes things easier (when the connecting parties don't see their channel and packager configurations as some kind of secret sauce and get to kindly exchange them), but the packager/channel is just the low level plumbing, a lot of effort has to be done on the higher levels in order to get them to play nicely with each other. Our jCard system already has a quite complete set of self tests that use this format, same goes for jPTS. As part of this message normalization effort we plan to morph our internal tests into a TCK. Andy and Dave from Online Strategies are already using a similar format and are keen to work together into merging the differences. Mark is also #noded for this effort :) We are releasing this work under a Creative Commons Attribution-Share Alike 3.0 License and everybody is welcome to participate. You can get the PDF version here and you are very welcome to actively collaborate with the DocBook version (http://github/ar/jPOS-CMF). This is by no means a perfect spec, there's a lot of work to be done, but instead of reinventing a new spec, or coding to someone else's proprietary spec, we encourage you to take this one as yours. You can even change the cover page (as long as you retain some due credit). Every new project will require some tweaks and addition to the spec and TCK, and we are here to make that happen fast. Feel free to contact us or send us a tweet.

/by apr on why-oh-why/

What's wrong with Payment gateways?

I've seen this problem coming a long time ago; in my country there's a local credit card association called POS2000. After a long long time they've settled on a single ISO-8583 v1987 based protocol that is a mix of several POS and host based protocols where every acquirer managed to bastardize the standard a little bit in order to make the POS implementor's life a little bit worse.

They did a pretty good job (at bastardizing us) and made jPOS quite better (we have now support for esoteric stuff such as the dynamic packagers that change the way we deal with a message for different message types, etc.).

But that's nothing compared to web based payment gateways.

The first craptastic work I've got to see was presented by a local credit card acquirer/issuer.

You know, the regular redirect-to-the-acquirer-site thing with OK and DECLINE URLs which were available in hidden fields, as if a malicious user couldn't read the page source code and hand-craft the OK-url to continue shopping. Come on! More acquirers followed the trend and provided similar pathetic implementations that very few merchants and less users actually use; but things get worst, thanks to the mouse and some visual tools, there's a whole new group of people writing SOAP based services. OMG!!

We are dealing with quite a few now, to support credit card transactions, prepaid top up applications, etc.

Decades of hard work by large financial institutions working on good standards go down the toilet, it's easier to "invent" an API than read an ISO spec and do the right thing. We are working now with a pre-paid phone company and you get to see things like no reversals, and one-second time-window for voids (come on!), and the results code are usually SQL syntax errors displayed to the client.

A similar thing happens with language-specific APIs, vendors think that developers are stupid and not capable enough to deal with a well specified protocol, so they create an API that is usually a bad and closed source implementation of a bad proprietary wire protocol.

Serenity now!

As a follow-up to the previous post about vdmspace, I've implemented a simple SpaceWriter TransactionParticipant that can be used to log all transaction contexts to the highly reliable VoldemortSpace (vdm:space). It can be added to your transaction flow like this:

The code looks like this:

package org.jpos.transaction;

import java.io.Serializable;
import org.jpos.space.Space;
import org.jpos.space.SpaceFactory;
import org.jpos.core.Configurable;
import org.jpos.core.Configuration;
import org.jpos.core.ConfigurationException;

public class SpaceWriter implements AbortParticipant, Configurable {
    Space sp;
    String prefix;
    Configuration cfg;
    public int prepare (long id, Serializable o) {
        return PREPARED | READONLY;
    }
    public int prepareForAbort (long id, Serializable o) { 
        return PREPARED | READONLY;
    }
    public void commit (long id, Serializable o) { 
        outContext (id, (Context) o);
    }
    public void abort  (long id, Serializable o) { 
        outContext (id, (Context) o);
    }
    private void outContext (long id, Context ctx) {
        if (sp == null)
            sp = SpaceFactory.getSpace (cfg.get ("space", null));
        sp.out (prefix + Long.toString (id), ctx);
    }
    public void setConfiguration (Configuration cfg) {
        this.cfg = cfg;
        prefix = cfg.get ("prefix", "");
    }
}

You can add this participant to the very end of your transaction flow. All persistent entries in your Context would get stored.

As a follow-up to the VoldemortSpace post and after one month of development and testing we are not proud (see caveats below) to announce the vdmspace module and its supporting voldemort module. I've added two modules to jposee/opt, 'voldemort' and 'vdmspace' (r153). I splitted them in two different modules because I think there might be situations where accessing a Voldemort store directly could be desirable, without the Space implementation layer. During the last month playing with this exciting technology I faced many problems and tried different implementations. I tried not to use a coordinator, but Voldemort provides no easy locking mechanism in its StoreClient interface other than optimistic locking, making some space operations difficult to implement. So here are the caveats:

• Using the vdmspace for high concurrency input / output (in space terms, in/out) over the same keys will work, but could eventually fail.
• An out with timeout works as expected, but requires an extra write in order to register the entry for later review by the garbage collector.
• You want to make sure that you run just one garbage collector in the cluster (this is a temporary limitation that can be easily solved).

Having said the cons, I believe the vdmspace is good for:

• Storing massive number of transactions, provided each transaction is stored under its own unique key (i.e. could be used to implement a SOR).
• Implementing a second level cache for configuration data that doesn't change too often.

In order to test this, you need to enable opt/commons, opt/voldemort and opt/vdmspace, then you can use simple code like this:

import org.jpos.space.*; Space sp = SpaceFactory.getSpace ("vdm:space"); ... ...

This needs a lot of test, so feedback is Welcome!

jPOS business partners from Jethro LTD UK will be visiting several jPOS sites in Naerobi, Kenya next week. If you are interested to meet their crew, please contact us and we'll make it happen. NOTE: the blond pretty lady from  their front page is not coming, she needs to stay in the front page :)

When we call:

   Object obj = sp.in ("MyQueue");
   ...
   ....
   // do some processing using 'obj'
   ...
   ...

I always feel worried about what could happen between the point in time you take the object off the Space and you place it in a safe storage for further processing. There's always some single point of failure toward the outer services, for instance, while you are reading a message from a socket, if that process dies, your message is lost, but in the case of a Space, specially a reliable one (such as the VoldemortSpace), it's just too sad to loose a message that was previously carefully stored in a highly available fail-safe way, just because a client worker crashes. The initial solutions that came to mind would involve passing around some kind of Transaction Object (like Jini's Transaction or JTA) so we could make the Space participate in the transaction, but that's something easy to say, but not that easy to implement. Then sometime ago, I've read about how Amazon's SQS nicely solves a problem like this with temporary reads, when you read from SQS, you get the object for a couple of minutes and you need to confirm that you actually got it, otherwise, the object would show up again in the queue. I think an easy way to implement that using very simple space operations, would be to implement a temporary 'move' operation. I think that a proper syntax would be something like this:

   K move (K from, long timeout);

You get the idea, you'd use something like:

  Object tmpKey = sp.move ("MyQueue", 60000L);
  try {
      Object value = sp.rdp (tmpKey);
      ...
      ... process the entry
  } finally {
      sp.inp (tmpKey);
  }

If for some reason, you fail to 'inp' from tmpKey in your 60 seconds time-window, the object would show up again in the 'MyQueue' queue. I'm not implementing this now, but I may add the method as a place holder in the Space interface.

When I start writing a new Space implementation, a Friend's episode where Phoebe's brother tells Phoebe he "melts stuff" comes to mind (hilarious). He melts stuff; I write Space implementations [nerdy laugh here]. Back in the late 90s I started reading about the Linda Coordination Language and loved it,  I deployed a 25 node Jini/JavaSpaces (Outrigger) based application (small supermarket chain, each node was a member of the Jini federation). Due to the slow links, some early problems with OutRigger and a low memory budget on the nodes, we had to replace that implementation with a minimalistic one, and that's why I wrote the first jPOS Space implementation. But I always wanted to have a reliable, self-healing, highly scalable space, and guess what, I believe Project Voldemort is a God send for that, a perfect fit. We still need a couple of weeks in order to be able to provide a first release, we still have some locking problems and need to work on the garbage collector in order to efficiently reclaim space used by expired entries, but I thought it could be a good idea to share with you the fact that we are working with this new and exciting technology just in case you want to get yourself up to speed with it. Meanwhile, you may want to read and play with Project Voldemort, Amazon Dynamo and the miniSpaces tutorial.