6. Frequently Asked Questions

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.

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 are 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 would usually see this error when tracing web applications using MaintainJ.war. J2EEAspect is not a class file. The J2EEAspect class is generated at runtime by MaintainJ agent. It is specified in the generated maintainj.xml file. For this to work, the below JVM argument should be added to your application server before restarting the server. Verify that it is correctly added.
-Dorg.aspectj.weaver.loadtime.configuration=file:< PathTo >\maintainj.xml

This error happens when you have aspectjrt.jar or aspectjweaver.jar deployed in your application. MaintainJ agent already adds the classes in those jar files higher up in classpath. Please remove aspectjrt.jar and aspectjweaver.jar file(s) in your application and it would resolve this error. You only need to remove these jars from your application when you deploy your application with MaintainJ.

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.

The details like the Java packages that you want to capture, whether you want to capture the call context, etc. are stored in maintainj.xml for web applications and in aop.xml file for non-web applications. These are special files used by MaintainJ agent to capture the call trace. aop.xml is always created under META-INF folder and META-INF/aop.xml should be added to the JVM classpath. For web applications, the maintainj.xml is added as a JVM argument. The out of the box MaintainJ wizards create these files for you.

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 MaintainJSwingWizard.jar shows the location of this file after the second step.

5.2 Where is the maintainj.xml file located?
MaintainJ.war generates this file and places it in the folder selected by you.
5.3 How can I edit the aop.xml / maintainj.xml files?

You may edit both these files 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.4 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 MaintainJSwingWizard.jar, the aop.xml is regenerated only if you repeat Step 2 to configure the instrumentation scope.

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.
You may see this exception when opening the trace file generated using an older version of MaintainJ. Please ensure that you are using the same version of MaintainJ tools to generate and view the trace files.

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 before hand. MaintainJ UML Editor plug-in offers a number of options to remove them from diagrams.

7.2.1 Predefined Filters is the first thing you should check to filter out unwanted details from the diagrams.

7.2.2 You 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.3 Excluding a class or classes is another great way to get focused diagrams.

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

7.2.5 You can use 'Delete getter/setter Calls' in the sequence diagram to delete the simple get/set method calls.

7.2.6 You can use 'Delete Constructor Calls' in the sequence diagram to delete all constructor calls.

7.2.7 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 in the Outline view 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.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.

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.
Yes, you can starting from MaintainJ V3.5! MaintainJ generated diagrams can be exported as UML2 models. These models can be imported into any UML2 compliant tools like RSA to view the UML2 class and sequence diagrams.
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. You can also export the diagrams as UML2 models and import into UML2 compliant tools like RSA.
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 the mnj files with others, you need to provide the entire MaintainJ Trace Files project that contains the ser and mnj files.p

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.