Skip to main content

Q2 templates

· 3 min read
Alejandro Revilla

Typical jPOS applications have many similar servers, muxes, and channels. Sometimes hundreds of them.

In order to simplify its configuration Q2 now supports templates that can be launched from a template deployer, or programmatically using Q2's deployTemplate method.

A template is identical to a regular QBean XML descriptor, and can be placed anywhere in the filesystem, or classpath (including dynamic classpath) that has a special keyword called __PREFIX__ that are replaced at deploy time.

Q2's deployTemplate method has the following signature:

deployTemplate(String resource, String filename, String prefix);
  • resource is the resource location (e.g.: templates/channel.xml). If the resource starts with jar:, Q2 fetchs it from the classpath (e.g.: jar:META-INF/q2/templates/channel.xml).
  • filename is the QBean descriptor filename, e.g.: 10_acme_channel.xml
  • prefix is the Environment prefix (see below).

Imagine you have an environment (cfg/default.yml) file that looks like this:

    acme:
        host: 192.168.1.1
        port: 8000
    emca:
        host: 192.168.1.2
        port: 8001

In a regular deployment, you could have two channel configurations like this:

    10_channel_acme.xml
    
    <channel-adaptor name="acme-channel-adaptor" ...>
      <channel class="${acme.channel}" packager=...>
        <property name="host" value="${acme.host}" />
        <property name="port" value="${acme.port}" />
        ...
        ...
      </channel>
      <in>acme-send</in>
      <out>acme-receive</out>
    </channel-adaptor>
    
    10_channel_emca.xml
    
    <channel-adaptor name="emca-channel-adaptor" ...>
      <channel class="${emca.channel}" packager=...>
        <property name="host" value="${emca.host}" />
        <property name="port" value="${emca.port}" />
        ...
        ...
      </channel>
      <in>emca-send</in>
      <out>emca-receive</out>
    </channel-adaptor>

With templates, you can have a single template like this somewhere in your filesystem or classpath (say templates/channel.xml).

<channel-adaptor name="__PREFIX__-channel-adaptor" 
    enabled="${__PREFIX__.enabled:false}"
    class="org.jpos.q2.iso.ChannelAdaptor" 
    logger="${__PREFIX__.logger:Q2}">
 <channel class="${__PREFIX__.channel}" 
         logger="${__PREFIX__.logger:Q2}" 
       packager="${__PREFIX__.packager:org.jpos.iso.packager.GenericPackager}">
  <property name="host" value="${__PREFIX__.host}" />
  <property name="port" value="${__PREFIX__.port}" />
  <property name="header" value="${__PREFIX__.header}" />
  <property name="connect-timeout" value="${__PREFIX__.timeout:5000}" />
  <property name="packager-config" value="${__PREFIX__.packagerConfig}" />
 </channel>
 <in>__PREFIX__-send</in>
 <out>__PREFIX__-receive</out>
 <reconnect-delay>${__PREFIX__.reconnect:10000}</reconnect-delay>
 <wait-for-workers-on-stop>${__PREFIX__.wait:yes}</wait-for-workers-on-stop>
</channel-adaptor>

and perhaps a mux.xml connected to it:

----
<mux name="__PREFIX__" class="org.jpos.q2.iso.QMUX" 
    enabled="${__PREFIX__.enabled:false}"
    logger="${__PREFIX__.logger:Q2}" realm="__PREFIX__">
  <key>${__PREFIX__.mux.key:41,11}</key>

 <in>__PREFIX__-receive</in>
 <out>__PREFIX__-send</out>

 <ready>__PREFIX__-channel.ready</ready>
</mux>
----

Then you can deploy a QBean descriptor like this:

<templates>
    <template resource="templates/channel.xml" descriptor-prefix="10_channel_">
        acme,emca
    </template>
    <template resource="templates/mux.xml" descriptor-prefix="20_mux_">
        acme,emca
    </template>
</templates>

The special text __PREFIX__ is replaced by Q2 in each file using the prefix acme and emca, so the properties:

  <property name="host" value="${__PREFIX__.host}" />
  <property name="port" value="${__PREFIX__.port}" />

gets converted to

  <property name="host" value="${acme.host}" />
  <property name="port" value="${acme.port}" />

Very simple, it's just configuration sugar, but comes very handy in deployments with hundreds of services.

This is available in jPOS Next (series 3.x.x) starting in 3.0.0-SNAPSHOT availble in jPOS Maven repo, as well as Github next branch.