[[qmux]]
== QMUX

**QMUX** is a modern and very simple, yet powerful, Q2 service 
that implements the
link:http://jpos.org/doc/javadoc/org/jpos/iso/MUX.html[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:

[source,xml]
------------
<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.

image:images/qmux.png[width="400px",alt="QMUX",align="center"] 

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:

[source,xml]
------------
<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:

[source,xml]
------------
<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.:

[source,xml]
------------
<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:


[source,xml]
------------
<mux class="org.jpos.q2.iso.QMUX" logger="Q2" name="mymux">
 <mtimapping>0123456789 0123456789 0022446789</mtimapping>
 ...
 ...
</mux>
------------