3 Introducing the Java Adapter

This chapter describes the Oracle GoldenGate Adapter for Java. The Oracle GoldenGate Adapter for Java implements 1) the capture of Java Message Service (JMS) messages to send for processing into Oracle GoldenGate trail data, and 2) the processing of transactional data captured by Oracle GoldenGate to be delivered as JMS messages.

This chapter includes the following sections:

3.1 Oracle GoldenGate VAM Message Capture

Oracle GoldenGate message capture connects to JMS messaging to parse messages and send them through a VAM interface to an Oracle GoldenGate Extract 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.

Using Oracle GoldenGate JMS message capture requires two components:

  • The dynamically linked shared VAM library that is attached to the Oracle GoldenGate Extract process.

  • A separate utility, Gendef, that uses the message capture properties file and parser-specific data definitions to create an Oracle GoldenGate source definitions file.

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 class path 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.

3.1.2 Typical Configuration

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

In this configuration, JMS messages are picked up by the Oracle GoldenGate Adapter 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.

Figure 3-1 Configuration for JMS Message Capture

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

3.2 Oracle GoldenGate Java User Exit

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, or an integration with a custom application Java API.

Oracle GoldenGate for Java provides the ability to execute Java code from the Oracle GoldenGate Extract process. Using Oracle GoldenGate for Java requires two components:

  • A dynamically linked or shared library, implemented in C/C++, integrating as a User Exit (UE) with the Oracle GoldenGate Extract process through a C API.

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

Figure 3-2 Configuration for Delivering JMS Messages

Description of Figure 3-2 follows
Description of "Figure 3-2 Configuration for Delivering JMS Messages"

3.2.1 Delivery Configuration Options

The dynamically linked library is configurable using a simple properties file. The Java framework is loaded by the user exit and is also initialized by a properties file. Application behavior can be customized by:

  • Editing the property files; for example to:

    • Set host names, port numbers, output file names, JMS connection settings;

    • Add/remove targets (such as JMS or files) by listing any number of active handlers to which the transactions should be sent;

    • Turn on/off debug-level logging, etc.

    • Identify which message format should be used.

  • Customizing the format of messages sent to JMS or files. Message formats can be custom tailored by:

    • Setting properties for the pre-existing format process (for fixed-length or field-delimited message formats);

    • Customizing message templates, using the Velocity template macro language;

    • (Optional) Writing custom Java code.

  • (Optional) Writing custom Java code to provide custom handling of transactions and operations, do filtering, or implementing custom message formats.

There are existing implementations (handlers) for sending messages via JMS and for writing out files to disk. There are several predefined message formats for sending the messages (e.g. XML or field-delimited); or custom formats can be implemented using templates. Each handler has documentation that describes its configuration properties; for example, a file name can be specified for a file writer, and a JMS queue name can be specified for the JMS handler. Some properties apply to more than one handler; for example, the same message format can be used for JMS and files.