Author: husted
Date: Sun Dec 31 10:20:43 2006
New Revision: 491462
URL: http://svn.apache.org/viewvc?view=rev&rev=491462
Log:
WW-1588 Update Retotranslater utilities for backporting to J4.
Added:
struts/struts2/trunk/backport/retrotranslator-runtime-1.1.0.jar (with
props)
struts/struts2/trunk/backport/retrotranslator-transformer-1.1.0.jar (with
props)
Removed:
struts/struts2/trunk/backport/retrotranslator-runtime-1.0.7.jar
struts/struts2/trunk/backport/retrotranslator-runtime-1.0.8.jar
Modified:
struts/struts2/trunk/backport/readme.html
struts/struts2/trunk/backport/translate.bat
Modified: struts/struts2/trunk/backport/readme.html
URL:
http://svn.apache.org/viewvc/struts/struts2/trunk/backport/readme.html?view=diff&rev=491462&r1=491461&r2=491462
==============================================================================
--- struts/struts2/trunk/backport/readme.html (original)
+++ struts/struts2/trunk/backport/readme.html Sun Dec 31 10:20:43 2006
@@ -48,6 +48,7 @@
<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>
@@ -75,7 +76,7 @@
</li>
</ol>
-<p>The full command line syntax:<br>
+<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>
@@ -117,7 +118,7 @@
<td>Off</td>
</tr>
<tr>
- <td nowrap><code>-advanced</code></td>
+ <td nowrap><a name="option_advanced"><code>-advanced</code></a></td>
<td>Allows to override Java 1.4 methods for better Java 5
compatibility.</td>
<td>Off</td>
</tr>
@@ -155,6 +156,17 @@
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>
+ <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>
</table>
<p>
For example, if you have a Java 5 application
<code>myapplication5.jar</code> you can use the following command
@@ -248,6 +260,17 @@
<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>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>failonwarning</code></td>
<td>Indicates whether the build will fail when there are verification
warnings.</td>
<td>On</td>
@@ -293,18 +316,22 @@
<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 -jar
<jarfile> [<args...>]</code>
+ 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
<class> [<args...>]</code>
+ net.sf.retrotranslator.transformer.JITRetrotranslator
<options> <class> [<args...>]</code>
</li>
<li>
- Alternatively you may simply call
<code>JITRetrotranslator.install()</code> from some JVM 1.4 compatible class
+ 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 <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">
@@ -313,8 +340,9 @@
<tr><td><code>java.util.concurrent,<br>java.util.concurrent.atomic,<br>java.util.concurrent.locks</code></td>
<td>almost all classes</td><td>almost all methods</td>
<td>
- <a
href="http://dcl.mathcs.emory.edu/util/backport-util-concurrent/index.php";>
Backport of JSR 166</a><br>
- <code>Condition.awaitNanos(long)</code> method is supported but
with
+ Supported via the <a
href="http://dcl.mathcs.emory.edu/util/backport-util-concurrent/index.php";>
+ Backport of JSR 166</a>.<br>
+ The <code>Condition.awaitNanos(long)</code> method is supported
with
<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)">
very little</a> accuracy guarantees.
</td></tr>
@@ -325,20 +353,25 @@
<code>new Flushable[...]</code> is replaced with <code>new
Object[...]</code>
</td></tr>
<tr><td><code>PrintStream</code></td><td>
- <code>append(CharSequence), append(CharSequence, int, int),
append(char)</code>
+ * (11 new methods and constructors)
</td><td> </td></tr>
<tr><td><code>PrintWriter</code></td><td>
- <code>PrintWriter(File), PrintWriter(File, String),
PrintWriter(String), PrintWriter(String, String)</code>
- </td><td> </td></tr>
+ * (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), append(CharSequence, int, int),
append(char)</code>
+ <code>append(CharSequence),<br>
+ append(CharSequence, int, int),<br>
+ append(char)</code>
</td><td> </td></tr>
<tr><td
rowspan="24"><code>java.lang</code></td><td><code>Appendable</code></td><td>*
</td><td>
<code>new Appendable[...]</code> is replaced with <code>new
Object[...]</code>
</td></tr>
- <tr><td><code>Boolean</code></td><td><code>parseBoolean(String),
compareTo(Boolean)</code></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>
@@ -353,38 +386,49 @@
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)</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</code></td><td>*</td><td>
<code>new Iterable[...]</code> is replaced with <code>new
Object[...]</code>
</td></tr>
-
<tr><td><code>Long</code></td><td><code>valueOf(long)</code></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</code></td><td>*</td><td>
<code>new Readable[...]</code> is replaced with <code>new
Object[...]</code>
</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>
- replace(CharSequence, CharSequence)</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)
+ </code></td><td> </td></tr>
<tr><td><code>StringBuffer</code></td><td><code>
- StringBuffer(CharSequence), append(CharSequence), append(CharSequence,
int, int),
- insert(int, CharSequence), insert(int, CharSequence, int, int)
+ 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(),
clearProperty(String)</code></td><td>
- <a
href="http://dcl.mathcs.emory.edu/util/backport-util-concurrent/index.php";>
Backport of JSR 166</a><br>
- <code>System.nanoTime()</code> method precision
+ <tr><td><code>System</code></td><td><code>nanoTime(),<br>
clearProperty(String)</code></td><td>
+ The <code>System.nanoTime()</code> method is supported via the
+ <a
href="http://dcl.mathcs.emory.edu/util/backport-util-concurrent/index.php";>Backport
of JSR 166</a>
+ and its 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(), getId()
- </code></td><td><code>Thread.getStackTrace()</code> returns non-empty
stack trace only for the current thread;<br>
- <code>Thread.getId()</code> does not reflect the order in which
threads are created.</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>TypeNotPresentException</code></td><td>*</td><td> </td></tr>
- <tr><td
rowspan="12"><code>java.lang.reflect</code></td><td><code>AnnotatedElement</code></td><td>*</td><td>
+ <tr><td rowspan="13"><code>java.lang.reflect</code></td>
+ <td><code>AccessibleObject</code></td><td>*</td><td> </td></tr>
+ <tr><td><code>AnnotatedElement</code></td><td>*</td><td>
<code>new AnnotatedElement[...]</code> is replaced with <code>new
Object[...]</code>
</td></tr>
<tr><td><code>Constructor</code></td><td>* (11 new
methods)</td><td> </td></tr>
@@ -404,34 +448,47 @@
<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), BigDecimal(long), ZERO, ONE, TEN,
divideAndRemainder(BigDecimal),
- divideToIntegralValue(BigDecimal), pow(int),
remainder(BigDecimal), toPlainString(), valueOf(double),
- valueOf(long)</code></td><td><code>BigDecimal.setScale(int,
int)</code> supports negative scales in advanced mode.</td></tr>
-
+ <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 in advanced mode.</td></tr>
<tr><td
><code>java.rmi.server</code></td><td><code>RemoteObjectInvocationHandler</code></td>
<td>*</td><td> </td></tr>
+ <tr><td ><code>java.net</code></td><td><code>URL</code></td>
+ <td><code>toURI()</code></td><td> </td></tr>
+
<tr><td><code>java.util.nio</code></td><td><code>CharBuffer</code></td><td>
- <code>append(CharSequence), append(CharSequence, int, int),
append(char), read(CharBuffer)</code>
+ <code>append(CharSequence),<br> append(CharSequence, int, int),<br>
append(char),<br> read(CharBuffer)</code>
</td><td> </td></tr>
- <tr><td
rowspan="9"><code>java.util</code></td><td><code>AbstractQueue</code></td><td>*</td><td>
- </td></tr>
+ <tr><td
rowspan="10"><code>java.util</code></td><td><code>AbstractQueue</code></td><td>*</td><td>
+ Supported via the <a
href="http://dcl.mathcs.emory.edu/util/backport-util-concurrent/index.php";>
+ Backport of JSR 166</a>.
+ </td></tr>
<tr><td><code>Arrays</code></td><td>* (21 new
methods)</td><td> </td></tr>
<tr><td><code>Collections</code></td><td>* (13 new methods)</td><td>
- <a
href="http://dcl.mathcs.emory.edu/util/backport-util-concurrent/index.php";>
Backport of JSR 166</a>
+ Supported via the <a
href="http://dcl.mathcs.emory.edu/util/backport-util-concurrent/index.php";>
+ Backport of JSR 166</a>.
</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</code></td><td>*</td><td> </td></tr>
+ <tr><td><code>PriorityQueue</code></td><td>*</td><td>
+ Supported via the <a
href="http://dcl.mathcs.emory.edu/util/backport-util-concurrent/index.php";>
+ Backport of JSR 166</a>.
+ </td></tr>
<tr><td><code>Queue</code></td><td>*</td><td>
+ Supported via the <a
href="http://dcl.mathcs.emory.edu/util/backport-util-concurrent/index.php";>
+ Backport of JSR 166</a>.<br>
<code>new Queue[...]</code> is replaced with <code>new
Object[...]</code>
</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),
toMatchResult()</code></td><td> </td></tr>
+ <code>quoteReplacement(String),<br>
toMatchResult()</code></td><td> </td></tr>
<tr><td><code>MatchResult</code></td><td>*</td><td>
<code>new MatchResult[...]</code> is replaced with <code>new
Object[...]</code>
</td></tr>
@@ -446,24 +503,34 @@
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://cvs.sourceforge.net/viewcvs.py/retrotranslator/Retrotranslator/src/net/sf/retrotranslator/runtime/java/util/EnumSet_.java?view=markup";>
+ <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>
(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://cvs.sourceforge.net/viewcvs.py/retrotranslator/Retrotranslator/src/net/sf/retrotranslator/runtime/java/math/_BigDecimal.java?view=markup";>
+ <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 an
instance.</li>
+ 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.
@@ -472,6 +539,9 @@
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, to make Retrotranslator use
<code>com.mycompany.internal.java.lang._String</code>
+ just specify <code>-backport com.mycompany.internal</code> at the command
line.
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>.
@@ -481,14 +551,16 @@
<p>
Basically, only classes, methods, and fields listed <a
href="#supported">above</a> should work, and other features,
- like formatted input/output, are not supported. Known issues:
+ 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>Access modifiers and constants inlined by a compiler are ignored
during the verification.</li>
- <li>Upcasting may help to translate invocations of inherited methods
introduced in Java 5: <br>
+ <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>
Added: struts/struts2/trunk/backport/retrotranslator-runtime-1.1.0.jar
URL:
http://svn.apache.org/viewvc/struts/struts2/trunk/backport/retrotranslator-runtime-1.1.0.jar?view=auto&rev=491462
==============================================================================
Binary file - no diff available.
Propchange: struts/struts2/trunk/backport/retrotranslator-runtime-1.1.0.jar
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: struts/struts2/trunk/backport/retrotranslator-transformer-1.1.0.jar
URL:
http://svn.apache.org/viewvc/struts/struts2/trunk/backport/retrotranslator-transformer-1.1.0.jar?view=auto&rev=491462
==============================================================================
Binary file - no diff available.
Propchange: struts/struts2/trunk/backport/retrotranslator-transformer-1.1.0.jar
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Modified: struts/struts2/trunk/backport/translate.bat
URL:
http://svn.apache.org/viewvc/struts/struts2/trunk/backport/translate.bat?view=diff&rev=491462&r1=491461&r2=491462
==============================================================================
--- struts/struts2/trunk/backport/translate.bat (original)
+++ struts/struts2/trunk/backport/translate.bat Sun Dec 31 10:20:43 2006
@@ -1,4 +1,4 @@
-java -jar retrotranslator-transformer-1.0.8.jar -srcjar
../lib/struts2-core-2.0.0.jar -destjar struts2-core-j4-2.0.0.jar
-java -jar retrotranslator-transformer-1.0.8.jar -srcjar
../lib/struts2-api-2.0.0.jar -destjar struts2-api-j4-2.0.0.jar
-java -jar retrotranslator-transformer-1.0.8.jar -srcjar
../lib/struts2-extras-2.0.0.jar -destjar struts2-extras-j4-2.0.0.jar
-java -jar retrotranslator-transformer-1.0.8.jar -srcjar
../lib/xwork-2.0-SNAPSHOT.jar -destjar xwork-j4-2.0-SNAPSHOT.jar
+java -jar retrotranslator-transformer-1.1.0.jar -srcjar
../lib/struts2-core-2.0.2.jar -destjar struts2-core-j4-2.0.2.jar
+java -jar retrotranslator-transformer-1.1.0.jar -srcjar
../lib/struts2-api-2.0.2.jar -destjar struts2-api-j4-2.0.2.jar
+java -jar retrotranslator-transformer-1.1.0.jar -srcjar
../lib/struts2-extras-2.0.2.jar -destjar struts2-extras-j4-2.0.2.jar
+java -jar retrotranslator-transformer-1.1.0.jar -srcjar
../lib/xwork-2.0-SNAPSHOT.jar -destjar xwork-j4-2.0-RC1.jar
