Introduction
This article steps through the integration of JXInsight with OracleAS EJB 3.0 Preview which is available for download from www.oracle.com. I have assumed that the application software has already been installed , configured, deployed, and tested to run the advanced EJB 3.0 demo example which can be found in the <ORACLE-AS-INSTALL-ROOT>/demo/howtoejb30entitymanager. A step by step guide to deploying the example can be found at /doc/how-to-ejb30-entitymanager.html


Step 1 - Download and Install the JXInsight Platform Installer
Click on the downloads link, downloading and installing the JXInsight platform installer. For this article I will be using the Windows XP (x86 32 bit) platform but please note that all Oracle AS operating systems and hardware platforms are supported by JXInsight and that the instructions provided here should be quite similar.


Step 2 - Deploy the JXInsight Java Libraries to OracleAS
Before proceeding please shutdown the the Oracle application server process if it is running then create the library ext directory in <ORACLE-AS-INSTALL-ROOT>/j2ee/home/lib as show in the screenshot below. There are now two possible scenarios. (1) Copy jdbidriver.jar from <JXINSIGHT-INSTALL-ROOT>/lib to the Oracle lib extension directory. This library contains the complete JXInsight profiler, tracer, jdbc drivers, and trace extensions. (2) In recent releases of JXInsight we have partitioned the jdbidriver.jar into small deployment units to support various classloader implementations and configurations. The reason for this is because JXInsight trace extensions work at the actual component or technology interface level rather than use reflection or native code which can be at times slow if one does not optimize the code. Working at the actual component interface levels not only makes our code more robust and performant it allows JXInsight to capture a wealth of contextual information that no other performance managment solution provides today. With the ability in J2EE web containers to deploy whole applications and technology stacks in the web-inf/lib directory our interface level integration can be at times impacted, because typically the jdbidriver.jar library is added to the application servers classpath. To resolve this we allow each trace extension to be deployed separately in different directories. The jxinsight-core.jar library must be accessible to all.

In this example I am using the second option though the first option could have been used because the OracleAS application demo example uses the servers actual technology libraries. To integrate JDBInsight and JXInsight J2EE / EJB3 (javax.persistence.EntityManager) trace extensions I copied over jxinsight-core.jar, jxinsight-ext-ejb3.jar, jxinsight-jdbc-drivers.jar and jxinsight-jdbc-drivers.jar to the library extension directory. These libraries can be found in the <JXINSIGHT-INSTALL-ROOT>/lib directory.




Step 3 - Deploy the JXInsight JVMPI Agent Native Library
Next copy over the jdbinsight JVMPI agent native library into the startup directory ,<ORACLE-AS-INSTALL-ROOT>, of the application server. Native agents for the support operating systems and hardware platforms can be found in the <JXINSIGHT-INSTALL-ROOT>/bin. The Windows x86 32 bit dynamic library, jdbinsight.dll, in <JXINSIGHT-INSTALL-ROOT>/bin/windows was copied over. Alternatively we could have placed the native agent directory on the OS library path. For Windows this means adding <JXINSIGHT-INSTALL-ROOT>/bin/windows to the PATH environment variable.



Next edit the following ejb30.cmd startup script in the bin directory. Adding -Xrunjdbinsight to the JVM command line via the JVMARGS variable already specified in the ejb30 script. If this is not present you may need to edit the actual Java call line further then in the script to append the -Xrunjdbinsight agent command. The -Djdbinsigh.properties.config system property was set to reference a properties file stored in the same directory. This is an ease of use facility for changing JXInsight system properties without changes to the startup script.

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.

Step 4 - Configure the JXInsight Servlet Filter Trace Extension
Lets now edit the web application configuration file, web.xml, located in the EJB30 demo application's WEB-INF directory.
<ORACLE-AS-INSTALL-ROOT>/j2ee/home/application/cmp30-advanced/cmp30-advanced-web/WEB-INF directory.

IMPORTANT JXINSIGHT 4.0 CHANGE NOTE In JXInsight 4.0 the ServletFilter class has been renamed. Please make the following configuration configuration changes. RENAME com.jinspired.jdbinsight.trace.ext.servlet.TraceFilter TO com.jinspired.jxinsight.trace.ext.servlet.TraceFilter.

To integrate the JXInsight trace extension simply add a servlet filter and servlet filter mapping configuration to the web.xml file. Additional information on our highly configurable approach to trace extension design and servlet configuration examples can be read here.



Note: If you rebuild the web application within the <ORACLE-AS-INSTALL-ROOT>/demo/howtoejb30entitymanager directory you will have to redo this step unless the change is made persistent to the web.xml in the actual source build directory.


Step 5 - Integrate JDBInsight for "True" Resource Transaction Analysis
To integrate JDBInsight for indepth and comprehensive resource transaction analysis I edited the data-sources.xml file. The data-sources.xml configuration file is located in <ORACLE-AS-INSTALL-ROOT>/j2ee/home/config directory.



The only change required for a Oracle DB backend integration was to change the datasource package name from oracle.jdbc.pool to com.jinspired.jdbinsight.drivers.jdbc2. For integration with other DBMS backends please read the JXInsight Install Guide.




Step 6 - Startup the Oracle AS EJB 3.0 Process
All the configuration is done so the Oracle server process can now be started. You should see the following terminal output on start.



Navigate to the demo application web page and start creating requests to generate Servlet, EJB3.0 and JDBC tracing and profiing events.



Step 7- The JXInsight Application Performance Management Console
Start up the JXInsight console and mount a server.



Switch to the Profile mode.



Transactions paths should be listed in the Paths Table.



Switch to the traces perspective.




William Louth, JXInsight's Product Architect