6. Frequently Asked Questions

1. Do I need Eclipse to use MaintainJ?

MaintainJ UML Editor 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 for instrumentation. Java code or jar files can be instrumented outside Eclipse too.

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. A client with 6000+ Java classes sees no 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. On an Intel Core 2 T5200 @ 1.6GHz and 1GB RAM PC, a 6000 call sequence diagram took less than 13 seconds to render.

3. I get a ClassNotfoundException for com.maintainj.inst.J2EEAspect but I don't find that class anywhere

com.maintainj.inst.J2EEAspect is not a class file. It is in META-INF/aop.xml file that 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). META-INF/aop.xml should be in application server classpath for AspectJ runtime instrumentation. It is automatically added to the server classpath in the MaintainJ generated start scripts. However, if you are seeing this message, there may be some problem with your server classpath. Check the classpath setting with which your server was started.

4. Trace file is not generated

There can be a few reasons for this.

a) If you are using the Swing 'Start and Stop Tracing' window and did not enter the absolute path for the trace file name, the trace file is put in your Eclipse project folder. Refresh your project to see the trace file. This only happens in versions prior to MaintainJ V2.8. Starting from V2.8, it forces you to enter the absolute path for trace file.
b) The use case that you ran may not have used any of the instrumented classes. If this is not the case, ensure that the instrumentation scope is properly defined.

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

<weaver options="-proceedOnError">
    <include within="org.jfree.chart..*"/>
    <exclude within="org.jfree.chart.ui..*"/>
    <exclude within="org.jfree.chart.JFreeChart"/>
</weaver>

6.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.

6.2.1 One can simply delete an unnecessary class. In sequence diagram this action deletes that class as well as all calls to and from that class. In class diagram that class gets deleted.

6.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 but the selected method call, select a call and choose Delete Duplicate Calls to this Method. This action removes all but the selected method call in the diagram. This can be used to remove all unnecessary get/set methods, repeating calls to boolean equals(Object obj) method, etc.

6.2.3 If the sequence diagram is big and too cluttered to understand, you can also delete all duplicate calls in the diagram by using 'Delete All Duplicate Calls' action. Right click anywhere in the diagram to see this option. This action leaves only one instance of each call in the diagram. This action should be used with discretion as this could cause some loss of useful information from the diagram.

6.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.

7. I get java.io.InvalidClassException when starting my application

The typical exception that you get is : java.io.InvalidClassException: package.className; local class incompatible: stream classdesc serialVersionUID = xx, local class serialVersionUID = yy. To fix this, please add -XaddSerialVersionUID to AspectJ weaver options in aop.xml. Check this blog for the location of aop.xml.

<weaver options="-proceedOnError -XaddSerialVersionUID ">
    <include within="test..*"/>   
    <exclude within="com.maintainj..*"/>
</weaver>

If you are using with MaintainJ run configuration, in the aspect tab, select 'Do Not Generate Aspect' checkbox. Selecting this checkbox will not regenerate aop.xml. If you don't select the checkbox, the changes you did to aop.xml will be overwritten.

If you are using MaintainJ.war or MaintainJ Swing Wizard, simply do not regenerate the aspect and restart the server or application.

8. What are the license terms?