9 Configuring Message Capture

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

This chapter includes the following sections:

9.1 Configuring the VAM Extract

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.

9.1.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.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.
TABLE OGG.*	A list of tables to process. Wildcards may be used in the table name.

9.1.3 Configuring Message Capture

Message capture is configured by the properties in the VAM 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.2 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 messages to a trail, commit the transaction, and remove its messages from the queue.

9.2.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 class path 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.2.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.2.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 the local transaction is rolled back leaving the messages in the JMS queue.