You can use the Event Replicator Target Adapter to replicate data to JMS queues and topics that are managed by webMethods Broker JNDI providers. Replicate the data to a JMS topic if you want to use publish-subscribe messaging; replicate the data to a JMS queue if you want to use point-to-point messaging. Once the data is published on a topic or queue, message consumers, such as webMethods Integration Server, can retrieve or consume it.
The following diagram depicts the interaction between the Event Replicator Target Adapter and the JNDI providers managed by webMethods Broker.
This document describes how to set up this JMS support in the Event Replicator Target Adapter and the high-level steps that must be taken in webMethods Broker. It covers the following topics:
webMethods Broker and My webMethods Version 7.1 or later must be installed. In addition, JMS support must be established within webMethods Broker. For complete information, read EntireX Message Service Provider (MSP), available in the webMethods EntireX documentation on Software AG's Empower web site.
To set up replication of Adabas data to a JMS topic or queue,
complete the following steps:
Set up JMS support in webMethods Broker specific for use by the Event Replicator Target Adapter. Be sure to perform the following steps in webMethods Broker:
Establish a JNDI (Java Naming and Directory Interface) provider for use by the Event Replicator Target Adapter. The root location of the JNDI is called the initial context. The JNDI serves as a template for the JMS administered objects (connection factories and destinations), storing their property settings in specified locations relative to the initial context. These settings are applied when the JMS connection factories and destinations are created and used when the JMS application runs.
Add topic and queue connection factories that configure the connections between JMS programs and webMethods Broker Server.
Bind and create topic and queue destinations in the JNDI.
As necessary, update client group access permissions to ensure they have permission to publish and subscribe to the document types used in any durable subscriptions for the JNDI's topics.
As necessary, create durable subscriptions, linking specific document types to a topic. This is necessary for subscriptions whose data is persisted if the subscriber is disconnected.
For complete information, read EntireX Message Service Provider (MSP), available in the webMethods EntireX documentation on Software AG's Empower web site.
Collect the following information about the JMS support in webMethods Broker:
The URL of the initial context of the JNDI provider established for use by the Event Replicator Target Adapter.
The lookup name of the JMS topic or queue destination (as defined to webMethods Broker) that should be used by the Event Replicator Target Adapter.
The name of the JMS topic or queue connection factory (as defined to webMethods Broker) that should be used by the Event Replicator Target Adapter.
Using the Event Replicator Target Adapter Administration tool, add a JMS target definition and save it. For more information, read Maintaining JMS Target Definitions.
Start the Event Replicator Target Adapter (if it is not already started), as described in Starting the Event Replicator Target Adapter.
Using the Adabas Event Replicator Subsystem (SYSRPTR), edit the Event Replicator subscriptions you want used to transform and submit data to the Event Replicator Target Adapter. For each subscription, verify that:
A global format buffer (GFB) and field table (GFFT) are generated for at least one SFILE definition in the subscription. The GFB and GFFT must be generated either by Event Replicator for Adabas using Predict file definitions or using the Data Mapping Tool.
At least one destination definition used by the subscription specifies a value of "SAGTARG" for the Destination Class field (DCLASS parameter).
Note:
DCLASS=SAGTARG cannot be specified for Adabas or file
destinations (DTYPE=ADABAS or FILE). It is only valid for webMethods EntireX, WebSphere MQ,
or NULL destinations. When DCLASS=SAGTARG is specified, the ADARUN RPLPARMS
parameter must be set to "FILE" or
"BOTH" to provide access to any field table (GFFT)
definitions.
Be sure to save the subscription definitions and any destination definitions you modified.
Activate the Event Replicator subscription and destination definitions. To activate subscription and destination definitions using Adabas Online System (AOS), read Managing Replication Definitions from AOS.
This section describes the structure of the XML messages containing replicated data that the Event Replicator Target Adapter publishes on JMS topics and queues. This structure is defined by an XML schema which is included with your Event Replicator Target Adapter.
This section is organized into the following topics:
The schema defining the JMS message structure is provided with the Event Replicator Target Adapter. It is called jms.xsd and can be found in the following locations:
| Platform | Directory |
|---|---|
| Windows Vista | C:\Program Files\Software AG\Event Replicator Target Adapter\vv.r.s\bin |
| Other Windows platforms | C:\Program Files\Software AG\Event Replicator Target Adapter\vv.r.s\bin |
| UNIX | $SAG/art/vvrs/bin |
The following XML elements are used in the XML messages sent to JMS topics and queues.
| Element Name | Hierarchy Level | Attributes | Subelements | Description |
|---|---|---|---|---|
<artdocument/> |
1 | version | <method/><tableName/><fields/> |
Identifies the message as an Event Replicator Target Adapter message containing replicated data from an Adabas database. |
<field/> |
3 | length name pre type value |
— | Identifies an individual field (column)
in the table that is affected by the data or table change and provides the
details about that change. The attributes that appear in the
<field/> element vary, based on the setting of
the <method/> element.
|
<fields/> |
2 | — | <field/> |
Surrounds the set of fields affected by the replicated data or table change. |
<method/> |
2 | — | — | Identifies the kind of change applied
to the database. Valid values are:
|
<tableName/> |
2 | — | — | Identifies the name of the table affected by the replicated data or table change. |
The following XML attributes are used in the XML messages sent to JMS topics and queues.
| Attribute Name | Element Used In | Prerequisite | Description |
|---|---|---|---|
| length | <field/> |
<method/> element must be
"create"
|
Identifies the length of a field being created. |
| name | <field/> |
always required | The name of the field (column). This is
the name passed to the Event Replicator Target Adapter in the generated GFB and GFFT used for Event Replicator
Target Adapter
processing.
This name is assigned to a database field when the Adabas database is initially set up. It can be renamed using the Data Mapping Tool before the Data Mapping Tool is used to generate the GFB and associated GFFT. |
| pre | <field/> |
<method/> element must be
"create"
|
Identifies the precision of a field being created. Alphanumeric fields have a precision of "0" (zero). |
| type | <field/> |
<method/> element must be
"create"
|
Identifies the data type of a field being created. |
| value | <field/> |
<method/> element must be
"insert", "update", or
"delete"
|
The value of the field being inserted or updated. |
| version | <artdocument/> |
— | The version of the Event Replicator Target Adapter schema used to generate this XML message. |
This section includes examples of all possible types of messages submitted by the Event Replicator Target Adapter to JMS queues and topics.
The following is a sample XML message produced when a table is
created. Note that the <method/> element is
set to "create.".
<artdocument version="1">
<method>create</method>
<tableName>empldb31fnr5</tableName>
<fields>
<field name="ISN" type="integer" length="30" pre="0" />
<field name="PERSONNEL-ID" type="string" length="8" pre="0" />
<field name="FIRST-NAME" type="string" length="20" pre="0" />
<field name="MIDDLE-I" type="string" length="1" pre="0" />
<field name="NAME" type="string" length="20" pre="0" />
<field name="MIDDLE-NAME" type="string" length="20" pre="0" />
<field name="MAR-STAT" type="string" length="1" pre="0" />
<field name="SEX" type="string" length="1" pre="0" />
<field name="BIRTH" type="date" length="10" pre="0" />
<field name="CITY" type="string" length="20" pre="0" />
<field name="ZIP" type="string" length="10" pre="0" />
<field name="POST-CODE" type="string" length="10" pre="0" />
<field name="COUNTRY" type="string" length="3" pre="0" />
<field name="AREA-CODE" type="string" length="6" pre="0" />
<field name="PHONE" type="string" length="15" pre="0" />
<field name="DEPT" type="string" length="6" pre="0" />
<field name="JOB-TITLE" type="string" length="25" pre="0" />
<field name="LEAVE-DUE" type="decimal" length="2" pre="0" />
<field name="LEAVE-TAKEN" type="decimal" length="2" pre="0" />
</fields>
</artdocument>
The following is a sample XML message produced when a table is
dropped. Note that the <method/> element is
set to "drop".
<artdocument version="1"> <method>drop</method> <tableName>empldb31fnr5</tableName> </artdocument>
The following is a sample XML message produced when a field
(column) is inserted into a table. Note that the
<method/> element is set to
"insert".
<artdocument version="1">
<method>insert</method>
<tableName>empldb31fnr5_INCOME_BONUS</tableName>
<fields>
<field name="ISN_INCOME_INDEX" value="1_1" />
<field name="BONUS" value="23000" />
<field name="BONUS_IX2" value="1" />
</fields>
</artdocument>
The following is a sample XML message produced when a field
(column) value is updated in a table. Note that the
<method/> element is set to
"update".
<artdocument version="1">
<method>update</method>
<tableName>empldb31fnr5_INCOME_BONUS</tableName>
<fields>
<field name="ISN_INCOME_INDEX" value="1_1" />
<field name="BONUS" value="230" />
<field name="BONUS_IX2" value="1" />
</fields>
</artdocument>
The following is a sample XML message produced when a field
(column) is deleted from a table. Note that the
<method/> element is set to
"delete".
<artdocument version="1">
<method>delete</method>
<tableName>empldb31fnr5_INCOME_BONUS</tableName>
<fields>
<field name="ISN_INCOME_INDEX" value="1_1" />
<field name="BONUS" value="23000" />
<field name="BONUS_IX2" value="1" />
</fields>
</artdocument>