forked from wdev/struts2
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathreadme.html
656 lines (624 loc) · 34.9 KB
/
readme.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
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
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>Retrotranslator</title>
</head>
<body>
<table border="0" width="98%">
<tr>
<td><h2>Retrotranslator</h2></td>
<td width="125" align="left"><a href="http://sourceforge.net"><img
src="http://sflogo.sourceforge.net/sflogo.php?group_id=153566&type=2"
width="125" height="37" border="0" alt="SourceForge.net Logo"/></a>
</td>
</tr>
</table>
<h4>Contents</h4>
<ol>
<li><a href="#what">What is Retrotranslator?</a></li>
<li><a href="#features">What Java 5 features are supported?</a></li>
<li><a href="#commandline">How to use Retrotranslator from a command line?</a></li>
<li><a href="#ant">How to use Retrotranslator from Apache Ant or Maven?</a></li>
<li><a href="#idea">How to use Retrotranslator from IntelliJ IDEA?</a></li>
<li><a href="#jit">How to use Just-in-Time Retrotranslator?</a></li>
<li><a href="#supported">What Java 5 classes and methods are supported?</a></li>
<li><a href="#extension">How to write an extension for Retrotranslator?</a></li>
<li><a href="#limitations">What are the limitations?</a></li>
<li><a href="#alternative">Alternative tools</a></li>
<li><a href="#contact">Contact</a></li>
<li><a href="#license">License</a></li>
</ol>
<h4><a name="what">What is Retrotranslator?</a></h4>
<a href="http://sourceforge.net/projects/retrotranslator">Retrotranslator</a> is a Java bytecode transformer
that translates Java classes compiled with JDK 5.0 into classes that can be run on JVM 1.4.
It is a free, open-source tool based on the <a href="http://asm.objectweb.org/">ASM bytecode manipulation framework</a>
and concurrency utilities
<a href="http://dcl.mathcs.emory.edu/util/backport-util-concurrent/index.php">backported to Java 1.4</a>.
<h4><a name="features">What Java 5 features are supported?</a></h4>
<ul>
<li>Generics (generic types)</li>
<li>Annotations (metadata)</li>
<li>Reflection on generics and annotations</li>
<li>Typesafe enums (enumerated types)</li>
<li>Autoboxing/unboxing</li>
<li>Enhanced for loop (for-each loop)</li>
<li>Varargs (variable arguments)</li>
<li>Covariant return types</li>
<li>Formatted output</li>
<li>Static import</li>
<li>Concurrency utilities</li>
<li>Collections framework enhancements</li>
</ul>
<h4><a name="commandline">How to use Retrotranslator from a command line?</a></h4>
<ol>
<li><a href="http://sourceforge.net/project/showfiles.php?group_id=153566">Download</a>
and unzip the binary distribution file <code>Retrotranslator-<i>n.n.n</i>-bin.zip</code>,
where <i>n.n.n</i> is the latest Retrotranslator release number.
</li>
<li>
Compile your classes with JDK 5.0 and put them into some directory, e.g. <code>myclasses</code>.
</li>
<li>
Go to the unzipped directory and execute:<br>
<code>java -jar retrotranslator-transformer-<i>n.n.n</i>.jar -srcdir myclasses</code>
</li>
<li>
If you use Java 5 API put <code>retrotranslator-runtime-<i>n.n.n</i>.jar</code> and
<code>backport-util-concurrent-<i>n.n</i>.jar</code> into the classpath of your application.
</li>
<li>
Run or debug the application as usual on J2SE 1.4.x, preferably 1.4.2.
</li>
</ol>
<p><a name="syntax">The full command line syntax:</a><br>
<code>java -jar retrotranslator-transformer-<i>n.n.n</i>.jar <options></code>
<br>or<br>
<code>java -cp retrotranslator-transformer-<i>n.n.n</i>.jar net.sf.retrotranslator.transformer.Retrotranslator <options></code></p>
<table border="1" cellspacing="0" cellpadding="5">
<tr><th>Option</th><th>Description</th><th>Default</th></tr>
<tr>
<td nowrap><code>-srcdir</code></td>
<td>The directory with classes that should be translated (may be specified several times).</td>
<td>-</td>
</tr>
<tr>
<td nowrap><code>-srcjar</code></td>
<td>The directory with classes that should be translated (may be specified several times).</td>
<td>-</td>
</tr>
<tr>
<td nowrap><code>-destdir</code></td>
<td>The directory to place translated classes.</td>
<td>Location of sources</td>
</tr>
<tr>
<td nowrap><code>-destjar</code></td>
<td>The JAR file to place translated classes.</td>
<td>Location of sources</td>
</tr>
<tr>
<td nowrap><a name="option_advanced"><code>-advanced</code></a></td>
<td>Whether to use alternative implementations of Java 1.4 classes and methods for better Java 5 compatibility.</td>
<td>Off</td>
</tr>
<tr>
<td nowrap><code>-verify</code></td>
<td>Asks the translator to examine translated bytecode for references to classes, methods, or fields
that cannot be found in the provided classpath.</td>
<td>Off</td>
</tr>
<tr>
<td nowrap><code>-classpath</code></td>
<td>The classpath for verification including <code>rt.jar</code>, <code>jce.jar</code>,
<code>jsse.jar</code> (from JRE 1.4), <code>retrotranslator-runtime-<i>n.n.n</i>.jar</code>,
and <code>backport-util-concurrent-<i>n.n</i>.jar</code>.</td>
<td>Current classpath</td>
</tr>
<tr>
<td nowrap><code>-srcmask</code></td>
<td>The wildcard pattern specifying files that should be translated (either bytecode or UTF-8 text),
e.g. "<code>*.class;*.tld</code>". There are three special characters: "<code>*?;</code>".
</td>
<td>*.class</td>
</tr>
<tr>
<td nowrap><code>-embed</code></td>
<td>Package name for a private copy of <code>retrotranslator-runtime-<i>n.n.n</i>.jar</code> and
<code>backport-util-concurrent-<i>n.n</i>.jar</code> to be put into <code>-destdir</code> or <code>-destjar</code>.
This makes your application independent of other versions of Retrotranslator present in the classpath.
</td>
<td>-</td>
</tr>
<tr>
<td nowrap><a name="option_backport"><code>-backport</code></a></td>
<td>Informs the translator about <a href="#extension">user-defined</a> backport packages.
Package names should be separated by semicolons.</td>
<td>-</td>
</tr>
<tr>
<td nowrap><code>-target</code></td>
<td>To make Java 6 classes compatible with Java 5 set this option to 1.5 and supply
<a href="#extension">user-defined</a> backport packages via the <code>backport</code> option.</td>
<td>1.4</td>
</tr>
<tr>
<td nowrap><code>-lazy</code></td>
<td>Asks the translator to only transform classes compiled with a <code>target</code> greater than the current one.</td>
<td>Off</td>
</tr>
<tr>
<td nowrap><code>-stripsign</code></td>
<td>Asks the translator to strip signature (generics) information.</td>
<td>Off</td>
</tr>
<tr>
<td nowrap><code>-verbose</code></td>
<td>Asks the translator for verbose output.</td>
<td>Off</td>
</tr>
<tr>
<td nowrap><code>-retainapi</code></td>
<td>Asks the translator to modify classes for JVM 1.4 compatibility but keep use of Java 5 API.
References introduced by a compiler will also remain unchanged,
like the use of <code>java.lang.StringBuilder</code> for string concatenation
or the implicit <code>valueOf</code> method call for autoboxing.</td>
<td>Off</td>
</tr>
<tr>
<td nowrap><code>-retainflags</code></td>
<td>Asks the translator to keep Java 5 specific access modifiers.</td>
<td>Off</td>
</tr>
</table>
<p>
For example, if you have a Java 5 application <code>myapplication5.jar</code> you can use the following command
to produce <code>myapplication4.jar</code> that will run on J2SE 1.4 and is independent of Retrotranslator,
since required classes are added to the translated application with a different package name:
</p>
<p>
<code>java -jar retrotranslator-transformer-<i>n.n.n</i>.jar
-srcjar myapplication5.jar -destjar myapplication4.jar -embed com.mycompany.internal</code><br>
</p>
<h4><a name="ant">How to use Retrotranslator from Apache Ant or Maven?</a></h4>
<p>The distribution contains an integrated <a href="http://ant.apache.org/">Apache Ant</a> task
<code>net.sf.retrotranslator.transformer.RetrotranslatorTask</code>. It has the following syntax:</p>
<table border="1" cellspacing="0" cellpadding="5">
<tr><th>Attribute</th><th>Description</th><th>Default</th></tr>
<tr>
<td><code>srcdir</code></td>
<td>The directory with classes that should be translated.</td>
<td>-</td>
</tr>
<tr>
<td><code>srcjar</code></td>
<td>The directory with classes that should be translated.</td>
<td>-</td>
</tr>
<tr>
<td><code>destdir</code></td>
<td>The directory to place translated classes.</td>
<td>Location of sources</td>
</tr>
<tr>
<td><code>destjar</code></td>
<td>The JAR file to place translated classes.</td>
<td>Location of sources</td>
</tr>
<tr>
<td><code>advanced</code></td>
<td>Whether to use alternative implementations of Java 1.4 classes and methods for better Java 5 compatibility.</td>
<td>Off</td>
</tr>
<tr>
<td><code>verify</code></td>
<td>Asks the translator to examine translated bytecode for references to classes, methods, or fields
that cannot be found in the provided classpath.</td>
<td>Off</td>
</tr>
<tr>
<td><code>classpath</code></td>
<td>The classpath for the verification, including <code>rt.jar</code>, <code>jce.jar</code>,
<code>jsse.jar</code> (from JRE 1.4), <code>retrotranslator-runtime-<i>n.n.n</i>.jar</code>,
and <code>backport-util-concurrent-<i>n.n</i>.jar</code>.
</td>
<td>Current classpath</td>
</tr>
<tr>
<td><code>classpathref</code></td>
<td>The classpath for the verification, given as a reference to a path defined elsewhere.
</td>
<td>Current classpath</td>
</tr>
<tr>
<td><code>srcmask</code></td>
<td>The wildcard pattern specifying files that should be translated (either bytecode or UTF-8 text),
e.g. "<code>*.class;*.tld</code>". There are three special characters: "<code>*?;</code>".
</td>
<td>*.class</td>
</tr>
<tr>
<td><code>embed</code></td>
<td>Package name for a private copy of <code>retrotranslator-runtime-<i>n.n.n</i>.jar</code> and
<code>backport-util-concurrent-<i>n.n</i>.jar</code> to be put into <code>-destdir</code> or <code>-destjar</code>.
This makes your application independent of other versions of Retrotranslator present in the classpath.
</td>
<td>-</td>
</tr>
<tr>
<td><code>backport</code></td>
<td>Informs the translator about <a href="#extension">user-defined</a> backport packages.
Package names should be separated by semicolons.</td>
<td>-</td>
</tr>
<tr>
<td><code>target</code></td>
<td>Set this option to 1.5 and supply <a href="#extension">user-defined</a> backport packages via
the <code>backport</code> option to make Java 6 classes compatible with Java 5.</td>
<td>1.4</td>
</tr>
<tr>
<td><code>lazy</code></td>
<td>Asks the translator to only transform classes compiled with a <code>target</code> greater than the current one.</td>
<td>Off</td>
</tr>
<tr>
<td><code>stripsign</code></td>
<td>Asks the translator to strip signature (generics) information.</td>
<td>Off</td>
</tr>
<tr>
<td><code>verbose</code></td>
<td>Asks the translator for verbose output.</td>
<td>Off</td>
</tr>
<tr>
<td><code>retainapi</code></td>
<td>Asks the translator to modify classes for JVM 1.4 compatibility but keep use of Java 5 API.
References introduced by a compiler will also remain unchanged,
like the use of <code>java.lang.StringBuilder</code> for string concatenation
or the implicit <code>valueOf</code> method call for autoboxing.</td>
<td>Off</td>
</tr>
<tr>
<td><code>retainflags</code></td>
<td>Asks the translator to keep Java 5 specific access modifiers.</td>
<td>Off</td>
</tr>
<tr>
<td><code>failonwarning</code></td>
<td>Indicates whether the build will fail when there are verification warnings.</td>
<td>On</td>
</tr>
</table>
<p>
You may use nested <code>fileset</code>, <code>jarfileset</code>, and <code>dirset</code> elements to specify
source files and <code>classpath</code> elements to specify classpath. For example:
</p>
<pre>
<path id="classpath">
<fileset dir="lib" includes="**/*.jar"/>
</path>
<taskdef name="retrotranslator" classpathref="classpath"
classname="net.sf.retrotranslator.transformer.RetrotranslatorTask" />
<retrotranslator destdir="build/classes14" verify="true">
<fileset dir="build/classes15" includes="**/*.class">
<jarfileset dir="build/lib15" includes="**/*.jar">
<classpath location="${java14_home}/jre/lib/rt.jar"/>
<classpath refid="classpath"/>
</retrotranslator>
</pre>
<p>
For <a href="http://maven.apache.org/">Maven</a> there is a
<a href="http://mojo.codehaus.org/retrotranslator-maven-plugin/">Retrotranslator plugin</a>
from the <a href="http://mojo.codehaus.org/">Mojo Project</a>.
</p>
<h4><a name="idea">How to use Retrotranslator from IntelliJ IDEA?</a></h4>
<p>
There is a <a href="http://plugins.intellij.net/plugin/?id=145">plugin</a> to automatically translate and verify
classes compiled by <a href="http://www.jetbrains.com/idea/">IntelliJ IDEA</a>, so you can develop in Java 5 but
run and debug on JRE 1.4.
</p>
<h4><a name="jit">How to use Just-in-Time Retrotranslator?</a></h4>
<p>
JIT Retrotranslator is able to translate at runtime Java classes loaded with any classloader.
It works on J2SE 1.4 from most JVM vendors like Sun, IBM, BEA, and Apple, but does nothing on J2SE 5.0.
However translation at runtime consumes additional memory and processing resources and it will not
work if your classes make use of Java 5 API but were compiled with "<code>-target 1.4</code>".
</p>
<ul>
<li>
If you want to run a JAR file with the JIT, execute:<br>
<code>java -cp retrotranslator-transformer-<i>n.n.n</i>.jar
net.sf.retrotranslator.transformer.JITRetrotranslator <options> -jar <jarfile> [<args...>]</code>
</li>
<li>
When the first option does not work or if you just want to run a class from your classpath, execute:<br>
<code>java -cp retrotranslator-transformer-<i>n.n.n</i>.jar:<classpath>
net.sf.retrotranslator.transformer.JITRetrotranslator <options> <class> [<args...>]</code>
</li>
<li>
Alternatively you may simply call <code>JITRetrotranslator.run()</code> from some JVM 1.4 compatible class
before Java 5 classes are loaded.
</li>
</ul>
<p>
JIT Retrotranslator can accept the <code><a href="#option_advanced">advanced</a></code>
and <code><a href="#option_backport">backport</a></code> options.
</p>
<h4><a name="supported">What Java 5 classes and methods are supported?</a></h4>
<table border="1" cellspacing="0" cellpadding="5">
<tr><th>Package</th><th>Class</th><th>Methods and fields</th><th>Compatibility notes</th></tr>
<tr><td><code>java.lang.annotation</code></td><td>* (all classes)</td><td>* (all methods)</td><td> </td></tr>
<tr><td><code>java.lang.instrument</code></td><td>* (all classes)</td><td>* (all methods)</td><td>
Bytecode instrumentation is not implemented.</td></tr>
<tr><td><code>java.util.concurrent,<br>java.util.concurrent.atomic,<br>java.util.concurrent.locks</code></td>
<td>almost all classes<sup><a href="#1">1</a></sup></td><td>almost all methods</td>
<td>The <code>LockSupport</code> class may be unusable due to poor efficiency.
The <code>Condition.awaitNanos(long)</code> method has
<a href="http://dcl.mathcs.emory.edu/util/backport-util-concurrent/doc/api/edu/emory/mathcs/backport/java/util/concurrent/helpers/Utils.html#awaitNanos(edu.emory.mathcs.backport.java.util.concurrent.locks.Condition, long)">
little</a> accuracy guarantees.</td></tr>
<tr><td rowspan="6"><code>java.io</code></td><td><code>Closeable<sup><a href="#2">2</a></sup></code>
</td><td><code>*</code></td><td> </td></tr>
<tr><td><code>Flushable<sup><a href="#2">2</a></sup></code></td><td><code>*</code></td><td> </td></tr>
<tr><td><code>PrintStream</code></td><td>
* (11 new methods and constructors)
</td><td> </td></tr>
<tr><td><code>PrintWriter</code></td><td>
* (11 new methods and constructors)
</td><td>
The <code>PrintWriter.format</code> and <code>PrintWriter.printf</code> methods always flush the output buffer.
</td></tr>
<tr><td><code>Reader</code></td><td><code>read(CharBuffer)</code></td><td> </td></tr>
<tr><td><code>Writer</code></td><td>
<code>append(CharSequence),<br>
append(CharSequence, int, int),<br>
append(char)</code>
</td><td> </td></tr>
<tr><td rowspan="26"><code>java.lang</code></td><td><code>Appendable<sup><a href="#2">2</a></sup></code></td><td>*
</td><td> </td></tr>
<tr><td><code>Boolean</code></td><td><code>parseBoolean(String),<br>
compareTo(Boolean)</code></td><td> </td></tr>
<tr><td><code>Byte</code></td><td><code>valueOf(byte)</code></td><td> </td></tr>
<tr><td><code>Character</code></td><td><code>valueOf(char)</code></td><td> </td></tr>
<tr><td><code>Class</code></td><td>* (21 new methods)</td><td>
<code>Class.getMethod(String, Class...)</code> and <code>Class.getDeclaredMethod(String, Class...)</code>
are intercepted to better support generics and covariant return types
on several platforms<sup><a href="#3">3</a></sup>.
</td></tr>
<tr><td><code>Deprecated</code></td><td>*</td><td> </td></tr>
<tr><td><code>Double</code></td><td><code>valueOf(double)</code></td><td> </td></tr>
<tr><td><code>Enum</code></td><td>*</td><td> </td></tr>
<tr><td><code>Float</code></td><td><code>valueOf(float)</code></td><td> </td></tr>
<tr><td><code>IllegalArgumentException</code></td><td><code>IllegalArgumentException(String, Throwable),<br>
IllegalArgumentException(Throwable)</code></td><td> </td></tr>
<tr><td><code>IllegalStateException</code></td><td><code>IllegalStateException(String, Throwable),<br>
IllegalStateException(Throwable)</code></td><td> </td></tr>
<tr><td><code>Integer</code></td><td><code>valueOf(int), signum(int)</code></td><td> </td></tr>
<tr><td><code>Iterable<sup><a href="#2">2</a></sup></code></td><td>*</td><td> </td></tr>
<tr><td><code>Long</code></td><td><code>valueOf(long), signum(long)</code></td><td> </td></tr>
<tr><td><code>Package</code></td><td>* (4 new methods)</td><td> </td></tr>
<tr><td><code>Readable<sup><a href="#2">2</a></sup></code></td><td>*</td><td> </td></tr>
<tr><td><code>Short</code></td><td><code>valueOf(short)</code></td><td> </td></tr>
<tr><td><code>String</code></td><td><code>contains(CharSequence),<br>
contentEquals(CharSequence),<br>
format(Locale, String, Object...),<br>
format(String, Object...),<br>
replace(CharSequence, CharSequence),<br>
isEmpty()<sup><a href="#4">4</a></sup>
</code></td><td> </td></tr>
<tr><td><code>StringBuffer</code></td><td><code>
StringBuffer(CharSequence),<br>
append(CharSequence),<br>
append(CharSequence, int, int),<br>
insert(int, CharSequence),<br>
insert(int, CharSequence, int, int)
</code></td><td> </td></tr>
<tr><td><code>StringBuilder</code></td><td>
All methods supported in <code>StringBuffer</code>
</td><td><code>StringBuilder</code> is replaced with <code>StringBuffer</code>.</td></tr>
<tr><td><code>SuppressWarnings</code></td><td>*</td><td> </td></tr>
<tr><td><code>System</code></td><td><code>nanoTime()<sup><a href="#1">1</a></sup>,<br> clearProperty(String)</code></td><td>
The <code>System.nanoTime()</code> method precision
<a href="http://dcl.mathcs.emory.edu/util/backport-util-concurrent/doc/api/edu/emory/mathcs/backport/java/util/concurrent/helpers/Utils.html#nanoTime()">
may vary</a> on different platforms.
</td></tr>
<tr><td><code>Thread</code></td><td><code>getStackTrace(),<br> getId()
</code></td><td>The <code>Thread.getStackTrace()</code>
method returns non-empty stack trace only for the current thread.<br>
The <code>Thread.getId()</code> method does not reflect the order in which threads are created.</td></tr>
<tr><td><code>Thread.State</code></td><td>*</td><td> </td></tr>
<tr><td><code>ThreadLocal</code></td><td><code>remove()<sup><a href="#3">3</a></sup></code></td>
<td><code>ThreadLocal</code> and <code>InheritableThreadLocal</code>
are replaced by corresponding classes from the runtime library.<sup><a href="#3">3</a></sup>.</td></tr>
<tr><td><code>TypeNotPresentException</code></td><td>*</td><td> </td></tr>
<tr><td rowspan="2"><code>java.lang.ref</code></td>
<td><code>SoftReference</code></td><td>*</td><td>
<code>SoftReference(Object,ReferenceQueue)</code>
supports <code>null</code> for the second parameter
on all platforms<sup><a href="#3">3</a></sup>.
</td></tr>
<tr><td><code>WeakReference</code></td><td>*</td><td>
<code>WeakReference(Object,ReferenceQueue)</code>
supports <code>null</code> for the second parameter
on all platforms<sup><a href="#3">3</a></sup>.
</td></tr>
<tr><td rowspan="13"><code>java.lang.reflect</code></td>
<td><code>AccessibleObject</code></td><td>*</td><td> </td></tr>
<tr><td><code>AnnotatedElement<sup><a href="#2">2</a></sup></code></td><td>*</td><td> </td></tr>
<tr><td><code>Constructor</code></td><td>* (11 new methods)</td><td> </td></tr>
<tr><td><code>Field</code></td><td>* (8 new methods)</td><td> </td></tr>
<tr><td><code>GenericArrayType</code></td><td>*</td><td> </td></tr>
<tr><td><code>GenericDeclaration<sup><a href="#2">2</a></sup></code></td><td>*</td><td> </td></tr>
<tr><td><code>GenericSignatureFormatError</code></td><td>*</td><td> </td></tr>
<tr><td><code>MalformedParameterizedTypeException</code></td><td>*</td><td> </td></tr>
<tr><td><code>Method</code></td><td>* (14 new methods)</td><td> </td></tr>
<tr><td><code>ParameterizedType</code></td><td>*</td><td> </td></tr>
<tr><td><code>Type<sup><a href="#2">2</a></sup></code></td><td>*</td><td> </td></tr>
<tr><td><code>TypeVariable</code></td><td>*</td><td> </td></tr>
<tr><td><code>WildcardType</code></td><td>*</td><td> </td></tr>
<tr><td ><code>java.math</code></td><td><code>BigDecimal</code></td><td>
<code>BigDecimal(int),<br> BigDecimal(long),<br> ZERO, ONE, TEN,<br> divideAndRemainder(BigDecimal),<br>
divideToIntegralValue(BigDecimal),<br> pow(int),<br> remainder(BigDecimal),<br>
toPlainString(),<br> valueOf(double),<br>
valueOf(long)</code></td><td>The <code>BigDecimal.setScale(int, int)</code>
method supports negative scales<sup><a href="#3">3</a></sup>.</td></tr>
<tr><td rowspan="3"><code>java.net</code></td><td><code>URL</code></td>
<td><code>openConnection(Proxy)</code>,<br>
<code>toURI()</code>
</td><td>The <code>Proxy</code> is ignored by the <code>openConnection(Proxy)</code> method.</td></tr>
<tr><td><code>Proxy</code></td><td>*</td><td> </td></tr>
<tr><td><code>ProxySelector</code></td><td>*</td><td> </td></tr>
<tr><td ><code>java.rmi.server</code></td><td><code>RemoteObjectInvocationHandler</code></td>
<td>*</td><td> </td></tr>
<tr><td ><code>java.text</code></td><td><code>DecimalFormat</code></td>
<td><code>isParseBigDecimal()<sup><a href="#3">3</a></sup>,<br>
setParseBigDecimal(boolean)<sup><a href="#3">3</a></sup></code></td><td>
<code>BigDecimal</code> parsing and formatting precision is limited by
<code>java.lang.Double</code> or <code>java.lang.Long</code> precision.
</td></tr>
<tr><td><code>java.util.nio</code></td><td><code>CharBuffer</code></td><td>
<code>append(CharSequence),<br> append(CharSequence, int, int),<br> append(char),<br> read(CharBuffer)</code>
</td><td> </td></tr>
<tr><td rowspan="10"><code>java.util</code></td><td><code>AbstractQueue<sup><a href="#1">1</a></sup></code></td>
<td>*</td><td> </td></tr>
<tr><td><code>Arrays</code></td><td>* (21 new methods)</td><td> </td></tr>
<tr><td><code>Collections<sup><a href="#1">1</a></sup></code></td><td>* (13 new methods)<br>
newSetFromMap(Map)<sup><a href="#4">4</a></sup>
</td><td> </td></tr>
<tr><td><code>EnumMap</code></td><td>*</td><td> </td></tr>
<tr><td><code>EnumSet</code></td><td>*</td><td> </td></tr>
<tr><td><code>Formatter</code></td><td>*</td><td> </td></tr>
<tr><td><code>LinkedList</code></td><td>* (5 new methods)</td><td> </td></tr>
<tr><td><code>PriorityQueue<sup><a href="#1">1</a></sup></code></td><td>*</td><td> </td></tr>
<tr><td><code>Queue<sup><a href="#1">1</a>,<a href="#2">2</a></sup></code></td><td>*</td><td> </td></tr>
<tr><td><code>UUID</code></td><td>*</td><td> </td></tr>
<tr><td rowspan="3"><code>java.util.regex</code></td><td><code>Matcher</code></td><td>
<code>quoteReplacement(String),<br> toMatchResult()</code></td><td> </td></tr>
<tr><td><code>MatchResult<sup><a href="#2">2</a></sup></code></td><td>*</td><td> </td></tr>
<tr><td><code>Pattern</code></td><td><code>quote(String)</code></td><td> </td></tr>
</table>
<p>
<a name="1"><sup>1</sup></a> Supported via the
<a href="http://dcl.mathcs.emory.edu/util/backport-util-concurrent/index.php"> Backport of JSR 166</a>.<br>
<a name="2"><sup>2</sup></a> In most cases this type is being replaced with it's base type.<br>
<a name="3"><sup>3</sup></a> Supported only in advanced mode, i.e. when
the <code><a href="#option_advanced">advanced</a></code> option is specified.<br>
<a name="4"><sup>4</sup></a> Introduced in Java 6, but available only for 1.4 target.<br>
</p>
<h4><a name="extension">How to write an extension for Retrotranslator?</a></h4>
<p>
Since most backported classes are discovered by Retrotranslator at translation time,
you may write an extension and simply put it into the Retrotranslator classpath to make it work.
For example, all references to
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/EnumSet.html"><code>java.util.EnumSet</code></a>
are replaced with references to
<a href="http://retrotranslator.cvs.sourceforge.net/retrotranslator/Retrotranslator/src/net/sf/retrotranslator/runtime/java/util/EnumSet_.java?view=markup">
<code>net.sf.retrotranslator.runtime.java.util.EnumSet<b>_</b></code></a> (optional trailing underscore) if the latter can be found.
But if you replace a whole class that exists in J2SE 1.4 you may encounter interoperability issues with other libraries.
So, for example, support for Java 5 fields, methods, and constructors of
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/math/BigDecimal.html"><code>java.math.BigDecimal</code></a> is placed into
<a href="http://retrotranslator.cvs.sourceforge.net/retrotranslator/Retrotranslator/src/net/sf/retrotranslator/runtime/java/math/_BigDecimal.java?view=markup">
<code>net.sf.retrotranslator.runtime.java.math.<b>_</b>BigDecimal</code></a> (leading underscore):
</p>
<ul>
<li>For a static field there is a public static field with the same name and type.</li>
<li>For a static method there is a public static method with the same signature.</li>
<li>For an instance method there is a public static method with the same signature
but with an additional first parameter representing the instance.</li>
<li>For a constructor there is a public static <code>convertConstructorArguments</code> method that
accepts constructor's arguments an returns an argument for a Java 1.4 constuctor.</li>
</ul>
<p>
Another approach for constructor backporting is used by
<a href="http://retrotranslator.cvs.sourceforge.net/retrotranslator/Retrotranslator/src/net/sf/retrotranslator/runtime/java/io/_PrintStream.java?view=markup">
<code>net.sf.retrotranslator.runtime.java.io.<b>_</b>PrintStream</code></a>. There is a public static
<code>createInstanceBuilder</code> method that accepts constructor's arguments an returns an object with public
<code>argument1</code>...<code>argumentN</code> methods and optional public void <code>initialize</code> method.
All <code>argumentX</code> methods provide arguments for a Java 1.4 constuctor and should not have any parameters.
The <code>initialize</code> method has a single parameter for the created instance and may be used for postprocessing.
</p>
<p>
However, if the backported methods require access
to non-public methods or fields of the instance, they cannot be fully handled by Retrotranslator.
While you can use reflection to access any data, translated code generally should not depend on security settings.
For example, it is impossible to write an implementation for methods <code>getSource()</code>
and <code>setSource()</code> of <code>java.beans.PropertyEditorSupport</code> that will work in any environment.
Also this approach cannot be used to replace instance field references.
</p>
<p>
You can put your extensions into packages other than <code>net.sf.retrotranslator.runtime</code>.
For example, specify the following at the command line to make Retrotranslator use
<code>com.mycompany.internal.java.lang._String</code> and to rewrite all references to
<code>com.sun.org.apache.xerces.internal.*</code> with <code>org.apache.xerces.*</code>:<br>
<code>-backport com.mycompany.internal;com.sun.org.apache.xerces.internal:org.apache.xerces</code>
</p>
<p>
If you have written an extension that does not contain copyrighted code, you may send
a <a href="http://sourceforge.net/tracker/?group_id=153566&atid=788281">patch</a>
under the <a href="#license">Retrotranslator license</a>.
</p>
<h4><a name="limitations">What are the limitations?</a></h4>
<p>
Basically, only classes, methods, and fields listed <a href="#supported">above</a> should work, and other features,
like formatted input, are not supported. Known issues:
</p>
<ul>
<li>Reflection-based tools may be unable to discover additional classes and methods introduced in Java 5 when running on JRE 1.4.</li>
<li>Some applications enable all features only if they detect Java 5, so you may need to override system properties:<br>
<code> java -Djava.version=1.5.0 -Djava.specification.version=1.5 -Djava.class.version=49.0 ...</code></li>
<li>Translated code running on JRE 5.0 may be incompatible with other Java 5 code when Java 5 API is used.</li>
<li>Reflection on generics and metadata may return incomplete information for dynamically generated classes.</li>
<li>Constants inlined by a compiler and access modifiers are ignored during the verification.</li>
<li>Inherited methods introduced in Java 5 may not work, however upcasting may help in some cases:<br>
<code> ((Writer) new FileWriter("file.tmp")).append("Hello").close();</code></li>
<li>Serialized objects produced by translated code may be incompatible with JRE 5.0.</li>
</ul>
<h4><a name="alternative">Alternative tools</a></h4>
<ul>
<li><a href="http://retroweaver.sourceforge.net/">Retroweaver</a>
- a Java bytecode weaver that enables you to take advantage
of the new 1.5 language features in your source code,
while still retaining compatibility with 1.4 virtual machines.</li>
<li><a href="http://tinyurl.com/r8xba">Declawer</a>
- a customized Java compiler which reduces 1.5 Generics to equivalent 1.4 syntax.</li>
</ul>
<h4><a name="contact">Contact</a></h4>
<ul>
<li><a href="http://retrotranslator.sourceforge.net/">Latest documentation</a></li>
<li><a href="http://sourceforge.net/forum/forum.php?forum_id=513539">Open discussion</a></li>
<li><a href="http://sourceforge.net/forum/forum.php?forum_id=513540">Help</a></li>
<li><a href="http://sourceforge.net/tracker/?group_id=153566&atid=788279">Bugs</a></li>
<li><a href="http://sourceforge.net/tracker/?group_id=153566&atid=788282">Feature requests</a></li>
<li><a href="http://sourceforge.net/users/tarasp/">Author</a></li>
</ul>
<h4><a name="license">License</a></h4>
<pre>
Retrotranslator: a Java bytecode transformer that translates Java classes
compiled with JDK 5.0 into classes that can be run on JVM 1.4.
Copyright (c) 2005 - 2007 Taras Puchko
All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
3. Neither the name of the copyright holders nor the names of its
contributors may be used to endorse or promote products derived from
this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
THE POSSIBILITY OF SUCH DAMAGE.
</pre>
</body>
</html>