5 Configuring the Domain for a Java EE Agent

Create and configure a WebLogic domain for a Java EE agent in the standard installation topology.

5.1 Creating the Database Schema

Ensure that you have created the required schema in your database for your Java EE agent.

Before you can configure the topology for your Java EE agent, make sure you have created the necessary schema in your database. See Creating the Master and Work Repository Schemas for instructions.

5.2 Generating a Template for a Java EE Agent

Use the Server Template Generation wizard to generate the non-default template for deploying a Java EE agent defined in the ODI master repository.

Use this procedure if you require changes to the default template that deploys a Java EE agent with default name and settings. To create a Java EE agent with the Server Template Generation wizard:
  1. From the Physical Agent Editor menu, select Generate Server Template to start the Template Generation wizard.
  2. In the Agent Information step, review the agent information and modify the default configuration as appropriate. This information includes the following parameters: the Agent Name, the Datasource JNDI Name, the Connection Retry Count, the Retry Delay, and the Supervisor Key.
    • The Connection Retry Count specifies the number of retry attempts if the agent loses the connection to the repository. Note that setting this parameter to a non-zero value enables a high availability connection retry feature if the ODI repository resides on an Oracle RAC database. If this feature is enabled, the agent can continue to execute sessions without interruptions even if one or more Oracle RAC nodes become unavailable.

    • The Retry Delay specifies the number of milliseconds between connection retry attempts.

    • The Supervisor Key specifies the name of the key in the application server credential store that contains the login and the password of an ODI user with Supervisor privileges. The agent uses these credentials to connect to the repository.

  3. Click Next.
  4. To add domain and shared libraries for the agent, navigate to the Libraries and Drivers page, and then check the libraries you want to deploy with your agent. Libraries can be any JAR or ZIP files required by the agent. Select any additional JDBC drivers or libraries for accessing the source and target data servers in this page. Note that library name validation is limited within the newly added libraries, not against already deployed shared libraries.
    • Domain libraries are the libraries deployed in a domain that are available to all applications running in the domain. This approach to adding libraries is typically used when adding infrequently changed JAR files. Note that when using this approach, you must reboot all servers in the domain for the change to take effect.

    • Shared libraries are libraries you specify in the agent deployment descriptor before deploying the agent to the domain. In this way, multiple applications can use the libraries resources and duplication is avoided. This approach to adding libraries is used for libraries that may need modifications or upgrade. Shared libraries allow you to change libraries without restarting the server, but you may need to restart the application.

  5. Click Next.
  6. In Template Target and Summary step, enter the Target Template Path that specifies the location where the server template is generated.
  7. Click Finish to close the wizard and generate the server template with your specifications.
The generated template can be used to deploy the agent in an Oracle WebLogic Server domain.

5.3 Creating a Java EE Agent with Oracle Data Integrator Studio

Create a Java EE agent in the Master Repository using Oracle Data Integrator Studio (ODI Studio).

A physical agent corresponds to a single standalone agent or a Java EE agent. A physical agent should have a unique name in the topology. The default agent name configured with the installer is OracleDIAgent and the port to be configured for this agent is the managed server port.

As part of its startup sequence, an agent connects to the master repository to see if there is a physical agent defined with its name. If it finds its entry, the agent continues with startup and, once started, it reads all the scheduled jobs of itself from the repository and starts processing.

If there is no physical agent entry for an agent, then the agent startup fails.

To create an agent using ODI Studio, see Creating an Agent in the Master Repository with ODI Studio.

5.4 Configuring the Domain for a Java EE Agent

Create and configure a WebLogic domain for a Java EE agent in the standard installation topology.

5.4.1 Starting the Configuration Wizard

This task explains how to start the WebLogic Server Configuration Wizard.

To begin domain configuration, navigate to the ORACLE_HOME/oracle_common/common/bin directory and start the WebLogic Server Configuration Wizard.

On UNIX operating systems:

./config.sh

On Microsoft Windows operating systems:

config.cmd

5.4.2 Navigating the Configuration Wizard Screens to Configure the Domain

This task explains how to create and configure a domain.

Follow the instructions in this section to create and configure the domain for the topology.

Note:

You can use the same procedure described in this section to extend an existing domain. If your needs do not match the instructions given in the procedure, be sure to make your selections accordingly, or refer to the supporting documentation for additional details.

To create and configure a domain:

  1. On the Configuration Type screen, select Create a New Domain.

    In the Domain Location field, specify your Domain home directory.

    It is recommended that you locate your Domain home in accordance with the directory structure summarized in Understanding the Recommended Directory Structure, 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.

    Tip:

    More information about the other options on this screen can be found in Configuration Type in Creating WebLogic Domains Using the Configuration Wizard.

  2. On the Templates screen, make sure Create Domain Using Product Templates is selected, then select the following templates:

    • Oracle Enterprise Manager Plugin for ODI

      Selecting this template automatically selects the following as dependencies:

      • Oracle Enterprise Manager

      • Oracle JRF

      • WebLogic Coherence Cluster Extension

    • Oracle Data Integrator - Agent

      Selecting this template automatically selects the following as dependencies:

      • Oracle Data Integrator - Agent Libraries

      • Oracle Data Integrator SDK Shared Library Template

      In addition, select the following templates:
      • Oracle Data Integrator - JFR

      • Oracle Data Integrator - REST Services

    • Oracle Data Integrator - Console

    Note:

    For information about configuring and managing a secondary topology using the Oracle Data Integrator Console see About the Secondary Topologies for Oracle Data Integrator.

    Tip:

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

  3. 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.

    It is recommended that you set your Application home in accordance with the directory structure summarized in Understanding the Recommended Directory Structure, to 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.

    Tip:

    More information about the Application home directory can be found in Choosing an Application Home.

    More information about the options on this screen can be found in Application Location.

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

    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.

  5. On the Domain Mode and JDK screen:

    • Select Production in the Domain Mode field.

    • Select the Oracle HotSpot JDK in the JDK field.

    Tip:

    More information about the options on this screen can be found in Domain Mode and JDK in Creating WebLogic Domains Using the Configuration Wizard.

  6. Select RCU Data to activate the fields on this screen. The RCU Data option instructs the Configuration Wizard to connect to the database and Service Table (STB) schema to automatically retrieve schema information for the schemas needed to configure the domain.

    Note:

    If you choose to select Manual Configuration on this screen, you will have to manually fill in the parameters for your schema on the JDBC Component Schema screen.

    After selecting RCU Data, fill in the following fields:

    Field Description

    DBMS/Service

    Enter the database DBMS name, or service name if you selected a service type driver.

    Host Name

    Enter the name of the server hosting the database.

    Port

    Enter the port number on which the database listens.

    Schema Owner

    Schema Password

    Enter the username and password for connecting to the database's Service Table schema. This is the schema username and password that was specified for the Service Table component on the "Schema Passwords" screen in RCU (see Creating the Database Schema).

    The default username is prefix_STB, where prefix is the custom prefix that you defined in RCU.

    Click Get RCU Configuration when you are finished specifying the database connection information. The following output in the Connection Result Log indicates that the operation succeeded:

    Connecting to the database server...OK
    Retrieving schema data from database server...OK
    Binding local schema components with retrieved data...OK
    
    Successfully Done.
    

    Tip:

    More information about the RCU Data option can be found in Understanding the Service Table Schema.

    More information about the other options on this screen can be found in Datasource Defaults

  7. Verify that the values on the JDBC Component Schema screen are correct for all schemas. If you selected RCU Data on the previous screen, the schema table should already be populated appropriately. For information about each of the schemas, see Understanding Repository Creation Utility Schemas, IDs, and Tablespaces in Creating Schemas with the Repository Creation Utility.

    Tip:

    For high availability environments, see the following sections in High Availability Guide for additional information on configuring data sources for Oracle RAC databases:

    More information about the other options on this screen can be found in JDBC Component Schema in Creating WebLogic Domains Using the Configuration Wizard.

  8. Use the JDBC Component Schema Test screen to test the datasource connections you have just configured.

    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.

    Tip:

    More information about the other options on this screen can be found in Test Component Schema in Creating WebLogic Domains Using the Configuration Wizard.

  9. Use the Credentials screen to create the following two keys:

    1. A key for the Supervisor user already exists. Modify the credential as follows:

      1. 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.

      2. The password must be the same password specified on the Custom Variables screen in RCU during schema creation (see step 6 in procedure in Navigating the Repository Creation Utility Screens to Create the Schema).

    2. Create a second credential as follows:

      1. Click the Plus sign (+) icon to add a new credential.

      2. In the Key Name field, enter the name of this domain as the key.

      3. In the Username and Password fields, provide the Administrator user's user name and password.

      4. Select oracle.odi.credmap as the store name.

    Note:

    If the repository is configured in external authentication mode, then the SUPERVISOR user name and password should be entered according to your external authentication settings.
  10. To complete domain configuration for the topology, select the following options on the Advanced Configuration screen:

    • Administration Server

      This is required to properly configure the listen address of the Administration Server.

    • Node Manager

      This is required to configure Node Manager.

    • Managed Server, Clusters and Coherence

      This is required to configure the Oracle Data Integrator Managed Server.

  11. On the Administration Server screen, select the drop-down list next to Listen Address and select the IP address on the host where the Administration Server will reside. Do not use "All Local Addresses."

    Do not specify any server groups for the Administration Server.

  12. The Node Manager screen can be used to select the type of Node Manager you want to configure, along with the Node Manager credentials.

    Select Per Domain as the Node Manager type, then specify the Node Manager credentials.

    Tip:

    More information about the options on this screen can be found in Node Manager.

    More information about the types of Node Manager can be found in Node Manager Overview.

  13. On the Managed Servers screen, a new Managed Server named ODI_server1 is created:

    1. 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."

    2. 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.

      Server groups target Fusion Middleware applications and services to one or more servers by mapping defined application service groups to each defined server group. A given application service group may be mapped to multiple server groups if needed. Any application services that are mapped to a given server group are automatically targeted to all servers that are assigned to that group. For more information, see Application Service Groups, Server Groups, and Application Service Mappings.

    These server names and will be referenced throughout this document; if you choose different names be sure to replace them as needed.

    Note:

    You must make a note of the IP address and port number for the Managed Server. You will need this information when you configure the ODI agent.

    Tip:

    More information about the options on this screen can be found in Managed Servers in Creating WebLogic Domains Using the Configuration Wizard.

  14. Use the Clusters screen to create a new cluster:

    1. Click the Add button.

    2. Specify ODI_cluster1 in the Cluster Name field.

    3. Leave the cluster Address field blank.

    By default, server instances in a cluster communicate with one another using unicast. If you want to change your cluster communications to use multicast, refer to Considerations for Choosing Unicast or Multicast.

    New clusters can also be created using Fusion Middleware Control. In such cases, cluster communication (unicast or multicast) can be configured when the new cluster is created.

    Tip:

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

  15. Use the Assign Servers to Clusters screen to assign ODI_server1 to the new cluster ODI_cluster1:

    1. In the Clusters pane, select the cluster to which you want to assign the servers; in this case, ODI_cluster1.

    2. 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.

    Tip:

    More information about the options on this screen can be found in Assign Servers to Clusters in Creating WebLogic Domains Using the Configuration Wizard.

  16. 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.

    See Table 8-2 for more information and next steps for configuring Coherence.

    Note:

    For Coherence licensing information, see Oracle Coherence Products in Licensing Information.

  17. Use the Machines screen to create a new machine in the domain. A machine is required in order for the Node Manager to be able to start and stop the servers.

    Tip:

    If you plan to create a high availability environment and know the list of machines required for your target topology, you can follow the directions in this section to create all of the machines at this time. For more information, see Optional Scale Out Procedure in High Availability Guide.

    1. Click the Add button to create a new machine.

    2. Specify ODI_machine1 in the Name field.

    3. In the Node Manager Listen Address field, select the IP address of the machine where the Managed Servers are being configured.

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

    4. Verify the port in the Node Manager Listen Port field.

      The port number 5556, shown in this example, may be referenced by other examples in the documentation. 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.

    Tip:

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

  18. Use the Assign Servers to Machines screen to assign the Administration Server and Managed Server to the new machine you just created:

    1. In the Machines pane, select the machine to which you want to assign the servers; in this case, ODI_machine1.

    2. 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.

    3. Repeat to assign ODI_server1 to ODI_machine1.

    Tip:

    More information about the options on this screen can be found in Assign Servers to Machines in Creating WebLogic Domains Using the Configuration Wizard.

  19. 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.

    Tip:

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

  20. The Configuration Success screen will show the Domain home location and URL of the Administration Server you just configured:

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

Click Finish to dismiss the configuration wizard.

5.5 Adding Libraries to a Java EE Agent

After configuring a Java EE agent, you can specify additional libraries if required.

To add libraries to a Java EE agent:
  1. Set the environment variable ODI_ADDITIONAL_CLASSPATH to locate additional jars before starting the agent. For example:

    ODI_ADDITIONAL_CLASSPATH=/share/libs/mytool.jar:/share/libs/drivers/mydriver.jar

  2. Do one the following:

    • Copy the additional libraries to the DOMAIN_HOME/lib directory. The Java EE will automatically add these libaries to the agent’s classpath.
    • Follow the steps below to use the generate_agent_wls_template.sh script or ODI Studio to generate an agent template and then create/extend a WebLogic domain with that template.

To generate a template for a Java EE agent using the generate_agent_wls_template.sh script, specify domain and shared libraries with the -domainLibraries and -sharedLibraries arguments as illustrated in the following example:
./generate_agent_wls_template.sh  
  -agentName sample 
  -agentContextName context 
  -odiUser SUPERVISOR 
  -destinationJar /home/userName/NewFormaterJar.jar 
  -retryCount 10 
  -retryDelayMS 1 
  -createDatasourceForMasterRepository false 
  -masterDataSource jdbc/odiMasterRepository,oracle.jdbc.OracleDriver,jdbc:oracle:thin:@mycompany.com-isESSDependency false 
  -addToPath /home/userName 
  -domainLibraries /home/userName/odi/myDomain/userlib/myLib.jar 
  -sharedLibraries MessageBox

To generate a template for a Java EE agent and specify additional libraries for the agent using ODI Studio:

  1. Start ODI Studio.
  2. Select Generate Server Template, to start the Template Generation wizard.
  3. In the Agent Information page, enter the agent information, such as the Java EE agent name, the datasource JNDI name, the connection retry count, and the Supervisor key.
  4. In the Libraries and Drivers page, select the libraries you want to deploy with your Java EE agent from the list of external libraries. Note that library name validation is limited within the newly added libraries, not against already deployed shared libraries. You can select a domain library or a shared library. Domain libraries are the libraries deployed in the WebLogic domain and are available to a Java EE agent, since they are available to all applications running in the domain. Domain libraries are typically used when adding infrequently changed JAR files. Note that when using this approach, you must reboot all servers in the domain for the change to take effect. Shared libraries are libraries you specify in the agent deployment descriptor, before deploying the agent to the domain. With shared libraries, multiple applications can use the libraries resources and duplication is avoided. Shared libraries are used for libraries that may need modifications or upgrade. These libraries allow you to change libraries without restarting the server, but you may need to restart the application
  5. Click Next to display the Datasources page.
  6. In that page, select the datasource definitions that you want to include in the agent template. You can only select datasources using this wizard. To add datasources use the Data Sources tab.
  7. Click Next to display the Template Target and Summary page.
  8. In that page, specify where the template should be generated in the Target Template Path box.
  9. Click Finish to close the wizard and generate the agent template.

5.6 Starting a Java EE Agent

Start Node Manager, then the WebLogic Administration Server and WebLogic Managed Servers for the Java EE agent.

Note:

If you have not yet configured the physical agent in the master repository, go to Creating an Agent in the Master Repository with ODI Studio.

5.6.1 Starting Node Manager

Learn how to start Oracle Node Manager in your domain.

To start Node Manager in a domain, first go to the domain DOMAIN_HOME/bin directory. Then start Node Manager as follows:

On UNIX operating systems, use nohup and nm.out as output file:

nohup ./startNodeManager.sh > nm.out&

On Windows operating systems, run:

startNodeManager.cmd

Note:

On Windows operating systems, Oracle recommends configuring 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".

For more information about additional Node Manager configuration options, see Administering Node Manager for Oracle WebLogic Server.

5.6.2 Starting the Administration Server

Learn how to start the WebLogic Administration Server.

To start the Administration Server, go the DOMAIN_HOME/bin directory.

On UNIX operating systems, run:

./startWebLogic.sh

On Windows operating systems, run:

startWebLogic.cmd

Note:

When you run ./startWebLogic.sh in the foreground, control does not return to the terminal. If you terminate the terminal, the Admin Server is also terminated. Therefore, Oracle recommends running the start script in the background to avoid killing the servers even if the terminal is closed.

If you selected Production Mode on the Domain Mode and JDK screen, you will be prompted for the login credentials of the Administrator user as provided on the Administrator Account screen.

Tip:

For more information about starting the Administration Server, see Starting and Stopping Administration Servers.

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.

You can verify that the Administration Server is up and running by access the Administration Server Console. The URL is provided on the Configuration Success screen.

Note:

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.

For more information about how to use the Administration Console, see Getting Started Using Oracle WebLogic Server Administration Console.

5.6.3 Starting the ODI Managed Server

Learn how to start the ODI Managed Server.

To start a WebLogic Managed Server:

  1. Login to Oracle Fusion Middleware Control:
    http://administration_server_host:administration_server_port/em
    

    The Administration Server host and port number were in the URL on the Configuration Success screen. The default Administration Server port number is 7001.

    The login credentials were provided on the Administrator Account screen.

  2. Bring up the Target Navigation, and expand domains until the ODI_server1 server (a WebLogic Managed Server) is visible.
    Target navigation panel
  3. Select ODI_server1 server, to display the server’s page.
  4. In that page, select Start Up to start the ODI_server1 server.
    Start ODI
  5. In the Target Navigation page, select the odi_domain to verify that the server you started is up and running.
    Monitor ODI

Tip:

For information about managing Oracle Fusion Middleware using Oracle Enterprise Manager Fusion Middleware Control, see Administering Oracle Fusion Middleware with Fusion Middleware Control.

5.7 Performing Next Steps

Learn about domain administration and configuration, and other tasks that prepare your Oracle Data Integrator environment for development.

Performing Basic Administrative Tasks contains basic administration tasks. You should familiarize yourself with the tasks described in this section and perform them as needed to verify that your domain is properly configured.

Performing Additional Domain Configuration Tasks contains additional domain configuration tasks that take advantage of additional Oracle Fusion Middleware products and features.

Preparing Oracle Data Integrator for Development contains common tasks to help prepare your Oracle Data Integrator environment for development.

Preparing Your Environment For High Availability contains important tasks to help prepare your environment to move to a highly available environment.