mirror of
https://github.com/apache/struts.git
synced 2026-08-31 19:35:40 +00:00
Antonio Petrelli
8dfaa6dd90
Fixed subversion properties. git-svn-id: https://svn.apache.org/repos/asf/struts/struts2/trunk@590812 13f79535-47bb-0310-9956-ffa450edef68
<!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"><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>
<td width="10">
</td>
<td width="127"><a href="http://www.jetbrains.com/idea/"><img
src="http://www.jetbrains.com/idea/opensource/img/banners/idea125x37_white.gif"
width="127" height="37" border="0" alt="The best Java IDE"/></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="#jarfile">How to produce a JAR file compatible with J2SE 1.4?</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 API is supported on J2SE 1.4?</a></li>
<li><a href="#extension">How to write an extension?</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>
<p>
Retrotranslator is a tool that makes Java applications compatible with various versions of the Java platform.
It supports all Java 5 language features and a significant part of Java 5 API on J2SE 1.4. In other Java
environments only the Java 5 language features that does not require new API are supported.
Retrotranslator is based on the <a href="http://asm.objectweb.org/">ASM</a> bytecode manipulation framework and the
<a href="http://dcl.mathcs.emory.edu/util/backport-util-concurrent/index.php">backport</a> of concurrency utilities.
</p>
<h4><a name="features">What Java 5 features are supported?</a></h4>
<ul>
<li>Generics</li>
<li>Annotations</li>
<li>Reflection on generics and annotations</li>
<li>Typesafe enums</li>
<li>Autoboxing/unboxing</li>
<li>Enhanced for loop</li>
<li>Varargs</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 Java 5 or later 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.
</li>
</ol>
<p><a name="syntax">The 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 <path></code></td>
<td>The directory with the files to process (may be specified several times).</td>
<td>-</td>
</tr>
<tr>
<td nowrap><code>-srcjar <file></code></td>
<td>The JAR archive file with the files to process (may be specified several times).</td>
<td>-</td>
</tr>
<tr>
<td nowrap><code>-destdir <path></code></td>
<td>The directory to place processed files.</td>
<td>The source directory.</td>
</tr>
<tr>
<td nowrap><code>-destjar <file></code></td>
<td>The JAR archive file to place processed files.</td>
<td>The source JAR file.</td>
</tr>
<tr>
<td nowrap><code>-srcmask <mask></code></td>
<td>The wildcard pattern specifying the files to transform rather than copy
(classes or UTF-8 text files), e.g. <code>*.class;?*.tld</code>.
</td>
<td><code>*.class</code></td>
</tr>
<tr>
<td nowrap><a name="option_target"><code>-target <version></code></a></td>
<td>The version of the JVM where classes should be able to run. The supported targets are
1.1, 1.2, 1.3, 1.4, and 1.5. While API support is available only for the 1.4 target,
user-defined <a href="#option_backport">backport</a> classes may be used for other targets as well.
</td>
<td><code>1.4</code></td>
</tr>
<tr>
<td nowrap><a name="option_classpath"><code>-classpath <path></code></a></td>
<td>The dependencies of the translated classes, including the target JVM and Retrotranslator itself.
The following files should be specified among others if the target is Sun JRE 1.4: <code>rt.jar</code>,
<code>jce.jar</code>, <code>jsse.jar</code>, <code>retrotranslator-runtime-<i>n.n.n</i>.jar</code>,
and <code>backport-util-concurrent-<i>n.n</i>.jar</code>.
This option may be omitted if the current Java environment matches the target one.
</td>
<td>The current classpath.</td>
</tr>
<tr>
<td nowrap><a name="option_verify"><code>-verify</code></a></td>
<td>Asks the translator to examine translated bytecode for references to classes, methods, or fields
that cannot be found in the <a href="#option_classpath">classpath</a>.
</td>
<td><code>false</code></td>
</tr>
<tr>
<td nowrap><a name="option_support"><code>-support <features></code></a></td>
<td>Enables advanced features. The names specified should be separated with semicolons, e.g.
<code>ThreadLocal.remove;BigDecimal.setScale</code>.
</td>
<td>-</td>
</tr>
<tr>
<td nowrap><a name="option_advanced"><code>-advanced</code></a></td>
<td>Enables all advanced features at once, but it's recommended to enable only required features
in order to avoid compatibility issues.
</td>
<td><code>false</code></td>
</tr>
<tr>
<td nowrap><a name="option_smart"><code>-smart</code></a></td>
<td>Makes all backport classes inheritable provided that the <a href="#option_classpath">classpath</a>
correctly reflects the target environment.
For example, the backport of the <code>Writer.append(String)</code> method may be used
to translate the following expression: <code>new FileWriter("file.tmp").append("Hello")</code>.
</td>
<td><code>false</code></td>
</tr>
<tr>
<td nowrap><a name="option_backport"><code>-backport <names></code></a></td>
<td>The <a href="#extension">backport</a> names separated with semicolons, e.g. <code>
com.myco.all;java.util:com.myco.ju;javax.net.SocketFactory:com.myco.jsse.Factory</code>.
The corresponding backport classes must be present in the <a href="#option_classpath">classpath</a>.
</td>
<td>-</td>
</tr>
<tr>
<td nowrap><code>-embed <package></code></td>
<td>The package name for a partial 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 along with translated classes.
This makes an application independent of other versions of Retrotranslator present in the classpath.
</td>
<td>-</td>
</tr>
<tr>
<td nowrap><code>-lazy</code></td>
<td>Asks the translator to transform and verify only the classes compiled with a target greater than the
<a href="#option_target">current</a> one.
</td>
<td><code>false</code></td>
</tr>
<tr>
<td nowrap><code>-stripsign</code></td>
<td>Asks the translator to strip signature (generics) information.</td>
<td><code>false</code></td>
</tr>
<tr>
<td nowrap><code>-verbose</code></td>
<td>Asks the translator for verbose output.</td>
<td><code>false</code></td>
</tr>
<tr>
<td nowrap><code>-retainapi</code></td>
<td>Asks the translator to modify classes for JVM compatibility but keep use of API
unless the <a href="#option_backport">backport</a> option is specified.
Any references introduced by a compiler remain unchanged, like the use of
<code>java.lang.StringBuilder</code> for string concatenation or
the implicit <code>valueOf</code> method calls for autoboxing.
</td>
<td><code>false</code></td>
</tr>
<tr>
<td nowrap><code>-retainflags</code></td>
<td>Asks the translator to keep Java 5 specific access modifiers.</td>
<td><code>false</code></td>
</tr>
<tr>
<td nowrap><code>-uptodatecheck</code></td>
<td>Asks the translator to skip processing of files if the destination files are newer.</td>
<td><code>false</code></td>
</tr>
</table>
<h4><a name="jarfile">How to produce a JAR file compatible with J2SE 1.4?</a></h4>
<p>
If you have <code>myapplication5.jar</code> file built with Java 5 you can use the following command to produce
<code>myapplication4.jar</code>. It will be compatible with Java 1.4 and independent of Retrotranslator because
backport 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>
<p>
Also it is recommended to specify the <a href="#option_classpath">classpath</a> and
<a href="#option_verify">verify</a> options. In case of verification failure try the
<a href="#option_smart">smart</a> and <a href="#option_advanced">advanced</a> options.
</p>
<h4><a name="ant">How to use Retrotranslator from Apache Ant or Maven?</a></h4>
<p>The distribution contains an <a href="http://ant.apache.org/">Apache Ant</a> task
<code>net.sf.retrotranslator.transformer.RetrotranslatorTask</code>. Every <a href="#commandline">command line</a>
option can be set using the corresponding attribute. In addition the source files can be specified with nested
<code>fileset</code>, <code>jarfileset</code>, and <code>dirset</code> elements and the
<a href="#option_classpath">classpath</a> can be set with nested <code>classpath</code>
elements or the <code>classpathref</code> attribute.
The source directories specified with <code>srcdir</code>, <code>dirset</code>,
and the <code>dir</code> attribute of <code>fileset</code> should contain the root package of the classes.
In case of warnings the build fails unless the value of
the <code>failonwarning</code> attribute is set to <code>false</code>. 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" failonwarning="false">
<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>
In order to run a Java 5 application on J2SE 1.4 start it with JIT Retrotranslator:
</p>
<ul>
<li>
<code>java -cp retrotranslator-transformer-<i>n.n.n</i>.jar
net.sf.retrotranslator.transformer.JITRetrotranslator
<options> -jar <jarfile> [<args...>]</code>
</li>
<li>
<code>java -cp retrotranslator-transformer-<i>n.n.n</i>.jar:<classpath>
net.sf.retrotranslator.transformer.JITRetrotranslator
<options> <class> [<args...>]</code>
</li>
</ul>
<p>
The options can include <code><a href="#option_support">support</a></code>,
<code><a href="#option_advanced">advanced</a></code>, <code><a href="#option_smart">smart</a></code>, and
<code><a href="#option_backport">backport</a></code>. When running on J2SE 5.0 JIT Retrotranslator simply calls
the application, but on J2SE 1.4 it also translates classes compiled for Java 5 or later. However this capability
depends on the current JVM and the application itself, so under certain conditions JIT Retrotranslator may be unable
to translate either a JAR file or classes from the classpath or both.
</p>
<h4><a name="supported">What API is supported on J2SE 1.4?</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 rowspan="6"><code>java.io</code></td>
<td><code>Closeable<sup><a href="#2">2</a></sup></code>
</td>
<td>* (all methods)</td>
<td> </td>
</tr>
<tr>
<td><code>Flushable<sup><a href="#2">2</a></sup></code></td>
<td>*</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>* (1 new method)</td>
<td> </td>
</tr>
<tr>
<td><code>Writer</code></td>
<td>* (3 new methods)</td>
<td> </td>
</tr>
<tr>
<td rowspan="28"><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>* (2 new methods)</td>
<td> </td>
</tr>
<tr>
<td><code>Byte</code></td>
<td>* (1 new method)</td>
<td> </td>
</tr>
<tr>
<td><code>Character</code></td>
<td>* (44 new methods)</td>
<td>New members of <code>Character.UnicodeBlock</code> are not supported.
All supplementary code points are considered as unassigned.
</td>
</tr>
<tr>
<td><code>Class</code></td>
<td>* (21 new methods)</td>
<td>
Enable features "<code>Class.getMethod</code>" and "<code>Class.getDeclaredMethod</code>" for more
uniform support of generics and covariant return types on different 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>* (2 new constructors)</td>
<td> </td>
</tr>
<tr>
<td><code>IllegalStateException</code></td>
<td>* (2 new constructors)</td>
<td> </td>
</tr>
<tr>
<td><code>Integer</code></td>
<td><code>valueOf(int),<br>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),<br>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>* (2 new methods)</td>
<td> </td>
</tr>
<tr>
<td><code>StackTraceElement</code></td>
<td>* (1 new constructor)</td>
<td> </td>
</tr>
<tr>
<td><code>String</code></td>
<td>* (10 new methods and constructors)<br><code>
isEmpty()<sup><a href="#4">4</a></sup>
</code></td>
<td> </td>
</tr>
<tr>
<td><code>StringBuffer</code></td>
<td>* (11 new methods and constructors)</td>
<td>
Enable feature "<code>StringBuffer.trimToSize</code>" to use an empty implementation of
the <code>StringBuffer.trimToSize()</code> method<sup><a href="#3">3</a></sup>.
</td>
</tr>
<tr>
<td><code>StringBuilder</code></td>
<td>*</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>* (8 new methods)</td>
<td>
The <code>Thread.getId()</code> method does not reflect the order in which threads are created.<br>
The <code>Thread.getStackTrace()</code> and <code>Thread.getAllStackTraces()</code>
methods return non-empty stack trace only for the current thread.<br>
Enable feature "<code>Thread.getState</code>" to support the <code>Thread.getState()</code> method, but it may
be able
to detect only <code>NEW</code>, <code>RUNNABLE</code> and <code>TERMINATED</code> states.<sup><a
href="#3">3</a></sup><br>
Enable features "<code>Thread.setUncaughtExceptionHandler</code>" and
"<code>Thread.setDefaultUncaughtExceptionHandler</code>" to support exception handlers for threads
created by translated code (in contrast to J2SE 5.0 the default <code>UncaughtExceptionHandler</code>
takes precedence over <code>ThreadGroup</code>)<sup><a href="#3">3</a></sup>.
</td>
</tr>
<tr>
<td><code>Thread.State</code></td>
<td>*</td>
<td> </td>
</tr>
<tr>
<td><code>Thread.UncaughtExceptionHandler<sup><a href="#2">2</a></sup></code></td>
<td>*</td>
<td> </td>
</tr>
<tr>
<td><code>ThreadLocal</code></td>
<td>* (1 new method)</td>
<td>Enable feature "<code>ThreadLocal.remove</code>" to use alternative <code>ThreadLocal</code>
and <code>InheritableThreadLocal</code> implementations with method
<code>remove()</code><sup><a href="#3">3</a></sup>.
</td>
</tr>
<tr>
<td><code>TypeNotPresentException</code></td>
<td>*</td>
<td> </td>
</tr>
<tr>
<td><code>java.lang.annotation</code></td>
<td>* (all classes)</td>
<td>*</td>
<td> </td>
</tr>
<tr>
<td><code>java.lang.instrument</code></td>
<td>*</td>
<td>*</td>
<td>
Bytecode instrumentation is not implemented.
</td>
</tr>
<tr>
<td><code>java.lang.management</code></td>
<td><code>ManagementFactory</code></td>
<td>
<code>getPlatformMBeanServer()</code></td>
<td>
The <code>ManagementFactory.getPlatformMBeanServer()</code> method simply returns
the first registered <code>MBeanServer</code> or creates it when no one exists.
An implementation of JMX 1.2 must be present in a classpath.
</td>
</tr>
<tr>
<td rowspan="2"><code>java.lang.ref</code></td>
<td><code>SoftReference</code></td>
<td>*</td>
<td>
Enable feature "<code>SoftReference.NullReferenceQueue</code>" to
support <code>null</code> for the second parameter of
<code>SoftReference(Object,ReferenceQueue)</code>
on all platforms<sup><a href="#3">3</a></sup>.
</td>
</tr>
<tr>
<td><code>WeakReference</code></td>
<td>*</td>
<td>
Enable feature "<code>WeakReference.NullReferenceQueue</code>" to
support <code>null</code> for the second parameter of
<code>WeakReference(Object,ReferenceQueue)</code>
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>* (4 new methods)</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 rowspan="2"><code>java.math</code></td>
<td><code>BigDecimal</code></td>
<td>
<code>ZERO, ONE, TEN,<br>
BigDecimal(int),<br>
BigDecimal(long),<br>
BigDecimal(char[]),<br>
BigDecimal(char[], int, int),<br>
divideAndRemainder(BigDecimal),<br>
divideToIntegralValue(BigDecimal),<br>
pow(int),<br>
remainder(BigDecimal),<br>
toPlainString(),<br>
valueOf(double),<br>
valueOf(long)</code></td>
<td>
Enable feature "<code>BigDecimal.setScale</code>" to support negative scales in method
<code>BigDecimal.setScale(int, int)</code><sup><a href="#3">3</a></sup>.
</td>
</tr>
<tr>
<td><code>BigInteger</code></td>
<td><code>TEN</code></td>
<td> </td>
</tr>
<tr>
<td rowspan="5"><code>java.net</code></td>
<td><code>HttpURLConnection</code></td>
<td>* (6 new methods)</td>
<td>
Enable features "<code>HttpURLConnection.setChunkedStreamingMode</code>",
"<code>HttpURLConnection.setFixedLengthStreamingMode</code>"
to use the corresponding methods, but on Java 1.4 they will simply return.
Consider using alternative or writing own protocol handlers.
</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>URL</code></td>
<td>* (2 new methods)</td>
<td>The <code>Proxy</code> is ignored by the
<code>URL.openConnection(Proxy)</code> method.
</td>
</tr>
<tr>
<td><code>URLConnection</code></td>
<td>* (4 new methods)</td>
<td>
Enable features "<code>URLConnection.getConnectTimeout</code>", "<code>URLConnection.setConnectTimeout</code>",
"<code>URLConnection.getReadTimeout</code>", "<code>URLConnection.setReadTimeout</code>"
to use the corresponding methods, but on Java 1.4 they will simply return.
Consider using alternative or writing own protocol handlers.
</td>
</tr>
<tr>
<td rowspan="2"><code>java.nio</code></td>
<td><code>CharBuffer</code></td>
<td>* (4 new methods)</td>
<td> </td>
</tr>
<tr>
<td><code>Charset</code></td>
<td>* (1 new method)</td>
<td>The <code>Charset.defaultCharset()</code> method returns UTF-8
if the default charset is unavailable (occurs on JDK 1.4.0).
</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>* (2 new methods)</td>
<td>
Enable feature "<code>DecimalFormat.setParseBigDecimal</code>" to support the
<code>DecimalFormat.setParseBigDecimal(boolean)</code> method, but
parsing and formatting precision will still be limited by the <code>java.lang.Double</code>
or <code>java.lang.Long</code> precision<sup><a href="#3">3</a></sup>.
</td>
</tr>
<tr>
<td rowspan="14"><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>ArrayDeque<sup><a href="#1">1</a>,<a href="#4">4</a></sup></code></td>
<td>*</td>
<td> </td>
</tr>
<tr>
<td><code>Arrays</code></td>
<td>* (21 new methods)<br>
<code>copyOf(...)</code><sup><a href="#4">4</a></sup> (10 methods)<br>
<code>copyOfRange(...)</code><sup><a href="#4">4</a></sup> (10 methods)
</td>
<td> </td>
</tr>
<tr>
<td><code>Collections<sup><a href="#1">1</a></sup></code></td>
<td>* (13 new methods)<br>
<code>newSetFromMap(Map)</code><sup><a href="#4">4</a></sup>
</td>
<td> </td>
</tr>
<tr>
<td><code>Deque<sup><a href="#1">1</a>,<a href="#2">2</a>,<a href="#4">4</a></sup></code></td>
<td>*</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>Properties</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>Timer</code></td>
<td>* (3 new methods and constructors)</td>
<td>
Enable feature "<code>Timer.All</code>" to use alternative <code>Timer</code>
and <code>TimerTask</code> implementations in order to be able to call <code>Timer(String)</code>,
<code>Timer(String, boolean)</code>, and <code>Timer.purge()</code><sup><a href="#3">3</a></sup>.
</td>
</tr>
<tr>
<td><code>UUID</code></td>
<td>*</td>
<td> </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 insufficient performance.
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="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>
<tr>
<td><code>javax.net.ssl</code></td>
<td><code>HttpsURLConnection</code></td>
<td> * (2 new methods)</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 replaced with its base type.<br>
<a name="3"><sup>3</sup></a> Supported only when the corresponding feature is enabled via the
<code><a href="#option_support">support</a></code> or
<code><a href="#option_advanced">advanced</a></code> options.<br>
<a name="4"><sup>4</sup></a> Introduced in Java 6.<br>
</p>
<h4><a name="extension">How to write an extension?</a></h4>
<p>
In order to support API unavailable on the target platform Retrotranslator should be able to replace all references
to new clases, constructors, methods, and fields with references to backports compatible with the platform.
The location of the backports must be specified with the <a href="#option_classpath">classpath</a> option. The
<a href="http://retrotranslator.cvs.sourceforge.net/retrotranslator/Retrotranslator/src/net/sf/retrotranslator/registry/backport14.properties?view=markup">default</a>
backports for the 1.4 target have been packaged into the <code>retrotranslator-runtime-<i>n.n.n</i>.jar</code> and
<code>backport-util-concurrent-<i>n.n</i>.jar</code> files, and to complement or override them additional backport
names may be specified via the <a href="#option_backport">backport</a> option. The backport names may have five
different forms, the first one declares a universal backport package and the others allow to reuse existing backports.
</p>
<table border="1" cellspacing="0" cellpadding="5">
<tr>
<th>Backport name form</th>
<th>Example</th>
</tr>
<tr>
<td><code><universal backport package name></code></td>
<td><code>net.sf.retrotranslator.runtime<br>
com.mycompany.backport</code></td>
</tr>
<tr>
<td><code><original package name>:<backport package name></code></td>
<td><code>java.util.concurrent:edu.emory.mathcs.backport.java.util.concurrent<br>
com.sun.org.apache.xerces.internal:org.apache.xerces</code></td>
</tr>
<tr>
<td><code><original class name>:<backport class name></code></td>
<td><code>java.lang.StringBuilder:java.lang.StringBuffer<br>
java.util.LinkedHashMap:org.apache.commons.collections.map.LinkedMap</code></td>
</tr>
<tr>
<td><code><original method name>:<backport method name></code></td>
<td><code>java.lang.System.nanoTime:edu.emory.mathcs.backport.java.util.concurrent.helpers.Utils.nanoTime</code></td>
</tr>
<tr>
<td><code><original field name>:<backport field name></code></td>
<td><code>java.util.Collections.EMPTY_MAP:edu.emory.mathcs.backport.java.util.Collections.EMPTY_MAP</code></td>
</tr>
</table>
<p>
The names of backport classes in a universal backport package consist of the backport package name,
the name of the original class, and an optional trailing underscore. For example,
<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> is a complete backport of
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/EnumSet.html"><code>java.util.EnumSet</code></a>.
But when classes exist on the target platform then the backports of their new fields, constructors and methods are
grouped into classes with a leading underscore in their names. Look at the
<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> class:
</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>
The <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> and
<a href="http://retrotranslator.cvs.sourceforge.net/retrotranslator/Retrotranslator/src/net/sf/retrotranslator/runtime/java/lang/_SecurityException.java?view=markup">
<code>net.sf.retrotranslator.runtime.java.lang.<b>_</b>SecurityException</code></a> classes use another type of
constructor backports. 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 an optional public void <code>initialize</code> method.
All the <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. If this approach does not work there is another flexible but not always supported one used by
<a href="http://retrotranslator.cvs.sourceforge.net/retrotranslator/Retrotranslator/src/net/sf/retrotranslator/runtime/java/lang/_StackTraceElement.java?view=markup">
<code>net.sf.retrotranslator.runtime.java.lang.<b>_</b>StackTraceElement</code></a>.
If backported methods require access to non-public methods or fields of the instance, they can do it with reflection
when the security manager allows such access. The backports of public instance fields are not supported, but private
instance fields can be emulated using a weak identity map, see
<a href="http://retrotranslator.cvs.sourceforge.net/retrotranslator/Retrotranslator/src/net/sf/retrotranslator/runtime/java/lang/_Thread.java?view=markup">
<code>net.sf.retrotranslator.runtime.java.lang.<b>_</b>Thread</code></a> for an example.
</p>
<h4><a name="limitations">What are the limitations?</a></h4>
<ul>
<li>Retrotranslator does not emulate the Java 5 memory model.</li>
<li>Only the classes, methods, and fields listed <a href="#supported">above</a> should work
and the other features, like formatted input, are not supported.
</li>
<li>Java 5 reflection methods should be able to load compiled classes as resources,
so for dynamically generated classes they may return incomplete information.
</li>
<li>The backported implementation of Java 5 API may be incompatible
with the original API implementation when running on J2SE 5.0.
</li>
<li>Reflection-based tools may be unable to discover Java 5 API when running on J2SE 1.4.</li>
<li>The constants inlined by a compiler and access modifiers are ignored during the verification.</li>
</ul>
<h4><a name="alternative">Alternative tools</a></h4>
<ul>
<li><a href="http://retroweaver.sourceforge.net/">Retroweaver</a></li>
<li><a href="http://tinyurl.com/r8xba">Declawer</a></li>
<li><a href="http://wiki.jboss.org/wiki/Wiki.jsp?page=JBossRetro">JBossRetro</a></li>
</ul>
<h4><a name="contact">Contact</a></h4>
<ul>
<li><a href="http://sourceforge.net/projects/retrotranslator">Project summary</a></li>
<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>
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>