5. Instrumentation

MaintainJ instrumentation depends on the JRE version and in case of J2EE applications on server type and version. Check the Introduction page for the supported configurations.

5.1 J2EE Applications
5.2 J2SE (Swing or non-GUI), Applets and JUnit  
5.3 Eclipse Plug-ins and Java Applications run from command prompt
5.4 How does instrumentation work?  

5.1 J2EE Applications

If you use Tomcat or JBoss and deploy and start the server from Eclipse Servers view, the MaintainJ J2EE Server Launcher plug-in should be used. Check the Demo Video.

For all other cases use MaintainJ.war. MaintainJ.war installs MaintainJ related jar files to the application server and configures your J2EE application for instrumentation. Deploy MaintainJ.war just as you would deploy any other war file. Open http://server/MaintainJ/index.jsp for installation and configuration page and follow the instructions. Check the Demo Video.

5.2 J2SE (Swing or non-GUI), Applet and JUnit Applications

Demo Videos - MaintainJ for Swing, Applet, JUnit

MaintainJ has a plug-in to instrument J2SE Swing or non-GUI applications. The same plug-in also instruments Applets and JUnit test cases. To instrument J2SE applications that are run from the command prompt, check the next section.

1) Click Run-->Run in Eclipse to open the launch configurations dialog.
2) On the left hand side, you will see three MaintainJ configurations for Java Applets, Java Applications and JUnit as highlighted in the screenshot below. MaintainJ launch configurations are the same as normal configurations except for the Aspect tab, which is the second from left.



3) Create a new configuration for your type of application just as you would, when running without MaintainJ. In the Aspect tab, choose the packages that you want to instrument. Limit the instrumentation scope to your application classes (Ex: com.maintainj.diagram).
4) Run the application or applet or JUnit test cases. This will create 'maintainj/META-INF/aop.xml' file in your main project's root folder. If you would like to manually edit aop.xml and do not want the wizard to overwrite your changes, select 'Do not regenerate aop.xml' checkbox.
5 a) For JUnit test cases, this will also create 'maintainj\JUnitTraceFiles' folder under which the trace files will be written for each test case. This is the last step if you are using MaintainJ with JUnit test cases.
5 b) For J2SE applications and applets, a Swing window will open along with your application/applet. Enter a file name with full path and without extension and click 'Stop Tracing' to log the call trace up to the point of starting the application. The generated trace file names, locations and number of calls in each file will be displayed. One trace file for each active thread will be generated. The thread name is appended to the given trace file name. Trace files have the extension 'ser'.

6) Once 'Stop Tracing' is clicked, the button is reset to 'Start Tracing' as above. Before performing an action for which a trace file is needed, click 'Start Tracing', perform the action and click 'Stop Tracing' to generate a new trace file.
7) Copy the trace files to any folder in your Eclipse workspace and open to view the UML diagrams.

5.3 Eclipse Plug-ins and Java Applications run from command prompt

Demo Videos - MaintainJ for Eclipse Plug-ins   MaintainJ for Applications run from command prompt

MaintainJ Aspect Wizard supports instrumenting any Java applications run from the command prompt (instead of running from Eclipse). The following steps explain how this wizard is used.

1) Start the MaintainJ Aspect Wizard using 'java -jar MaintainJSwingWizard.jar' .
2 Select Application Type as either Eclipse Plug-in or J2SE Application. Select a folder to copy the MaintainJ related files. In case of plug-ins, provide the plug-in activator class name. This is the class that extends AbstractUIPlugin (for GUI plug-ins) or Plugin (for non-GUI plug-ins). In case of Java applications, provide the absolute name of the main class (the class with public static void main(String[]) method).

3) Choose the package(s) in the plug-in (or application) that you want to instrument. Limit the instrumentation scope to your plug-in (or application) classes. You may exclude some package(s) from instrumentation scope.

4) The wizard copies MaintainJ jar files, META-INF/aop.xml (the aspect) and eclipseShortcut.bat(start_with_maintainj.bat for Java applications) to the installation folder. In eclipseShortcut.bat, replace <<ECLIPSE_ROOT>> with Eclipse root folder and <<JAVA_HOME>> with Java home folder. The Java version should be 1.5 or above for Eclipse plug-ins. Start Eclipse with eclipseShortcut.bat. For Java applications, change start_with_maintainj.bat to set application classpath.
5) When the plug-in or application, whose classes are instrumented, is started, a 'MaintainJ - Start and Stop Tracing' Swing window pops up. This is the same window as shown in the last section. Enter a file name with full path and without extension and click 'Stop Tracing' to log the call trace up to the point of starting the plug-in. One or more trace files with the given file name with thread name appended (Ex: EclipseShapeDropped_main.ser) are generated. One trace file for each active thread is generated.
6) Once 'Stop Tracing' is clicked, the button is reset to 'Start Tracing'. Before performing an action for which a trace file is needed, click 'Start Tracing', perform the action and click 'Stop Tracing' to generate a new trace file.

5.4 How does instrumentation work?

1. Prepare the aspect.

The aspect should be in aop.xml file. Below is a sample file.

<aspectj>
 <aspects>
   <concrete-aspect name="com.maintainj.inst.J2EEAspect" extends="com.maintainj.aspect.ExecutionAspect">
     <pointcut name="anyExecution" expression="execution(* *.*(..)) || execution(*.new(..))"/>
   </concrete-aspect>
 </aspects>
  <weaver options="-proceedOnError -showWeaveInfo -verbose ">
   <include within="com.test..*"/>
  </weaver>
</aspectj>

The only line that needs to be changed is the one within 'weaver options' section in blue. Replace 'com.test' package with a package in your application. Only the classes under the included packages and their sub-packages will be instrumented. Only instrumented classes will be shown in diagrams. You may include as many packages as you want. If you want to include a class, simply replace 'com.test..*' with the class name. You can also exclude some classes or packages similarly. Use 'exclude' keyword to exclude classes or packages from instrumentation scope.

2. Update you application classpath.

In case of J2EE applications, update the server classpath so that it will apply to all applications running on the server. For J2SE, JUnit or Applets, just put them under application classpath. All the jar files mentioned below can be found in eclipse/plugins/com.maintainj.launcher.core_x.x.x folder for J2SE applications and in MaintainJ.war for J2EE applications. The files to be put in classpath vary for Jdk 1.4 and for Jdk 1.5 and above.

For JDK 1.5 or above, these three files need to be in classpath. The aop.xml created in last step needs to be under META-INF folder and that folder needs to be in classpath. If aop.xml is at c:\maintainj\META-INF\aop.xml,  c:\maintainj needs to be in classpath.

MaintainJAspect.jar, aspectweaver.jar, META-INF/aop.xml

For Jdk 1.4, the following files need to be put in classpath.

aspectjweaver.jar, MaintainJAspect.jar, AjPreProcessor.jar, aspectwerkz-core-2.0.jar, awaj-boot.jar (for J2SE and all non-WebSphere servers), java14Adapter.jar (for WebSphere only1)

3. Update JVM arguments

This setting also is different for Jdk1.4 and for Jdk1.5 or later Jdk versions.

For JDK 1.5 or above,
-javaagent:<<PathTo>>\aspectjweaver.jar

For JDK 1.4,
"-Daj5.def=<<PathTo>>\META-INF\aop.xml" "-Xbootclasspath/p:<<PathTo>>\awaj-boot.jar" "-Xbootclasspath/a:<<PathTo>>\aspectwerkz-core-2.0.jar;<<PathTo>>\AjPreProcessor.jar;<<PathTo>>\aspectjweaver.jar;" -Daspectwerkz.classloader.preprocessor=org.aspectj.ext.ltw13.ClassPreProcessorAdapter

4. Generate trace file

The challenge here is to find a way to turn on and turn off tracing. In the wizards that come with MaintainJ, this is done using a Swing window for J2SE applications. For J2EE applications, this is done using a JSP. But you are free to devise your own method.

a) To turn on tracing, call the following method. JoinPointMap class is present in MaintainJAspect.jar.

JoinPointMap.setAddJoinPoint(true);

b) To write the call trace to a file and turn off tracing use the following statements.

JoinPointMap.setAddJoinPoint(false);
String[][] serFiles = JoinPointMap.writeToFile("c:\\TraceFile");
JoinPointMap.clear();

The first line needs some explanation. The call returns an String[][] where String[][0] is the ser file name and String[][1] is the number of calls in that trace file. The trace file name is given without any extension. The extension .ser is automatically added to the file name. One trace file for each thread in the use case is generated. One trace file with all the calls in all threads also is generated with name _AllThreads.ser appended to the given file name.