11 Installing Observer Libraries on Oracle Enterprise Gateway

This chapter provides instructions for installing and uninstalling observer libraries into Oracle Enterprise Gateway 11.1.1.6.

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 Enterprise Gateway server is BTMObserver_OEG_11.1.1.6_OEG_*.zip.

Notes:

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

For a list of the exact platform and 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.

For detailed information about a specific observer's compatibility and functionality, refer to the README.txt file located in the observer's nanoagent directory after you expand the observer ZIP file.

Installing Observer Libraries on Enterprise Gateway 11.1.1.6

Shut down your Enterprise Gateway server.
Unpack the observer ZIP file (BTMObserver_OEG_11.1.1.6_OEG_*.zip) into a temporary directory, referred to henceforth as observer_temp.

Unpacking the ZIP file creates three directories named config, lib, and scripts.
Copy all of the JAR files located in the lib directory to OEG_HOME/ext/lib, where OEG_HOME is your Enterprise Gateway server's home directory (the top-level installation directory).

Note:
By default, the observer looks in the lib directory for its libraries. For information on overriding this default location, see Overriding the Default Location of Observer Libraries.
Ensure that the user account running Enterprise Gateway 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
Open OEG_HOME/system/conf/jvm.xml in a text editor and make the following changes inside the <JVMSettings> element:
1. Associate your observer with a monitor by adding the following line as the first child of the <JVMSettings> element:
```
<SystemProperty name="AP_NANO_CONFIG_URL" value="http://Host_Name:Port_Number/btmmonitor/agent/agent/"/>
```
  Replace Host_Name:Port_Number with the host name and port number of the monitor you want to associate with your observer.
2. Then add the following lines as the 2nd, 3rd, and 4th children of the <JVMSettings> element:
```
<SystemProperty name="AP_NANO_HOME" value="$VDISTDIR/NanoAgent"/>
<SystemProperty name="AP_NANO_LOG_BASEDIR" value="$VDISTDIR/NanoAgent"/>
<SystemProperty name="AP_NANO_CLASSLOADER_BASEDIR" value="$VDISTDIR/ext/lib"/>
```
3. Optional – If you want to target this observer by way of an observer configuration label, add the following line as the 5th child of the <JVMSettings> element:
```
<SystemProperty name="ap.nano.config.label" value="My_Label_String"/>
```
  Replace My_Label_String with the string you want to use as a label for this observer. For more information about targeting observers refer to Applying an Observer Communication Policy.
4. Locate this line:
```
<ClassPath name="$VDISTDIR/system/lib/system/iaik_jce.jar"/>
```
  and then add this line just before it:
```
<ClassPath name="$VDISTDIR/ext/lib/orawsdl_1.0.0.jar"/>
```
Restart your Enterprise Gateway server.
Publish the interceptor module to finish the installation of the observer as follows:
1. Open the observer_temp/scripts/publishLoadableModule.py script file in a text editor.
2. Set the defUsername and defPassword variables using the credentials of an Enterprise Gateway administrator's account (the user name of the default administrator account is admin), for example:
```
defUserName = "admin"
defPassword = "mypassword"
```
3. Set the defServer variable to the base URL of the Enterprise Gateway server, for example:
```
defServer = "http://myOegHost:8090"
```
  Do not add a trailing slash (/) to this URL.
4. Save and close the script file.
5. Run the script, for example:
  
  On Windows systems, run:
```
%OEG_HOME%/Win32/bin/jython.bat publishLoadableModule.py
```
  On UNIX-like systems, run:
```
$OEG_HOME/posix/bin/jython publishLoadableModule.py
```
Ensure that the user under which your Enterprise Gateway server is running has permission to write to the observer's error log directory.

By default, the observer's error log directory is OEG_HOME. For information about configuring error logging, see Chapter 13, "Logging Observer Errors and Debugging Information."
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 Observer Libraries from Enterprise Gateway 11.1.1.6

This section describes how to uninstall observer libraries from an Enterprise Gateway 11.1.1.6 server.

Remove the observer interceptor module from your Enterprise Gateway server as follows:
1. Open the observer_temp/scripts/removeLoadableModule.py script file in a text editor.
  
  Note:
  If observer_temp no longer exists, refer to Installing Observer Libraries on Enterprise Gateway 11.1.1.6 for information about recreating it.
2. Set the defUsername and defPassword variables using the credentials of an Enterprise Gateway administrator's account (the user name of the default administrator account is admin), for example:
```
defUserName = "admin"
defPassword = "mypassword"
```
3. Set the defServer variable to the base URL of the Enterprise Gateway server, for example:
```
defServer = "http://myOegHost:8090"
```
  Do not add a trailing slash (/) to this URL.
4. Save and close the script file.
5. Run the script, for example:
  
  On Windows systems, run:
```
%OEG_HOME%/Win32/bin/jython.bat removeLoadableModule.py
```
  On UNIX-like systems, run:
```
$OEG_HOME/posix/bin/jython removeLoadableModule.py
```
Shut down your Enterprise Gateway server.
Remove all of the observer-related JAR files located in OEG_HOME/ext/lib.

The observer-related JAR files are those prefixed with “ap-” plus the following files:
```
orahttp_client_1.0.0.jar
orawsdl_1.0.0.jar
xstream-1.2.2.jar 
```
Note:
Take care not to remove JAR files that are being shared with another module.
Open OEG_HOME/system/conf/jvm.xml in a text editor and remove any and all observer-related elements from inside the <JVMSettings> element, including the following:
```
<SystemProperty name="AP_NANO_CONFIG_URL" value="http://host-name:port-number/btmmonitor/agent/agent/"/>

<ClassPath name="$VDISTDIR/ext/lib/orawsdl_1.0.0.jar"/>
```
Also remove all <VMArg> elements whose name attribute begins with the following string:
```
-Dcom.amberpoint
```
Save and close the jvm.xml file.
Restart your Enterprise Gateway server.