JXInsight / JDBInsight

BEA WebLogic Server 8.1

Medical Records (MedRec) Samples J2EE Application
Integration Guide
Introduction

This document details the required steps in integrating JDBInsight/JXInsight with the well known sample application, Medical
Records, shipped with BEA WebLogic 8.1 Server. The document can serve as a basis for understanding the steps required in
integrating the product with a relatively complex J2EE application. Though Windows XP was chosen as the platform for this
document the steps are nearly identical across all platforms except for file conventions and OS library paths.

The Avitek Medical Records (or MedRec) is a WebLogic Server sample application suite that demonstrates aspects of the J2EE
platform. MedRec is designed as an educational tool for all levels of J2EE developers. It showcases the use of each J2EE
component, and illustrates best practice design patterns for component interaction and client development.

The important integration changes are:

• WebLogic Startup Scripts

OS Library Paths, JVM parameters and class path changes

• Server Configuration File - [Link]

JDBC Connection Pools and XA DataSources
BEA WebLogic Startup Scripts

The following image shows the JVM runtime calling section within the [Link] script on Windows prior to
integration.

Typically there are 2 required changes to any application server but as this is distributed transaction (XA) integration an
additional system property change is required to ensure correct transaction analysis. (1) The [Link] containing the JDBC
drivers, JVM profiler, Transaction Analyzer is added to the JVM class path. (2) The JVM is instructed to load the JDBInsight
native library. The native library needs to be available on the OS library path (see install guide for platform specific changes).
For this integration the Windows dynamic link library was placed in the same working directory of the startup script. A change
to PATH within the script could also have been possible. (3) Instruct the profiler to install the XA transaction analyzer. By
default XA support is turned off and a basic one phase commit analyzer is used.

IMPORTANT JXINSIGHT 4.0 CHANGE NOTE

The old library [Link] has been renamed and partitioned into multiple jars to support the class loading of particular trace
extension into child class loaders which is typical within J2EE application server and web container classloader hierarchies.
When deploying a jxinsight-ext-*.jar library the [Link] must be deployed instead of [Link]. The jxinsight-
[Link] must be visible to all trace extensions via the same classloader or a direct/indirect parent classloader. For backward
compatibility the [Link] (previously named [Link]) is built with all JXInsight and JDBInsight classes and
resources.

IMPORTANT JXINSIGHT 4.0 CHANGE NOTE

All system properties have been changed from jdbinsight.* to jxinsight.*. For backward compatibility existing jdbinsight.*
properties will be recognized though it is strongly recommended that all customers upgrade their existing configurations.
BEA WebLogic Server Configuration File
The following image displays the default BEA WebLogic server configuration (medrec/[Link]) for the medical records
application connection pools prior to integration. The first connection pool uses the JDBC 1.x standard database connector
interface – [Link]. This connection pool is used by the JMS service as a backing message store. The second connection
pool uses the standard JDBC 2 database connector interface for distributed transactions – [Link]. This is used
by the Web (Servlets, JSP, Struts) and EJB components (Session and Entity beans). Both connection pools will have minor
changes made to them to allow for comprehensive transactional analysis.

The following section within the configuration file shows the association of the transaction datasource with the XA connection
pool as well as the JMS Store association with the JDBC 1.x connection pool. This section will remain unchanged.
For the first connection pool there are two changes. (1) The DriverName is changed to refer to the JDBInsight JDBC 1.x proxy
driver. (2) The connection URL is modified slightly so that the JDBInsight driver can be informed that you would like a
particular database (URL) to be profiled and analyzed. If the URL is not modified the JDBInsight driver will pass through the
connect call to the underlying vendor driver.

Technical Note: Determining the vendor driver is achieved via the [Link] class. The JDBInsight driver will strip
away the modification, “:jdbinsight” before requesting a driver or connection for the DriverManager class.

The second pool will also have two changes made to it. (1) The DriverName attribute is changed to refer to the JDBInsight
JDBC 2 XA data source. (2) The Properties attribute is changed so that the JDBInsight datasource knows the driver class
name (DriverClassName) of the driver to be instantiated and proxied, and the location (Url) of a properties file used to
configure the instantiated instance.

Technical Note: There should be no characters between the ‘;’ and ‘Url…’ the line break was added for readability. BEA
WebLogic 8.1 Server does not trim additional white space when determining what properties to set on a data source.

The contents of the properties file, [Link], created and referred to within the Properties attribute is shown below.

Technical Note: JDBInsight differs slightly in the naming of Java Bean properties. WLS merely prefixes the property with set
whereas JDBInsight uses the Java Beans standard design pattern for names and property change events which (lower case the
first let after a property setter).
Running the BEA WebLogic Server
First run the startMedRecServer platform specific script. The following images highlight the important terminal outputs.

The JVMPI native agent has been loaded.

The JXInsight JNDI extension and trace adaptor have been instantiated.

The JDBInsight server has been started. The JDBC datasources have been loaded and successfully bound to the
naming service.
Connecting the Console with the BEA WebLogic Server
After performing some user transactions within the Avitek Medical Records J2EE Web application the JDBInsight/JXInsight
console can connect to the server JVM process and retrieve profile model. To create a server connection within the console
select the menu item, ‘Mount Server...’ from the ‘File’ menu. The following dialog is displayed. Enter the IP address or host
name and the JDBInsight server reactor port number which by default is 1515.

By default the console will connect to the server and retrieve the performance monitoring model associated with the Metric
mode. A JDBInsight/JXInsight server connection has 3 modes: Metric, Profile and Trace (JDBC). The Metric mode provides
high level JMV metrics. The Profile mode provides deep transactional insight into the execution behavior of the J2EE
components include JXInsight custom traces. The Trace mode provides JDBC transaction timeline analysis.
The Profile mode can be switched to via the drop down menus at the top right hand corner of view sites. The screenshot
below shows the [Link](..) call within the visits table.

To view the automatic JNDI integration switch to the Traces perspective within the Profile mode. The screenshot below
shows traces started for lookup calls on a [Link] object (naming service)