Upload
others
View
17
Download
0
Embed Size (px)
Citation preview
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.