USER MANUALS

JMS Listeners

Virtual DataPort can subscribe to a JMS server (Java Message Service (JMS)) to listen to requests. Therefore, clients, instead of connecting to Virtual DataPort via JDBC, ODBC or a web service, can send a request to a JMS server, which forwards it to Virtual DataPort. Then, the response is sent back to a queue or a topic of the JMS server, which forwards it to the client/s.

The first time you create a JMS listener, first, install the client jars of the JMS server you are going to use. The appendix Installing the JMS Connectors to Create JMS Listeners and Web Services with SOAP Over JMS explains how to do this.

When creating a JMS listener, you can set it up to:

  1. Execute the VQL statements received from a JMS server.

  2. Or, define a query with the interpolation variable (@JMSEXPRESSION) in the JMS listener and at runtime, replace this variable with the values received from the JMS server.

You can configure the listener to publish the result of the queries to a JMS server (a queue or a topic) topic. The output can be an XML document or a JSON document.

Example of how the option a) works: a client sends a message such as SELECT * FROM internet_inc WHERE iinc_id=1 to the JMS server. The JMS server will forward this to Virtual DataPort, which will send a response back like XML response message sent by a JMS listener if the selected output is XML, or like JSON response message sent by a JMS listener if the selected output is JSON.

XML response message sent by a JMS listener
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <item>
        <iinc_id>1.00</iinc_id>
        <summary>Error in ADSL router</summary>
        <ttime>29-jun-2005 19h 19m 41s</ttime>
        <taxid>B78596011</taxid>
        <specific_field1>1</specific_field1>
        <specific_field2>1</specific_field2>
    </item>
</response>
JSON response message sent by a JMS listener
[{
   "IINC_ID": 1,
   "SUMMARY": "Error in ADSL router",
   "TTIME": "2005-06-29",
   "TAXID": "B78596011",
   "SPECIFIC_FIELD1": "1",
   "SPECIFIC_FIELD2": "1"
}]

If the request is a DML sentence such as ALTER VIEW incidents CACHE INVALIDATE, the response will be empty (see XML response message to a DML query and JSON response message to a DML query)

XML response message to a DML query
<?xml version="1.0" encoding="UTF-8"?>
<response />
JSON response message to a DML query
[]

Example of how option b) works: if you have created a JMS listener with the following query:

Sample query defined in a JMS listener
SELECT *
FROM incidents
WHERE taxid = '@JMSEXPRESSION'

When the listener receives a value like B78596014, the Server will execute the following query:

Sample query defined in a JMS listener
SELECT *
FROM incidents
WHERE taxid = 'B78596014'

If the query defined in the JMS listener does not contain the @JMSEXPRESSION variable, the value received from the listener is ignored and the query will be executed “as is”.

Advanced JMS Configuration

There are several configuration options available to control how JMS messages are processed by Denodo JMS listeners.

When you change any of these options, restart Virtual DataPort to apply the changes.

Acknowledge Mode

JMS messages acknowledge mode, as defined by the JMS documentation, can be configured with property com.denodo.jms.acknowledgeMode. This property must be set to one of the following values:

  1. AUTO_ACKNOWLEDGE (default value)

  1. CLIENT_ACKNOWLEDGE

  2. DUPS_OK_ACKNOWLEDGE

Acknowledge On Query Finish and Serialized Processing

When “Acknowledge On Query Finish” mode is enabled, JMS listeners will acknowledge the reception of a message only after the query associated to it has finished.

The mode “Acknowledge On Query Finish” is disabled by default. To enable it, execute this:

SET 'com.denodo.jms.acknowledgeMode'='CLIENT_ACKNOWLEDGE';
SET 'com.denodo.jms.acknowledgeOnQueryFinish'='true';

To enable or disable “Acknowledge On Query Finish” on a listener in particular, execute this:

SET 'com.denodo.jms.acknowledgeOnQueryFinish.<database of the JMS listener>.<name of the JMS listener>'='<boolean>';

To disable this for a particular listener, the value of this property has to be “false”. To enable this for a particular listener, set this property to “true”

Examples of enabling / disabling “Acknowledge On Query Finish”

Enabling “Acknowledge On Query Finish” on all listeners except two of them
SET 'com.denodo.jms.acknowledgeMode'='CLIENT_ACKNOWLEDGE';
SET 'com.denodo.jms.acknowledgeOnQueryFinish'='true';
SET 'com.denodo.jms.acknowledgeOnQueryFinish.customer360.jms_orders_queue'='false';
SET 'com.denodo.jms.acknowledgeOnQueryFinish.customer360_development.jms_orders_queue_v2'='false';
Enabling “Acknowledge On Query Finish” only on one listener
SET 'com.denodo.jms.acknowledgeMode'='CLIENT_ACKNOWLEDGE';
SET 'com.denodo.jms.acknowledgeOnQueryFinish'='false';
SET 'com.denodo.jms.acknowledgeOnQueryFinish.customer360.jms_orders_queue'='true';
Removing the “Acknowledge On Query Finish” setting for a particular data source
SET 'com.denodo.jms.acknowledgeOnQueryFinish.customer360.jms_orders_queue' = NULL;

In this case, the data source “jms_orders_queue” will use the default configuration for “Acknowledge On Query Finish”.


When “Serialized Processing” mode is enabled, JMS listeners only process one JMS message at a time.

The mode “Serialized Processing” is disabled by default. To enable it, execute this:

SET 'com.denodo.jms.serializeMessageProcessing'='true';

To enable or disable “Serialized Processing” on a listener in particular, execute this:

SET 'com.denodo.jms.serializeMessageProcessing.<database of the JMS listener>.<name of the JMS listener>'='<boolean>';

To disable this for a particular listener, the value of this property has to be “false”. To enable this for a particular listener, set this property to “true”

Examples of enabling / disabling “Serialized Processing”

Enabling “Serialized Processing” on all listeners except two of them
SET 'com.denodo.jms.serializeMessageProcessing'='true';
SET 'com.denodo.jms.serializeMessageProcessing.customer360.jms_orders_queue'='false';
SET 'com.denodo.jms.serializeMessageProcessing.customer360_development.jms_orders_queue_v2'='false';
Enabling “Serialized Processing” only on one listener
SET 'com.denodo.jms.serializeMessageProcessing'='false';
SET 'com.denodo.jms.serializeMessageProcessing.customer360.jms_orders_queue'='true';
Removing the “Serialized Processing” setting for a particular data source
SET 'com.denodo.jms.serializeMessageProcessing.customer360.jms_orders_queue' = NULL;

In this case, the data source “jms_orders_queue” will use the default configuration for “Serialized Processing”.


Activating both modes (“Acknowledge On Query Finish” and “Serialized Processing”) is useful when you need to make sure that all the messages in the queue that a JMS listener is subscribed to will be executed by Virtual DataPort.

You may activate “Serialized Processing” only (without activating “Acknowledge On Query Finish”) if the messages of a particular queue define long queries and you need the queue to be emptied as soon as possible: in this case, there will be no guarantee that all the queries defined by the messages in the queue are actually executed by Virtual DataPort.

Enabling Advanced Logging for JMS Listeners

You can enable advanced logging for JMS listeners. This way, whenever a JMS message issues a query that fails, the following information will be logged:

  1. The JMS listener which received the message.

  1. JMS message metadata (id, timestamp, etc.).

  2. VQL query executed by the listener.

  3. Obtained error.

To activate the advanced logging for JMS listeners, follow these steps:

  1. Stop Virtual DataPort.

  2. Open the file <DENODO_HOME>/conf/vdp/log4j2.xml in an editor.

  3. Add a new appender like this (replace <DENODO_HOME> with the actual path):

    JMSOUT appender
    <RollingFile name="JMSOUT"
             fileName="<DENODO_HOME>/logs/vdp/vdp-jms${env:vdp.instance.log}.log"
             filePattern="<DENODO_HOME>/logs/vdp/vdp-jms${env:vdp.instance.log}.log.%i">
       <Policies>
             <SizeBasedTriggeringPolicy size="10 MB" />
       </Policies>
       <DefaultRolloverStrategy max="7" />
       <PatternLayout pattern="%-4r [%t] %d{yyyy-MM-dd'T'HH:mm:ss.SSS} %x -\t%m  %n" />
</RollingFile>

  1. Add a new logger:

    com.denodo.jms.verbose logger
    <Logger name="com.denodo.jms.verbose" level="debug" additivity="false" >
       <AppenderRef ref="JMSOUT" />
</Logger>

  2. Start Virtual DataPort.

After this, the listeners will log the detailed information in <DENODO_HOME>/logs/vdp/vdp-jms.log.

Add feedback