COMPAS currently works with any application server that implements the JMX Remote API (JSR 160). All major application server vendors have announced support for JSR 160, including IBM Websphere, BEA Weblogic, JBoss and JOnAS.

Current status: Since only JOnAS has a fully working and documented implementation of JSR 160, COMPAS has only been tested with it so far. It is however trivial to change the working server in COMPAS, by changing a few values in a COMPAS configuration file. Weblogic 9.0 final release already has full support for JSR 160 but the current beta release does not fully support the basic JMX spec (to be corrected in the final release). JBoss 4.x will soon include support for JSR 160 as well.

Installing COMPAS J2EE is straightforward. The following steps must be followed:

1. Obtain and unpack COMPAS J2EE.
2. Obtain the required libraries.
3. Configure the required COMPAS properties.
4. Install the COMPAS probes into the target J2EE application.
5. Using precise timestamps.
6. Configuring the alert threshold.
7. Test the installation.

1. Obtaining and unpacking COMPAS J2EE

Get the latest version and unzip it to a location of your choice (which we will refer to as COMPAS_HOME).

2. Obtaining the required libraries

The following open-source packages must be available in order for COMPAS to run. Follow the links to download them.

				BCEL BeanShell BSF
Log4J	Ant	Velocity	Xerces	ant dependencies

The easiest way to install the Ant dependencies is to copy the respective jars (bsh-version.jar, bcel-version.jar, bsf.jar) into the lib directory under ANT_HOME (the Ant installation directory). This way they will be loaded automatically by Ant.

Note that the required Xerces libraries are available with the newer versions of Ant so they do not need to be downloaded anymore.

In addition, the JMX reference implementation and the JMX Remote reference implementations need to be installed. Both are freely available from Sun at:

http://java.sun.com/products/JavaManagement/download.html

3. Configuring the required COMPAS properties

Edit the build.properties and compas-env.conf files to correspond to your environment. These files are located in COMPAS_HOME and COMPAS_HOME/resources respectively.

An example of build.properties follows. It is used to set locations for jars and directories corresponding to libraries required by the distribution building and instrumentation operations.

# COMPAS properties

# required COMPAS libraries (use the forward slash character '/' as pathname delimiter on all platforms)
jmx.lib.path=D:/java/jmx-1_2_1-bin/lib
jmx.remote.lib.path=D:/java/jmxremote-1_0_1-bin/lib
j2ee.jar.path=D:/java/libs/j2ee.jar
velocity.jar.path=D:/java/velocity-1.4/velocity-1.4.jar
xerces.lib.path=D:/java/ant/lib
ant.lib.path=D:/java/ant/lib
bcel.jar.path=D:/java/ant/lib/bcel-5.1.jar
log4j.jar.path=D:/java/logging-log4j-1.2.9/dist/lib/log4j-1.2.9.jar
commons.collections.jar.path=D:/java/commons-collections-3.1/commons-collections-3.1.jar

#building properties (you need to set these if you want to build compas from the source files
distrib.location=d:/work.personal/distributions/compas
proxies.proj.location=d:/work.personal/workspaces/open-source/COMPAS-Proxies

The compas-env.conf file specifies startup options and JMX connection properties. Some of the JMX properties have different values from server to server. Others correspond to server installation properties, such as host name and port number. The following example corresponds to the JOnAS application server (tested with v.4.3.4). All servers that support the JMX Remote API are supported though. Weblogic 9.0 properties are present in the file but are commented out since the current beta version of 9.0 does not support registering custom JMX MBeans, an essential requirement of COMPAS. In the final 9.0 release, this problem will be solved, and will be able to use those values to connect to Weblogic.

# COMPAS: the execution environment properties file

#resource path: the full path name of the resources directory. required for access from EJBs
#must use / as the path separator character
resource_path = resources/

#GUI selection
#valid values are: MULTI, BASIC, SIMPLE_TREE, FULL
gui = FULL

appserver = JSR160-COMPLIANT
#for JOnAS
jsr160.server.protocol = rmi
jsr160.server.host = technetium.inrialpes.fr
jsr160.naming.host = technetium.inrialpes.fr
jsr160.naming.port = 1099
jsr160.jndi.path = /jrmpconnector_jonas

#for Weblogic
#jsr160.server.protocol = t3
#jsr160.server.host = technetium.inrialpes.fr
#jsr160.naming.host = technetium.inrialpes.fr
#jsr160.naming.port = 1099
#jsr160.jndi.path = /jndi/weblogic.management.mbeanservers.domainruntime

#optional properties
#for Weblogic 9:
#javax.naming.Context.SECURITY_PRINCIPAL=weblogic
#javax.naming.Context.SECURITY_CREDENTIALS=weblogic
#javax.management.remote.JMXConnectorFactory.PROTOCOL_PROVIDER_PACKAGES= "weblogic.management.remote"

# end

4. Installing the COMPAS probes

COMPAS can automatically inject monitoring probes into an existing J2EE EAR archive. You might already have an EAR deployed onto your application server. COMPAS will generate another EAR from your original EAR (target EAR). The generated EAR can then be deployed onto the application server, in place of the original EAR.

The instrumentation.properties file is used to specify the names and locations for the target and instrumented EARs. An example follows:

#COMPAS Instrumentation Properties

targetEAR=d:/work.personal/workspaces/open-source/AdaptiveCellsJ/distrib/adaptivecellsj.ear
compasEARlocation=d:/temp/compas.output
compasEARName=adaptivecellsj-proxified.ear

Generating an instrumented version of your EAR implies running the insert_probes ant task found in the ant script build.xml. A batch file is provided on windows to simplify setting the required environment variables and classpath. Run

run-generation.bat

to install the probes in the target EAR. The output will be similar to the screenshot below.

5. Using Precise time stamps

6. Configuring The Alert Threshold

#temporary configuration file to specify the alert threshold for compas probes
#specify a value in milliseconds.
#this file must reside in C:\compas_alert_threshold.conf

threshold = 300

7. Testing the installation

If you have correctly set the properties files, you should be able to run the COMPAS Client (on the same machine or on a remote machine with respect to the application server). Running COMPAS implies running the run task found in the ant script build.xml. A batch file is provided on windows to simplify setting the required environment variables and classpath. Run

run-compas.bat

to start-up the COMPAS Client GUI.