Oracle by Example brandingODI 12c - Creating a Java EE Agent

section 0Before You Begin

This tutorial shows you how to use Oracle Data Integrator Studio (ODI Studio) graphical tools to create an Oracle Data Integrator (ODI) Java EE Agent. This tutorial takes approximately 25 minutes to complete.

Background

A common task that is performed using ODI is to deploy and configure an ODI Java EE Agent. With ODI 12c, the Runtime Agent can be deployed as a Java EE component within an application server. It benefits in this configuration from the application server layer features such as clustering and connection pooling for large configurations. This Java EE Agent exposes an MBeans interface enabling lifecycle operations (start/stop) from the application server console and metrics that can be used by the application server console to monitor the agent activity.

What Do You Need?

  • The following is a list of software required:
  • A supported operating system
  • Oracle Database 12c (If not done before, start the services and components for Oracle Database 12c)
  • Oracle Data Integrator 12cR1 installed as ODI Enterprise
  • Oracle WebLogic Server (WLS) 12cR1 (other versions are supported as well). This OBE requires that WebLogic Server (WLS) is installed. If you do not have WLS installed, see alternate OBE here
  • Optional Software - Oracle SQL Developer 12c (included with Database 12c install)

Prerequisites

Before starting this tutorial, you should have:

  • Started Oracle Database services and components such as the Listener.
  • A Database user with DBA role privileges such as the SYS or SYSTEM account.
  • Already installed and configured ODI Master and Work repositories
  • Already created an ODI project and mapping for a flat file to a relational table

Before attempting this OBE, you should have successfully completed the following OBEs:

ODI12c: Creating and Connecting to ODI Master and Work Repositories

ODI12c: Creating an ODI Project: Developing an ODI XML to Database Transformation Using Interface with ODI Constraint. Note: Alternatively you may have your own ODI interface created and used for testing ODI JEE agent . In this case, you don't have to complete this OBE.
To access these OBEs, click here

section 1Create a New Domain with WebLogic Server

This OBE uses JEE Agents that run in a "full" WebLogic domain. The GUI Configuration Wizard uses templates to determine which components are needed to support the function of the agent. There are three possible kinds of agents:

  • Completely standalone agent (no WLS installed)
  • Standalone collocated agent (WLS is installed and the agent is started as its own binary. This OBE uses this kind of agent.)
  • JEE agent (WLS installed and used. The domain, admin server, managed servers, node managers, and so on are started in the normal WLS way. The agent is one of many possible JEE apps running in the domain.)

To create the domain for the agent, perform the following steps:

Basic Configuration

  1. Navigate to the ORACLE_HOME/oracle_common/common/bin directory:
  • (UNIX) ORACLE_HOME/oracle_common/common/bin
  • (Windows) ORACLE_HOME\oracle_common\common\bin

where ORACLE_HOME is your ODI 12c home directory.

  1. Execute the following command to start the Configuration Wizard:
  • (UNIX) ./config.sh
  • (Windows) config.cmd
  1. On the Configuration Type screen, select Create a New Domain. In the Domain Location field, specify your Domain home directory, and click Next.

Note: It is recommended that you locate your Domain home in accordance with the directory structure summarized in Understanding the Recommended Directory Structure in Oracle Fusion Middleware Planning an Installation of Oracle Fusion Middleware, where the Domain home is located outside the Oracle home directory. This directory structure will help you avoid issues when you need to upgrade or reinstall your software. More information about the other options on this screen can be found in Configuration Type.

  1. On the Templates screen, select Create Domain Using Product Templates, then select the following templates:
  • Oracle Enterprise Manager Plugin for ODI - 12.2.1.3.0 [em]

Selecting this template automatically selects the following as dependencies:

    • Oracle Enterprise Manager - 12.2.1.3.0 [em]
    • Oracle JRF - 12.2.1.3.0 [oracle_common]
    • WebLogic Coherence Cluster Extension - 12.2.1.3.0 [wlserver]
  • Oracle Data Integrator - Agent - 12.2.1.3.0 [odi]

Selecting this template automatically selects the following as dependencies:

    • Oracle Data Integrator - Agent Libraries - 12.2.1.3.0 [odi]
    • Oracle Data Integrator SDK Shared Library Template - 12.2.1.3.0 [odi]
  • Oracle Data Integrator - Console - 12.2.1.3.0 [odi]

Note: More information about the options on this screen can be found in Templates in Creating WebLogic Domains Using the Configuration Wizard.

  1. On the Application Location screen, select the location where you want to store your applications associated with your domain. This location is also referred to as the Application home directory.

Note: It is recommended that you locate your Application home in accordance with the directory structure summarized in Understanding the Recommended Directory Structure, where the Application home is located outside the Oracle home directory. This directory structure will help you avoid issues when you need to upgrade or re-install your software.

  1. On the Administrator Account screen, specify the user name and password for the default WebLogic Administrator account for the domain, and click Next.

Note: It is recommended that you make a note of the user name and password specified on this screen; you will need these credentials later to boot and connect to the domain's Administration Server.

  1. On the Domain Mode and JDK panel, select Production in the Domain Mode field and Oracle HotSpot JDK in the JDK field, and click Next.
  2. On the Database Configuration Type panel, change the Service to the database service (not database instance), such as orcl.exampledomain.com. Change the Host Name to localhost and change the Schema Password to the password for DEV_STB that you picked when you ran RCU.
  3. Click Get RCU Configuration to continue, staying on this panel. The Connection Result Log should end with Successfully Done. Click Next to continue.
  4. On the JDBC Component Schema panel, leave the defaults. Click Next to continue.
  5. On the JDBC Component Schema Test panel, leave the defaults. The Connection Result Log should end with Test Successful! Click Next to continue.

A green check mark in the Status column indicates a successful test. If you encounter any issues, see the error message in the Connection Result Log section of the screen, fix the problem, then try to test the connection again.

  1. To specify Supervisor Credentials, go to the Credentials screen to create the following two keys:
  • A key for the Supervisor user already exists. Modify the credential as follows:
    • Specify SUPERVISOR (all CAPS) as the user name. This is the default name initially assigned to the Supervisor account and cannot be changed unless you create a new Supervisor account.
    • The password must be the same password specified on the Custom Variables screen in RCU during schema creation.
  • Create a second credential as follows:
    • Click the Plus sign (+) icon to add a new credential.
    • In the Key Name field, enter the name of this domain as the key.
    • In the Username and Password fields, provide the Administrator user's user name and password.
    • Select oracle.odi.credmap as the store name.

In summary, you have completed the first half, the basic part of the configuration. You must continue with the second half, the advanced configuration.

Advanced Configuration

  1. On the Advanced Configuration panel, select Administration Server, Node Manager, Managed Server, Clusters, and Coherence. Click Next.
  2. On the Administration Server screen, select the drop-down list next to Listen Address and select the IP address of the host where the Administration Server will reside, or use the system name or DNS name that maps to a single IP address.

Note: Do not use "All Local Addresses." Do not specify any server groups for the Administration Server.

  1. On the Node Manager screen, select Per Domain Default Location as the Node Manager type, and then specify Node Manager credentials.
  2. On the Managed Servers screen, a new Managed Server named ODI_server1 is created:
  • In the Listen Address drop-down list, select the IP address of the host on which the Managed Server will reside. Do not use "All Local Addresses."
  • In the Server Groups drop-down list, select JRF-MAN-SVR. This server group ensures that the Oracle JRF services are targeted to the Managed Servers you are creating.
  • Listen port is set to 15101.

Note: Take note of the IP address and port number for the Managed Server. You will need this information when you configure the ODI agent.

  1. Click Next.
  2. In the Clusters screen:
  • Click the Add button.
  • Specify ODI_cluster1 in the Cluster Name field.
  • Leave the cluster Address field blank.
  1. Use the Assign Servers to Clusters screen to assign ODI_server1 to the new cluster ODI_cluster1:
  • In the Clusters pane, select the cluster to which you want to assign the servers; in this case, ODI_cluster1.
  • In the Servers pane, assign ODI_server1 to ODI_cluster1 by doing one of the following:
    • Click once on ODI_server1 to select it, then click on the right arrow to move it beneath the selected cluster (ODI_cluster1) in the Clusters pane.
    • Double-click on ODI_server1 to move it beneath the selected cluster (ODI_cluster1) in the clusters pane.
  1. Use the Coherence Clusters screen to configure the Coherence cluster that is automatically added to the domain. Leave the default port number 0 as the Coherence cluster listen port.

Note: Setting the unicast listen port to 0 creates an offset for the Managed Server port numbers. The offset is 5000, meaning the maximum allowed value that can be assigned to a Managed Server port number is 60535, instead of 65535.

  1. Use the Machines screen to create a new machine in the domain. A machine is required for the Node Manager to be able to start and stop the servers.
  • Click the Add button to create a new machine.
  • Specify ODI_machine1 in the Name field.
  • In the Node Manager Listen Address field, select the IP address of the machine where the Managed Servers are being configured.

Note: You must select a specific interface and not "localhost." This allows Coherence cluster addresses to be dynamically calculated.

  • Verify the port in the Node Manager Listen Port field (for example, 5556. Replace this port number with your own port number as needed).

Note: If you are extending an existing domain, you can assign servers to any existing machine. It is not necessary to create a new machine unless your situation requires it.

  1. Use the Assign Servers to Machines screen to assign the Administration Server and Managed Server to the new machine you just created:
  • In the Machines pane, select the machine to which you want to assign the servers; in this case, ODI_machine1.
  • In the Servers pane, assign AdminServer to ODI_machine1 by doing one of the following:
    • Click once on AdminServer to select it, then click on the right arrow to move it beneath the selected machine (ODI_machine1) in the Machines pane.
    • Double-click on AdminServer to move it beneath the selected machine (ODI_machine1) in the Machines pane.
  • Repeat to assign ODI_server1 to ODI_machine1.
  1. The Configuration Summary screen contains the detailed configuration information for the domain you are about to create. Review the details of each item on the screen and verify that the information is correct.
  • You can go back to any previous screen if you need to make any changes, either by using the Back button or by selecting the screen in the navigation pane.
  • Domain creation will not begin until you click Create.
  1. The Configuration Success screen will show the Domain home location and URL of the Administration Server you just configured:

Make a note of both items as you will need them to start the servers in your domain.

  1. Click Finish to dismiss the configuration wizard.

In summary, you completed both halves of the domain configuration. This creates several directories with configuration files and scripts.

section 2Create a Physical Agent

  1. Start ODI Studio by running odi.sh. The splash screen and progress bar displays briefly.
  2. On the Designer or Topology tab, click Connect To Repository...
  3. On the Enter Wallet Password dialog box, enter the password you chose when you installed ODI. Click OK to continue.
  4. On the Oracle Data Integrator Login dialog box, enter the Supervisor's password you chose when you installed ODI. It may be pre-populated for you. Click OK to continue.
  5. On the Topology tab, expand Physical Architecture, then expand Agents. Right-click Agents and select New Agent. An unnamed Agent panel opens on the right.
  6. On the Agent panel, on the Definition tab, in Name, enter the name that matches the agent you created with the earlier domain wizard: OracleDIAgent1.
  7. In Port, enter the port that matches the agent you created with the earlier domain wizard. Verify that Host is correct.
  8. Save your work but do not close the panel. Leave the panel open. You should now see the new agent display on the left under Topology > Physical Architecture > Agents.

In summary, you created the physical agent configuration for within ODI. This points to the executables created in the previous steps.

section 3Start the Java EE Agent

To start the Java EE Agent, you must first start the Node Manager, then the WebLogic Administration Server, and the WebLogic Managed Servers for Java EE agent as expained below:

Start the Node Manager

  1. To start your per-domain Node Manager, go to the DOMAIN_HOME/bin directory.
  2. On UNIX operating systems, run this command, using nohup and nm.out as an example output file:

nohup ./startNodeManager.sh > LOG_DIR/nm.out

where LOG_DIR is the location of the directory in which you want to store the log files.

  1. On Windows operating systems, run:

startNodeManager.cmd

Note: On Windows operating systems, it's recommended to run Node Manager to run as a startup service. This allows Node Manager to start up automatically each time the system is restarted. For more information, see "Running Node Manager as a Startup Service" in Administering Node Manager for Oracle WebLogic Server.

Start the Administration Server

  1. To start the Administration Server, go the DOMAIN_HOME/bindirectory.
  2. On UNIX operating systems, run:

./startWebLogic.sh

  1. On Windows operating systems, run:

startWebLogic.cmd

  1. At the prompt, enter the Administrator password for the domain.

Note: In production mode, a boot identity file can be created to bypass the need to provide a user name and password when starting the Administration Server. For more information, see "Creating a Boot Identity File for an Administration Server" in Administering Server Startup and Shutdown for Oracle WebLogic Server.

  1. You can verify that the Administration Server is up and running by accessing the Administration Server Console. The URL is provided on the Configuration Success screen. Make sure that the database hosting your product schemas is up and running and accessible by the Administration Server.

http://administration_server_host:administration_server_port/console

The default Administration Server port number is 7001.

Start the Managed Server

  1. Log in to Oracle Fusion Middleware Control:

http://administration_server_host:administration_server_port/em

The Administration Server host and port number can be copied from the URL on the Configuration Success screen. The default Administration Server port number is 7001. The login credentials can be copied from the Administrator Account screen.

  1. From the Target Navigation pane, click the arrows to expand the domain until the Managed Servers (ODI_server1) is visible.
  2. Select the Managed Server (ODI_server1).
  3. Next to the WebLogic Server menu, select Start Up.
  4. In the Target Navigation page, select your domain name to see that all the servers are up and running.

Start the Agent

  1. Go to the DOMAIN_HOME/bin directory.
  2. Start the agent:
    • (UNIX) ./startComponent.sh OracleDIAgent1
    • (Windows) startComponent.cmd OracleDIAgent1

section 4Create a Logical Agent

Most components in ODI have a physical and logical side to them. You already created the physical agent with ports and names. The logical agent is much simpler and shorter.

To create a logical agent that corresponds with the previous physical agent, perform the following steps:

  1. On the Topology tab, expand Logical Architecture, then expand Agents.
  1. Right-click Agents and select New Logical Agent. An unnamed Logical Agent panel displays on the right.
  2. On the Logical Agent panel, on the Definition tab, in Name, enter MyAgent. In the Physical Agents pull-down, select OracleDIAgent1.
  3. Save your work. You should now see the new agent display on the left under Topology > Logical Architecture > Agents.
  4. You can close all the open tabs on the right.

In summary, you created a logical agent to match the previous physical agent.

more informationWant to Learn More?

  • In this tutorial, you should have learned how to:
  • Use the Configuration Wizard to create a domain from a template for a Java EE agent.
  • Use ODI Studio to create a physical agent.
  • Start the physical agent background process from the OS prompt.
  • Start the Node Manager, Administrative server, and the Managed server.

Resources

The following are conceptual or procedural Help topics relevant to the topic of this tutorial:

  • Online documentation, viewlets, samples, and OLN URLs on OTN:
    • Older versions: here
    • Current version: here
  • External Web sites for related information:
  • To learn more about Oracle Data Integrator 12c, refer to additional OBEs in the Oracle Learning Library, or on the ODI Studio Start Page.