Skip to content

Latest commit

 

History

History
165 lines (134 loc) · 5.78 KB

qmux.adoc

File metadata and controls

165 lines (134 loc) · 5.78 KB
Raw

QMUX

QMUX is a modern and very simple, yet powerful, Q2 service that implements the MUX interface as described in [multiplexing_with_mux].

Tip

Users of the old ISOMUX, which is still available in the compat_1_5_2 module are encouraged to upgrade to this new service.

QMUX 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 doesn’t even have to run on the same machine. They could use distributed/remote space implementations. The new space-based code doesn’t require an extra thread, something very useful in systems where a large number of MUXes are required.

QBean descriptor

A QMUX configuration looks like this:

<mux class="org.jpos.q2.iso.QMUX" logger="Q2" name="mymux">
 <in>your-channel-receive</in>                               (1)
 <out>your-channel-send</out>                                (2)
 <ready>your-channel.ready</ready>                           (3)
</mux>

  1. The MUX <in> queue has to be named after the ChannelAdaptor’s <out> queue.

  2. In the same way, the MUX’s <out> queue needs to match the ChannelAdaptor’s <in> queue.

  3. In order to provide a usable MUX.isConnected() method, the MUX needs to have a way to know if the underlying channel, loosely connected through the in/out queues is actually connected. The channel adaptor sets an entry in the space named after the channel’s name with the extension .ready as true when connected, so the optional ready element has to match that name. If a <ready> element isn’t present, MUX.isConnected() will always return true.

QMUX

QMUX is registered in the NameRegistrar under the name provided in the qbean configuration file using the "mux." prefix, ("mux.mymux" in our example) so that other components can get a reference, cast it to MUX and use its:

In order to handle messages arriving to QMUX that do not match a response QMUX is waiting for, we can attach one or more ISORequestListeners.

The XML configuration looks like this:

<mux class="org.jpos.q2.iso.QMUX" logger="Q2" name="mymux">
 <in>your-channel-receive</in>
 <out>your-channel-send</out>
 <ready>your-channel.ready</ready>
 <request-listener class="my.request.listener" logger="Q2" realm="myrealm">
  <property name="myproperty" value="abc" />
  <property name="myotherproperty" value="xyz" />
  <property file="cfg/myprop.cfg" />
 </request-listener>
</mux>

As an alternative (or in addition to the request listeners), we can define an unhandled queue. If messages arrive to QMUX and QMUX isn’t waiting for it, it gets placed in the unhandled queue.

The configuration looks like this:

<mux class="org.jpos.q2.iso.QMUX" logger="Q2" name="mymux">
 <in>your-channel-receive</in>
 <out>your-channel-send</out>
 <ready>your-channel.ready</ready>
 <unhandled>myunhandledqueue</unhandled>
</mux>
Note

In order for this mechanism to work, a separate jPOS service should be waiting for messages arriving to the unhandled queue.

In order to prevent a situation where a QMUX is configured to push messages to an unhandled queue and no service is listening to those messages, a 120 seconds timeout is used. So messages will be present for just 120 seconds. This little protection is intended to avoid out of memory issues.

MTI mapping and default key

QMUX use the MTI as well as fields '41' and '11' as its default key.

That default can be changed using the '<key>...</key>' elements in the QMUX configuration, i.e.:

<mux class="org.jpos.q2.iso.QMUX" logger="Q2" name="mymux">
 <key>42 41 11</key>                                             (1)
 <key mti="0800">41</key>                                        (2)
 <in>your-channel-receive</in>
 <out>your-channel-send</out>
 <ready>your-channel.ready</ready>
 <unhandled>myunhandledqueue</unhandled>
</mux>

  1. overrides default key.

  2. overrides default key for 0800 messages.

In addition to the fields defined in the '<key>' element, QMUX maps each digit of the MTI to use as a key part in order to avoid mixing for instance a response for a 100-class message such as a 0100 with a reversal response. The reason for this additional mapping is because most reversals share the same STAN (field 11) with the original authorization.

Each of the three digits of the MTI gets mapped using the following default values:

  • 0123456789

  • 0123456789

  • 0022446789

The value 0123456789 means no special handling is required, a value of '0' in the first position of the MTI i.e. the first '0' in a '0100' message) will expect a '0' in that very same position in the response. The first position represents the ISO-8583 version number (see [iso8583]), so if we send a 1987 message, we expect a 1987 response.

Same goes for the second position, if we send a '0100' we expect a '0110', and that’s what the '0123456789' mapping does, it actually takes no action.

For the third position, we use the default value 0022446789. That means that a '1' in the third position (i.e. a '0110') will be considered a '0' when creating the MTI key part, so that a '0110' response will match the original '0100'.

These mappings can be changed using the '<mtimapping>' element in the QMUX configuration. The default values would be represented as:

<mux class="org.jpos.q2.iso.QMUX" logger="Q2" name="mymux">
 <mtimapping>0123456789 0123456789 0022446789</mtimapping>
 ...
 ...
</mux>