2 Installation

This chapter describes how to install and configure the JCA adapter. It contains the following topics:

Chapter2, "Installing the JCA Adapter"
Chapter2, "Configuring the JCA adapter"

Installing the JCA Adapter

The JCA adapter must be installed in an existing Oracle home Middle Tier for OracleAS Integration InterConnect 10g Release 2 (10.1.2).

This section contains the following topics:

Preinstallation Tasks
Installation Tasks

Preinstallation Tasks

Refer to following guides before installing the JCA adapter:

Oracle Application Server Installation Guide for information about Oracle Universal Installer startup.

Oracle Application Server Integration InterConnect Installation Guide for information on software, hardware, and system requirements for OracleAS Integration InterConnect.

Note:

OracleAS Integration InterConnect Hub is installable through the OracleAS Integration InterConnect Hub installation type. You must install the OracleAS Integration InterConnect Hub before proceeding with the JCA adapter installation.

Installation Tasks

To install the JCA adapter:

In the Available Product Components window of the OracleAS Integration InterConnect installation, select OracleAS Integration InterConnect JCA Adapter and click Next.

Figure 2-1 Available Product Components Window

Description of "Figure 2-1 Available Product Components Window"
The Set Oracle Wallet Password window is displayed. Enter and confirm the password, which will be used to manage OracleAS Integration InterConnect installation. Click Next.
- Go to step 3, if installing the JCA adapter in an OracleAS Middle Tier Oracle home that does not have an InterConnect component already installed. Ensure that the OracleAS Integration InterConnect hub has been installed.
- Go to step 4, if installing the JCA adapter in an OracleAS Middle Tier Oracle home that has an existing InterConnect component. Ensure that it is a home directory to an OracleAS Integration InterConnect component.
The Specify Hub Database Connection window is displayed. Enter information in the following fields:
- Host Name: The host name of the computer where the hub database is installed.
- Port Number: The TNS listener port for the hub database.
- Database SID: The System Identifier (SID) for the hub database.
- Password: The password for the hub database user.
Click Next. The Specify HTTP Adapter Name window is displayed.
Enter the application to be defined. Blank spaces are not permitted. The default value is myJCAAdapter.

Figure 2-2 Specify JCA Adapter Name Window

Description of "Figure 2-2 Specify JCA Adapter Name Window"
Click Next. The Summary window is displayed.
Click Install to install the JCA adapter. The adapter is installed in the following directory, depending on the operating system:

Platform Directory

UNIX ORACLE_HOME/integration/interconnect/adapters/Application

Windows ORACLE_HOME\integration\interconnect\adapters\Application
Click Exit on the Installation window to exit the JCA adapter installation.

Installing Multiple JCA Adapters in the Same Oracle Home

To install multiple instances of the JCA adapter in same Oracle home, use the copyAdapter script located in the ORACLE_HOME/integration/interconnect/bin directory.

Usage: copyAdapter app1 app2

For example, you have one instance of JCA adapter with name myJCAApp installed on a computer. To install another instance of the JCA adapter with name myJCAApp1 in the same Oracle home, use the following command:

copyAdapter myJCAApp myJCAApp1

The copyAdapter script is copied to the following bin directory only during Hub installation:

UNIX: ORACLE_HOME/integration/interconnect/bin
Windows: ORACLE_HOME\integration\interconnect\bin

If you need to use this script to create multiple adapters on a spoke computer, then copy the script to the bin directory on the spoke computer, and edit the script to reflect the new Oracle home.

After running the copyAdapter script, If you want to manage or monitor the newly installed adapter through Oracle Enterprise Manager 10g Application Server Control Console, then you need to modify the opmn.xml file by adding information about the new instance. For example, you have created a new instance of the JCA adapter myJCAApp1 by using the copyAdapter script. To manage the myJCAApp1 adapter through Enterprise Manager, perform the following:

Navigate to the MiddleTier\bin directory and run the following command to stop the Enterprise Manager:
```
emctl stop iasconsole
```

Next, specify the information about this new instance in the opmn.xml file located in the ORACLEMIDDLETIER_HOME/opmn/conf directory as follows:

<process-type id="myJCAApp1" module-id="adapter" working-dir="$ORACLE_
HOME/integration/interconnect/adapters/myJCAApp1" status="enabled">
       <start timeout="600" retry="2"/>
       <stop timeout="120"/>
       <port id="icadapter_dmsport_range" range="15701-15800"/>
       <process-set id="myJCAApp1" restart-on-death="true" numprocs="1">
            <module-data>
                <category id="start-parameters">
                    <data id="java-parameters" value="-Xms8M"/>
                    <data id="class-name"
                     value="oracle.oai.agent.service.AgentService"/>
                </category>
                <category id="stop-parameters">
                    <data id="java-parameters" value="-mx64m"/>
                    <data id="class-name"
                     value="oracle.oai.agent.proxy.ShutdownAgent"/>
                    <data id="application-parameters"
                     value="persistence/Agent.ior"/>
                </category>
            </module-data>
       </process-set>
</process-type>

The opmn.xml file would appear like this:

<process-type id="myJCAApp" module-id="adapter" working-dir="$ORACLE
_HOME/integration/interconnect/adapters/myJCAApp" status="enabled">
       <start timeout="600" retry="2"/>
       <stop timeout="120"/>
       <port id="icadapter_dmsport_range" range="15701-15800"/>
       <process-set id="myJCAApp" restart-on-death="true" numprocs="1">
            <module-data>
                <category id="start-parameters">
                    <data id="java-parameters" value="-Xms8M"/>
                    <data id="class-name"
                     value="oracle.oai.agent.service.AgentService"/>
                </category>
                <category id="stop-parameters">
                    <data id="java-parameters" value="-mx64m"/>
                    <data id="class-name"
             value="oracle.oai.agent.proxy.ShutdownAgent"/>
             <data id="application-parameters"
              value="persistence/Agent.ior"/>
         </category>
     </module-data>
  </process-set>
</process-type>
            
<process-type id="myJCAApp1" module-id="adapter" working-dir="$ORACLE
_HOME/integration/interconnect/adapters/myJCAApp1" status="enabled">
       <start timeout="600" retry="2"/>
       <stop timeout="120"/>
       <port id="icadapter_dmsport_range" range="15701-15800"/>
       <process-set id="myJCAApp1" restart-on-death="true" numprocs="1">
        <module-data>
          <category id="start-parameters">
              <data id="java-parameters" value="-Xms8M"/>
              <data id="class-name"
               value="oracle.oai.agent.service.AgentService"/>
          </category>
          <category id="stop-parameters">
               <data id="java-parameters" value="-mx64m"/>
               <data id="class-name"
                value="oracle.oai.agent.proxy.ShutdownAgent"/>
               <data id="application-parameters"
                value="persistence/Agent.ior"/>
          </category>
        </module-data>
       </process-set>
</process-type>

Save the opmn.xml file.
Navigate to the MiddleTier\opmn\bin directory and run the following command to reload the OPMN:
```
opmnctl reload
```

You can start the myJCAApp1 adapter by using the following command

opmnctl startproc ias-component="InterConnect" process-type="myJCAApp1"

Navigate to the MiddleTier\bin directory and run the following command to start the Enterprise Manager:
```
emctl start iasconsole
```
Login to the Oracle Enterprise Manager 10g Application Server Control Console to view and manage the newly installed or copied adapter. For information about how to use Oracle Enterprise Manager 10g Application Server Control Console , refer to the Oracle Application Server Integration InterConnect User's Guide

Note:

While installing multiple adapters in the same computer, the copyadapter script does not create entries for the new adapter's password in the Oracle Wallet. You need to manually create a password for this new adapter using the Oracle Wallet Manager. To store the password in Oracle Wallet, use the following format:

ApplicationName/password

The number of entries is dependent on the type of adapter. For example, Database Adapter needs two entries whereas AQ Adapter needs only one entry. For more information about how to manage your passwords in Oracle Wallet, refer to AppendixA, "How do I secure my passwords?"in Appendix A, "Frequently Asked Questions"

Configuring the JCA adapter

After installing the JCA adapter, you can configure it for your needs. The following tables describe the location and details of the configuration files.

Table 2-1 describes the location where the adapter is installed.

Table 2-1 JCA Adapter Directory

Platform	Directory
UNIX	`ORACLE_HOME/integration/interconnect/adapters/Application`
Windows	`ORACLE_HOME\integration\interconnect\adapters\Application`

Table 2-2 describes the various executable files available for the JCA adapter.

Table 2-2 OA Executable Files

File	Description
`start` (UNIX)	Does not take parameters; starts the adapter.
`start.bat` (Windows)	Does not take parameters; starts the adapter.
`stop` (UNIX)	Does not take parameters; stops the adapter.
`stop.bat` (Windows)	Does not take parameters; stops the adapter.

Table 2-3 describes the JCA adapter configuration files.

Table 2-3 OA Configuration Files

File	Description
`adapter.ini` (UNIX)	Consists of all the initialization parameters that the adapter reads at startup.
`adapter.ini` (Windows)	Consists of all the initialization parameters that the adapter reads at startup.

Table 2-4 describes the directories used by the JCA adapter.

Table 2-4 JCA Directories

Directory	Description
`logs`	The logging of adapter activity is done in subdirectories of the logs directory. Each new run of the adapter creates a new subdirectory in which logging is done in an `log.xml` file.
`persistence`	The messages are persisted (made available) in this directory. Do not edit this directory or its files.

JCA Adapter Ini File Settings

The following are the .ini files used to configure the JCA adapter:

hub.ini Parameters
adapter.ini Parameters

hub.ini Parameters

The JCA adapter connects to the hub database using the parameters in the hub.ini file located in the hub directory. Table 2-5 gives a description and an example for each parameter of the hub.ini file.

Table 2-5 hub.ini Parameters

Parameter	Description	Example
`hub_host`	The name of the computer hosting the hub database. There is no default value. The value is set during installation.	`hub_host=mpscottpc`
`hub_instance`	The SID of the hub database. There is no default value. The value is set during installation.	`hub_instance=orcl`
`hub_port`	The TNS listener port number for the hub database instance. There is no default value. The value is set during installation.	`hub_port=1521`
`hub_username`	The name of the hub database schema (or user name). The default value is `ichub`.	`hub_username=ichub`
`repository_name`	The name of the repository that communicates with the adapter. The default value is `InterConnectRepository`.	`repository_name=InterConnectRepository`

Oracle Real Application Clusters hub.ini Parameters

When a hub is installed on a Oracle Real Application Cluster database, the parameters listed in Table 2-6 represent information about additional nodes used for connection and configuration. These parameters are in addition to the default parameters for the primary node. In Table 2-6, x represents the node number which can range from 2 to total number of nodes in a cluster. For example, if the cluster contains 4 nodes, then x can be a value between 2 and 4.

Table 2-6 Oracle Real Application Clusters hub.ini Parameters

Parameter	Description	Example
`hub_hostx`	The host where the Real Application Clusters database is installed.	`hub_host2=dscott13`
`hub_instancex`	The instance on the respective node.	`hub_instance2=orcl2`
`hub_num_nodes`	The number of nodes in a cluster.	`hub_num_nodes=4`
`hub_portx`	The port where the TNS listener is listening.	`hub_port2=1521`

adapter.ini Parameters

The agent component of the JCA adapter reads the adapter.ini file at run time to access information on configuring the JCA adapter parameter. Table 2-7 gives a description and an example for each parameter of the adapter.ini file.

Table 2-7 adapter.ini Parameters

Parameter	Description	Example
`agent_admin_port`	Specifies the port through which the adapter can be accessed through firewalls. Possible value: A valid port number Default value: None	`agent_admin_port=15005`
`agent_delete_file_cache_at_startup`	Specifies whether to delete the cached metadata during startup. If any agent caching method is enabled, then metadata from the repository is cached locally on the file system. Set the parameter to `true` to delete all cached metadata on startup. Possible values: `true` or `false` Default value: `true` Note: After changing metadata or DVM tables for the adapter in iStudio, you must delete the cache to guarantee access to new metadata or table information.	`agent_delete_file_cache_at_startup=false`
`agent_dvm_table_caching`	Specifies the Domain Value Mapping (DVM) table caching algorithm. Possible values: `startup`: Cache all DVM tables at startup. This may be time-consuming if there are many tables in the repository. `demand`: Cache tables as they are used. `none`: No caching. This slows down performance. Default value: `demand`.	`agent_dvm_table_caching=demand`
`agent_log_level`	Specifies the amount of logging necessary. Possible values: `0`=errors only `1`=status and errors `2`=trace, status, and errors Default value: `1`	`agent_log_level=2`
`agent_lookup_table_caching`	Specifies the lookup table caching algorithm. Possible values: `startup`: Cache all lookup tables at startup. This may be time-consuming if there are many tables in the repository. `demand`: Cache tables as they are used. `none`: No caching. This slows down performance Default value: `demand`	`agent_lookup_table_caching=demand`
`agent_max_ao_cache_size`	Specifies the maximum number of application object metadata to cache. Possible value: An integer greater than or equal to `1` Default value: `200`	`agent_max_ao_cache_size=200`
`agent_max_co_cache_size`	Specifies the maximum number of common object metadata to cache. Possible value: An integer greater than or equal to `1` Default value: `100`	`agent_max_co_cache_size=100`
`agent_max_dvm_table_cache_size`	Specifies the maximum number of DVM tables to cache. Possible value: An integer greater than or equal to `1` Default value: `200`	`agent_max_dvm_table_cache_size=200`
`agent_max_lookup_table_cache_size`	Specifies the maximum number of lookup tables to cache. Possible value: Any integer greater than or equal to `1` Default value: `200`	`agent_max_lookup_table_cache_size=200`
`agent_max_message_metadata_cache_size`	Specifies the maximum number of message metadata (publish/subscribe and invoke/implement) to cache. Possible value: An integer greater than or equal to `1` Default value: `200`	`agent_max_message_metadata_cache_size=200`
`agent_max_queue_size`	Specifies the maximum size internal OracleAS Integration InterConnect message queues can grow. Possible value: An integer greater than or equal to `1` Default value: `1000`	`agent_max_queue_size=1000`
`agent_message_selector`	Specifies conditions for message selection when the adapter registers its subscription with the hub. Possible value: A valid Oracle Advanced Queue message selector string (like `'%,%s_adaptername%,%'`) Default value: None	`agent_message_selector=%,aqapp`,`%`
`agent_metadata_caching`	Specifies the metadata caching algorithm. Possible values: `startup`: Cache everything at startup. This may be time-consuming if there are many tables in the repository. `demand`: Cache metadata as it is used. `none`: No caching. This slows down performance Default value: None	`agent_metadata_caching=demand`
`agent_persistence_cleanup_interval`	Specifies how often to run the persistence cleaner thread in milliseconds. Possible value: An integer greater than or equal to `30000` milliseconds Default value: `60000`	`agent_persistence_cleanup_interval=60000`
`agent_persistence_queue_size`	Specifies the maximum size of internal OracleAS Integration InterConnect persistence queues. Possible value: An integer greater than or equal to `1` Default value: `1000`	`agent_persistence_queue_size=1000`
`agent_persistence_retry_interval`	Specifies how often the persistence thread retries when it fails to send an OracleAS Integration InterConnect message. Possible value: An integer greater than or equal to `5000` milliseconds Default value: `60000`	`agent_persistence_retry_interval=60000`
`agent_pipeline_from_hub`	Specifies whether to activate the pipeline for messages from the hub to the bridge. If you set the pipeline to `false`, then the file persistence is not used in that direction. Possible value: `true`, `false` Default value: `false`	`agent_pipeline_from_hub=false`
`agent_pipeline_to_hub`	Specifies whether to activate the pipeline for messages from the bridge to the hub. If you set the pipeline to `false`, then the file persistence is not used in that direction. Possible value: `true`, `false` Default value: `false`	`agent_pipeline_to_hub=false`
`agent_reply_message_selector`	Specifies the application instance to which the reply must be sent. This parameter is used if multiple adapter instances exist for the given application and given partition. Possible value: A string built using the application name (parameter:application) concatenated with the instance number (parameter:instance_number). Default value: None	If `application=aqapp, instance_number=2`, then `agent_reply_message_selector=`recipient_list `like` '`%,aqapp2,%`'
`agent_reply_subscriber_name`	Specifies the subscriber name used when multiple adapter instances are used for the given application and given partition. This parameter is optional if only one instance is running. Possible value: The application name (`parameter:application`) concatenated with the instance number (`parameter:instance_number`). Default value: None	If `application=oaapp` and `instance_number=2`, then `agent_reply_subscriber_name=oaapp2`
`agent_subscriber_name`	Specifies the subscriber name used when this adapter registers its subscription. Possible value: A valid Oracle Advanced Queue subscriber name Default value: None	`agent_subscriber_name=oaapp`
`agent_throughput_measurement_enabled`	Specifies if the throughput measurement is enabled. Set this parameter to `true` to turn on throughput measurements. Default value: `true`	`agent_throughput_measurement_enabled=true`
`agent_tracking_enabled`	Specifies if message tracking is enabled. Set this parameter to `false` to turn off tracking of messages. Set this parameter to `true` to track messages with tracking fields set in iStudio. Default value: `true`	`agent_tracking_enabled=true`
`agent_use_custom_hub_dtd`	Specifies whether to use a custom DTD for the common view message when handing it to the hub. By default, adapters use a specific OracleAS Integration InterConnect DTD for all messages sent to the hub. Set this parameter to `true` to have the adapter use the DTD imported for the message of the common view instead of the OracleAS Integration InterConnect DTD. Default value: `false`	`agent_use_custom_hub_dtd=false`
`application`	Specifies the name of the application to which this adapter connects. This must match the name specified in iStudio while creating metadata. Possible value: An alphanumeric string. Default value: None	`application=oaapp`
`instance_number`	Specifies the instance number to which this adapter corresponds. Specify a value only if you have multiple adapter instances for the given application with the given partition. Possible value: An integer greater than or equal to `1`. Default value: None	`instance_number=1`
`partition`	Specifies the partition this adapter handles as specified in iStudio. Possible value: An alphanumeric string. Default value: None	`partition=germany`
`service_class`	Specifies the entry class for the Windows service. Possible value: `oracle/oai/agent/service/AgentService`. Default value: None	`service_class=oracle/oai/agent/service/AgentService`
`service_classpath`	Specifies the class path used by the adapter JVM. If a custom adapter is developed and the adapter is to pick up any additional jar files, then add the files to the existing set of jar files. Possible value: A valid `PATH` setting Default value: None This parameter is for Microsoft Windows only.	`service_classpath=D:\oracle\oraic\integration\interconnect\lib\oai.jar; D:\oracle\oraic\jdbc\classes12.zip`
`service_jdk_dll`	Specifies the Dynamic Link Library(DLL) that the adapter JVM should use. Possible value: A valid `jvm.dll` Default value: `jvm.dll` This parameter is for Microsoft Windows only.	`service_jdk_dll=jvm.dll`
`service_jdk_version`	Specifies the JDK version that the adapter JVM should use. Possible value: A valid JDK version number Default value: 1.4.2 This parameter is for Microsoft Windows only.	`service_jdk_version=1.4`
`service_max_heap_size`	Specifies the maximum heap size for the adapter JVM. Possible value: A valid JVM heap size Default value: `536870912` This parameter is only for Microsoft Windows.	`service_max_heap_size=536870912`
`service_max_java_stack_size`	Specifies the maximum size the JVM stack can grow. Possible value: A valid JVM maximum stack size Default value: Default value for the JVM This parameter is only for Microsoft Windows.	`service_max_java_stack_size=409600`
`service_max_native_stack_size`	Specifies the maximum size the JVM native stack can grow. Possible value: The valid JVM maximum native stack size Default value: Default value for the JVM This parameter is only for Microsoft Windows.	`service_max_native_size=131072`
`service_min_heap_size`	Specifies the minimum heap size for the adapter JVM. Possible value: The valid JVM heap size Default value: `67108864` This parameter is only for Microsoft Windows.	`service_min_heap_size=67108864`
`service_num_vm_args`	Specifies the number of `service_vm_argnumber` parameters specified in JVM. Possible value: The number of `service_vm_argnumber` parameters Default value: `2` This parameter is only for Microsoft Windows.	`service_num_vm_args=1`
`service_path`	Specifies the environment variable `PATH`. The `PATH` variable is set before starting the Java Virtual Machine (JVM). Typically, list all directories that contain necessary DLLs. Possible value: The valid `PATH` environment variable setting Default value: None This parameter is only for Microsoft Windows.	`service_path=%JREHOME%\bin;D:\oracle\oraic\bin`
`service_vm_arg`number	Specifies any additional arguments to the JVM. For example, to retrieve line numbers in any stack traces, set `service_vm_arg1=java.compiler=NONE`. If a list of arguments exists, then use multiple parameters as shown in the example, by incrementing the last digit by `1`. Possible value: A valid JVM arguments Default value: None This parameter is only for Microsoft Windows.	`service_vm_arg1=java.compiler= NONE` `service_vm_arg2=oai.adapter=.aq`

JCA Adapter-specific Parameters

Table 2-8 lists the parameters specific to the JCA adapter.

Table 2-8 JCA Adapter-specific Parameters

Parameter Description Example

Parameter	Description	Example
`connection1_name`	Specifies EIS-specific connection factory instance. Possible value: `connection1_name=eis/DatabaseAdapter`	`connection1_name=eis/DatabaseAdapter`
`connection1_mcf_class`	Specifies the managed connection factory class. Possible value: `oracle.tip.adapter.db.DBManagedConnectionFactory`	`connection1_mcf_class=oracle.tip.adapter.db.DBManagedConnectionFactory`
`connection1_mcf_params`	Specifies the managed connection factory class parameters such as `ConnectionString`, `DriverClassname`, `UserName`, and `Password`.	`connection1_mcf_params={ConnectionString=jdbc:oracle:thin:@apatel-pc.us.oracle.com:1521:orcl, DriverClassName=oracle.jdbc.driver.OracleDriver, UserName=scott, Password=tiger}`

connection1_name

Specifies EIS-specific connection factory instance.

Possible value: connection1_name=eis/DatabaseAdapter

connection1_name=eis/DatabaseAdapter

connection1_mcf_class

Specifies the managed connection factory class.

Possible value: oracle.tip.adapter.db.DBManagedConnectionFactory

connection1_mcf_class=oracle.tip.adapter.db.DBManagedConnectionFactory

connection1_mcf_params

Specifies the managed connection factory class parameters such as ConnectionString, DriverClassname, UserName, and Password.

connection1_mcf_params={ConnectionString=jdbc:oracle:thin:@apatel-pc.us.oracle.com:1521:orcl, DriverClassName=oracle.jdbc.driver.OracleDriver, UserName=scott, Password=tiger}