1. Oracle GoldenGate for Distributed Applications and Analytics
  2. Replicate Data
  3. Source
  4. Java Message Service (JMS)

9.1.8 Java Message Service (JMS)

This article explains using the Oracle GoldenGate for Distributed Applications and Analytics (GG for DAA) to capture Java Message Service (JMS) messages to be written to an Oracle GoldenGate trail.

Parent topic: Source

9.1.8.1 Prerequisites

Parent topic: Java Message Service (JMS)

9.1.8.1.1 Set up Credential Store Entry to Detect Source Type

JMS Capture

Similar to Kafka, for the sake of detecting the source type, user can create a credential store entry with the prefix: jms://.

Note:

You can set up Credential Store Entry in Administration Service/ DB Connections.
Example 
alter credentialstore add user jms:// password <anypassword> alias jms
If the extract parameter file does not specify SOURCEDB parameter with USERIDALIAS option, then the source type will be assumed to be JMS, and a warning message will be logged to indicate this.

Parent topic: Prerequisites

9.1.8.2 Oracle GoldenGate Java Delivery

Through the Oracle GoldenGate Java API, transactional data captured by Oracle GoldenGate can be delivered to targets other than a relational database, such as a JMS (Java Message Service), files written to disk, streaming data to a Oracle GoldenGate for Distributed Applications and Analytics (GG for DAA) application, or integration with a custom application Java API. Oracle GoldenGate Java Delivery can work with either an Extract or Replicat process. Using the Oracle GoldenGate Replicat process is considered the best practice. Oracle GoldenGate Java Delivery requires Java 8 as a dependency.

Oracle GoldenGate for Java provides the ability to execute Java code from the Oracle GoldenGate Replicat process. Using Oracle GoldenGate for Java requires the following conditions to be met:

  • A dynamically linked or shared library, implemented in C/C++, integrating an extension module of Oracle GoldenGate Replicat process.

  • A set of Java libraries (JARs), which comprise the Oracle GoldenGate Java API. This Java framework communicates with the Replicat through the Java Native Interface (JNI).

  • Java 8 must be installed and accessible on the machine hosting the Oracle GoldenGate Java Delivery process or processes. Environmental variables must be correctly set to resolve Java and its associated libraries.

Figure 9-1 Configuration for Delivering JMS Messages

Description of Figure 9-1 follows
Description of "Figure 9-1 Configuration for Delivering JMS Messages"

Parent topic: Java Message Service (JMS)

9.1.8.3 Configuring Message Capture

This chapter explains how to configure the VAM Extract to capture JMS messages.

Parent topic: Java Message Service (JMS)

9.1.8.3.1 Oracle GoldenGate VAM Message Capture

Oracle GoldenGate VAM Message Capture only works with the Oracle GoldenGate Extract process. Oracle GoldenGate message capture connects to JMS messaging to parse messages and send them through a VAM interface to an Oracle GoldenGate Extract process that builds an Oracle GoldenGate trail of message data. This allows JMS messages to be delivered to an Oracle GoldenGate system running for a target database. Java 8 is a required dependency for Oracle GoldenGate VAM Message Capture.

Using Oracle GoldenGate JMS message capture requires the dynamically linked shared VAM library that is attached to the Oracle GoldenGate Extract process.

Parent topic: Configuring Message Capture

9.1.8.3.1.1 Message Capture Configuration Options

The options for configuring the three parts of message capture are:

  • Message connectivity: Values in the property file set connection properties such as the Java classpath for the JMS client, the JMS source destination name, JNDI connection properties, and security information.

  • Parsing: Values in the property file set parsing rules for fixed width, comma delimited, or XML messages. This includes settings such as the delimiter to be used, values for the beginning and end of transactions and the date format.

  • VAM interface: Parameters that identify the VAM, dll, or so library and a property file are set for the Oracle GoldenGate core Extract process.

9.1.8.3.1.2 Typical Configuration

The following diagram shows a typical configuration for capturing JMS messages.

Figure 9-2 Configuration for JMS Message Capture

Description of Figure 9-2 follows
Description of "Figure 9-2 Configuration for JMS Message Capture"

In this configuration, JMS messages are picked up by the Oracle GoldenGate for Distributed Applications and Analytics (GG for DAA) JMS Handler and transferred using the adapter's message capture VAM to an Extract process. The Extract writes the data to a trail which is sent over the network by a Data Pump Extract to an Oracle GoldenGate target instance. The target Replicat then uses the trail to update the target database.

9.1.8.3.2 Configuring the VAM Extract

JMS Capture only works with the Oracle GoldenGate Extract process. To run the Java message capture application you need the following:

  • Oracle GoldenGate for Java Adapter

  • Extract process

  • Extract parameter file configured for message capture

  • Description of the incoming data format, such as a source definitions file.

  • Java 8 installed on the host machine

Parent topic: Configuring Message Capture

9.1.8.3.2.1 Adding the Extract

To add the message capture VAM to the Oracle GoldenGate installation, add an Extract and the trail that it will create using GGSCI commands:

ADD EXTRACT jmsvam, VAM
ADD EXTTRAIL dirdat/id, EXTRACT jmsvam, MEGABYTES 100

The process name (jmsvam) can be replaced with any process name that is no more than 8 characters. The trail identifier (id) can be any two characters.

Note:

Commands to position the Extract, such as BEGIN or EXTRBA, are not supported for message capture. The Extract will always resume by reading messages from the end of the message queue.

9.1.8.3.2.2 Configuring the Extract Parameters

The Extract parameter file contains the parameters needed to define and invoke the VAM. Sample Extract parameters for communicating with the VAM are shown in the table.

Parameter Description 
EXTRACT jmsvam

The name of the Extract process.

 
VAM ggjava_vam.dll,
PARAMS dirprm/jmsvam.properties

Specifies the name of the VAM library and the location of the properties file. The VAM properties should be in the dirprm directory of the Oracle GoldenGate installation location. 

TRANLOGOPTIONS VAMCOMPATIBILITY 1

Specifies the original (1) implementation of the VAM is to be used.

 
TRANLOGOPTIONS GETMETADATAFROMVAM

Specifies that metadata will be sent by the VAM.

 
EXTTRAIL dirdat/id

Specifies the identifier of the target trail Extract creates.
9.1.8.3.2.3 Configuring Message Capture

Message capture is configured by the properties in the VAM properties file (Adapter Properties file. This file is identified by the PARAMS option of the Extract VAM parameter and used to determine logging characteristics, parser mappings and JMS connection settings.

9.1.8.3.3 Connecting and Retrieving the Messages

To process JMS messages you must configure the connection to the JMS interface, retrieve and parse the messages in a transaction, write each message to a trail, commit the transaction, and remove its messages from the queue.

Parent topic: Configuring Message Capture

9.1.8.3.3.1 Connecting to JMS

Connectivity to JMS is through a generic JMS interface. Properties can be set to configure the following characteristics of the connection:

  • Java classpath for the JMS client

  • Name of the JMS queue or topic source destination

  • Java Naming and Directory Interface (JNDI) connection properties

    • Connection properties for Initial Context

    • Connection factory name

    • Destination name

  • Security information

    • JNDI authentication credentials

    • JMS user name and password

The Extract process that is configured to work with the VAM (such as the jmsvam in the example) will connect to the message system. when it starts up.

Note:

The Extract may be included in the Manger's AUTORESTART list so it will automatically be restarted if there are connection problems during processing.

Currently the Oracle GoldenGate for Java message capture adapter supports only JMS text messages.

9.1.8.3.3.2 Retrieving Messages

The connection processing performs the following steps when asked for the next message:

  • Start a local JMS transaction if one is not already started.

  • Read a message from the message queue.

  • If the read fails because no message exists, return an end-of-file message.

  • Otherwise return the contents of the message.

9.1.8.3.3.3 Completing the Transaction

Once all of the messages that make up a transaction have been successfully retrieved, parsed, and written to the Oracle GoldenGate trail, the local JMS transaction is committed and the messages removed from the queue or topic. If there is an error then the local transaction is rolled back leaving the messages in the JMS queue.

9.1.8.3.4 Oracle GoldenGate VAM Message Capture

Oracle GoldenGate VAM Message Capture only works with the Oracle GoldenGate Extract process. Oracle GoldenGate message capture connects to JMS messaging to parse messages and send them through a VAM interface to an Oracle GoldenGate Extract process that builds an Oracle GoldenGate trail of message data. This allows JMS messages to be delivered to an Oracle GoldenGate system running for a target database. Java 8 is a required dependency for Oracle GoldenGate VAM Message Capture.

Using Oracle GoldenGate JMS message capture requires the dynamically linked shared VAM library that is attached to the Oracle GoldenGate Extract process.

Parent topic: Configuring Message Capture

9.1.8.3.4.1 Message Capture Configuration Options

The options for configuring the three parts of message capture are:

  • Message connectivity: Values in the property file set connection properties such as the Java classpath for the JMS client, the JMS source destination name, JNDI connection properties, and security information.

  • Parsing: Values in the property file set parsing rules for fixed width, comma delimited, or XML messages. This includes settings such as the delimiter to be used, values for the beginning and end of transactions and the date format.

  • VAM interface: Parameters that identify the VAM, dll, or so library and a property file are set for the Oracle GoldenGate core Extract process.

9.1.8.3.4.2 Typical Configuration

The following diagram shows a typical configuration for capturing JMS messages.

Figure 9-3 Configuration for JMS Message Capture

Description of Figure 9-3 follows
Description of "Figure 9-3 Configuration for JMS Message Capture"

In this configuration, JMS messages are picked up by the Oracle GoldenGate for Distributed Applications and Analytics (GG for DAA) JMS Handler and transferred using the adapter's message capture VAM to an Extract process. The Extract writes the data to a trail which is sent over the network by a Data Pump Extract to an Oracle GoldenGate target instance. The target Replicat then uses the trail to update the target database.