10 Installing Observer Libraries for OC4J

This topic provides instructions for installing and uninstalling observer libraries for an Oracle Containers for Java (OC4J) instance running within Oracle SOA Suite 10g.

Note:

For a list of the exact application server versions supported by this observer, refer to the Business Transaction Management (BTM) Certification Matrix. You can find this document online at http://support.oracle.com.

The Observer Distribution File

The Business Transaction Management observers are distributed by way of ZIP files. Each ZIP file contains one type of observer that is suitable for installation into a particular application server. The ZIP file suitable for installing an observer into an OC4J instance is BTMObserver_Oc4j_10.1_Soa10g_*.zip.

Note:

In the complete ZIP file name, the asterisk (*) is replaced with the observer version number.

Installing the Observer Libraries on OC4J

  1. Locate the appropriate observer distribution ZIP file (BTMObserver_Oc4j_10.1_Soa10g_*.zip).

  2. Unpack the ZIP file into SOA_Suite_Install_Dir/j2ee, where SOA_Suite_Install_Dir is your SOA Suite 10g installation directory, for example:

    C:\product\10.1.3.1\OracleAS_1\j2ee

    For the remainder of this procedure, replace SOA_Suite_Install_Dir with the actual path to your SOA Suite 10g installation directory.

    Unpacking the ZIP file creates a nanoagent directory containing two subdirectories—config and lib.

    Note:

    By default, the observer looks in the lib directory for its libraries. For information on overwriting this default location, see Overriding the Default Location of Observer Libraries.

  3. Ensure that the user account running the OC4J instance has at least the following privileges:

    • read permission on the nanoagent/config and nanoagent/lib directories (on UNIX-like systems traverse permission is also required)

    • read permission on all JAR files in the lib directory

  4. Open SOA_Suite_Install_Dir/opmn/conf/opmn.xml in a text editor.

  5. Locate the Java startup options for your OC4J instance as follows:

    1. Locate the <process-type> element whose module-id attribute is set to "OC4J".

    2. Inside this element, locate the <category> element whose id attribute is set to "start-parameters".

    3. Inside this element, locate the <data> element whose id attribute is set to "java-options".

      This element's value attribute contains the Java startup options.

  6. Configure the observer into your OC4J instance by editing the Java startup options as follows:

    1. Define the observer home directory by adding the following Java system property, substituting the appropriate value in place of SOA_Suite_Install_Dir:

      -DAP_NANO_HOME=SOA_Suite_Install_Dir\j2ee\nanoagent

    2. Associate the observer with a monitor by adding the following Java system property, replacing Host:Port with the host name and port number at which the monitor is available:

      -DAP_NANO_CONFIG_URL=http:^//Host:Port^/btmmonitor^/agent^/agent^/

      Take care to insert the caret symbols (^) as shown.

      Note:

      If you are using replicated monitors, you must set the host and port portion of the URL to the host and port of your load balancer's HTTP virtual server. For example, if the HTTP virtual server's IP address is 10.147.46.152, and its port number is 5072, then you would set the URL to: 
      http:^//10.147.46.152:5072^/btmmonitor^/agent^/agent^/

      For more information about the load balancer's HTTP virtual server, see Configuring Your Load Balancer.

    3. Add the following JVM arguments, substituting the appropriate value in place of SOA_Suite_Install_Dir:

      -javaagent:SOA_Suite_Install_Dir\j2ee\nanoagent\lib\bootstrap\ap-nano-bootstrap.jar  -Xbootclasspath^/a:SOA_Suite_Install_Dir\j2ee\nanoagent\lib\bootstrap\ap-nano-bootstrap.jar;SOA_Suite_Install_Dir\j2ee\nanoagent\lib\bootstrap\com.oracle.diagnostics.instrumentor.jar

      Take care that the only space you insert into this string is between “ap-nano-bootstrap.jar” and “-Xbootclasspath”.

    4. Add Java system properties to hold the username and password of an administrator-privileged account for the OC4J instance as follows:

      -DAP_NANO_OC4J_USER=OC4J_Username
-DAP_NANO_OC4J_PASSWORD=OC4J_Password

      The password can be clear or encrypted text. You can encrypt passwords using the encryptPassword CLI command, for example:

      btmcli encryptPassword -password "myPassword"

      For information about accessing the CLI (command line interface), see Invoking the CLI.

    Here is an example of the entire addition to the Java startup options:

    -DAP_NANO_HOME=C:\product\10.1.3.1\OracleAS_1\j2ee\nanoagent -DAP_NANO_CONFIG_URL=http:^//mymonitor.mydomain.com:8080^/btmmonitor^/agent^/agent^/ -javaagent:C:\product\10.1.3.1\OracleAS_1\j2ee\nanoagent\lib\bootstrap\ap-nano-bootstrap.jar -Xbootclasspath^/a:C:\product\10.1.3.1\OracleAS_1\j2ee\nanoagent\lib\bootstrap\ap-nano-bootstrap.jar;C:\product\10.1.3.1\OracleAS_1\j2ee\nanoagent\lib\bootstrap\com.oracle.diagnostics.instrumentor.jar -DAP_NANO_OC4J_USER=oc4jadmin -DAP_NANO_OC4J_PASSWORD=welcome1

  7. Ensure that the user under which your OC4J instance is running has permission to write to the observer's error log directory.

    By default, the observer's error log directory is SOA_Suite_Install_Dir\j2ee\home. For information about configuring error logging, see Chapter 14, "Logging Observer Errors and Debugging Information."

  8. Restart your OC4J instance.

  9. Ensure that the monitor to which your observer forwards messages has an Observer Communication policy applied to it.

    For information on applying an Observer Communication policy, see Applying an Observer Communication Policy.

Uninstalling the Observer Libraries from OC4J

  1. Shutdown your OC4J instance.

  2. Delete the SOA_Suite_Install_Dir/j2ee/nanoagent directory.

  3. Open SOA_Suite_Install_Dir/opmn/conf/opmn.xml in a text editor.

  4. Delete the Java startup options that you added when you installed the observer (see step 6 in the previous procedure for a description of these options).

    Here is an example of the entire addition to the Java startup options:

    -DAP_NANO_HOME=C:\product\10.1.3.1\OracleAS_1\j2ee\nanoagent -DAP_NANO_CONFIG_URL=http:^//mymonitor.mydomain.com:8080^/btmmonitor^/agent^/agent^/ -javaagent:C:\product\10.1.3.1\OracleAS_1\j2ee\nanoagent\lib\bootstrap\ap-nano-bootstrap.jar -Xbootclasspath^/a:C:\product\10.1.3.1\OracleAS_1\j2ee\nanoagent\lib\bootstrap\ap-nano-bootstrap.jar;C:\product\10.1.3.1\OracleAS_1\j2ee\nanoagent\lib\bootstrap\com.oracle.diagnostics.instrumentor.jar -DAP_NANO_OC4J_USER=oc4jadmin -DAP_NANO_OC4J_PASSWORD=welcome1

  5. Delete the observer log files.

    By default, the observer's error log directory is SOA_Suite_Install_Dir\j2ee\home. For more information about the log files, see Chapter 14, "Logging Observer Errors and Debugging Information."

  6. Restart your OC4J instance.