Retrotranslator

SourceForge.net Logo

Contents

  1. What is Retrotranslator?
  2. What Java 5 features are supported?
  3. How to use Retrotranslator from a command line?
  4. How to use Retrotranslator from Apache Ant or Maven?
  5. How to use Retrotranslator from IntelliJ IDEA?
  6. How to use Just-in-Time Retrotranslator?
  7. What Java 5 classes and methods are supported?
  8. How to write an extension for Retrotranslator?
  9. What are the limitations?
  10. Alternative tools
  11. Contact
  12. License

What is Retrotranslator?

Retrotranslator 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 ASM bytecode manipulation framework and concurrency utilities backported to Java 1.4.

What Java 5 features are supported?

How to use Retrotranslator from a command line?

  1. Download and unzip the binary distribution file Retrotranslator-n.n.n-bin.zip, where n.n.n is the latest Retrotranslator release number.
  2. Compile your classes with JDK 5.0 and put them into some directory, e.g. myclasses.
  3. Go to the unzipped directory Retrotranslator-n.n.n-bin and execute:
    java -jar retrotranslator-transformer-n.n.n.jar -srcdir myclasses
  4. If you use Java 5 API put retrotranslator-runtime-n.n.n.jar and backport-util-concurrent.jar into the classpath of your application.
  5. Run or debug the application as usual on any JVM 1.4, preferably JRE 1.4.2.

The full 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>

OptionDescriptionDefault
-srcdir Directory with classes compiled using JDK 5.0 (may be specified several times). -
-srcjar JAR file with classes compiled using JDK 5.0 (may be specified several times). -
-destdir Directory to place classes compatible with J2SE 1.4. Location of sources
-destjar JAR file to place classes compatible with J2SE 1.4. Location of sources
-stripsign Asks the translator to strip signature (generics) information. Off
-verbose Asks the translator for verbose output. Off
-lazy Asks the translator to transform only Java 5 classes. Off
-advanced Allows to override Java 1.4 methods for better Java 5 compatibility. Off
-verify Asks the translator for warnings when references to unknown classes, methods, or fields are found. Off
-classpath The classpath to use for verification including rt.jar, jce.jar, jsse.jar (from JRE 1.4), retrotranslator-runtime-n.n.n.jar, and backport-util-concurrent.jar. Current classpath
-srcmask Files to translate (either bytecode or UTF-8 text) , e.g. "*.class;*.tld". Only three special characters are supported: "*?;". *.class
-embed Package name for a private copy of retrotranslator-runtime-n.n.n.jar and backport-util-concurrent.jar to be put into -destdir or -destjar. This makes your application independent of other versions of Retrotranslator present in the classpath. -
-retainapi 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 java.lang.StringBuilder for string concatenation or the implicit valueOf method call for autoboxing. Off
-retainflags Asks the translator to keep Java 5 specific access modifiers. Off
-backport Informs the translator about user-defined backport packages. Package names should be separated by semicolons. -

For example, if you have a Java 5 application myapplication5.jar you can use the following command to produce myapplication4.jar 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:

java -jar retrotranslator-transformer-n.n.n.jar -srcjar myapplication5.jar -destjar myapplication4.jar -embed com.mycompany.internal

How to use Retrotranslator from Apache Ant or Maven?

The distribution contains an integrated Apache Ant task net.sf.retrotranslator.transformer.RetrotranslatorTask. It has the following syntax:

AttributeDescriptionDefault
srcdir Directory with classes compiled using JDK 5.0. -
srcjar JAR file with classes compiled using JDK 5.0. -
destdir Directory to place classes compatible with J2SE 1.4. Location of sources
destjar JAR file to place classes compatible with J2SE 1.4. Location of sources
stripsign Asks the translator to strip signature (generics) information. Off
verbose Asks the translator for verbose output. Off
lazy Asks the translator to transform only Java 5 classes. Off
advanced Allows to override Java 1.4 methods for better Java 5 compatibility. Off
verify Asks the translator for warnings when references to unknown classes, methods, or fields are found. Off
classpath The classpath to use for verification including rt.jar, jce.jar, jsse.jar (from JRE 1.4), retrotranslator-runtime-n.n.n.jar, and backport-util-concurrent.jar. Current classpath
srcmask Files to translate (either bytecode or UTF-8 text) , e.g. "*.class;*.tld". Only three special characters are supported: "*?;". *.class
embed Package name for a private copy of retrotranslator-runtime-n.n.n.jar and backport-util-concurrent.jar to be put into -destdir or -destjar. This makes your application independent of other versions of Retrotranslator present in the classpath. -
retainapi 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 java.lang.StringBuilder for string concatenation or the implicit valueOf method call for autoboxing. Off
retainflags Asks the translator to keep Java 5 specific access modifiers. Off
backport Informs the translator about user-defined backport packages. Package names should be separated by semicolons. -
failonwarning Indicates whether the build will fail when there are verification warnings. On

You may use nested src elements to specify source directories or JAR files, and nested classpath elements to specify classpath for verification. For example:

    <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">
        <src path="build/classes15"/>
        <classpath location="${java14_home}/jre/lib/rt.jar"/>
        <classpath refid="classpath"/>
    </retrotranslator>

For Maven there is a Retrotranslator plugin from the Mojo Project.

How to use Retrotranslator from IntelliJ IDEA?

To automatically translate and verify classes compiled by IntelliJ IDEA you may download a plugin that generates classes compatible with 1.4 virtual machines from your Java 5 source code.

How to use Just-in-Time Retrotranslator?

JIT Retrotranslator is able to translate at runtime Java classes loaded with any classloader. It works on J2SE 1.4 from Sun, IBM, BEA, and Apple, but does nothing on J2SE 5.0 and other platforms. 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 "-target 1.4".

JIT Retrotranslator can accept -advanced and -backport options.

What Java 5 classes and methods are supported?

PackageClassMethods and fieldsCompatibility notes
java.lang.annotation* (all classes)* (all methods) 
java.util.concurrent,
java.util.concurrent.atomic,
java.util.concurrent.locks
almost all classesalmost all methods Supported via the Backport of JSR 166.
The Condition.awaitNanos(long) method is supported with very little accuracy guarantees.
java.ioCloseable* new Closeable[...] is replaced with new Object[...]
Flushable* new Flushable[...] is replaced with new Object[...]
PrintStream * (11 new methods and constructors)  
PrintWriter * (11 new methods and constructors) The PrintWriter.format and PrintWriter.printf methods always flush the output buffer.
Readerread(CharBuffer) 
Writer append(CharSequence),
append(CharSequence, int, int),
append(char)
 
java.langAppendable* new Appendable[...] is replaced with new Object[...]
BooleanparseBoolean(String),
compareTo(Boolean)
 
BytevalueOf(byte) 
CharactervalueOf(char) 
Class* (21 new methods) Class.getMethod(String, Class...) and Class.getDeclaredMethod(String, Class...) are intercepted in advanced mode to better support generics and covariant return types on several JVM implementations.
Deprecated* 
DoublevalueOf(double) 
Enum* 
FloatvalueOf(float) 
IllegalArgumentExceptionIllegalArgumentException(String, Throwable),
IllegalArgumentException(Throwable)
 
IllegalStateExceptionIllegalStateException(String, Throwable),
IllegalStateException(Throwable)
 
IntegervalueOf(int), signum(int) 
Iterable* new Iterable[...] is replaced with new Object[...]
LongvalueOf(long), signum(long) 
Package* (4 new methods) 
Readable* new Readable[...] is replaced with new Object[...]
ShortvalueOf(short) 
Stringcontains(CharSequence),
contentEquals(CharSequence),
format(Locale, String, Object...),
format(String, Object...),
replace(CharSequence, CharSequence)
 
StringBuffer StringBuffer(CharSequence),
append(CharSequence),
append(CharSequence, int, int),
insert(int, CharSequence),
insert(int, CharSequence, int, int)
 
StringBuilder All methods supported in StringBuffer StringBuilder is replaced with StringBuffer
SuppressWarnings* 
SystemnanoTime(),
clearProperty(String)
The System.nanoTime() method is supported via the Backport of JSR 166 and its precision may vary on different platforms.
ThreadgetStackTrace(),
getId()
The Thread.getStackTrace() method returns non-empty stack trace only for the current thread.
The Thread.getId() method does not reflect the order in which threads are created.
TypeNotPresentException* 
java.lang.reflect AccessibleObject* 
AnnotatedElement* new AnnotatedElement[...] is replaced with new Object[...]
Constructor* (11 new methods) 
Field* (8 new methods) 
GenericArrayType* 
GenericDeclaration* new GenericDeclaration[...] is replaced with new Object[...]
GenericSignatureFormatError* 
MalformedParameterizedTypeException* 
Method* (14 new methods) 
ParameterizedType* 
Type* new Type[...] is replaced with new Object[...]
TypeVariable* 
WildcardType* 
java.mathBigDecimal BigDecimal(int),
BigDecimal(long),
ZERO, ONE, TEN,
divideAndRemainder(BigDecimal),
divideToIntegralValue(BigDecimal),
pow(int),
remainder(BigDecimal),
toPlainString(),
valueOf(double),
valueOf(long)
The BigDecimal.setScale(int, int) method supports negative scales in advanced mode.
java.rmi.serverRemoteObjectInvocationHandler * 
java.netURL toURI() 
java.util.nioCharBuffer append(CharSequence),
append(CharSequence, int, int),
append(char),
read(CharBuffer)
 
java.utilAbstractQueue* Supported via the Backport of JSR 166.
Arrays* (21 new methods) 
Collections* (13 new methods) Supported via the Backport of JSR 166.
EnumMap* 
EnumSet* 
Formatter* 
LinkedList* (5 new methods) 
PriorityQueue* Supported via the Backport of JSR 166.
Queue* Supported via the Backport of JSR 166.
new Queue[...] is replaced with new Object[...]
UUID* 
java.util.regexMatcher quoteReplacement(String),
toMatchResult()
 
MatchResult* new MatchResult[...] is replaced with new Object[...]
Patternquote(String) 

How to write an extension for Retrotranslator?

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 java.util.EnumSet are replaced with references to net.sf.retrotranslator.runtime.java.util.EnumSet_ (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 java.math.BigDecimal is placed into net.sf.retrotranslator.runtime.java.math._BigDecimal (leading underscore):

Another approach for constructor backporting is used by net.sf.retrotranslator.runtime.java.io._PrintStream. There is a public static createInstanceBuilder method that accepts constructor's arguments an returns an object with public argument1...argumentN methods and optional public void initialize method. All argumentX methods provide arguments for a Java 1.4 constuctor and should not have any parameters. The initialize method has a single parameter for the created instance and may be used for postprocessing.

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 getSource() and setSource() of java.beans.PropertyEditorSupport that will work in any environment. Also this approach cannot be used to replace instance field references.

You can put your extensions into packages other than net.sf.retrotranslator.runtime. For example, to make Retrotranslator use com.mycompany.internal.java.lang._String just specify -backport com.mycompany.internal at the command line. If you have written an extension that does not contain copyrighted code, you may send a patch under the Retrotranslator license.

What are the limitations?

Basically, only classes, methods, and fields listed above should work, and other features, like formatted input, are not supported. Known issues:

Alternative tools

Contact

License

    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, 2006 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.