This chapter includes the following sections.
Topics:
Parent topic: Oracle GoldenGate Java Delivery
Processing transaction, operation and metadata events in Java works as follows:
The Oracle GoldenGate Replicat or Extract process reads local trail data and passes the transactions, operations and database metadata to the Java Delivery Module. Metadata can come from the trail itself, a source definitions file.
Events are fired by the Java framework, optionally filtered by custom Event Filters.
Handlers (event listeners) process these events, and process the transactions, operations and metadata. Custom formatters may be applied for certain types of targets.
There are several existing handlers:
Various built in Big Data handlers to apply records to supported Big Data targets, see Introduction to GoldenGate for Big Data to configure this type of handler.
JMS message handlers to send to a JMS provider using either a MapMessage
, or using a TextMessage
with customized formatters.
A specialized message handler to send JMS messages to Oracle Advanced Queuing (AQ).
A file writer handler, for writing to a single file, or a rolling file.
Note:
The file writer handler is particularly useful as development utility, since the file writer can take the exact same formatter as the JMS TextMessage
handler. Using the file writer provides a simple way to test and tune the formatters for JMS without actually sending the messages to JMS
Event handlers can be configured using the main Java property file or they may optionally read in their own properties directly from yet another property file (depending on the handler implementation). Handler properties are set using the following syntax:
gg.handler.{name}.someproperty=somevalue
This will cause the property someproperty
to be set to the value somevalue
for the handler instance identified in the property file by name
. This name
is used in the property file to define active handlers and set their properties; it is user-defined.
Implementation note (for Java developers): Following the preceding example: when the handler is instantiated, the method void
setSomeProperty
(String value) will be called on the handler instance, passing in the String value somevalue
. A JavaBean PropertyEditor
may also be defined for the handler, in which case the string can be automatically converted to the appropriate type for the setter method. For example, in the Java application properties file, we may have the following:
# the list of active handlers: only two are active gg.handlerlist=one, two # set properties on 'one' gg.handler.one.type=file gg.handler.one.format=com.mycompany.MyFormatter gg.handler.one.file=output.xml # properties for handler 'two' gg.handler.two.type=jms_text gg.handler.two.format=com.mycompany.MyFormatter gg.handler.two.properties=jboss.properties # set properties for handler 'foo'; this handler is ignored gg.handler.foo.type=com.mycompany.MyHandler gg.handler.foo.someproperty=somevalue
The type identifies the handler class; the other properties depend on the type of handler created. If a separate properties file is used to initialize the handler (such as the JMS handlers), the properties file is found in the classpath. For example, if properties file is at: {
gg_install_dir
}/dirprm/foo.properties
, then specify in the properties file as follows: gg.handler.
name
.properties=foo.properties
.
The main Java property file identifies active handlers. The JMS handler may optionally use a separate property file for JMS-specific configuration. This allows more than one JMS handler to be configured to run at the same time.
There are examples included for several JMS providers (JBoss, TIBCO, Solace, ActiveMQ, WebLogic). For a specific JMS provider, you can choose the appropriate properties files as a starting point for your environment. Each JMS provider has slightly different settings, and your environment will have unique settings as well.
The installation directory for the Java JARs (ggjava
) contains the core application JARs (ggjava.jar
) and its dependencies in resources/lib/*.jar
. The resources directory contains all dependencies and configuration, and is in the classpath.
If the JMS client JARs already exist somewhere on the system, they can be referenced directly and added to the classpath without copying them.
The following types of JMS handlers can be specified:
jms – sends text messages to a topic or queue. The messages may be formatted using Velocity templates or by writing a formatter in Java. The same formatters can be used for a jms_text message
as for writing to files. (jms_text
is a synonym for jms
.)
aq – sends text messages to Oracle Advanced Queuing (AQ). The aq
handler is a jms
handler configured for delivery to AQ. The messages can be formatted using Velocity templates or a custom formatter.
jms_map – sends a JMS MapMessage to a topic or queue. The JMSType
of the message is set to the name of the table. The body of the message consists of the following metadata, followed by column name and column value pairs:
GG_ID
– position of the record, uniquely identifies this operation
GG_OPTYPE
– type of SQL (insert/update/delete),
GG_TABLE
– table name on which the operation occurred
GG_TIMESTAMP
– timestamp of the operation
The file handler is often used to verify the message format when the actual target is JMS, and the message format is being developed using custom Java or Velocity templates. Here is a property file using a file handler:
# one file handler active, using Velocity template formatting gg.handlerlist=myfile gg.handler.myfile.type=file gg.handler.myfile.rollover.size=5M gg.handler.myfile.format=sample2xml.vm gg.handler.myfile.file=output.xml
This example uses a single handler (though, a JMS handler and the file handler could be used at the same time), writing to a file called output.xml
, using a Velocity template called sample2xml.vm
. The template is found using the classpath.
For information on coding a custom handler, see Coding a Custom Handler in Java.
As previously described, the existing JMS and file output handlers can be configured through the properties file. Each handler has its own specific properties that can be set: for example, the output file can be set for the file handler, and the JMS destination can be set for the JMS handler. Both of these handlers may also specify a custom formatter. The same formatter may be used for both handlers. As an alternative to writing Java code for custom formatting, a Velocity template may be specified For further information, see Filtering Events.
Summary statistics about the throughput and amount of data processed are generated when the Replicat or Extract process stops. Additionally, statistics can be written periodically either after a specified amount of time or after a specified number of records have been processed. If both time and number of records are specified, then the report is generated for whichever event happens first. These statistical summaries are written to the Oracle GoldenGate report file and the log files.