Oracle® GoldenGate Application Adapters

Installing Oracle GoldenGate Adapters

Release 12c (12.1.2.1.1)

E61859-01

May 2015

This document provides information on how to install a new instance of the Oracle GoldenGate Adapters.

The document contains the following sections:

- Section 1, "Preparing for Installation"

- Section 2, "Installing Oracle GoldenGate Adapters"

- Section 3, "Documentation Accessibility"

1 Preparing for Installation

Prepare your Java environment by ensuring that you have the correct version of Java installed, and that the environmental variables have been set up and configured correctly.

1.1 Installing Java

The Oracle GoldenGate Adapters are certified for Java 1.7. Before installing and running Oracle GoldenGate for Java, you must install Java (JDK or JRE) version 1.7 or later. Either the Java Runtime Environment (JRE) or the full Java Development Kit (which includes the JRE) may be used.

1.2 Setting up Environmental Variables

To configure your Java environment for Oracle GoldenGate for Java:

- The PATH environmental variable should be configured to find your Java Runtime

- The shared (dynamically linked) Java virtual machine (JVM) library must also be found.

On Windows, these environmental variables should be set as system variables; on Linux/UNIX, they should be set globally or for the user running the Oracle GoldenGate processes. Examples of setting these environmental variables for Windows and UNIX/Linux are listed below.

Note:
There may be two versions of the JVM installed when installing Java; one in JAVA_HOME/.../client, and another in JAVA_HOME/.../server. For improved performance, use the server version, if it is available. On Windows, only the client JVM may be there if only the JRE was installed (and not the JDK).

1.2.1 Java on Windows

After Java is installed, configure the PATH to find the JRE and JVM DLL (jvm.dll):

Example 1 Configuring Path for Java on Windows

set JAVA_HOME=C:\Program Files\Java\jdk1.7.0
set PATH=%JAVA_HOME%\bin;%PATH%
set PATH=%JAVA_HOME%\jre\bin\server;%PATH%

In the example above, the directory %JAVA_HOME%\jre\bin\server should contain the file jvm.dll.

Verify the environment settings by opening a command prompt and checking the java version:

C:\> java -version
java version "1.7.0_30" Java(TM) SE Runtime Environment (build 1.7.0_30-b13)

1.2.2 Java on Linux/UNIX

Configure the environment to find the JRE in the PATH, and the JVM shared library, using the appropriate environmental variable for your system. For example, on Linux (and Solaris, etc.), set LD_LIBRARY_PATH to include the directory containing the JVM shared library as follows (for sh/ksh/bash):

Example 2 Configuring path for Java on Linux

export JAVA_HOME=/opt/jdk1.7
export PATH=$JAVA_HOME/bin:$PATH
export LD_LIBRARY_PATH=$JAVA_HOME/jre/lib/i386/server:$LD_LIBRARY_PATH

In the example above, the directory $JAVA_HOME/jre/lib/i386/server should contain the file libjvm.so. The actual directory containing the JVM library depends on the OS and if the 32-bit or 64-bit JVM is being used.

Verify the environment settings by opening a command prompt and checking the java version:

$ java -version
java version "1.7.0_30"
Java(TM) SE Runtime Environment (build 1.7.0_30-b02)

2 Installing Oracle GoldenGate Adapters

To install the Oracle GoldenGate Adapters, download a zip file of the build for your operating system and platform; then follow the installation steps.

2.1 Installation Overview

This section provides an overview of the installation contents and the Oracle GoldenGate instances used with the Oracle GoldenGate Adapter

2.1.1 Contents of the Installation Zip File

The Oracle GoldenGate Adapters installation zip file contains:

- Oracle GoldenGate Java Adapter

- Oracle GoldenGate Flat File Adapter.

- A version of Oracle GoldenGate designed to run the adapters. This version is sometimes labeled generic because it is not specific to any database, but it is platform dependent.

2.1.2 Using the Generic Build of Oracle GoldenGate

For JMS capture, the Java Adapter must run in the generic build of Oracle GoldenGate. However, the generic build is not required when using the adapter for delivery of trail data to a target; in this case the Oracle GoldenGate Flat File or Java Adapters can be used with any database version of Oracle GoldenGate.

2.1.3 Considerations for Using a Non-generic Instance of Oracle GoldenGate

There are both advantages and disadvantages to installing the adapters to a non-generic Oracle GoldenGate instance. Also, there are limitations in the releases of Oracle GoldenGate core that are compatible with releases of the adapters.

Advantages

- The non-generic instance allows you to configure Extract to login to the database for metadata. This removes the need to use a source definitions file that must be synchronized your the source database DDL.

- There is no need to manage two separate versions of Oracle GoldenGate when doing database capture and JMS delivery on the same server.

Disadvantages

- If you need to patch Oracle GoldenGate core instance, you must also copy the adapters into the new patched installation of Oracle GoldenGate.

- The Oracle GoldenGate Adapters are only tested and certified with the generic version of Oracle GoldenGate core. New patches of the core can trigger incompatibilities.

Limitations

- The Oracle GoldenGate Adapters can only be installed with an Oracle GoldenGate instance that is the same major release. Therefore, 11.1.x releases of the adapters can only be installed to 11.1.x releases of Oracle GoldenGate; 11.2.x with 11.2.x, and 12.1.2.x with 12.1.2.x.

- The generic build must be used with JMS capture, as this is the only version of Extract that is capable of loading the VAM.

- A DEFGEN utility is not included with the adapters. To generate source definitions, you will need a version of Oracle GoldenGate that is built specifically for your database type.

2.1.4 Installing to a Non-Generic Instance of Oracle GoldenGate

If you decide to install the Java user exit to a non-generic instance of Oracle GoldenGate, unzip to a temporary location first and then copy the adapter files to your Oracle GoldenGate installation location

To do this, follow these steps:

1. Extract the Oracle GoldenGate installation zip file to a temporary directory.

2. Extract the Oracle GoldenGate installation zip file into your Oracle GoldenGate installation directory.

3. Copy or move the files from the temporary directory ggjava subdirectory into the Oracle GoldenGate installation directory.

4. Copy or move the shared libraries from the temporary location into the Oracle GoldenGate installation directory.

5. Optionally you can also copy Gendef and flatfilewriter.so or flatfilewriter.dll. (There is no need to copy the shared library ggjava_vam since it works only with the generic build.)

6. Delete the temporary directory.

2.2 Downloading Oracle GoldenGate Adapters

Oracle GoldenGate Adapters are available for Windows, Linux, and UNIX (32 and 64 bit). To download, first visit the Oracle support site to see if there is a patch available for your operating system and architecture.

Note:
If you are not planning to use the generic build included in the installation, ensure that the major release of the Oracle GoldenGate Adapters build you download matches (or is known to be compatible with) the major release of the Oracle GoldenGate instance that will be used with it.

1. Navigate to http://support.oracle.com.

2. Sign in with your Oracle ID and password.

3. Select the Patches and Upgrades tab.

4. On the Search tab, click Product or Family.

5. In the Product Field, type Oracle GoldenGate Application Adapters.

6. From the Release drop-down list, select the release version that you want to download.

7. Make sure Platform is displayed as the default in the next field, and then select the platform from the drop-down list.

8. Leave the last field blank.

9. Click Search.

10. In the Advanced Patch Search Results list, select the available builds that satisfy the criteria that you supplied.

11. In the file Download dialog box, click the zip file to begin the download.

If patches are not available on the support site, go to the Oracle delivery site for the release download.

1. Navigate to http://edelivery.oracle.com.

2. Sign in with your Oracle ID and password.

3. On the Terms and Restrictions page:

- Accept the Trial License Agreement (even if you have a permanent license).

- Accept the Export Restrictions.

- Click Continue.

4. On the Media Pack Search page:

- Select the Oracle Fusion Middleware Product Pack.

- Select the platform on which you will be installing the software.

- Click Go.

5. In the Results list:

- Select the Oracle GoldenGate Applications Adapters Media Pack that you want.

- Click Continue.

6. On the Download page:

- View the Readme file.

- Click Download for each component that you want. Follow the automatic download process to transfer the zip file to your system.

Note:
Release Notes may or may not be included with the download. If they are not, you can find them in the documentation library on Oracle Technical Network (OTN). There should be a link to the Release Notes in the Readme.

2.3 Directory Structure

The following table is a sample that includes the subdirectories and files that result from unzipping the installation file and creating the subdirectories. The following conventions have been used:

- Subdirectories are enclosed in square brackets []

- Levels are indicated by a pipe and hyphen |-

- The Internal notation indicates a read-only directory that should not be modified

- Text files (*.txt) are not included in the list

- Oracle GoldenGate utilities, such as Defgen, Logdump, and Keygen, are not included in the list

Table 1 Sample installation directory structure

Directory

Explanation

[gg_install_dir]

Oracle GoldenGate installation directory, such as C:/ggs on Windows or /home/user/ggs on UNIX.

|-ggsci

Command line interface used to start, stop, and manage processes.

|-mgr

Manager process.

|-extract

Extract process that will start the Java application or flat file writer.

|-[AdapterExamples]

Sample configuration files for Java user exit, Java API, flat file writer, and JMS capture adapters.

|-[UserExitExamples]

Sample C programming language user exit code examples.

|-[dirprm]

Subdirectory that holds all the parameter and property files created by the user, for example:

javaue.prm
javaue.properties
jmsvam.prm
jmsvam.properties
ffwriter.prm

|-[dirdef]

Subdirectory that holds source definitions files (*.def) defining the metadata of the trail:

- Created by the Defgen core utility for the user exit trail data.

- Created by the Gendef adapter utility for VAM message capture.

|-[dirdat]

Subdirectory that holds the trail files produced by the VAM Extract or read by the user exit Extract.

|-[dirrpt]

Subdirectory that holds log and report files.

|-[dirchk]

Internal: Subdirectory that holds checkpoint files.

|-[dirpcs]

Internal: Subdirectory that holds process status files.

|-[dirjar]

Internal: Subdirectory that holds Oracle GoldenGate Monitor jar files.

|-[ggjava]

Internal: Installation directory for Java jars. Read-only; do not modify.

|-|-ggjava.jar

The main Java application jar that defines the class path and dependencies.

|-|-[resources]

Subdirectory that contains all ggjava.jar dependencies. Includes subdirectories for:

- [class] - properties and resources

- [lib] - application jars required by ggjava.jar

|-ggjava_ue.dll

The user exit shared library. This is libggjava_ue.so on UNIX.

|-ggjava_vam.dll

The VAM shared library. This is libggjava_vam.so on UNIX.

|-gendef

Utility to generate the adapter source definitions files containing metadata of the JMS message input. Note that this is different from the Oracle GoldenGate Defgen utility that creates source definitions containing the input metadata for the trail.

|-flatfilewriter.dll

The Windows dll or the UNIX so library for the Oracle GoldenGate Flat File Adapter.

|-. . .

Other subdirectories and files included in the installation or created later.

2.4 Installation Steps

Perform the following steps to install the Oracle GoldenGate Adapters:

1. Create an installation directory that has no spaces in its name. Then extract the zip file into this new installation directory. For example:

Shell> mkdir installation_directory
Shell> cp path/to/installation_zip installation_directory
Shell> cd installation_directory
Shell> unzip installation_zip

If you are on Linux or UNIX also:

Shell> tar -xf installation_tar

This will download the files into several of the subdirectories Section 2.3, "Directory Structure."

2. Stay on the installation directory and bring up GGSCI to create the remaining subdirectories in the installation location.

3. Shell> ggsci
GGSCI> CREATE SUBDIRS

4. Create a Manager parameter file:

GGSCI> EDIT PARAM MGR

5. Specify a port for the Manager to listen on by using the editor to add a line to the Manager parameter file. For example:

PORT 7801

6. If you are on Windows and running Manager as a service, set the system variable PATH to include jvm.dll, then delete the Manager service and re-add it.

7. Go to GGSCI, start the Manager, and check to see that it is running:

GGSCI>START MGR
GGSCI>INFO MGR

Note:
To check for environmental variable problems locating the JVM at runtime:

- Add the parameter GETENV(PATH) for Windows or GETENV(LD_LIBRARY_PATH) for UNIX to the Extract parameter file.

- Start the Extract process

- Check the output for the report using the GGSCI command: SEND EXTRACT group_name REPORT

3 Documentation Accessibility

For information about Oracle's commitment to accessibility, visit the Oracle Accessibility Program website at http://www.oracle.com/pls/topic/lookup?ctx=acc&id=docacc.

Access to Oracle Support

Oracle customers that have purchased support have access to electronic support through My Oracle Support. For information, visit http://www.oracle.com/pls/topic/lookup?ctx=acc&id=info or visit http://www.oracle.com/pls/topic/lookup?ctx=acc&id=trs if you are hearing impaired.

Installing Oracle GoldenGate Adapters, Release 12c (12.1.2.1.1)

E61859-01

Copyright © 2015, Oracle and/or its affiliates. All rights reserved.

This software and related documentation are provided under a license agreement containing restrictions on use and disclosure and are protected by intellectual property laws. Except as expressly permitted in your license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license, transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means. Reverse engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is prohibited.

The information contained herein is subject to change without notice and is not warranted to be error-free. If you find any errors, please report them to us in writing.

If this is software or related documentation that is delivered to the U.S. Government or anyone licensing it on behalf of the U.S. Government, the following notice is applicable:

U.S. GOVERNMENT END USERS: Oracle programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, delivered to U.S. Government end users are "commercial computer software" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, use, duplication, disclosure, modification, and adaptation of the programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, shall be subject to license terms and license restrictions applicable to the programs. No other rights are granted to the U.S. Government.

This software or hardware is developed for general use in a variety of information management applications. It is not developed or intended for use in any inherently dangerous applications, including applications that may create a risk of personal injury. If you use this software or hardware in dangerous applications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure its safe use. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of this software or hardware in dangerous applications.

Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners.

Intel and Intel Xeon are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks are used under license and are trademarks or registered trademarks of SPARC International, Inc. AMD, Opteron, the AMD logo, and the AMD Opteron logo are trademarks or registered trademarks of Advanced Micro Devices. UNIX is a registered trademark of The Open Group.

This software or hardware and documentation may provide access to or information about content, products, and services from third parties. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to third-party content, products, and services unless otherwise set forth in an applicable agreement between you and Oracle. Oracle Corporation and its affiliates will not be responsible for any loss, costs, or damages incurred due to your access to or use of third-party content, products, or services, except as set forth in an applicable agreement between you and Oracle.

Oracle Legal Notices

Copyright Notice

Copyright © 1994-2015, Oracle and/or its affiliates. All rights reserved.

Trademark Notice

Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners.

Intel and Intel Xeon are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks are used under license and are trademarks or registered trademarks of SPARC International, Inc. AMD, Opteron, the AMD logo, and the AMD Opteron logo are trademarks or registered trademarks of Advanced Micro Devices. UNIX is a registered trademark of The Open Group.

License Restrictions Warranty/Consequential Damages Disclaimer

This software and related documentation are provided under a license agreement containing restrictions on use and disclosure and are protected by intellectual property laws. Except as expressly permitted in your license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license, transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means. Reverse engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is prohibited.

Warranty Disclaimer

The information contained herein is subject to change without notice and is not warranted to be error-free. If you find any errors, please report them to us in writing.

Restricted Rights Notice

If this is software or related documentation that is delivered to the U.S. Government or anyone licensing it on behalf of the U.S. Government, the following notice is applicable:

U.S. GOVERNMENT END USERS: Oracle programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, delivered to U.S. Government end users are "commercial computer software" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, use, duplication, disclosure, modification, and adaptation of the programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, shall be subject to license terms and license restrictions applicable to the programs. No other rights are granted to the U.S. Government.

Hazardous Applications Notice

This software or hardware is developed for general use in a variety of information management applications. It is not developed or intended for use in any inherently dangerous applications, including applications that may create a risk of personal injury. If you use this software or hardware in dangerous applications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure its safe use. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of this software or hardware in dangerous applications.

Third-Party Content, Products, and Services Disclaimer

This software or hardware and documentation may provide access to or information on content, products, and services from third parties. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to third-party content, products, and services. Oracle Corporation and its affiliates will not be responsible for any loss, costs, or damages incurred due to your access to or use of third-party content, products, or services.

Alpha and Beta Draft Documentation Notice

If this document is in preproduction status:

This documentation is in preproduction status and is intended for demonstration and preliminary use only. It may not be specific to the hardware on which you are using the software. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to this documentation and will not be responsible for any loss, costs, or damages incurred due to the use of this documentation.