- What is Retrotranslator?
- What Java 5.0 features are supported?
- How to use Retrotranslator from the command line?
- How to use Retrotranslator from Apache Ant or Maven?
- How to use Retrotranslator from IntelliJ IDEA?
- How to produce a jar file compatible with Java 1.4?
- How to use Just-in-Time Retrotranslator?
- What API is supported on Java 1.4 and Java 1.3?
- How to write an extension?
- What are the limitations?
- Alternative tools
- Contact
- License
Retrotranslator is a tool that makes Java applications compatible with Java 1.4, Java 1.3 and other environments. It supports all Java 5.0 language features and a significant part of the Java 5.0 API on both J2SE 1.4 and J2SE 1.3. In other Java environments only the Java 5.0 features that don't depend on the new API are supported. Retrotranslator employs the ASM bytecode manipulation framework to transform compiled Java classes and the backport of the Java 5.0 concurrency utilities to emulate the Java 5.0 API.
- Generics
- Annotations
- Reflection on generics and annotations
- Typesafe enums
- Autoboxing/unboxing
- Enhanced for loop
- Varargs
- Covariant return types
- Formatted output
- Static import
- Concurrency utilities
- Collections framework enhancements
- Download (old releases on SourceForge) and unzip the binary distribution file
Retrotranslator-_n.n.n_-bin.zip, where n.n.n is the latest Retrotranslator release number. - Compile your classes with Java 5.0 or Java 6 and put them into some directory, e.g.
myclasses. - Go to the unzipped directory and execute:
java -jar retrotranslator-transformer-_n.n.n_.jar -srcdir myclasses
Use appropriate options to verify the result and for troubleshooting, e.g. -verify, -classpath, -advanced, and -smart. - Put
retrotranslator-runtime-_n.n.n_.jarandbackport-util-concurrent-_n.n_.jarinto the classpath of your application if you use the Java 5.0 API. - Run or debug the application as usual on Java 1.4.
The command line syntax:
java -jar retrotranslator-transformer-_n.n.n_.jar <options>
or
java -cp retrotranslator-transformer-_n.n.n_.jar net.sf.retrotranslator.transformer.Retrotranslator <options>
| Option | Description | Default |
|---|---|---|
|
|
The directory with the files to process (can be specified several times). | - |
|
|
The jar file with the files to process (can be specified several times). | - |
|
|
The directory to place processed files. | The source. |
|
|
The jar file to place processed files. | The source. |
|
|
The wildcard pattern specifying the files to transform rather than copy (classes or UTF-8 text files), e.g. |
|
|
The version of the JVM where the translated application should be able to run (1.1, 1.2, 1.3, 1.4, or 1.5). The Java 5.0 API is supported only for the 1.4 and 1.3 targets, but user-defined backport classes can be used for other targets as well. |
|
|
|
The dependencies of the translated classes including backport packages and jar files from the target JVM. For the 1.4 target the following files should be specified among others: |
The current classpath. | |
|
Asks the translator to examine translated bytecode for references to classes, methods, or fields that cannot be found in the classpath. Every use of Java 5.0 API will result in a warning message if the classpath contains jar files from JRE 1.4. |
|
|
|
Enables advanced features. The names specified should be separated with semicolons, e.g. |
- | |
|
Enables all advanced features at once, but it's recommended to enable only required features in order to avoid compatibility issues. |
|
|
|
Makes all backport classes inheritable provided that the classpath correctly reflects the target environment. For example, the backport of the |
|
|
|
Makes access to volatile fields of Java 5.0 classes compliant with Java 5.0 memory model at the cost of decreased performance. Highly recommended to use. |
|
|
|
Makes access to final instance fields of Java 5.0 classes compliant with Java 5.0 memory model at the cost of decreased performance. Not recommended to use. |
|
|
|
The backport names separated with semicolons, e.g. |
- | |
|
|
The unique package name for a partial copy of |
- |
|
|
Asks the translator to transform and verify only the classes compiled with a target greater than the current one. |
|
|
|
Whether to remove signature (generics) information. |
|
|
|
Whether to remove annotations and related attributes. |
|
|
|
Asks the translator for verbose output. |
|
|
|
Asks the translator to modify classes for JVM compatibility but keep use of API unless overriden with the backport option. Any references introduced by a compiler remain unchanged, like the use of |
|
|
Prevents replacement of certain types like |
|
|
|
|
Whether to keep Java 5.0 specific access modifiers. |
|
|
|
Asks the translator to skip processing of files if the destination files are newer. |
|
|
|
Setting this option to |
|
The distribution contains an Apache Ant task net.sf.retrotranslator.transformer.RetrotranslatorTask. Every command line option can be set using the corresponding attribute. In addition the source files can be specified with nested fileset, jarfileset, and dirset elements and the classpath can be set with nested classpath elements or the classpathref attribute. The source directories specified with srcdir, dirset, and the dir attribute of fileset should contain the root package of the classes. In case of warnings the build fails unless the value of the failonwarning attribute is set to false. The following script can be used to build one jar compatible with Java 1.4 and another one compatible with Java 1.3.
<taskdef name="retrotranslator" classname="net.sf.retrotranslator.transformer.RetrotranslatorTask">
<classpath>
<fileset dir="../Retrotranslator-n.n.n-bin">
<include name="retrotranslator-transformer-n.n.n.jar" />
<include name="retrotranslator-runtime-n.n.n.jar" />
<include name="backport-util-concurrent-n.n.jar" />
</fileset>
</classpath>
</taskdef>
<retrotranslator target="1.4" destjar="build/application14.jar"
smart="true" verify="true" failonwarning="false">
<fileset dir="build/classes" includes="**/*.class" />
<jarfileset dir="build/lib" includes="**/*.jar" />
<classpath>
<fileset dir="../j2sdk1.4.2_17/jre/lib" includes="**/*.jar"/>
<fileset dir="../Retrotranslator-n.n.n-bin">
<include name="retrotranslator-runtime-n.n.n.jar" />
<include name="backport-util-concurrent-n.n.jar" />
</fileset>
<fileset dir="lib" includes="**/*.jar"/>
</classpath>
</retrotranslator>
<retrotranslator target="1.3" destjar="build/application13.jar"
smart="true" verify="true" failonwarning="false">
<fileset dir="build/classes" includes="**/*.class" />
<jarfileset dir="build/lib" includes="**/*.jar" />
<classpath>
<fileset dir="../jdk1.3.1_20/jre/lib" includes="**/*.jar"/>
<fileset dir="../Retrotranslator-n.n.n-bin">
<include name="retrotranslator-runtime13-n.n.n.jar" />
<include name="backport-util-concurrent-java12-n.n.jar" />
</fileset>
<fileset dir="lib" includes="**/*.jar"/>
</classpath>
</retrotranslator>Maven users can use the Retrotranslator plugin from the Mojo Project.
There is a plugin to automatically translate and verify classes compiled by IntelliJ IDEA, so you can develop in Java 5.0 but run and debug on Java 1.4.
If you have a myapplication5.jar file built with Java 5.0 you can use the following command to produce myapplication4.jar. The jar file 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.
java -jar retrotranslator-transformer-_n.n.n_.jar -srcjar myapplication5.jar -destjar myapplication4.jar -embed com.mycompany.internal
Also it is recommended to specify the classpath, verify, and smart options. In case of verification failure try the support option.
In order to run a Java 5.0 application on Java 1.4 start it with JIT Retrotranslator using one of the following commands:
java -cp retrotranslator-transformer-_n.n.n_.jar net.sf.retrotranslator.transformer.JITRetrotranslator <options> -jar <jarfile> [<args...>]java -cp <classpath including Retrotranslator> net.sf.retrotranslator.transformer.JITRetrotranslator <options> <class> [<args...>]
The options include -support, -advanced, -smart, -backport, -syncvolatile, -syncfinal, and -keepclasslit. 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.0 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.
An asterisk designates all API members introduced in Java 5.0. Most classes and methods added in Java 1.4 and in Java 6.0 cannot be used on earlier VMs.
| Package | Class | Members | Compatibility notes |
|---|---|---|---|
|
|
|
* (all members introduced in Java 5.0) | |
|
|
* | ||
|
|
* (11 new methods and constructors) |
||
|
|
* (11 new methods and constructors) |
The |
|
|
|
* (1 new method) |
||
|
|
* (3 new methods) |
||
|
|
|
* | |
|
|
|||
|
|
* (1 new method) |
||
|
|
* (44 new methods) |
New members of |
|
|
|
* | ||
|
|
* (21 new methods) |
Enable feature " |
|
|
|
* |
||
|
|
|
||
|
|
* | ||
|
|
|
||
|
|
* (2 new constructors) |
||
|
|
* (2 new constructors) |
||
|
|
|
||
|
|
* | ||
|
|
|
||
|
|
|
The quality of computation may be insufficient for applications of certain types. | |
|
|
* (4 new methods) |
Enable feature " |
|
| * | |||
|
|
* (2 new methods) |
||
|
|
* (1 new constructor) |
||
|
|
* (10 new methods and constructors) |
Enable features " |
|
|
|
* (11 new methods and constructors) |
Enable feature " |
|
|
|
* |
|
|
|
|
* | ||
|
|
|
The |
|
|
|
* (8 new methods) |
The |
|
|
|
* | ||
|
|
* | ||
|
|
* (1 new method) |
Enable feature " |
|
|
|
* | ||
|
|
|
The additional constructors and methods are available for all Java 1.3 exception classes if the -smart option has been used. |
|
|
|
* (2 new constructors) |
||
|
|
* (all classes) |
* | |
|
|
* | * | Bytecode instrumentation is not implemented. |
|
|
|
|
The |
|
|
|
* |
Enable feature " |
|
|
* |
Enable feature " |
|
|
|
|
* (4 new methods) |
|
|
|
* | ||
|
|
* (11 new methods) |
||
|
|
* (8 new methods) |
||
|
|
* | ||
|
|
* | ||
|
|
* | ||
|
|
* | ||
|
|
* (1 new method) |
||
|
|
* (14 new methods) |
||
|
|
* | ||
|
|
* | ||
|
|
* | ||
|
|
* | ||
|
|
|
|
Enable feature " |
|
|
|
||
|
|
|
* (6 new methods) |
Enable features " |
|
|
* | ||
|
|
* | ||
|
|
Enable feature " |
||
|
|
* (2 new methods) |
The |
|
|
|
* (4 new methods) |
Enable features " |
|
|
|
|
* (4 new methods) |
|
|
|
* (1 new method) |
The |
|
|
|
|
* | |
|
|
|
* (2 new methods) |
Enable feature " |
|
|
|
* | |
| * | |||
|
|
* (21 new methods) |
||
|
|
|||
|
|
* (13 new methods) |
||
| * | |||
|
|
* | ||
|
|
* | ||
|
|
* | ||
|
|
* (5 new methods) |
||
|
|
* | ||
|
|
* |
Requires an implementation of JAXP 1.3 for J2SE 1.3. |
|
| * | |||
|
|
* (3 new methods and constructors) |
Enable feature " |
|
|
|
* | ||
|
|
almost all classes1 |
almost all methods |
The |
|
|
|
|
|
|
|
* | ||
|
|
|
Enable features " |
|
|
|
|
* (2 new methods) |
1 Supported via the Backport of JSR 166.
2 In most cases this type is being replaced with its base type.
3 Supported only when the corresponding feature is enabled via the -support or -advanced options.
4 Introduced in Java 6.
5 Not supported on J2SE 1.3.
6 Introduced in Java 1.4 and supported on J2SE 1.3.
In order to support the API unavailable on the target platform Retrotranslator should be able to replace all references to new classes, constructors, methods, and fields with references to backports compatible with the platform. The location of the backports must be specified with the classpath option. The default backports for the 1.4 target have been packaged into the retrotranslator-runtime-_n.n.n_.jar and backport-util-concurrent-_n.n_.jar files, and to complement or override them additional backport names can be specified via the backport option or a properties file. The backport names can have five different forms, the first one declares a universal backport package and the others allow reusing existing backports.
| Backport name form | Example |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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, net.sf.retrotranslator.runtime.java.util.EnumSet**_** is a complete backport of java.util.EnumSet. 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 net.sf.retrotranslator.runtime.java.math.**_**BigDecimal class:
- For a static field there is a public static field with the same name and type.
- For a static method there is a public static method with the same signature.
- For an instance method there is a public static method with the same signature but with an additional first parameter representing the instance.
- For a constructor there is a public static
convertConstructorArgumentsmethod that accepts constructor's arguments and returns an argument for a Java 1.4 constructor.
The net.sf.retrotranslator.runtime.java.io.**_**PrintStream and net.sf.retrotranslator.runtime.java.lang.**_**SecurityException classes use another type of constructor backports. There is a public static createInstanceBuilder method that accepts constructor's arguments an returns an object with public argument1...argumentN methods and an optional public void initialize method. All the argumentX methods don't have any parameters and provide arguments for a constructor that exists on the target platform. The initialize method has a single parameter for the created instance and can be used for postprocessing. And the most flexible but unsupported in certain cases way has been used by net.sf.retrotranslator.runtime.java.lang.**_**StackTraceElement.
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 net.sf.retrotranslator.runtime.java.lang.**_**Thread for an example.
- The Java 5.0 memory model is not fully supported even with the syncvolatile and syncfinal options if the fields are being accessed via reflection.
- Only the classes, methods, and fields listed above should work and the other features, like formatted input, are not supported.
- The Java 1.4 compilers and applications performing bean introspection may fail to work correctly with covariant return types.
- The backported implementation of the Java 5.0 API is not interoperable with the original implementation.
- Reflection-based tools may be unable to discover the backported implementation of the Java 5.0 API.
- The Java 5.0 reflection methods may return incomplete information for dynamically generated classes.
- The constants inlined by a compiler and access modifiers are ignored during the verification.
Copyright (c) 2005 - 2009 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.