MaintainJ V3.3 User Guide

Table of Contents 1. MaintainJ Introduction.............................................................................................................................. 3

1.1. Instrument Code ................................................................................................................................ 3

1.2. Generate Trace Files .......................................................................................................................... 4

1.3. View the Diagrams ............................................................................................................................. 4

2. Why should I use MaintainJ? .................................................................................................................... 5

2.1 Why should managers be interested? ................................................................................................ 5

2.2 Why should developers be interested? .............................................................................................. 5

3. MaintainJ Quick Start ................................................................................................................................ 7

3.1 MaintainJ Eclipse Plug-ins Installation ................................................................................................ 7

3.1.1. MaintainJ Update URL's .............................................................................................................. 7

3.1.2. MaintainJ Plug-in Zip Files........................................................................................................... 7

3.1.3. Verify Installation ........................................................................................................................ 8

3.1.4. Download Evaluation License ..................................................................................................... 8

3.2 MaintainJ.war - To generate call trace files for Web Applications ..................................................... 8

3.3 MaintainJ Aspect Wizard .................................................................................................................... 8

4. MaintainJ UML Diagram Editor ................................................................................................................. 9

4.1 Sequence Diagram Features ............................................................................................................... 9

4.2 Class Diagram Features ..................................................................................................................... 10

4.3 Common Features in both Class and Sequence Diagrams ................................................................ 10

4.4 To Perform Impact Analysis .............................................................................................................. 11

5. Generating Call Trace Files ...................................................................................................................... 14

5.1 Generating call trace for J2EE Applications ...................................................................................... 14

5.2 Generating call trace for J2SE (Swing or non-GUI), Applet and JUnit Applications .......................... 14

5.3 Generating call trace for Java Applications run from command prompt ......................................... 16

5.4 Generating call trace files on multiple JVMs and merging the trace files ........................................ 19

5.5 Generating call trace files without a MaintainJ wizard ..................................................................... 21

6. Frequently Asked Questions ................................................................................................................... 23

1. MaintainJ Introduction

MaintainJ reduces the time needed to understand complex enterprise Java applications from

days to minutes. It also helps to document the application's runtime behaviour using

sequence and class diagrams.

MaintainJ generates runtime sequence diagrams using the call trace captured for a single

use case while you run the application. The captured information includes data at each

method call, any sql calls to the database and the response time of each call. You can trace

applications running on a single JVM or on multiple JVM's and view the end-to-end call trace

in a single sequence diagram.

You may want to check the sample screenshots of the generated sequence and class

diagrams.

The following are the three steps to generate the diagrams:

1.1. Instrument Code

This step changes class files at runtime. No changes are done to the source files nor are any

changes persisted to the file system. You can choose the packages to be instrumented.

Instrumented applications are slow to service the first request but perform with little

overhead later.

Below are the types of Java applications supported out of the box by MaintainJ. In fact, any

non-J2ME Java applications can use MaintainJ by following these steps. The JRE versions

currently supported are 1.4, 1.5 and 1.6.

a) J2SE applications/Applets/JUnit - Tracing J2SE applications (Swing or non-GUI),

Applets and JUnit is supported.

b) J2EE applications - The following J2EE application server are supported - Tomcat 4, 5,

6 & 7, JBoss 3, 4 & 5, WebLogic 8, 9 & 10, WebSphere 5, 6 & 7. Glassfish and Jetty servers

are also supported. If your server is not supported, follow these steps to generate the trace

files. We would add support to your server on request.

c) Databases - MaintainJ captures the actual runtime sql calls sent to the database

regardless of the JDBC frameworks used by the application. MaintainJ supports Oracle, DB2,

MySQL, PostgreSQL and Derby out of the box. Microsoft SQL Server also is supported.

Contact support if you are using MS SQL Server or any other databases.

1.2. Generate Trace Files

Next, run the instrumented application and demarcate the start and end points of a use

case. Call trace for the use case will be logged to the given trace file (.ser file).

a) J2EE Applications - A JSP is provided to demarcate the start and end points. You need to

click a 'Start Tracing' button before a use case starts and click 'Stop Tracing' at the end of

the use case. The call trace will be logged to the given file when 'Stop Tracing' is clicked.

b) J2SE/Applet/JUnit - A Swing window in which you can start and stop tracing opens when

your instrumented application starts. Click 'Start Tracing' button before a use case starts

and 'Stop Tracing' at the end of the use case. The call trace will be logged to the given file

when 'Stop Tracing' is clicked.

1.3. View the Diagrams

Create a MaintainJ Trace Files Project by following File->New->Project->MaintainJ-

>MaintainJ Trace Files Project. Copy the trace files to this project and open to view the

diagrams in MaintainJ UML Editor.

2. Why should I use MaintainJ?

Costs of software maintenance are well documented. This compilation puts maintenance

cost at more than 90% of total software cost. The same paper puts the cost of

understanding the code at 50% of maintenance cost.

Currently there are no good tools to understand enterprise scale Java applications. Most of

the reverse engineering tools generate the class diagrams, a static time view of the system.

But when a developer is changing code, he/she is more interested in knowing how classes

interact at runtime for a single use case. MaintainJ generates runtime sequence and class

diagrams for a single use case.

2.1 Why should managers be interested?

Change is constant and everywhere - business changes, development teams change,

enhancements and bug fixes involve changes, interfacing with new applications need

changes, etc.

Change involves risk. Understanding reduces risk. MaintainJ significantly reduces the effort

spent in understanding large Java applications.

Typically, developers depend on debuggers to analyze runtime interactions. Debuggers

definitely help but diagrams are better for the same reason that managers prefer graphs to

numbers.

Most of the currently available reverse engineering tools generate class diagrams and a

static sequence diagrams. Generally, the class diagrams generated are not for a single use

case. They are more for the entire system and are too cluttered to understand. Static

sequence diagrams are generated from code and show the possible call flows starting from

a method. This helps to understand the code structure to certain extent but do not help to

understand the runtime behavior.

MaintainJ generates runtime diagrams for a use case and that is what developers crave for

while debugging a complex Java application.

In agile development environments, MaintainJ can also be used to generate always up-to-

date UML documentation from code.

MaintainJ is based on open source Eclipse project and works on any IDE that is built on

Eclipse platform.

2.2 Why should developers be interested?

Any developer who has ever tried to change a large Java application should not need much

persuasion. For the remaining few, here are a few reasons:

Dynamic Binding - Dynamic or runtime binding in Java makes understanding code more

difficult. Developers often need to understand the runtime object interactions for a specific

use case either to debug or enhance the application. Dynamic binding helps in building very

flexible systems but, at the same time it increases the time to understand the system. It is

also common to employ multiple levels of dynamic binding, like a Vector containing another

Vector, which further complicates the issue.

Observer Pattern - Many enterprise applications follow Observer Pattern for flexibility,

where 'listener' (or observer) objects change model state besides 'listening' (or observing)

for the state changes. When many such listener objects, which are often determined at

runtime, change the model, it becomes hard to understand and debug a large application.

Multi-threaded Applications - Multi-threaded applications are always difficult to code and

debug. Using MaintainJ, one can see the sequence of method calls happening in each thread

in a neat sequence diagram. This makes debugging multi-threaded applications much

easier.

Externalized Data and Rules - Externalizing configuration data as well as rule based logic

to XML files is very commonly found in the present day Java applications. Very often, the

logic to determine the runtime classes is soft-coded in xml files. In a not so well

documented large-scale system, it is very hard to understand how the xml file drive the

system.

Poor Design - Designing robust and flexible systems at the same time is hard. Maintaining

them as the systems evolve is harder. If poor design slips into this equation, it becomes

very hard to understand a system after 2-3 years from initial launch.

Here are some other scenarios where MaintainJ helps developers.

Complements Debugger - MaintainJ complements debugger rather than replacing it. By

generating the class and sequence diagrams for a use case, it reduces the time spent in

debugger. Unlike other reverse engineering tools, MaintainJ offers uncluttered and focused

UML diagrams. For sequence diagrams, which get cluttered very easily, MaintainJ offers

features like call folding to generate crisp diagrams.

During Code reviews - MaintainJ can also be used during code reviews. Rather than

reviewing the entire source code, one can review the diagrams to find deviations from the

design standards. Class diagrams showing the dependencies help to weed out unwanted

dependencies.

For Agile Teams - For agile programming teams, MaintainJ provides always up-to-date

documentation of the system. Useful UML diagrams can be generated whenever one needs

them.

3. MaintainJ Quick Start

We strongly suggest you to watch this demo video first to understand MaintainJ's

potential.

For detailed installation instructions, check the following sections. To get started quickly,

use the MaintainJ Quick Start wizard, which will present the download links and installation

steps relevant to your application.

3.1 MaintainJ Eclipse Plug-ins Installation

MaintainJ has two Eclipse features:

a) MaintainJ Feature (always required)

b) MaintainJ J2EE Server Feature (required only for Tomcat and JBoss applications).

MaintainJ requires Eclipse 3.2 or newer versions. The following sections help you to install

the plug-ins.

3.1.1. MaintainJ Update URL's

MaintainJ Feature: http://www.maintainj.com/updates/3.3.0

MaintainJ J2EE Server Feature: http://www.maintainj.com/updates/3.3.0/server

Follow these steps to install using the update URL's:

In Eclipse, click 'Help-->Install New Software'.

Click 'Add' and in the dialog box opened, enter one of the URL's above.

Select the just added site in the 'Available Software Sites' dropdown list and follow

the wizard steps.

3.1.2. MaintainJ Plug-in Zip Files

We strongly recommend you to use the Update URL's to install, but if you cannot for any

reason, you may install using the following zip files.

MaintainJ Feature: MaintainJ_3.3.0.zip

MaintainJ J2EE Server Feature: MaintainJ_J2EE_Launcher_3.3.0.zip

Unzip the zip files to <EclipseRoot>>/eclipse/plugins folder and restart Eclipse.

GEF (Graphical Editing Framework) plug-in is required for MaintainJ. Install it if you do not

already have it installed. Ensure that you install the GEF version that works with your

Eclipse version.

3.1.3. Verify Installation

MaintainJ UML Diagram Editor: Download the sample trace file (for Alfresco login use case)

and copy it to a MaintainJ Trace Files Project (which can be created by following File->New-

>Project->MaintainJ->MaintainJ Trace Files Project). When you open the trace file,

sequence and class diagrams should show.

MaintainJ Run Configurations : Click 'Run-->Run Configurations' in Eclipse to open the run

configurations dialog. On the left hand side, you should see Java Application with MaintainJ

MaintainJ Wizards: Click 'File-->New-->Other' in Eclipse. In the 'New' wizard, you should

see MaintainJ folder.

Tomcat/JBoss Server Configurations: Open 'Servers' view in Eclipse and create a new

Server (right click,New->Server). Under Apache and JBoss, you should see 'Tomcat with

MaintainJ' and 'JBoss with MaintainJ'.

3.1.4. Download Evaluation License

Register to download the evaluation license.

3.2 MaintainJ.war - To generate call trace files for Web Applications

MaintainJ.war web application is the wizard to install and configure MaintainJ on application

servers. Deploy MaintainJ.war directly to the application server or from an Eclipse based IDE

(after importing the war as a project). Open http://server/MaintainJ/index.jsp and follow

the instructions.

Check the demo video.

3.3 MaintainJ Aspect Wizard

MaintainJSwingWizard.jar - Start as 'java -jar MaintainJSwingWizard.jar'

Use this wizard for core Java applications launched from outside Eclipse. Check the demo

video. If you are launching your application from inside Eclipse, use MaintainJ

Launcher plug-in.

4. MaintainJ UML Diagram Editor

MaintainJ UML Diagram Editor renders sequence and class diagrams from the call trace files.

To view the UML diagrams, add the trace files to a MaintainJ Trace Files Project in Eclipse

and open. MaintainJ Trace Files Project can be created by by following File->New->Project-

>MaintainJ->MaintainJ Trace Files Project.

All menu options in MaintainJ UML Diagram Editor are provided in context menus, which can

be seen by right clicking anywhere in the diagram or the Eclipse Outline View. Depending on

the selected figure, relevant options are displayed in the context menu. You can 'Undo' and

'Redo' most of the operations in the editor.

4.1 Sequence Diagram Features

Color Coded Calls: Calls are color coded. Public calls are shown in green, private

calls are shown in red and protected calls are shown in yellow.

Collapse/Expand Calls: icon beside a call name indicates a collapsed

call. icon beside a call name indicates an expanded call. All calls are collapsed

initially to present an easy to read diagram. You can expand and collapse the calls as

you explore the diagram. Click on to expand a call and on to collapse a call.

Collapse All Calls: Collapses all calls in the diagram.

Expand All Calls: Expands all calls in the diagram. For trace files with thousands of

calls, expanding all calls will make editing the diagram slow. You should either

explore the diagram by expanding calls of interest or browse the diagram using the

Outline view.

Delete getter/setter calls: Often the simple get() and set() methods clutter the

diagram. You can delete all of them in one go using this action.

Keyboard Navigation: Sequence diagram can be navigated using keyboard keys.

Up and Down arrow keys move focus to previous and next method calls. Left arrow

collapses an expanded call and right arrow expands a collapsed call. Delete button

deletes a call.

Show Activations: Clicking this option draws an activation box for the duration a

method is active.

Show Thread Information: MaintainJ generates one trace file for each active

thread while tracing is turned on. These trace files can be merged using Merge Trace

Files wizard (at File->New->Other->MaintainJ->Merge Trace Files) to view them in a

single sequence diagram. Clicking 'Show Thread Information' displays each thread in

a different color. The thread name is also displayed before the method name. You

can also merge trace files generated in different JVMs for a single use case and see

different threads in different colors.

Call Response Time: Sequence diagram shows the response time for each call in

milliseconds. You can see the response time either in the tooltip by hovering the

mouse over a call or in the Eclipse Properties View after selecting a call.

No Loop Calls: If same call repeats to the same class from a method (typically in a

loop), only the first call is shown to avoid clutter.

No Recursive Calls: Recursive calls are not shown to avoid clutter.

No Immediate Return Calls: Immediate return calls are deleted to avoid diagram

clutter.

4.2 Class Diagram Features

The class diagram is a class dependency diagram that shows the dependencies between the

classes involved based on the call sequence.

Show Class Hierarchy: To view the hierarchy of a class, select a class, right click

and choose 'Show Class Hierarchy'. For this feature to work, the hierarchy classes

should be available in workspace when the diagram was opened.

Classes can be resized and rearranged: Classes can be resized if a long class

name is not fully displayed in the box. Classes can be rearranged to make the

diagram more readable. Class relations can be bent by selecting a relation and

dragging the centre point.

Shows class fields and methods in tool tip: When you hover the mouse over a

class, the class fields and methods are shown in the tool tip. For this feature to work,

the class file should be present in the workspace either as a source file or .class file.

4.3 Common Features in both Class and Sequence Diagrams

The following features are available to both class and sequence diagrams.

Both diagrams are in sync: The class diagram always shows the classes currently

shown in the sequence diagram. If a class is deleted from sequence diagram, the

same class is deleted from class diagram and vice versa.

Runtime Classes: All classes shown in the diagram are concrete runtime classes.

No abstract base classes or interfaces are shown.

Save and Save As: Trace files are initially saved as *.ser files. These files hold the

original call trace of the use case. The changes done to the diagram generated from

a *.ser file cannot be saved back to the *.ser file. The changes have to be saved to a

*.mnj file, which can also be opened in MaintainJ editor. Choose 'File-->Save As' to

save the diagram to a file with extension *.mnj. You can change the diagram

generated from *.mnj file and save the changes back to the same file.

Delete: Calls and classes can be deleted with Delete key or 'Delete' option in the

context menu. When a collapsed call is deleted, all hidden enclosed calls are deleted

too. When an expanded call is deleted, only that call is deleted. When a class is

deleted, all calls to that class and calls going out from that class are deleted. You

might want to delete classes that do not make any further calls (like Value Objects

with only get/set methods). You might also delete classes that you want to ignore for

now, though they make further calls. You can 'Undo' all the delete operations.

Outline View: Eclipse 'Outline View' lists all undeleted classes and calls whether

they are shown or hidden in the diagram. You can right click a class/call and choose

'Select In Diagram' to select the corresponding figure. If the corresponding figure is

not currently displayed, the sequence diagram will expanded minimally to open the

breadcrumb trail of the selected call or class. Outline View serves two important

purposes. i) For a large diagram, it gives an overview of all packages, classes and

calls in the diagram without expanding all calls. ii) It helps to filter out unwanted

packages/classes/calls without expanding all calls. You can select all unwanted

packages/classes/calls and delete them in one go.

Exclude Class: This feature allows you to delete a class without deleting the calls

this class is making on other classes (Deleting a class deletes all calls from and to

that class). Assume you have 3 classes - MyServlet, SessionFacade and MyDAO.

Typically, in a J2EE application all calls to the DAO's are routed through a facade

class (MyServlet calls SessionFacade calls MyDAO). If you exclude the SessionFacade

class from the diagram, this is what happens:

a) SessionFacade class is deleted from the diagram

b) the calls from SessionFacade to MyDAO are rearranged as MyServlet calling

MyDAO directly.

This is same as what happens when a class is excluded from instrumentation scope

in aop.xml. This feature is useful when you want to capture all calls in the trace file,

but would like to exclude some class(es) or package(s) from the diagram. From the

Outline View, you can select class(es) or package(s) and exclude all of them in one

go.

Tooltips: Tooltips for a class show the complete class name. Tooltips for a method

call show the values of parameters and return value if call context data was

captured. Method call tooltips always show the response time of the call and where

this method is declared. If a method is defined in the superclass and is called on the

subclass instance, the tooltip shows the superclass name.

Print: 'Print' option prints the active diagram.

Export As JPG/BMP Image: This option is used to export the diagram as a jpg or

bmp image. Large images take lot of system resources and cannot be exported. Use

the filtering features to delete unimportant classes and calls. Try to reduce the

diagram to about 400 calls before exporting as a diagram. BMP images take greater

resources than a jpg image.

Double click to open source file: Double clicking a call opens the source file where

this call is defined. All Java projects in workspace are searched for the source file and

the file is opened with the corresponding line is selected. Double clicking a Class

figure opens the class file.

4.4 To Perform Impact Analysis

After changing the application to fix a defect or to add a new feature, you may want to find

all the existing use cases impacted by the change. It is necessary to find the impacted use

cases, so that proper regression testing can be conducted before the new code is put into

production. Static time source code searching does not enable us to determine the use

cases that depend on a class or database table.

The 'MaintainJ Search' feature allows you find out all the use cases that depend on a Java

class or method or on a database table or field.

Click the menu option 'Search' (Control+H) in Eclipse. In the search dialog box opened, you

will notice a 'MaintainJ Search' tab, where you can search for a trace file or class or a

method across multiple trace file projects. This gets even better by allowing you to search

for a particular method parameter value. Let us explain these powerful capabilities using

two concrete examples.

1. Java class or method search: Consider the simple code snippet below, a very common

pattern used in Java applications.

interface DataSource{

String loadData();

}

class FileDataSource implements DataSource{

String loadData(){

//Read from file and return the data

}

}

class NetworkDataSource implements DataSource{

String loadData(){

//Read from network and return the data

}

}

class DataLoader{

private DataSource dataSource;

DataLoader(DataSource ds){

dataSource=ds;

}

String loadData(){

return dataSource.loadData();

}

}

By analyzing the source code above, it is impossible to tell whether DataLoader uses

FileDataSource or NetworkDataSource at runtime when a use case is executed. Using the

static time source code analysis tools, it is impossible to precisely tell if a use case depends

on FileDataSource or NetworkDataSource.

Because MaintainJ captures the classes, method calls and their parameters as the use cases

are executed, it can precisely identify whether a use case calls FileDataSource or

NetworkDataSource.

Once the trace files are captured for all use cases in the application, you simply need to

search for FileDataSource to find out all the use cases that depend on it. Armed with this

information, you can conduct focused and comprehensive regression testing and put the

code back into production with more confidence.

2. SQL Search: Most Java applications use databases. Consider that we need to identify all

the test cases impacted by a change to a table structure. This is not an easy task in an

enterprise setting where many applications depend on the same database. There are many

database frameworks for Java and each of them embeds the SQL differently in XML or

source code or both. For code analysis tools, it is difficult to map a Java class to a SQL

statement and impossible to map a use case to a set of tables used.

Because MaintainJ captures all the runtime SQL statements sent to database when a use

case is executed, it can precisely identify the use cases that depend on a database table(s)

or field(s).

To find all the use cases that use a table, use the following search criteria in the 'MaintainJ

Search' tab:

Class name: '*Statement' (searches both Statement and PreparedStatement)

Method name: 'execute*'

Method parameter name: 'sqlStatment'

Method parameter value: <<Table name or field name as referred to in the SQL>>

The search results show all the use cases that depend on the table/field and show the SQL

statements using those tables/fields.

A Powerful Feature

This is a very powerful feature that no available static time dependency analysis tools can

offer. However, take note of the assumption and current limitations of the feature:

The assumption is that you have already captured the trace files for all use cases of the

application. If this is a considerable effort during a release cycle, it can be started on more

important modules of the application and expanded to other modules later.

The limitations are:

a) Assume that class ConcreteUser extends AbstractUser. If you change AbstractUser, there

is a chance that use cases depending on ConcreteUser will be impacted though you did not

change ConcreteUser. In the current release users will have to use their discretion when

analyzing the impact of changes to classes in a class hierarchy.

b) Only the impact of changes to Java classes, JSP's and database resources can be

identified currently. Impact of changes to HTML, CSS or Javascript cannot be predicted.

5. Generating Call Trace Files

Java applications run in different runtime configurations like Applets, Swing/SWT based GUI

applications, non-GUI applications (batch/socket server apps, etc), J2EE server applications

etc. MaintainJ supports many of these configurations out of the box with the help of

wizards. Check the Introduction page for the supported configurations and related demo

videos. The following sections explain generating the call trace files using these wizards and

even without using the wizards.

5.1 Generating call trace for J2EE Applications

5.2 Generating call trace for J2SE (Swing or non-GUI), Applets and JUnit

5.3 Generating call trace for Java Applications run from command prompt

5.4 Generating call trace files on Multiple JVMs and merging the trace files

5.5 Generating call trace files without a MaintainJ wizard

5.1 Generating call trace for 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 to the same server instance where you are running your application.

Open http://server/MaintainJ/index.jsp for installation and configuration page and follow the

instructions. Check the Demo Video.

5.2 Generating call trace for J2SE (Swing or non-GUI), Applet and JUnit Applications

Demo Videos - MaintainJ for Swing, Applet, JUnit

Use this if you are currently running your application in Eclipse using Java Application / Java

Applet / JUnit run configurations.

1) Click Run-->Run Configurations in Eclipse to open the run 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 run configurations

are the same as normal configurations except for the MaintainJ 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 MaintainJ tab, choose the packages that you want to capture.

Choose only the packages of interest and avoid very high level packages. If you want to

capture the values of parameters and return value for each call, select 'Capture method call

context data'. You can also capture the actual runtime sql statements your application is

sending to the database server by selecting 'Capture SQL' and then choosing your database.

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 a MaintainJ Trace Files Project in Eclipse and open to view the UML

diagrams. MaintainJ Trace Files Project can be created by by following File->New->Project-

>MaintainJ->MaintainJ Trace Files Project.

5.3 Generating call trace for Java Applications run from command prompt

Demo Videos - MaintainJ for Applications run from command prompt

This Swing based Wizard supports generating trace files for any Java application that is run

from the command prompt (instead of running from Eclipse). The following steps explain

how this wizard is used.

1) Download MaintainJSwingWizard.jar and start the Wizard using 'java -jar

MaintainJSwingWizard.jar'

2) Select Application Type as J2SE Application. Select a folder to copy the MaintainJ related

files. Provide the absolute name of the main class (the class with public static void

main(String[]) method).

3) Choose the package(s) in the application or plug-in. Limit the instrumentation scope to

your application or plug-in classes. You may also exclude the package(s) that are not of

interest. The other options are same as explained above in section 5.2

4) The wizard copies MaintainJ jar files, META-INF/aop.xml (the aspect) and

start_with_maintainj.bat to the installation folder. Edit start_with_maintainj.bat to set

application classpath.

5) When the Java application, 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 Generating call trace files on multiple JVMs and merging the trace files

MaintainJ supports tracing applications running on multiple JVMs simultaneously and

merging the trace files for an end-to-end call flow. For example, consider a scenario where a

J2EE application calls a web service running on a different J2EE server. You may be

interested in seeing the end-to-end call flow of a request going from the J2EE application to

the web service and coming back. You can do this by following the steps below. This feature

is supported only for JRE 1.5 and above.

1) Start MaintainJ Node Manager window using

'java -classpath <pathTo>/MaintainJAspect.jar

com.maintainj.swing.NodeManagerWindow' . You will find MaintainJAspect.jar under

eclipse\plugins\com.maintainj.launcher.core_x.x.x. A Swing window similar to the

screenshot below opens. Do not do anything yet in this window.

2) While starting the applications with MaintainJ, select the option to trace multiple JVMs

and provide a port number to start the MaintainJ Node Agent. You will see this option on all

MaintainJ wizards. In the Eclipse run configuration MaintainJ tab, select 'Capturing call trace

on multiple Java VMs'. Select the same option if you are using MaintainJSwingWizard

explained in section 5.3. If you are tracing a J2EE application using MaintainJ.war, you will

see the same option in 'Step 5: Capture call trace'.

3) You may trace any combination of Java applications running on different JVMs - multiple

J2EE applications or a socket server application and a J2EE application, etc. Once all the

applications are started with MaintainJ, go back to the MaintainJ Node Manager window

opened in step 1.

4) Enter the IP addresses of the machines where you are running your applications and the

port numbers you gave in step 2. Click 'Test Connection'. Make sure that the status changes

to 'Tested'.

5) Click 'Synchronize Nodes' button.

6) Enter the name of the scenario. This will be used to as an identifier for the generated

trace files.

7) Click 'Start Tracing' when you are ready to trace.

8) Run the scenario in your application and click 'Stop Tracing'.

9) You will see the list of generated trace files. Click 'Download trace files from all nodes' if

you want to copy all the trace files to a local folder.

10) You can merge these trace files using Merge Trace Files wizard (at File->New->Other-

>MaintainJ->Merge Trace Files) to view them in a single sequence diagram.

5.5 Generating call trace files without a MaintainJ wizard

If the wizards that come with MaintainJ do not work for your application, you can still

generate the trace files using the procedure below.

There are 4 steps to instrument your application and generate the trace files. The first three

steps will instrument the application. The last step will set the start and end points of the

use case and will write the call trace to a file.

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 must 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 captured in the 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

using the 'exclude' keyword.

The above aop.xml file does not capture method call context data, JSP's and the SQL

statements. If you want to add those options, either contact MaintainJ customer support or

use one of the wizards to first generate the aop.xml and then edit it as necessary.

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 instructions here apply for applications running using JRE 1.5 or above. If you are using

JRE 1.4, please contact MaintainJ customer support or use one of the wizards on a sample

application to check the jar files added to classpath.

The aop.xml created in last step needs to be under META-INF folder and that folder needs to

be in classpath. Assuming that the location of aop.xml is c:\maintainj\META-INF\aop.xml,

below are the jar files and the folder that is added to the classpath for applications using

JRE 1.5 or above.

MaintainJAspect.jar;aspectweaver.jar;c:\maintainj

3. Update JVM arguments

Again, the instructions below are for JRE 1.5 or above.

-javaagent:<<PathTo>>\aspectjweaver.jar

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 input to JoinPointMap.writeToFile() is the trace file name, which is given without any

extension. This method returns a String[][] where String[][0] is the generated trace file

name and String[][1] is the number of calls in that trace file. The extension .ser is

automatically added to the file name. One trace file for each thread in the use case is

generated.

6. Frequently Asked Questions

1. Do I need Eclipse to use MaintainJ?

2. How does MaintainJ scale?

3. I get a ClassNotfoundException for com.maintainj.inst.J2EEAspect. Where is that class?

4. Trace file is not generated

5. Where is the aop.xml file (the trace configuration file)? How can I edit it?

6. I do not see the UML diagrams when I open the trace file

7. My diagrams are too big and cluttered. How can I filter out the unnecessary classes and

calls?

8. I get java.lang.OutOfMemoryError:PermGen space

9. Can I import the diagrams into Rational Rose?

10. How can I use MaintainJ for documentation and share the MaintainJ diagrams with

others?

11. What are the license terms?

1. Do I need Eclipse to use MaintainJ?

MaintainJ needs Eclipse to view the diagrams. As Eclipse and GEF (API used to render the

diagrams) are open source projects, you can use them for free.

You don't need Eclipse to generate the trace files. While some wizards are provided in

Eclipse to generate the trace files, one can do the same outside Eclipse.

For example, MaintainJ.war can be used outside Eclipse to generate the trace files for J2EE

applications. You can also follow these steps to manually generate the trace files.

2. How does MaintainJ scale?

MaintainJ scales very well for large scale applications. Large applications can potentially

slow down MaintainJ at two stages : a) during instrumentation and b) during diagram

rendering.

Instrumented applications take longer time to service the first request. Just like JSPs that

get compiled at the first request, the classes get runtime instrumented at the first request.

For subsequent requests, there is little overhead. Capturing call context also adds some

overhead.

Rendering the diagram is typically very quick and does not take much memory. As loop calls

and return calls are not logged to the trace files, number of calls to render is kept low. That

said, users should limit the trace file to a single user action to make the diagrams focused

and easier to understand. Also, avoid using 'Expand All' to expand all calls in the diagram as

a large diagram of 5,000+ calls will make navigating the diagram slow. You should either

explore the diagram or use the 'Select In Diagram' feature in Outline view to open the call

trail to a particular call.

3.I get a ClassNotfoundException for com.maintainj.inst.J2EEAspect. Where is that

class?

com.maintainj.inst.J2EEAspect is not a class file. It is specified in META-INF/aop.xml. The

aop.xml file is generated in 'Step 2' of MaintainJ.war installation (or if the Tocat/JBoss

servers are started using MaintainJ J2EE Server plug-in, the file is generated when the

server is started). The J2EEAspect class is generated at runtime by AspectJ. For this to

work, the META-INF/aop.xml should be in application server classpath. For example, if the

path of aop.xml is c:\maintainj\META-INF\aop.xml, c:\maintainj should be added to the

classpath.

META-INF/aop.xml is automatically added to the server classpath in the MaintainJ generated

startup scripts. However, if you are seeing the ClassNotfoundException, there may be a

problem with your server classpath. Check the classpath setting with which your server was

started.

4. Trace file is not generated

The use case that you ran may not have called any of the instrumented classes. If this is

not the case, ensure that the instrumentation scope is properly defined.

5. Where is the aop.xml file (the trace configuration file)? How can I edit it?

The details like the Java packages that you want to capture, whether you want to capture

the call context, etc. are stored in aop.xml file. This is a special file used by AspectJ Load

Time Weaving mechanism that is used to capture the call trace. This file is always created

under META-INF folder and META-INF/aop.xml should be added to the JVM classpath. The

out of the box MaintainJ wizards create this file for you and add it to the JVM classpath.

5.1 Where is the aop.xml file located?

Different MaintainJ wizards place this file under different folders.

a) The J2SE, JUnit, Applet applications launched from Eclipse using the MaintainJ run

configurations create a 'maintainj' folder under the main project and place META-

INF/aop.xml under that folder.

b) The MaintainJ J2EE Server plugin for Tomcat and JBoss puts the file under

<TomcatRoot>/maintainj and <JBossRoot>/bin/maintainj folders respectively.

c) The MaintainJ.war shows the location of this file after Step 2: Configure Instrumentation

Scope.

d) The MaintainJSwingWizard.jar also shows the location of this file after the second step.

5.2 How can I edit the aop.xml file?

You may edit it manually to define more fine-grained configuration. Change the weaver

options section to include or exclude more packages. There can be any number of includes

or excludes. This sample below includes all classes and sub-packages

under org.jfree.chart and excludes sub-packages and classes

under org.jfree.chart.ui package. It also excludes org.jfree.chart.JFreeChart class. Note the

difference in syntax when excluding a class.

<weaver options="-proceedOnError -nowarn -XaddSerialVersionUID">

<include within="org.jfree.chart..*"/>

<exclude within="org.jfree.chart.ui..*"/>

<exclude within="org.jfree.chart.JFreeChart"/>

</weaver>

5.3 After editing the file make sure that it is not overwritten by the wizards

If you are using any of the Eclipse launch configurations, the aop.xml is regenerated every

time the application or server is launched. Select the 'Do not regenerate aop.xml' checkbox

at the bottom of the MaintainJ tab to not overwrite your changes. If you are using

MaintainJ.war or MaintainJSwingWizard.jar, the aop.xml is regenerated only if you repeat

Step 2 to configure the instrumentation scope.

6. I do not see the UML diagrams when I open the trace file

The MaintainJ UML Diagram Editor plug-in is not installed properly. If it is installed correctly,

you should see MaintainJ icon beside the trace file in Eclipse.

7. My diagrams are too big and cluttered. How can I filter out the unnecessary

classes and calls?

MaintainJ offers two options to get focused diagrams by removing the unimportant calls that

clutter the diagrams. The first option is not capturing unimportant calls while tracing the

application. The second option is to remove the unimportant calls from the diagram after

the diagram is rendered.

7.1 Do not capture the unimportant calls

MaintainJ has a number of options to follow this approach.

7.1.1 MaintainJ automatically removes all repeating calls in a loop except the first call. If a

method is called 100 times in a loop, only the first call is shown in the diagram. Recursive

calls are also removed in a similar manner.

7.1.2 You can limit the packages and projects that will be instrumented. As only the

instrumented classes and methods are logged to the trace file, this is another way to avoid

unwanted packages or projects from the diagrams.

7.1.3 You can also limit the scope of instrumentation at a finer level by editing the

generated META-INF/aop.xml file. Check the above faq entry 'Where is the aop.xml file (the

trace configuration file)? How can I edit it?' for details.

7.2 To remove unnecessary calls from the diagrams

Besides loop and recursive calls, there may be number of calls that just clutter the sequence

diagram and add little to our understanding. Often, it is hard to know such unnecessary

calls beforehand. MaintainJ UML Editor plug-in offers a number of options to remove them

from diagrams.

7.2.1 One can simply delete the unnecessary classes or packages (from Outline view). The

deleted class and all the calls to and from that class will be deleted.

7.2.2 There can be a method in a particular class that is called multiple times in the

sequence diagram but adds little to our understanding. To remove all repeating calls except

the selected call, select a call and choose Delete Duplicate Calls to this Method. This can be

used to remove all unnecessary get/set methods, repeating calls to boolean equals(Object

obj) method, etc.

7.2.3 You can use 'Delete getter/setter methods' in the sequence diagram to delete the

simple get/set method calls.

7.2.4 You can also use the Outline view to select and delete multiple packages, classes or

calls at once.

7.2.5 Excluding a class or classes is another great way to get focused diagrams.

7.3 Use 'Save As' feature to split the diagrams

When the trace file is opened, all calls are initially collapsed into a few top level calls. If you

delete a top level call, it will delete all the calls inside that call as well. Then, the 'Save As'

feature can be used to save the smaller diagram. This way a trace file of 5000 calls can be

split into two trace files of 2000 and 3000 calls, for example.

8. I get java.lang.OutOfMemoryError:PermGen space

MaintainJ changes the instrumented class files while they are loaded into the memory. If

you are instrumenting thousands of classes, the default memory size allocated for class

definition may not be sufficient. You need to add '-XX:MaxPermSize=256m' to the JVM

arguments to set the maximum memory available for class definition to 256MB. You may

search the web to find more about this error.

9. Can I import the diagrams into Rational Rose?

No, but we will support this feature in future. Having said that, consider the points below

that highlight the advantages of viewing the diagrams in MaintainJ itself than importing

them into Rose.

1. The Rose diagrams are static, which will make sense for a small sequence diagram of

about 20 calls. You can get the similar static diagram by filtering out unwanted calls from

MaintainJ generated diagrams and exporting the diagrams as images.

2. The diagrams can be explored in MaintainJ, which is not possible in Rose. You have the

end-to-end call trace (either on a single JVM or multiple JVMs) information of the use case

and you can explore the diagram for areas of interest.

3. Using MaintainJ, the thread interactions at runtime can be seen in a single diagram. You

will lose this information once you import the diagram into Rose.

4. Using MaintainJ you can see the response time, runtime context at each call and the sql

calls sent to the database, which is not be possible in Rose.

10. How can I use MaintainJ for documentation and share the MaintainJ diagrams

with others?

You can use MaintainJ for documenting and sharing the application knowledge with your

team members.

1. You can export the sequence and class diagrams as bmp or jpg images after filtering out

the unimportant calls in the diagram.

2. After filtering out the unimportant calls, you can save the original .ser files as .mnj files

and open them in the same exact state they were in when the diagrams were saved. To

share these files with others, you need to provide the original .ser trace file as well as the

.mnj files associated with the .ser file.

11. What are the license terms?

MaintainJ is a free to use software during the evaluation period. Once the evaluation period

ends, users need to buy the license to use MaintainJ. Read the complete License

Agreement.