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 tools like RAD or RSA?

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

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 tools like RAD and RSA?

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.

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

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.