18 Using the Java Message Service Handler

The Java Message Service (JMS) Handler allows operations from a trail file to be formatted in messages, and then published to JMS providers like Oracle Weblogic Server, Websphere, and ActiveMQ.

This chapter describes how to use the JMS Handler.

• Overview
  
• Setting Up and Running the JMS Handler
  

18.1 Overview

The Java Message Service is a Java API that allows applications to create, send, receive, and read messages. The JMS API defines a common set of interfaces and associated semantics that allow programs written in the Java programming language to communicate with other messaging implementations.

The JMS Handler captures the Oracle GoldenGate trail and sends those messages to the configured JMS providers.

18.2 Setting Up and Running the JMS Handler

The JMS Handler setup (JNDI configuration) depends on the JMS provider that you use.

The following sections provide instructions for configuring the JMS Handler components and running the handler.

Runtime Prerequisites

The JMS provider should be up and running with the required ConnectionFactory and QueueConnectionFactory and TopicConnectionFactory configured.

Security

Configure the SSL according to the JMS Provider used.

• Classpath Configuration
  Oracle recommends that you store the JMS Handler properties file in the Oracle GoldenGate dirprm directory.
• Java Naming and Directory Interface Configuration
  
• Handler Configuration
  
• Sample Configuration Using Oracle WebLogic Server
  

18.2.1 Classpath Configuration

Oracle recommends that you store the JMS Handler properties file in the Oracle GoldenGate dirprm directory.

The JMS Handler requires the JMS Provider client JARs are in the classpath in order to execute. Additionally, in Java 8, the Java EE Specification classes have been moved out of the JDK to an independent project. JMS is a part of the Java EE Specification so the Java EE Specification jar is an additional depdendency. For more information to download the jar, see JMS Dependencies.

The location of the providers client JARs is similar to:

gg.classpath= path_to_the_providers_client_jars

18.2.2 Java Naming and Directory Interface Configuration

You configure the Java Naming and Directory Interface (JNDI) properties to connect to an Initial Context to look up the connection factory and initial destination.

Table 18-1 JNDI Configuration Properties

Properties	Required/ Optional	Legal Values	Default	Explanation
java.naming.provider.url	Required	Valid provider URL with port	None	Specifies the URL that the handler uses to look up objects on the server. For example, t3://localhost:7001 or if SSL is enabled t3s://localhost:7002.
java.naming.factory.initial	Required	Initial Context factory class name	None	Specifies which initial context factory to use when creating a new initial context object. For Oracle WebLogic Server, the value is weblogic.jndi.WLInitialContextFactory.
java.naming.security.principal	Required	Valid user name	None	Specifies the user name to use.
java.naming.security.credentials	Required	Valid password	None	Specifies the password for the user.

18.2.3 Handler Configuration

You configure the JMS Handler operation using the properties file. These properties are located in the Java Adapter properties file (not in the Replicat properties file).

To enable the selection of the JMS Handler, you must first configure the handler type by specifying gg.handler.name.type=jms and the other JMS properties as follows:

Table 18-2 JMS Handler Configuration Properties

Properties	Required/ Optional	Legal Values	Default	Explanation
gg.handler.name.type	Required	JMS	None	Set to jms to send transactions, operations, and metadata as formatted text messages to a JMS provider. Set to jms_map to send JMS map messages.
gg.handler.name.destination	Required	Valid queue or topic name	None	Sets the queue or topic to which the message is sent. This must be correctly configured on the JMS server. For example, queue/A, queue.Test, example.MyTopic.
gg.handler.name.destinationType	Optional	queue | topic	queue	Specifies whether the handler is sending to a queue (a single receiver) or a topic (publish/subscribe). The gg.handler.name.queueOrTopic property is an alias of this property. Set to queue removes a message from the queue once it has been read. Set to topic publishes messages and can be delivered to multiple subscribers.
gg.handler.name.connectionFactory	Required	Valid connection factory name	None	Specifies the name of the connection factory to lookup using JNDI. The gg.handler.name.ConnectionFactoryJNDIName property is an alias of this property. .
gg.handler.name.useJndi	Optional	true | false	true	Set to false, then JNDI is not used to configure the JMS client. Instead, factories and connections are explicitly constructed.
gg.handler.name.connectionUrl	Optional	Valid connection URL	None	Specify only when you are not using JNDI to explicitly create the connection.
gg.handler.name.connectionFactoryClass	Optional	Valid connectionFactoryClass	None	Set to access a factory only when not using JNDI. The value of this property is the Java class name to instantiate, which constructs a factory object explicitly.
gg.handler.name.physicalDestination	Optional	Name of the queue or topic object obtained through the ConnectionFactory API instead of the JNDI provider	None	The physical destination is important when JMS is configured to use JNDI. The ConnectionFactory is resolved through a JNDI lookup. Setting the physical destination means that the queue or topic is resolved by invoking a method on the ConnectionFactory instead of invoking JNDI.
gg.handler.name.user	Optional	Valid user name	None	The user name to send messages to the JMS server.
gg.handler.name.password	Optional	Valid password	None	The password to send messages to the JMS server.
gg.handler.name.sessionMode	Optional	auto | client | dupsok	auto	Sets the JMS session mode, these values equate to the standard JMS values: Session.AUTO_ACKNOWLEDGE The session automatically acknowledges a client's receipt of a message either when the session has successfully returned from a call to receive or when the message listener the session has called to process the message successfully returns. Session.CLIENT_ACKNOWLEDGE The client acknowledges a consumed message by calling the message's acknowledge method. Session.DUPS_OK_ACKNOWLEDGE This acknowledgment mode instructs the session to lazily acknowledge the delivery of messages.
gg.handler.name.localTX	Optional	true | false	true	Sets whether local transactions are used when sending messages. Local transactions are enabled by default, unless sending and committing single messages one at a time. Set to false to disable local transactions.
gg.handler.name.persistent	Optional	true | false	true	Sets the delivery mode to persistent or not. If you want the messages to be persistent, the JMS provider must be configured to log the message to stable storage as part of the client's send operation.
gg.handler.name.priority	Optional	Valid integer between 0-10	4	The JMS server defines a 10 level priority value, with 0 as the lowest and 9 as the highest.
gg.handler.name.timeToLive	Optional	Time in milliseconds	0	Sets the length of time in milliseconds from its dispatch time that a produced message is retained by the message system. Set to zero specifies that the time is unlimited.
gg.handler.name.custom	Optional	Class names implementing oracle.goldengate.messaging.handler.GGMessageLifeCycleListener	None	Configures a message listener allowing properties to be set on the message before it is delivered.
gg.handler.name.format	Optional	xml | tx2ml | xml2 | minxml | csv | fixed | text | logdump | json | json_op | json_row | delimitedtext | Velocity template	delimitedtext	Specifies the format used to transform operations and transactions into messages sent to the JMS server. The velocity template should point to the location of the template file. Samples are available under: AdapterExamples/java-delivery/sample-dirprm/. Example: format_op2xml.vm <$op.TableName sqlType='$op.sqlType' opType='$op.opType' txInd='$op.txState' ts='$op.Timestamp' numCols='$op.NumColumns' pos='$op.Position'> #foreach( $col in $op ) #if( ! $col.isMissing()) <$col.Name colIndex='$col.Index'> #if( $col.hasBefore()) #if( $col.isBeforeNull()) <before><isNull/></before> #else <before><![CDATA[$col.before]]></before> #{end}## if col has 'before' value #{end}## if col 'before' is null #if( $col.hasValue()) #if( $col.isNull()) <after><isNull/></after> #{else} <after><![CDATA[$col.value]]></after> #{end}## if col is null #{end}## if col has value </$col.Name> #{end}## if column is not missing #{end}## for loop over columns </$op.TableName>
gg.handler.name.includeTables	Optional	List of valid table names	None	Specifies a list of tables the 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. 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. If any table matches the include list of tables, the transaction is included. The list of table names specified are case sensitive.
gg.handler.name.excludeTables	Optional	List of valid table names	None	Specifies a list of tables the handler will exclude. 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 exclude list of tables, the transaction is excluded. The list of table names specified are case sensitive.
gg.handler.name.mode	Optional	op | tx	op	Specifies whether to output one operation per message (op) or one transaction per message (tx).

18.2.4 Sample Configuration Using Oracle WebLogic Server

java.naming.provider.url=t3://localhost:7001
java.naming.factory.initial=weblogic.jndi.WLInitialContextFactory
java.naming.security.principal=weblogic
java.naming.security.credentials=Welcome
gg.handler.myjms1.type=jms
gg.handler.myjms1.destination=myq
gg.handler.myjms1.connectionFactory=mycf
gg.handler.myjms1.format=xml