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
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<!-- $Id: README.html 1477 2005-02-05 07:04:28Z nfiedler $ -->
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta content=
"HTML Tidy for Linux/x86 (vers 1st September 2004), see www.w3.org"
name="generator" />
<title>JSwat plugin</title>
</head>
<body>
<h1>jEdit JSwat Plugin README</h1>
<hr />
<!-- Note: <hr></hr> is required instead of <hr/> because otherwise
Swing's JEditorPane would show an additional ">" in JDK 1.4. -->
<h2>Acknowledgments</h2>
<p>JSwat is a Java debugger developed primarily by Nathan Fiedler and
can be found at the <a href=
"http://www.bluemarsh.com/java/jswat/">JSwat website</a>. The jEdit
plugin was initially developed by David Taylor, then later maintained
by Stefano Maestri. In February of 2003 the plugin was merged into
the JSwat project and Nathan Fiedler is now the maintainer of the
plugin.</p>
<hr />
<h2>Introduction</h2>
<p>The JSwat plugin integrates JSwat with jEdit, making it possible
to debug Java code directly within jEdit. While not all of the JSwat
functionality is provided through the graphical interface, the most
important features are available in the menu and dockable window.</p>
<p>The plugin provides menu items and toolbar buttons for controlling
the debuggee (attach, detach, start, stop, suspend, resume) and
setting breakpoints. It also displays the usual JSwat panels for
displaying threads, local and field variables, the loaded classes,
the call stack, and so on. In addition, the usual JSwat command
interface is available to utilize all of JSwat's debugging
commands.</p>
<hr />
<h2>Requirements</h2>
<p>The requirements for the JSwat plugin include the same
requirements as JSwat itself. That is, the JPDA classes must be made
available to the plugin in order for it to start. If the JPDA classes
are contained in the <code>tools.jar</code> file in the JDK
<code>lib</code> directory, they will be loaded automatically. If
not, then continue reading this section.</p>
<p>See the JSwat <a href=
"http://www.bluemarsh.com/repos/jswat/trunk/README.html">README</a>
for how to make the JPDA classes available to the plugin. In addition
to the possibilities listed in that file, you can also copy the
<code>tools.jar</code> file from the JDK <code>lib</code> directory
to your <code>.jedit/jars</code> directory.</p>
<hr />
<h2>Installing the JSwat plugin</h2>
<p>If you have used a version of the JSwatPlugin prior to 1.3, you
will have to manually delete the <code>jswat2.jar</code> file from
the jEdit <code>jars</code> directory. Otherwise you will get
exceptions when trying to start the plugin.</p>
<p>To install the plugin, simply copy the jar files from the plugin
directory to the jEdit <code>jars</code> directory. Then start jEdit
and the JSwatPlugin should be available in the plugins menu.</p>
<hr />
<h2>Using the JSwat plugin</h2>
<h3>Setting the JSwat session parameters</h3>
<p>The following parameters control how the debuggee is started, as
well as specifying the all-important classpath and sourcepath values.
These should be familiar as they are the same sort of options
provided in JSwat itself.</p>
<dl>
<dt><strong>Class Path</strong></dt>
<dd>The class path to be used when using the "Start VM"
action. Specify it as you would when using the command line, or use
the classpath builder by clicking on the associated button.<br />
Note that this setting is ignored during remote debugging, because
in this case the classpath of the remote debuggee gets used
instead.</dd>
<dt><strong>Source Path</strong></dt>
<dd>A list of directories to search for source files. This is
specified the same way as the class path.</dd>
<dt><strong>Stop in main() method when launching</strong></dt>
<dd>If selected, JSwat automatically sets a breakpoint at the first
line of the main method of the main class. This applies only to a
launched session (action "Start VM"), not a remote
debugging session (action "Attach to remote VM").</dd>
<dt><strong>Raise window upon debugging event</strong></dt>
<dd>If selected, JSwat tries to raise the jEdit window above other
windows on your desktop whenever a breakpoint is hit or some other
debugging event occurred. Note that the behavior of this feature
depends on the desktop manager you are using. For example, on newer
Windows systems, this may cause the jEdit entry in the task bar to
flash (in case it is not already in the foreground).</dd>
<dt><strong>Shorten class names</strong></dt>
<dd>If selected, JSwat will strip the package names from class
names in the Locals, Breakpoints and Stack panel.</dd>
</dl>
<h3>Setting/Removing/Disabling breakpoints</h3>
<p>To set a breakpoint, place the caret on the line you wish to set
the breakpoint on and select the Toggle Breakpoint action from the
JSwat plugin menu.</p>
<p>A blue marker will appear in the gutter next to any lines with
breakpoints set. If there is a VM session running, and the breakpoint
class can be resolved, the marker will appear in red.</p>
<p><strong>Note:</strong> Only line breakpoints can be set using the
JSwat plugin. However, method breakpoints can be set using the usual
JSwat <code>stop</code> command, although the plugin will not be able
to indicate the location of the breakpoint.</p>
<p>If a breakpoint has already been set on the caret line, the
breakpoint will be disabled. This is indicated by a gray marker.</p>
<p>If the breakpoint on the caret line has already been disabled, the
breakpoint will be removed.</p>
<h3>Starting a debugging session</h3>
<p>To start a debugging session, use may either use remote debugging
or launched debugging.<br />
See "<strong>Launching a new debugging session</strong>" or
"<strong>Attaching to a remote debugging session</strong>"
below.</p>
<h3>Launching a new debugging session</h3>
<p>To launch a new debugging session, select the "Start VM"
menu item from the JSwat plugin menu. A dialog will be shown with the
following parameters:</p>
<dl>
<dt><strong>Java Home</strong></dt>
<dd>The directory in which a JDK is installed, such as
"c:\jdk1.4.2"</dd>
<dt><strong>JVM Executable</strong></dt>
<dd>The name of the JVM executable, such as "java". The
path to the JVM executable is assumed to be <code>{Java
Home}/bin</code>.</dd>
<dt><strong>Debuggee VM options</strong></dt>
<dd>Any arguments to be passed to the debuggee VM, such as
"-classic". Do not add the "-classpath"
parameter here, as it will be added by JSwat, according to the
classpath setting specified in the Global Options dialog.</dd>
<dt><strong>Set -D Properties</strong></dt>
<dd>This opens a dialog where you can specify the <code>-D</code>
options passed to the debuggee VM.</dd>
<dt><strong>Class name and arguments</strong></dt>
<dd>This field must start with the fully qualified name of the main
class of the debuggee application, such as
<code>org.gjt.sp.jedit.Main</code>.<br />
Append any command line arguments to be passed to the application.
These will become the String[] args parameter to the
<code>main</code> method of the main class specified at the line
start.</dd>
<dt><strong>Start VM suspended</strong></dt>
<dd>If checked, the debugger will not start the application until
the debuggee is resumed.</dd>
</dl>
<h3>Attaching to a remote debugging session</h3>
<p>To attach to re remote debugging session, select the "Attach
to remove VM" menu item from the JSwat plugin menu. A dialog
will be shown with the following parameters:</p>
<dl>
<dt><strong>Transport Type</strong></dt>
<dd>Choose the transport type that you have chosen to start the
debuggee application with. JSwat supports socket transport and
shared memory transport.<br />
Note that JSwat supports the shared memory connector, when the
system allows it. This is generally only true for Windows
systems.</dd>
<dt><strong>Host</strong></dt>
<dd>When using socket transport, enter the hostname of the remote
debuggee. If you leave this field blank, it defaults to
"localhost".</dd>
<dt><strong>Port number</strong></dt>
<dd>When using socket transport, enter the port number of the
remote debuggee listening for connection events.<br />
Typically socket-based debugging means that each time the debugger
is detached, the debuggee will listen on a new port. To avoid this,
add "<code>address=1234</code>" to the list of arguments
to the <code>-Xrunjdwp</code> option. The value is a port number
between 1 and 65535. Usually port numbers below 1024 are for
privileged use only. Be sure to choose a port number that is not
being used by any other socket-based application.</dd>
<dt><strong>Shared name</strong></dt>
<dd>When using shared memory transport, enter the shared memory
name of the remote debuggee here.</dd>
</dl>
<h3>Run until line</h3>
<p>This feature allows you to place a temporary breakpoint on the
line where the caret is. The target will run until this line (or
another breakpoint is triggered). Once the temporary breakpoint has
been triggered, it will be automatically deleted.</p>
<h3>Get variable value</h3>
<p>The value of variables can be seen by allowing the mouse pointer
to hover over a variable name in the source code. If the variable is
in scope, its value will be displayed as a tooltip.</p>
<hr />
<h2>Building the JSwat plugin</h2>
<p>The JSwat plugin is built using <a href=
"http://ant.apache.org/">Apache Ant</a> and a <code>build.xml</code>
file is provided for this purpose. You may want to create a
<code>build.properties</code> file to set some of the build
properties to suit your environment; in particular, you may want to
set the <code>install.dir</code> property. See the plugin
<code>build.xml</code> file for the details.</p>
<p>You will need to set your <code>CLASSPATH</code> to include the
jEdit jar file (<code>jedit.jar</code>) so the plugin can find the
classes it needs.</p>
<p>To build the plugin, invoke <kbd>ant</kbd> with no arguments. This
will make the jar files and copy them to the <code>install.dir</code>
directory. The jar files will need to be in the jEdit
<code>jars</code> directory for jEdit to find the plugin.</p>
<hr />
<h2>Reporting Problems</h2>
<p>If you find any problems in JSwat or the plugin, or you have an
idea for a feature request, please send an email to
<code>jswat-bugs@bluemarsh.com</code> with as much information as you
can provide (software versions, environment settings, the
problem/feature description).</p>
<hr />
<h2>Revision History</h2>
<p>1.6 - February 4, 2005 (Dirk Moebius)</p>
<ul>
<li>Fixed bug 898: NPE in
<code>JEditSourceView.scrollToLine()</code> when the debugger hits
a breakpoint.</li>
<li>Fixed bug: breakpoint indicators and variable tooltips were not
shown on the first jEdit view, only on subsequently opened views.
Generally, JSwatPlugin should now behave better when more than one
jEdit view is opened. (But you may still open only one JSwat
instance.)</li>
<li>Fixed bug: the Ant build file (<code>build.xml</code>) had a
bug so that the plugin version number of the
<code>JSwat.props</code> file inside the JSwatPlugin.jar archive
was not updated correctly when using "<code>ant
dist</code>" after "<code>ant release</code>".</li>
<li>Fixed bug: memory hole when unloading and reloading the
JSwatPlugin (text area decorators were not removed from text
areas).</li>
<li>Fixed bug: JSwatPlugin did not use the AWT event thread to open
files and perform scrolling, resulting in a couple of concurrency
issues.</li>
<li>Fixed bug: the source distribution files
<code>JSwatPlugin-src-{version}.tar.gz</code> and
<code>JSwatPlugin-src-{version}.zip</code>, which are built by
"<code>ant dist</code>", wrongly included the class
binaries. This made them twice as large as they need to be.</li>
</ul>
<p>1.5.5 - November 14, 2004</p>
<ul>
<li>Fixed bug 895: breakpoint indicator was not showing in the
source code viewer.</li>
<li>Fixed bug 896: toolbar buttons are now enabling and disabling
appropriately.</li>
</ul>
<p>1.5.4 - April 29, 2004 (Dirk Moebius)</p>
<ul>
<li>New: Added action "Hotswap Class" to hotswap the
class surrounding the current cursor position.</li>
<li>Fixed bug: changing the dock position of the JSwat panel
required a restart of jEdit.</li>
<li>Fixed bug: jEdit would sometimes throw
IndexOutOfBoundsException if the buffer was shorter than the
current debug position.</li>
<li>Fixed bug: Invoking a JSwatPlugin action before the JSwat panel
was docked for the first time threw a NullPointerException.</li>
<li>If the user opens a second jEdit view, display a message in the
dock panel saying that only one instance of JSwatPlugin is
allowed.</li>
<li>BeanShell scripts can now invoke JSwat commands by calling
<code>com.bluemarsh.jswat.plugins.jedit.JSwatPlugin
.invokeJSwatCommand(View view, String command)</code>.</li>
<li>Renamed action "Dock JSwat Plugin" to "Show
JSwat Plugin" (associated shortcuts remain the same).</li>
</ul>
<p>1.5(.0-3) - February 16, 2004 (Dirk Moebius)</p>
<ul>
<li>New: Remote debugging (actions "Attach to remote VM"
and "Detach from remote VM").</li>
<li>New: Now opens source files in source file archives. You can
now specify source file archives in the source path (ZIP or JAR
files). For this feature, the Archive plugin is required (version
0.3.3 or higher), otherwise you will get an error message when the
debugger tries to open such a file.</li>
<li>Updated to work with JSwat 2.21. Now requires jEdit 4.1pre1 or
higher.</li>
<li>Reworked options panel; the launch properties (Java home etc.)
have been moved to the "Start VM" action; new JSwat
options "Stop in main() when launching", "Raise
window upon debugging event" and "Shorten class
names"; the plugin now shares its settings with an installed
JSwat standalone application.</li>
<li>Actions "Add Breakpoint" and "Remove
Breakpoint" in the JSwat plugin menu replaced by a single
action "Toggle Breakpoint". You might need to reassign
jEdit shortcuts.</li>
<li>Breakpoints shown in the text area gutter are now displayed
with an appropriate color: red for resolved, blue for unresolved,
gray for disabled (same as in JSwat standalone).</li>
<li>The current debugging line is now indicated with a red
highlight. In previous versions, the plugin used jEdit's
current line indicator for this. This was inappropriate, because
you could move the cursor somewhere else and you would lose your
debugging position.</li>
<li>The JSwat plugin now may be docked into the bottom or top area.
In this case, the two split panes are displayed side-by-side.</li>
<li>JSwat debugging log information is now dumped to a file
jswat.log in the user's home, instead of the activity log. This
is faster.</li>
<li>Fixed bug: setting breakpoint after changing the current buffer
did not work. This appears to have fixed bug 735 as well.</li>
<li>Fixed bug 738: moved initialization out of <code>start()</code>
method so plugin will launch faster.</li>
<li>Fixed bug: breakpoints in inner classes now work.</li>
<li>Fixed bug: variable tooltip did not show null values.</li>
<li>Fixed bug: help document README.html did not show up in jEdit
Help.</li>
</ul>
<p>1.4 - November 10, 2003</p>
<ul>
<li>Fixed bug 737: breakpoint indicator now appears and disappears
immediately, rather than when the text area just happened to be
repainted.</li>
<li>Fixed bug 773: VM start dialog ignored the Java home and
application parameters values.</li>
</ul>
<p>1.3 - March 9, 2003</p>
<ul>
<li>Added "Help" menu item to the JSwat plugin menu, so
the JSwat help can now be accessed.</li>
<li>Looks for the JPDA classes on startup and reports an error if
they are not found.</li>
<li>Replaced the red colored toolbar buttons; they clashed with the
predominantly blue-colored buttons.</li>
<li>Put the classes in a proper package
(com.bluemarsh.jswat.plugins.jedit), conforming with Java coding
standards.</li>
<li>Now remembers the position of the split-pane divider.</li>
<li>Installed plugin in the JSwat source tree under
<code>plugins/jedit</code>. It is now part of the JSwat
project.</li>
<li>Removed copious amounts of unnecessary, duplicate, and/or
defunct code, and filled in some missing pieces.</li>
<li>Breakpoints panel said "junk" because it was not
initialized properly. This change also fixed the other problems
with the breakpoints panel.</li>
<li>Removed debugging messages from output panel.</li>
<li>Added edit popup menus to text areas and text fields.</li>
<li>Removed dependence on CommonControls classes; use the class in
JSwat that provides specialized functionality.</li>
<li>Added "New" button to toolbar to start debuggee.</li>
<li>After switching buffer, adapter still used old class name for
setting breakpoints.</li>
</ul>
<p>1.2.1 (Stefano Maestri)</p>
<ul>
<li>Porting to JSwat version 2.8 (requires JDK version 1.4 or
later).</li>
<li>Solved a bug (error when the plugin was not docked).</li>
</ul>
<p>1.2.0 (Stefano Maestri)</p>
<ul>
<li>Porting to JSwat version 2.4 (requires JDK version 1.4 or
later).</li>
</ul>
<p>1.1.6 (Stefano Maestri)</p>
<ul>
<li>Porting to jEdit 4.0</li>
</ul>
<p>1.1.5 (David Taylor)</p>
<ul>
<li>Now uses MiscUtilities.isToolsJarAvailable() to find
tools.jar.</li>
<li>Has a "run until line" action/button that will add a
once-off breakpoint to the line the caret is on.</li>
<li>Now tries to show a variable's value as a tooltip.</li>
<li>The JSwat dockable can be opened and closed from the plugin
menu.</li>
<li>The JSwat options dialog can be opened from the plugin
menu.</li>
<li>Clears the JSwat messages area when a debugging session
begins.</li>
<li>Uses the CommonControls PathBuilder component to allow complex
class and source paths to be constructed easily.</li>
<li>Now handles attaching to running processes better (using the
JSwat attach command).</li>
</ul>
<p>1.1.4 (David Taylor)</p>
<ul>
<li>The plugin works with version 1.4 of JSwat.</li>
<li>Use jEdit's current line highlight feature to show current
line while debugging. The user's preference is respected when
the debugging session ends.</li>
<li>The options window is centered in the jEdit view when it is
displayed before starting the debugger.</li>
<li>The JSwat breakpoints panel is now available in the lower split
of the plugin's dockable window.</li>
</ul>
<p>1.1.3 (David Taylor)</p>
<ul>
<li>Toolbar only appears when debugger is active, and it appears in
the debugger window rather than on the jEdit toolbar.</li>
</ul>
<p>1.1.2 (David Taylor)</p>
<ul>
<li>Plugin now looks for tools.jar in java.home.</li>
<li>Plugin now has its own toolbar that is displayed in the jEdit
toolbar area.</li>
<li>Plugin no longer uses JSwat.preferences, so this file no longer
needs to be copied from the jar to user.home.</li>
<li>Plugin cleans up unfinished debugging sessions.</li>
</ul>
<p>1.1.1 (David Taylor)</p>
<ul>
<li>Plugin code is now completely separate from JSwat source.</li>
<li>JSwat UI elements are now displayed in a dockable window rather
than a top level frame.</li>
<li>Plugin only uses actions.xml, and no longer uses classes that
extend EditAction.</li>
<li>Plugin recognizes when a buffer has been closed and will reopen
it if required.</li>
</ul>
<p>1.0.1 (David Taylor)</p>
<ul>
<li>Initial public release.</li>
</ul>
</body>
</html>
|
