12 Configuring Message Delivery

This chapter explains how to configure the adapter for delivering messages. To do this, you must set up the properties in the user exit properties file, configure an Extract or Replicate process to run the user exit, and identify the built-in or custom event handlers you will use.

This chapter includes the following sections:

12.1 Configure the JRE in the User Exit Properties File

Modify the user exit properties file to point to the location of the Oracle GoldenGate for Java main jar (ggjava.jar) and set any additional JVM runtime boot options as required (these are passed directly to the JVM at startup):

jvm.bootoptions=-Djava.class.path=ggjava/ggjava.jar
-Dlog4j.configuration=log4j.properties -Xmx512m

Note the following options in particular:

  • java.class.path can include any custom jars in addition to the core application (ggjava.jar). The current directory (.) is included by default in the class path. You can reference files relative to the Oracle GoldenGate install directory, to allow storing Java property files, Velocity templates and other class path resources in the dirprm subdirectory. It is also possible to append to the class path in the Java application properties file.

  • The log4j.configuration option specifies a log4j properties file, found in the class path. There are pre-configured default log4j settings for basic logging (log4j.properties), debug logging (debug-log4j.properties), and detailed trace-level logging (trace-log4j.properties), found in the resources/classes directory.

Once the user exit properties file is correctly configured for your system, it usually remains unchanged. See User Exit Properties, for additional configuration options.

12.2 Configure Extract to Run the User Exit

The user exit Extract is configured as a data pump. The data pump consumes a local trail (for example dirdat/aa) and sends the data to the user exit. The user exit is responsible for processing all the data.

Following is an example of adding a data pump Extract:

ADD EXTRACT javaue, EXTTRAILSOURCE ./dirdat/aa

The process names and trail names used above can be replaced with any valid name. Process names must be 8 characters or less, trail names must to be two characters. In the user exit Extract parameter file (javaue.prm) specify the location of the user exit library.

Table 12-1 User Exit Extract Parameters

Parameter Explanation 
EXTRACT javaue

All Extract parameter files start with the Extract name

 
SOURCEDEFS ./dirdef/tcust.def

The Extract process requires metadata describing the trail data. This can come from a database or a source definitions file. This metadata defines the column names and data types in the trail being read (./dirdat/aa).

 
SETENV (GGS_USEREXIT_CONF = "dirprm/javaue.properties")

(Optional) An absolute or relative path (relative to the Extract executable) to the properties file for the C user exit library. The default value is extract_name.properties in the dirprm directory.

 
SETENV (GGS_JAVAUSEREXIT_CONF = "dirprm/javaue.properties")

(Optional) The Java properties.This example places the properties file in the dirpm directory.

 
CUSEREXIT ggjava_ue.dll CUSEREXIT
PASSTHRU
INCLUDEUPDATEBEFORES

The CUSEREXIT parameter includes the following:

  • The location of the user exit library. For UNIX, the library would be suffixed .so

  • CUSEREXIT - the callback function name that must be uppercase.

  • PASSTHRU - avoids the need for a dummy target trail.

  • INCLUDEUPDATEBEFORES - needed for transaction integrity.

 
TABLE schema.*;

The tables to pass to the User Exit; tables not included will be skipped. No filtering may be done in the user exit Extract; otherwise transaction markers will be missed. You can filter in the primary Extract, or use another, upstream data pump, or filter data directly in the Java application.

Note:

Using PASSTHRU disables the statistical reporting that allows report counts to be included in the processing report. To collect report count statistics and send them to the Extract from the user exit, use the property gg.report.time.

The two environment properties shown above are optional.

  • SETENV (GGS_USEREXIT_CONF = "dirprm/javaue.properties")

    This changes the default configuration file used for the User Exit shared library. The value given is either an absolute path, or a path relative to Extract (or Replicat). The example above uses a relative path to put this property file in the dirprm directory.

    The default file used is extract_name.properties, located in the dirprm directory. So, if the Extract name is pumpA, then the prm file is dirprm/pumpA.prm and the properties file is dirprm/pumpA.properties.

  • SETENV (GGS_JAVAUSEREXIT_CONF = "dirprm/javaue.properties")

    This changes the default properties file used for the Oracle GoldenGate for Java framework. The value found is a path to a file found in the class path or in a normal file system path.

    Both GGS_USEREXIT_CONF and GGS_JAVAUSEREXIT_CONF default to the same file; dirprm/extract_name.properties.

12.3 Configure the Java Handlers

The Oracle GoldenGate Java API has a property file used to configure active event handlers. To test the configuration, you may use the built-in file handler. Here are some example properties, followed by explanations of the properties (comment lines start with #):

# the list of active handlers
gg.handlerlist=myhandler
# set properties on 'myhandler'
gg.handler.myhandler.type=file
gg.handler.myhandler.format=tx2xml.vm
gg.handler.myhandler.file=output.xml

This property file declares the following:

  • Active event handlers. In the example a single event handler is active, called myhandler. Multiple handlers may be specified, separated by commas. For example: gg.handlerlist=myhandler, yourhandler

  • Configuration of the handlers. In the example myhandler is declared to be a file type of handler: gg.handler.myhandler.type=file

    Note:

    See the documentation for each type of handler (e.g. the JMS handler or the file writer handler) for the list of valid properties that can be set.

  • The format of the output is defined by the Velocity template tx2xml.vm. You may specify your own custom template to define the message format; just specify the path to your template relative to the Java class path (this is discussed later).

This property file is actually a complete example that will write captured transactions to the output file output.xml. Other handler types can be specified using the key words: jms_text (or jms), jms_map, singlefile (a file that does not roll), and others. Custom handlers can be implemented, in which case the type would be the fully qualified name of the Java class for the handler.