-
Notifications
You must be signed in to change notification settings - Fork 4
/
faq.html
279 lines (234 loc) · 13.8 KB
/
faq.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
<HTML>
<BODY>
<p><h1>6. Frequently Asked Questions</h1></p>
<font face="Verdana" size="2">
1. <a href="#eclipseNeeded">Do I need Eclipse to use MaintainJ?</a>
<br><br>2. <a href="#scale">How does MaintainJ scale?</a>
<br><br>3. <a href="#cnfe">I get a ClassNotfoundException for com.maintainj.inst.J2EEAspect. Where is that class?</a>
<br><br>4. <a href="#traceFile">Trace file is not generated</a>
<br><br>5. <a href="#aoplocation">Where is the aop.xml file (the trace configuration file)? How can I edit it?</a>
<br><br>6. <a href="#noDiagram">I do not see the UML diagrams when I open the trace file</a>
<br><br>7. <a href="#filtergetset">My diagrams are too big and cluttered. How can I filter out the unnecessary classes and calls?</a>
<br><br>8. <a href="#permgen">I get java.lang.OutOfMemoryError:PermGen space</a>
<br><br>9. <a href="#rose">Can I import the diagrams into Rational tools like RAD or RSA?</a>
<br><br>10. <a href="#documentation">How can I use MaintainJ for documentation and share the MaintainJ diagrams with others?</a>
<br><br>11. <a href="#license">What are the license terms?</a>
</font>
</p>
</p>
</p>
<font face="Verdana" size="-1">
<p><b><a name="eclipseNeeded"></a>1. Do I need Eclipse to use MaintainJ?</b></p>
<p>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.</p>
<p>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.
<p>For example, MaintainJ.war can be used outside Eclipse to generate the trace files
for J2EE applications. You can also follow these
<a href="userGuide.jsp?param=runtime#howitworks">steps</a> to manually
generate the trace files.
</p>
<p><b><a name="scale"></a>2. How does MaintainJ scale?</b></p>
<p>
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.
<p>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. </p>
<p>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.
</p>
<p><b><a name="cnfe"></a></b>
<b>3. I get a ClassNotfoundException for com.maintainj.inst.J2EEAspect. Where is that class?</b></p>
<p>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 Tomcat/JBoss
servers are started using MaintainJ J2EE Server plug-in, the aop.xml 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, <font color="#0d6af0">c:\maintainj</font>
should be added to the classpath.
<p>
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.</p>
<p><b><a name="traceFile"></a>
4. Trace file is not generated</b></p>
<p>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.
<p><a name="aoplocation"></a>
<b>5. Where is the aop.xml file (the trace configuration file)? How can I edit it?</b></p>
<p>
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.
<p><u>5.1 Where is the aop.xml file located?</u>
<p>Different MaintainJ wizards place this file under different folders.
<br>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.<br>
b) The MaintainJ J2EE Server plugin for Tomcat and JBoss puts the file under
<TomcatRoot>/maintainj and <JBossRoot>/bin/maintainj folders respectively.<br>
c) The MaintainJ.war shows the location of this file after Step 2: Configure Instrumentation Scope.<br>
d) The MaintainJSwingWizard.jar also shows the location of this file after the second step.
<p><u>5.2 How can I edit the aop.xml file?</u>
<p> 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
<font color="#0d6af0">org.jfree.chart</font> and excludes sub-packages and classes under
<font color="#0d6af0">org.jfree.chart.ui</font> package.
It also excludes <font color="#0d6af0">org.jfree.chart.JFreeChart</font>
class. Note the difference in syntax when excluding a class.</p>
<font size="2" face="Verdana">
<p><weaver options="-proceedOnError -nowarn -XaddSerialVersionUID"><br>
<include within="org.jfree.chart..*"/><br>
<font color="#0d6af0">
<exclude within="org.jfree.chart.ui..*"/><br>
<exclude within="org.jfree.chart.JFreeChart"/></font><br>
</weaver></p>
<p><u>5.3 After editing the file make sure that it is not overwritten by the wizards</u>
<p>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.
<p><a name="noDiagram"></a>
<b>6. I do not see the UML diagrams when I open the trace file</b></p>
<p>The MaintainJ UML Diagram Editor plug-in is not installed properly. If it is
installed correctly, you should see MaintainJ icon
<img border="0" src="images/mnj.gif" width="16" height="14" > beside the trace file
in Eclipse.
</font>
<p><a name="filtergetset"></a>
<b>7. My diagrams are too big and cluttered. How can I filter out the unnecessary classes and calls?</b></p>
<p><font face="Verdana" size="2">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.</font></p>
<p><u>7.1 Do not capture the unimportant calls</u></p>
<p>MaintainJ has a number of options to follow this
approach. </p>
<p>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.</p>
<p>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.</p>
<a name="aopfile"></a>
<p>7.1.3 You can also limit the scope of instrumentation at a finer level by
editing the generated <i>META-INF/aop.xml</i> file. Check the above
faq entry
'<a href="#aoplocation">Where is the aop.xml file (the trace configuration file)? How can I edit it?</a>'
for details.
</p>
<p><u>7.2 To remove unnecessary calls from the
diagrams</font></u><p><font face="Verdana" size="2">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.
<p>
7.2.1 <a href="userGuide.jsp?param=uml#filters">Predefined Filters</a>
is the first thing you should check to filter out unwanted details from the
diagrams.
</p>
<p>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.
</p>
<p>
7.2.3 <a href="userGuide.jsp?param=uml#excludeClass">Excluding a class</a>
or classes is another great way to get focused diagrams.
</p>
<p>
7.2.4 You can also use the Outline view to select and delete
multiple packages, classes or calls at once.
</p>
<p>
7.2.5 You can use 'Delete getter/setter Calls' in the
sequence diagram to delete the simple get/set method calls.
</p>
<p>
7.2.6 You can use 'Delete Constructor Calls' in the
sequence diagram to delete all constructor calls.
</p>
<p>
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 <i>Delete Duplicate Calls to this Method</i>. This can be used to remove
all unnecessary get/set methods, repeating calls to boolean equals(Object obj) method, etc.</p>
<p><u>7.3
Use 'Save As' feature to split the diagrams</font></u><p>
<font face="Verdana" size="2">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.
<p><a name="permgen"></a>
<b>8. I get java.lang.OutOfMemoryError:PermGen space</b></p>
<p>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.</p>
<p><a name="rose"></a>
<b>9. Can I import the diagrams into Rational tools like RAD and RSA?</b></p>
<p>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.
<!--
Having said that, we ask you to
consider the points below that highlight the advantages of viewing the diagrams in
MaintainJ itself than importing them into Rose.<br><br>
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.<br>
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.<br>
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.<br>
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.<br>
-->
</p>
<p>
<a name="documentation"></a>
<b>10. How can I use MaintainJ for documentation and share
the MaintainJ diagrams with others?</b></p>
<p>
You can use MaintainJ for documenting and sharing the application knowledge with your team members.<p>
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.<br>
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
</p>
<p><a name="license"></a>
<b>11. What are the license terms?</b></p>
<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
<a href="userGuide.jsp?param=license">License Agreement</a>.</p>
</font>
</BODY>
</HTML>