10 Java Delivery Properties

Specifies the type of logging that is to be used. The default implementation for the Oracle GoldenGate Adapters is the jdk option. This is the built-in Java logging called java.util.logging (JUL). The other logging options are log4j or logback.

For example, to set the type of logging to log4j:

gg.log=log4j 

The recommended setting is log4j. The log file is created in the dirrpt subdirectory of the installation. The default log file name includes the group name of the associated Extract and the file extension is .log.

<process name>_<log level>_log4j.log

Therefore if the Oracle GoldenGate Replicat process is called javaue, and the gg.log.level is set to debug, the resulting log file name will be:

javaue_debug_log4j.log

Specifies the overall log level for all modules. The syntax is:

gg.log.level={ERROR|WARN|INFO|DEBUG|TRACE}

The log levels are defined as follows:

• ERROR – Only write messages if errors occur

• WARN – Write error and warning messages

• INFO – Write error, warning and informational messages

• DEBUG – Write all messages, including debug ones.

• TRACE - Highest level of logging, includes all messages.

The default logging level is INFO. The messages in this case will be produced on startup, shutdown and periodically during operation. If the level is switched to DEBUG, large volumes of messages may occur which could impact performance. For example, the following sets the global logging level to INFO:

# global logging level
gg.log.level=INFO

Specifies the path to the log file. The syntax is:

gg.log.file=path_to_file

Where the path_to_file is the fully defined location of the log file. This allows a change to the name of the log, but you must include the Replicat name if you have more than one Replicat to avoid one overwriting the log of the other.

Specifies the classpath to the JARs used to implement logging. This configuration property is not typically used as the ggjava.jar library includes the required logging dependency libraries.

gg.log.classpath=path_to_jars

Specifies the initial Java classpath and other boot options that will be applied when the JVM starts. The java.class.path needs colon (:) separators for UNIX/Linux and semicolons (;) for Windows. This is where to specify various options for the JVM, such as initial and maximum heap size and classpath; for example:

• -Xms: initial java heap size

• -Xmx: maximum java heap size

• -Djava.class.path: classpath specifying location of at least the main application JAR, ggjava.jar. Other JARs, such as JMS provider JARs, may also be specified here as well; alternatively, these may be specified in the Java application properties file. If using a separate log4j properties file then the location of the properties file must be included in the bootoptions java.class.path included in the bootoptions variable.

• -verbose:jni: run in verbose mode (for JNI)

For example (all on a single line):

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

The log4j.configuration property identifies a log4j properties file that is resolved by searching the classpath. You may use your own log4j configuration, or one of the preconfigured log4j settings: log4j.properties (default level of logging), debug-log4j.properties (debug logging) or trace-log4j.properties (very verbose logging). To use log4j logging with the Replicat process gg.log=log4j must be set.

Use of the one of the preconfigured log4j settings does not require any change to the classpath since those files are already included in the classpath. The -Djava.class.path variable must include the path to the directory containing a custom log4j configuration file without the * wild card appended.

The handler list is a list of active handlers separated by commas. These values are used in the rest of the property file to configure the individual handlers. For example:

gg.handlerlist=name1, name2
gg.handler.name1.propertyA=value1
gg.handler.name1.propertyB=value2
gg.handler.name1.propertyC=value3
gg.handler.name2.propertyA=value1
gg.handler.name2.propertyB=value2
gg.handler.name2.propertyC=value3

Using the handlerlist property, you may include completely configured handlers in the property file and just disable them by removing them from the handlerlist.

This type of handler. This is either a predefined value for built-in handlers, or a fully qualified Java class name. The syntax is:

gg.handler.name.type={jms|jms_map|aq|singlefile|rollingfile|custom_java_class}

Where:

All but the last are pre-defined handlers:

• jms – Sends transactions, operations, and metadata as formatted messages to a JMS provider

• aq – Sends transactions, operations, and metadata as formatted messages to Oracle Advanced Queuing (AQ)

• jms_map – Sends JMS map messages

• singlefile – Writes to a single file on disk, but does not roll the file

• rollingfile – Writes transactions, operations, and metadata to a file on disk, rolling the file over after a certain size, amount of time, or both. For example:

  gg.handler.name1.rolloverSize=5000000
  gg.handler.name1.rolloverTime=1m
  
  

• custom_java_class – Any class that extends the Oracle GoldenGate for Java AbstractHandler class and can handle transaction, operation, or metadata events

  The Oracle GoldenGate foe Big Data package also contains more predefined handlers to write to various Big Data targets.

Specifies the format used to transform operations and transactions into messages sent to JMS, to the Big Data target or to a file. The format is specified uniquely for each handler. The value may be:

• Velocity template

• Java class name (fully qualified - the class specified must be a type of formatter)

• csv for delimited values (such as comma separated values; the delimiter can be customized)

• fixed for fixed-length fields

• Built-in formatter, such as:

  • xml – demo XML format

  • xml2 – internal XML format

For example, to specify a custom Java class:

gg.handlerlist=abc
gg.handler.abc.format=com.mycompany.MyFormat

Or, for a Velocity template:

gg.handlerlist=xyz
gg.handler.xyz.format=path/to/sample.vm

If using templates, the file is found relative to some directory or JAR that is in the classpath. By default, the Oracle GoldenGate installation directory is in the classpath, so the preceding template could be placed in the dirprm directory of the Oracle GoldenGate installation location.

The default format is to use the built-in XML formatter.

Specifies a list of tables this handler will include.

If the schema (or owner) of the table is specified, then only that schema matches the table name; otherwise, the table name matches any schema. A comma separated list of tables can be specified. For example, to have the handler only process tables foo.customer and bar.orders:

gg.handler.myhandler.includeTables=foo.customer, bar.orders

If the catalog and schema (or owner) of the table are specified, then only that catalog and schema matches the table name; otherwise, the table name matches any catalog and schema. A comma separated list of tables can be specified. For example, to have the handler only process tables dbo.foo.customer and dbo.bar.orders:

gg.handler.myhandler.includeTables=dbo.foo.customer, dbo.bar.orders

Specifies a list of tables this handler will exclude.

If the schema (or owner) of the table is specified, then only that schema matches the table name; otherwise, the table name matches any schema. A list of tables may be specified, comma-separated. For example, to have the handler process all operations on all tables except table date_modified in all schemas:

gg.handler.myhandler.excludeTables=date_modified

If the catalog and schema (or owner) of the table are specified, then only that catalog and schema matches the table name; otherwise, the table name matches any catalog and schema. A list of tables may be specified, comma-separated. For example, to have the handler process all operations on all tables except table date_modified in catalog dbo and schema bar:

gg.handler.myhandler.excludeTables=dbo.bar.date_modified

Specifies whether to output one operation per message (op) or one transaction per message (tx). The default is op. Use gg.handler.name.format.mode when you have a custom formatter.

Specifies the delimiter to use between fields. Set this to no value to have no delimiter used. For example:

gg.handler.handler1.format.delim=,

Specifies the quote character to be used if column values are quoted. For example:

gg.handler.handler1.format.quote='

Specifies the metadata column values to appear at the beginning of the record, before any column data. Specify any of the following, in the order they should appear:

• position – unique position indicator of records in a trail

• opcode – I, U, or D for insert, update, or delete records (see: insertChar, updateChar, deleteChar)

• txind – transaction indicator – such as 0=begin, 1=middle, 2=end, 3=whole tx (see beginTxChar, middleTxChar, endTxChar, wholeTxChar)

• opcount – position of a record in a transaction, starting from 0

• catalog – catalog of the schema for the record

• schema – schema/owner of the table for the record

• tableonly – just table (no schema/owner)

• table – full name of table, catalog.schema.table

• timestamp – commit timestamp of record

For example:

gg.handler.handler1.format.metacols=opcode, table, txind, position

Specifies a special column prefix for a column value that was not captured from the source database transaction log. The column value is not in trail and it is unknown if it has a value or is NULL

The character used to represent the missing state of the column value can be customized. For example:

gg.handler.handler1.format.missingColumnChar=M

By default, the missing column value is set to an empty string and does not show.

Specifies a special column prefix for a column value that exists in the trail and is not NULL.

The character used to represent the state of the column can be customized. For example:

gg.handler.handler1.format.presentColumnChar=P

By default, the present column value is set to an empty string and does not show.

Specifies a special column prefix for a column value that exists in the trail and is set to NULL.

The character used to represent the state of the column can be customized. For example:

gg.handler.handler1.format.nullColumnChar=N

By default, the null column value is set to an empty string and does not show.

Specifies the header metadata character (see metacols) used to identify a record as the begin of a transaction. For example:

gg.handler.handler1.format.beginTxChar=B

Specifies the header metadata characters (see metacols) used to identify a record as the middle of a transaction. For example:

gg.handler.handler1.format.middleTxChar=M

Specifies the header metadata characters (see metacols) used to identify a record as the end of a transaction. For example:

gg.handler.handler1.format.endTxChar=E

Specifies the header metadata characters (see metacols) used to identify a record as a complete transaction; referred to as a whole transaction. For example:

gg.handler.handler1.format.wholeTxChar=W

Specifies the character to identify an insert operation. The default I.

For example, to use INS instead of I for insert operations:

gg.handler.handler1.format.insertChar=INS

Specifies the character to identify an update operation. The default is U.

For example, to use UPD instead of U for update operations:

gg.handler.handler1.format.updateChar=UPD

Specifies the character to identify a delete operation. The default is D.

For example, to use DEL instead of D for delete operations:

gg.handler.handler1.format.deleteChar=DEL

Specifies the character to identify a truncate operation. The default is T.

For example, to use TRUNC instead of T for truncate operations:

gg.handler.handler1.format.truncateChar=TRUNC

Specifies the end-of-line character as:

• EOL - Native platform

• CR - Neutral (UNIX-style \n)

• CRLF - Windows (\r\n)

For example:

gg.handler.handler1.format.endOfLine=CR

Specifies the left or right justification of fixed fields. For example:

gg.handler.handler1.format.justify=left

Controls whether before images should be included in the output. There must be before images in the trail. For example:

gg.handler.handler1.format.includeBefores=false

Specifies the name of the output file for the given handler. If the handler is a rolling file, this name is used to derive the rolled file names. The default file name is output.xml.

Controls whether the file should be appended to (true) or overwritten upon restart (false).

If using the file handler, this specifies the size of the file before a rollover should be attempted. The file size will be at least this size, but will most likely be larger. Operations and transactions are not broken across files. The size is specified in bytes, but a suffix may be given to identify MB or KB. For example:

gg.handler.myfile.rolloverSize=5MB

The default rollover size is 10MB.

These properties set limits for grouping transactions.

Specifies a comma delimited list of additional paths to directories or JARs to add to the classpath. Optionally, the list can be delimited by semicolons for Windows systems or by colons for UNIX. For example:

gg.classpath=C:\Program Files\MyProgram\bin;C:\Program Files\ProgramB\app\bin;

This Adapter properties file configuration property should be used to configure pathing to custom Java JARs or to the external dependencies of Big Data applications.

Specifies how often statistics are calculated and sent to Extract for the processing report. If Extract is configured to print a report, these statistics are included. The syntax is:

gg.report.time=report_interval{s|m|h}

Where:

• report_interval is an integer

• The valid time units are:

  • s - seconds

  • m - minutes

  • h - hours

If no value is entered, the default is to calculate and send every 24 hours.

Specifies the binary encoding type. The desired output encoding for binary data can be configured using this property. For example:

gg.binaryencoding=base64|hex

The default value is base64. The valid values to represent binary data are:

• base64 - a base64 string 

• hex - a hexadecimal string