This chapter includes the following sections:
Processing transaction, operation and metadata events in Java works as follows:
The Oracle GoldenGate Replicat reads local trail data and passes the transactions, operations and database metadata to the user exit. Metadata can come from a source definitions file or a metadata definition included in the trail.
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:
A message handler 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 above 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 class path. 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 class path.
If the JMS client jars already exist somewhere on the system, they can be referenced directly and added to the class path 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 temlates 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 via 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 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 user exit log files.