10.4.4.3 Java Application Properties
The following defines the properties which may be set in the Java application property file.
- Properties for All Handlers
- Properties for Formatted Output
- Properties for CSV and Fixed Format Output
- File Writer Properties
- JMS Handler Properties
- JNDI Properties
- General Properties
- Java Delivery Transaction Grouping
Parent topic: Java Delivery Properties
10.4.4.3.1 Properties for All Handlers
The following properties apply to all handlers:
Parent topic: Java Application Properties
10.4.4.3.1.1 gg.handlerlist
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
.
Parent topic: Properties for All Handlers
10.4.4.3.1.2 gg.handler.name.type
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 JavaAbstractHandler
class and can handle transaction, operation, or metadata eventsThe Oracle GoldenGate for Distributed Applications and Analytics (GG for DAA) package also contains more predefined handlers to write to various GG for DAA targets.
Parent topic: Properties for All Handlers
10.4.4.3.2 Properties for Formatted Output
The following properties apply to all handlers capable of producing formatted output; this includes:
-
The
jms_text handler
(but not thejms_map handler
) -
The
aq
handler -
The
singlefile
androlling
handlers, for writing formatted output to files -
The predefined Oracle GoldenGate for Distributed Applications and Analytics (GG for DAA) handlers
- gg.handler.name.format
- gg.handler.name.includeTables
- gg.handler.name.excludeTables
- gg.handler.name.mode, gg.handler.name.format.mode
Parent topic: Java Application Properties
10.4.4.3.2.1 gg.handler.name.format
Specifies the format used to transform operations and transactions into messages sent to JMS, to the Oracle GoldenGate for Distributed Applications and Analytics (GG for DAA) 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.
Parent topic: Properties for Formatted Output
10.4.4.3.2.2 gg.handler.name.includeTables
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
Note:
In order to selectively process operations on a table by table basis, the handler must be processing in operation mode. If the handler is processing in transaction mode, then when a single transaction contains several operations spanning several tables, if any table matches the include list of tables, the transaction will be included.
Parent topic: Properties for Formatted Output
10.4.4.3.2.3 gg.handler.name.excludeTables
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
Parent topic: Properties for Formatted Output
10.4.4.3.2.4 gg.handler.name.mode, gg.handler.name.format.mode
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.
Parent topic: Properties for Formatted Output
10.4.4.3.3 Properties for CSV and Fixed Format Output
If the handler is set to use either comma separated values (CSV) CSV
or fixed
format output, the following properties may also be set.
- gg.handler.name.format.delim
- gg.handler.name.format.quote
- gg.handler.name.format.metacols
- gg.handler.name.format.missingColumnChar
- gg.handler.name.format.presentColumnChar
- gg.handler.name.format.nullColumnChar
- gg.handler.name.format.beginTxChar
- gg.handler.name.format.middleTxChar
- gg.handler.name.format.endTxChar
- gg.handler.name.format.wholeTxChar
- gg.handler.name.format.insertChar
- gg.handler.name.format.updateChar
- gg.handler.name.format.deleteChar
- gg.handler.name.format.truncateChar
- gg.handler.name.format.endOfLine
- gg.handler.name.format.justify
- gg.handler.name.format.includeBefores
Parent topic: Java Application Properties
10.4.4.3.3.1 gg.handler.name.format.delim
Specifies the delimiter to use between fields. Set this to no value to have no delimiter used. For example:
gg.handler.handler1.format.delim=,
Parent topic: Properties for CSV and Fixed Format Output
10.4.4.3.3.2 gg.handler.name.format.quote
Specifies the quote character to be used if column values are quoted. For example:
gg.handler.handler1.format.quote='
Parent topic: Properties for CSV and Fixed Format Output
10.4.4.3.3.3 gg.handler.name.format.metacols
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
, orD
for insert, update, or delete records (see:insertChar
,updateChar
,deleteChar
) -
txind – transaction indicator – such as
0
=begin,1
=middle,2
=end,3
=whole tx (seebeginTxChar
,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
Parent topic: Properties for CSV and Fixed Format Output
10.4.4.3.3.4 gg.handler.name.format.missingColumnChar
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.
Parent topic: Properties for CSV and Fixed Format Output
10.4.4.3.3.5 gg.handler.name.format.presentColumnChar
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.
Parent topic: Properties for CSV and Fixed Format Output
10.4.4.3.3.6 gg.handler.name.format.nullColumnChar
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.
Parent topic: Properties for CSV and Fixed Format Output
10.4.4.3.3.7 gg.handler.name.format.beginTxChar
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
Parent topic: Properties for CSV and Fixed Format Output
10.4.4.3.3.8 gg.handler.name.format.middleTxChar
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
Parent topic: Properties for CSV and Fixed Format Output
10.4.4.3.3.9 gg.handler.name.format.endTxChar
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
Parent topic: Properties for CSV and Fixed Format Output
10.4.4.3.3.10 gg.handler.name.format.wholeTxChar
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
Parent topic: Properties for CSV and Fixed Format Output
10.4.4.3.3.11 gg.handler.name.format.insertChar
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
Parent topic: Properties for CSV and Fixed Format Output
10.4.4.3.3.12 gg.handler.name.format.updateChar
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
Parent topic: Properties for CSV and Fixed Format Output
10.4.4.3.3.13 gg.handler.name.format.deleteChar
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
Parent topic: Properties for CSV and Fixed Format Output
10.4.4.3.3.14 gg.handler.name.format.truncateChar
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
Parent topic: Properties for CSV and Fixed Format Output
10.4.4.3.3.15 gg.handler.name.format.endOfLine
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
Parent topic: Properties for CSV and Fixed Format Output
10.4.4.3.3.16 gg.handler.name.format.justify
Specifies the left or right justification of fixed fields. For example:
gg.handler.handler1.format.justify=left
Parent topic: Properties for CSV and Fixed Format Output
10.4.4.3.3.17 gg.handler.name.format.includeBefores
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
Parent topic: Properties for CSV and Fixed Format Output
10.4.4.3.4 File Writer Properties
The following properties only apply to handlers that write their output to files: the file
handler and the singlefile
handler.
Parent topic: Java Application Properties
10.4.4.3.4.1 gg.handler.name.file
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
.
Parent topic: File Writer Properties
10.4.4.3.4.2 gg.handler.name.append
Controls whether the file should be appended to (true
) or overwritten upon restart (false
).
Parent topic: File Writer Properties
10.4.4.3.4.3 gg.handler.name.rolloverSize
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
.
Parent topic: File Writer Properties
10.4.4.3.5 JMS Handler Properties
The following properties apply to the JMS handlers. Some of these values may be defined in the Java application properties file using the name of the handler. Other properties may be placed into a separate JMS properties file, which is useful if using more than one JMS handler at a time. For example:
gg.handler.myjms.type=jms_text gg.handler.myjms.format=xml gg.handler.myjms.properties=weblogic.properties
Just as with Velocity templates and formatting property files, this additional JMS properties file is found in the classpath. The preceding properties file weblogic.properties
would be found in {
gg_install_dir
}/dirprm/weblogic.properties
, since the dirprm
directory is included by default in the classpath.
Settings that can be made in the Java application properties file will override the corresponding value set in the supplemental JMS properties file (weblogic.properties
in the preceding example). In the following example, the destination property is specified in the Java application properties file. This allows the same default connection information for the two handlers myjms1
and myjms2
, but customizes the target destination queue.
gg.handlerlist=myjms1,myjms2 gg.handler.myjms1.type=jms_text gg.handler.myjms1.destination=queue.sampleA gg.handler.myjms1.format=sample.vm gg.handler.myjms1.properties=tibco-default.properties gg.handler.myjms2.type=jms_map gg.handler.myjms2.destination=queue.sampleB gg.handler.myjms2.properties=tibco-default.properties
To set a property, specify the handler name as a prefix; for example:
gg.handlerlist=sample gg.handler.sample.type=jms_text gg.handler.sample.format=my_template.vm gg.handler.sample.destination=gg.myqueue gg.handler.sample.queueortopic=queue gg.handler.sample.connectionUrl=tcp://host:61616?jms.useAsyncSend=true gg.handler.sample.useJndi=false gg.handler.sample.connectionFactory=ConnectionFactory gg.handler.sample.connectionFactoryClass=\ org.apache.activemq.ActiveMQConnectionFactory gg.handler.sample.timeToLive=50000
10.4.4.3.5.1 Standard JMS Settings
The following outlines the JMS properties which may be set, and the accepted values. These apply for both JMS handler types: jms_text
(TextMessage
) and jms_map
(MapMessage
).
- gg.handler.name.destination
- gg.handler.name.user
- gg.handler.name.password
- gg.handler.name.queueOrTopic
- gg.handler.name.persistent
- gg.handler.name.priority
- gg.handler.name.timeToLive
- gg.handler.name.connectionFactory
- gg.handler.name.useJndi
- gg.handler.name.connectionUrl
- gg.handler.name.connectionFactoryClass
- gg.handler.name.localTX
- gg.handlerlist.nop
- gg.handler.name.physicalDestination
Parent topic: JMS Handler Properties
10.4.4.3.5.1.1 gg.handler.name.destination
The queue or topic to which the message is sent. This must be correctly configured on the JMS server. Typical values may be: queue/A
, queue.Test
, example.MyTopic
, etc.
gg.handler.name
.destination=queue_or_topic
Parent topic: Standard JMS Settings
10.4.4.3.5.1.2 gg.handler.name.user
(Optional) User name required to send messages to the JMS server.
gg.handler.name
.user=user_name
Parent topic: Standard JMS Settings
10.4.4.3.5.1.3 gg.handler.name.password
(Optional) Password required to send messages to the JMS server
gg.handler.name
.password=password
Parent topic: Standard JMS Settings
10.4.4.3.5.1.4 gg.handler.name.queueOrTopic
Whether the handler is sending to a queue (a single receiver) or a topic (publish / subscribe). This must be correctly configured in the JMS provider. This property is an alias of gg.handler
.name
.destination
. The syntax is:
gg.handler.name
.queueOrTopic=queue|topic
Where:
-
queue
– a message is removed from the queue once it has been read. This is the default. -
topic
– messages are published and may be delivered to multiple subscribers.
Parent topic: Standard JMS Settings
10.4.4.3.5.1.5 gg.handler.name.persistent
If the delivery mode is set to persistent or not. If the messages are to be persistent, the JMS provider must be configured to log the message to stable storage as part of the client's send operation. The syntax is:
gg.handler.name
.persistent={true|false}
Parent topic: Standard JMS Settings
10.4.4.3.5.1.6 gg.handler.name.priority
JMS defines a 10 level priority value, with 0 as the lowest and 9 as the highest. Priority is set to 4 by default. The syntax is:
gg.handler.name
.priority=integer
For example:
gg.handler.name
.priority=5
Parent topic: Standard JMS Settings
10.4.4.3.5.1.7 gg.handler.name.timeToLive
The length of time in milliseconds from its dispatch time that a produced message should be retained by the message system. A value of zero specifies the time is unlimited. The default is zero. The syntax is:
gg.handler.name
.timeToLive=milliseconds
For example:
gg.handler.name
.timeToLive= 36000
Parent topic: Standard JMS Settings
10.4.4.3.5.1.8 gg.handler.name.connectionFactory
Name of the connection factory to lookup using JNDI. ConnectionFactoryJNDIName
is an alias. The syntax is:
gg.handler.name
.connectionFactory=JNDI_name
Parent topic: Standard JMS Settings
10.4.4.3.5.1.9 gg.handler.name.useJndi
If gg.handler.
name
.usejndi
is false
, then JNDI is not used to configure the JMS client. Instead, factories and connections are explicitly constructed. The syntax is:
gg.handler.name
.useJndi=true|false
Parent topic: Standard JMS Settings
10.4.4.3.5.1.10 gg.handler.name.connectionUrl
Connection URL is used only when not using JNDI to explicitly create the connection. The syntax is:
gg.handler.name
.connectionUrl=url
Parent topic: Standard JMS Settings
10.4.4.3.5.1.11 gg.handler.name.connectionFactoryClass
The Connection Factory Class is used to access a factory only when not using JNDI. The value of this property is the Java class name to instantiate; constructing a factory object explicitly.
gg.handler.name
.connectionFactoryClass=java_class_name
Parent topic: Standard JMS Settings
10.4.4.3.5.1.12 gg.handler.name.localTX
Specifies whether or not local transactions are used. The default is true
, local transactions are used. The syntax is:
gg.handler.name.localTX=true|false
Parent topic: Standard JMS Settings
10.4.4.3.5.1.13 gg.handlerlist.nop
Disables the sending of JMS messages to allow testing of message generation. This is a global property used only for testing. The events are still generated and handled and the message is constructed. The default is false
; do not disable message send. The syntax is:
gg.handlerlist.nop=true|false
Users can take advantage of this option to measure the performance of trail records processing without involving the handler module. This approach can narrow down the possible culprits of a suspected performance issue while applying trail records to the target system.
Parent topic: Standard JMS Settings
10.4.4.3.5.1.14 gg.handler.name.physicalDestination
Name of the queue or topic object, obtained through the ConnectionFactory
API instead of the JNDI provider.
gg.handler.name.physicalDestination=queue_name
Parent topic: Standard JMS Settings
10.4.4.3.5.2 Group Transaction Properties
These properties set limits for grouping transactions.
Parent topic: JMS Handler Properties
10.4.4.3.6 JNDI Properties
These JNDI properties are required for connection to an Initial Context to look up the connection factory and initial destination.
java.naming.provider.url=url
java.naming.factory.initial=java-class-name
If JNDI security is enabled
, the following properties may be set:
java.naming.security.principal=user-name
java.naming.security.credentials=password-or-other-authenticator
For example:
java.naming.provider.url= t3://localhost:7001 java.naming.factory.initial=weblogic.jndi.WLInitialContextFactory java.naming.security.principal=jndiuser java.naming.security.credentials=jndipw
Parent topic: Java Application Properties
10.4.4.3.7 General Properties
The following are general properties that are used for the Java framework:
10.4.4.3.7.1 gg.classpath
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 Oracle GoldenGate for Distributed Applications and Analytics (GG for DAA).
Parent topic: General Properties
10.4.4.3.7.2 gg.report.time
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.
Parent topic: General Properties
10.4.4.3.7.3 gg.binaryencoding
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
Parent topic: General Properties
10.4.4.3.8 Java Delivery Transaction Grouping
Transaction grouping can significantly improve the performance of Java integrations
especially Oracle GoldenGate for Distributed Applications and Analytics (GG for DAA)
integrations. Java Delivery provides functionality to perform transaction grouping.
When Java Delivery is hosted by a Replicat process then the
GROUPTRANSOPS
Replicat configuration should be used to perform
transaction grouping.
Parent topic: Java Application Properties