Return-Path:
+ 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 ASM bytecode manipulation framework and the
+ backport of concurrency utilities.
+ The full command line syntax: The command line syntax:
-
- Retrotranslator
+
+
+
+
Contents
-
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?
-
-myclasses
.
+ Compile your classes with Java 5 or later and put them into some directory, e.g. myclasses
.
@@ -72,235 +77,179 @@
backport-util-concurrent-n.n.jar
into the classpath of your application.
+
java -jar retrotranslator-transformer-n.n.n.jar <options>
or
- java -cp retrotranslator-transformer-n.n.n.jar net.sf.retrotranslator.transformer.Retrotranslator <options>
java -cp retrotranslator-transformer-n.n.n.jar
+ net.sf.retrotranslator.transformer.Retrotranslator <options>
Option | Description | Default |
---|---|---|
-srcdir |
- The directory with classes that should be translated (may be specified several times). | -- | -
-srcjar |
- The directory with classes that should be translated (may be specified several times). | -- | -
-destdir |
- The directory to place translated classes. | -Location of sources | -
-destjar |
- The JAR file to place translated classes. | -Location of sources | -
-advanced |
- Whether to use alternative implementations of Java 1.4 classes and methods for better Java 5 compatibility. | -Off | -
-verify |
- Asks the translator to examine translated bytecode for references to classes, methods, or fields - that cannot be found in the provided classpath. | -Off | -
-classpath |
- The classpath for verification including rt.jar , jce.jar ,
- jsse.jar (from JRE 1.4), retrotranslator-runtime-n.n.n.jar ,
- and backport-util-concurrent-n.n.jar . |
- Current classpath | -
-srcmask |
- The wildcard pattern specifying files that should be translated (either bytecode or UTF-8 text),
- e.g. "*.class;*.tld ". There are three special characters: "*?; ".
- |
- *.class | -
-embed |
- Package name for a private copy of retrotranslator-runtime-n.n.n.jar and
- backport-util-concurrent-n.n.jar to be put into -destdir or -destjar .
- This makes your application independent of other versions of Retrotranslator present in the classpath.
- |
- - | -
-backport |
- Informs the translator about user-defined backport packages. - Package names should be separated by semicolons. | -- | -
-target |
- To make Java 6 classes compatible with Java 5 set this option to 1.5 and supply
- user-defined backport packages via the backport option. |
- 1.4 | -
-lazy |
- Asks the translator to only transform classes compiled with a target greater than the current one. |
- Off | -
-stripsign |
- Asks the translator to strip signature (generics) information. | -Off | -
-verbose |
- Asks the translator for verbose output. | -Off | -
-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 | -
Option | +Description | +Default | +
-srcdir <path> |
+ The directory with the files to process (may be specified several times). | +- | +
-srcjar <file> |
+ The JAR archive file with the files to process (may be specified several times). | +- | +
-destdir <path> |
+ The directory to place processed files. | +The source directory. | +
-destjar <file> |
+ The JAR archive file to place processed files. | +The source JAR file. | +
-srcmask <mask> |
+ The wildcard pattern specifying the files to transform rather than copy
+ (classes or UTF-8 text files), e.g. *.class;?*.tld .
+ |
+ *.class |
+
-target <version> |
+ 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 backport classes may be used for other targets as well. + | +1.4 |
+
-classpath <path> |
+ 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: rt.jar ,
+ jce.jar , jsse.jar , retrotranslator-runtime-n.n.n.jar ,
+ and backport-util-concurrent-n.n.jar .
+ This option may be omitted if the current Java environment matches the target one.
+ |
+ The current classpath. | +
-verify |
+ Asks the translator to examine translated bytecode for references to classes, methods, or fields + that cannot be found in the classpath. + | +false |
+
-support <features> |
+ Enables advanced features. The names specified should be separated with semicolons, e.g.
+ ThreadLocal.remove;BigDecimal.setScale .
+ |
+ - | +
-advanced |
+ Enables all advanced features at once, but it's recommended to enable only required features + in order to avoid compatibility issues. + | +false |
+
-smart |
+ Makes all backport classes inheritable provided that the classpath
+ correctly reflects the target environment.
+ For example, the backport of the Writer.append(String) method may be used
+ to translate the following expression: new FileWriter("file.tmp").append("Hello") .
+ |
+ false |
+
-backport <names> |
+ The backport names separated with semicolons, e.g.
+ com.myco.all;java.util:com.myco.ju;javax.net.SocketFactory:com.myco.jsse.Factory .
+ The corresponding backport classes must be present in the classpath.
+ |
+ - | +
-embed <package> |
+ The package name for a partial copy of retrotranslator-runtime-n.n.n.jar and
+ backport-util-concurrent-n.n.jar to be put along with translated classes.
+ This makes an application independent of other versions of Retrotranslator present in the classpath.
+ |
+ - | +
-lazy |
+ Asks the translator to transform and verify only the classes compiled with a target greater than the + current one. + | +false |
+
-stripsign |
+ Asks the translator to strip signature (generics) information. | +false |
+
-verbose |
+ Asks the translator for verbose output. | +false |
+
-retainapi |
+ Asks the translator to modify classes for JVM compatibility but keep use of API
+ unless the backport option is specified.
+ Any references introduced by a compiler remain unchanged, like the use of
+ java.lang.StringBuilder for string concatenation or
+ the implicit valueOf method calls for autoboxing.
+ |
+ false |
+
-retainflags |
+ Asks the translator to keep Java 5 specific access modifiers. | +false |
+
-uptodatecheck |
+ Asks the translator to skip processing of files if the destination files are newer. | +false |
+
- 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:
+ If you have myapplication5.jar
file built with Java 5 you can use the following command to produce
+ myapplication4.jar
. 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:
java -jar retrotranslator-transformer-n.n.n.jar
- -srcjar myapplication5.jar -destjar myapplication4.jar -embed com.mycompany.internal
+ -srcjar myapplication5.jar -destjar myapplication4.jar -embed com.mycompany.internal
+ Also it is recommended to specify the classpath and + verify options. In case of verification failure try the + smart and advanced options. +
The distribution contains an integrated Apache Ant task
- net.sf.retrotranslator.transformer.RetrotranslatorTask
. It has the following syntax:
Attribute | Description | Default |
---|---|---|
srcdir |
- The directory with classes that should be translated. | -- | -
srcjar |
- The directory with classes that should be translated. | -- | -
destdir |
- The directory to place translated classes. | -Location of sources | -
destjar |
- The JAR file to place translated classes. | -Location of sources | -
advanced |
- Whether to use alternative implementations of Java 1.4 classes and methods for better Java 5 compatibility. | -Off | -
verify |
- Asks the translator to examine translated bytecode for references to classes, methods, or fields - that cannot be found in the provided classpath. | -Off | -
classpath |
- The classpath for the verification, including rt.jar , jce.jar ,
- jsse.jar (from JRE 1.4), retrotranslator-runtime-n.n.n.jar ,
- and backport-util-concurrent-n.n.jar .
- |
- Current classpath | -
classpathref |
- The classpath for the verification, given as a reference to a path defined elsewhere. - | -Current classpath | -
srcmask |
- The wildcard pattern specifying files that should be translated (either bytecode or UTF-8 text),
- e.g. "*.class;*.tld ". There are three special characters: "*?; ".
- |
- *.class | -
embed |
- Package name for a private copy of retrotranslator-runtime-n.n.n.jar and
- backport-util-concurrent-n.n.jar to be put into -destdir or -destjar .
- This makes your application independent of other versions of Retrotranslator present in the classpath.
- |
- - | -
backport |
- Informs the translator about user-defined backport packages. - Package names should be separated by semicolons. | -- | -
target |
- Set this option to 1.5 and supply user-defined backport packages via
- the backport option to make Java 6 classes compatible with Java 5. |
- 1.4 | -
lazy |
- Asks the translator to only transform classes compiled with a target greater than the current one. |
- Off | -
stripsign |
- Asks the translator to strip signature (generics) information. | -Off | -
verbose |
- Asks the translator for verbose output. | -Off | -
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 | -
failonwarning |
- Indicates whether the build will fail when there are verification warnings. | -On | -
- You may use nested fileset
, jarfileset
, and dirset
elements to specify
- source files and classpath
elements to specify classpath. For example:
+
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
. For example:
<path id="classpath"> @@ -308,7 +257,7 @@ </path> <taskdef name="retrotranslator" classpathref="classpath" classname="net.sf.retrotranslator.transformer.RetrotranslatorTask" /> - <retrotranslator destdir="build/classes14" verify="true"> + <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"/> @@ -321,297 +270,690 @@ from the Mojo Project.How to use Retrotranslator from IntelliJ IDEA?
+There is a plugin to automatically translate and verify classes compiled by IntelliJ IDEA, so you can develop in Java 5 but run and debug on JRE 1.4.
-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 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 "
-target 1.4
". + In order to run a Java 5 application on J2SE 1.4 start it with JIT Retrotranslator:
java -cp retrotranslator-transformer-n.n.n.jar
- net.sf.retrotranslator.transformer.JITRetrotranslator <options> -jar <jarfile> [<args...>]
+ net.sf.retrotranslator.transformer.JITRetrotranslator
+ <options> -jar <jarfile> [<args...>]
java -cp retrotranslator-transformer-n.n.n.jar:<classpath>
- net.sf.retrotranslator.transformer.JITRetrotranslator <options> <class> [<args...>]
- JITRetrotranslator.run()
from some JVM 1.4 compatible class
- before Java 5 classes are loaded.
+ net.sf.retrotranslator.transformer.JITRetrotranslator
+ <options> <class> [<args...>]
- JIT Retrotranslator can accept the advanced
- and backport
options.
+ The options can include support
,
+ advanced
, smart
, and
+ backport
. 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.
Package | Class | Methods and fields | Compatibility notes |
---|---|---|---|
java.lang.annotation | * (all classes) | * (all methods) | |
java.lang.instrument | * (all classes) | * (all methods) | - Bytecode instrumentation is not implemented. |
java.util.concurrent, |
- almost all classes1 | almost all methods | -The LockSupport class may be unusable due to poor efficiency.
- The Condition.awaitNanos(long) method has
-
- little accuracy guarantees. |
java.io | Closeable2
- | * | |
Flushable2 | * | ||
PrintStream | + | ||
Package | +Class | +Methods and fields | +Compatibility notes | +
java.io |
+ Closeable2
+ |
+ * (all methods) | ++ |
Flushable2 |
+ * | ++ | |
PrintStream |
+ * (11 new methods and constructors) - | ||
PrintWriter | + | ++ | |
PrintWriter |
+ * (11 new methods and constructors) - | + | +
The PrintWriter.format and PrintWriter.printf methods always flush the output buffer.
- |
Reader | read(CharBuffer) | ||
Writer |
- append(CharSequence),
- | ||
java.lang | Appendable2 | * - | |
Boolean | parseBoolean(String), | ||
Byte | valueOf(byte) | ||
Character | valueOf(char) | ||
Class | * (21 new methods) |
- Class.getMethod(String, Class...) and Class.getDeclaredMethod(String, Class...)
- are intercepted to better support generics and covariant return types
- on several platforms3.
- | |
Deprecated | * | ||
Double | valueOf(double) | ||
Enum | * | ||
Float | valueOf(float) | ||
IllegalArgumentException | IllegalArgumentException(String, Throwable), | ||
IllegalStateException | IllegalStateException(String, Throwable), | ||
Integer | valueOf(int), signum(int) | ||
Iterable2 | * | ||
Long | valueOf(long), signum(long) | ||
Package | * (4 new methods) | ||
Readable2 | * | ||
Short | valueOf(short) | ||
String | contains(CharSequence), |
+||
Reader |
+ * (1 new method) | ++ | |
Writer |
+ * (3 new methods) | ++ | |
java.lang |
+ Appendable2 |
+ * + | ++ |
Boolean |
+ * (2 new methods) | ++ | |
Byte |
+ * (1 new method) | ++ | |
Character |
+ * (44 new methods) | +New members of Character.UnicodeBlock are not supported.
+ All supplementary code points are considered as unassigned.
+ |
+|
Class |
+ * (21 new methods) | +
+ Enable features "Class.getMethod " and "Class.getDeclaredMethod " for more
+ uniform support of generics and covariant return types on different platforms3.
+ |
+|
Deprecated |
+ * | ++ | |
Double |
+ valueOf(double) |
+ + | |
Enum |
+ * | ++ | |
Float |
+ valueOf(float) |
+ + | |
IllegalArgumentException |
+ * (2 new constructors) | ++ | |
IllegalStateException |
+ * (2 new constructors) | ++ | |
Integer |
+ valueOf(int), |
+ + | |
Iterable2 |
+ * | ++ | |
Long |
+ valueOf(long), |
+ + | |
Package |
+ * (4 new methods) | ++ | |
Readable2 |
+ * | ++ | |
Short |
+ * (2 new methods) | ++ | |
StackTraceElement |
+ * (1 new constructor) | ++ | |
String |
+ * (10 new methods and constructors)
isEmpty()4
- | ||
StringBuffer |
- StringBuffer(CharSequence), | ||
StringBuilder |
- All methods supported in StringBuffer
- | StringBuilder is replaced with StringBuffer . | |
SuppressWarnings | * | ||
System | nanoTime()1, | + | ++ |
StringBuffer |
+ * (11 new methods and constructors) | +
+ Enable feature "StringBuffer.trimToSize " to use an empty implementation of
+ the StringBuffer.trimToSize() method3.
+ |
+|
StringBuilder |
+ * | +StringBuilder is replaced with StringBuffer . |
+|
SuppressWarnings |
+ * | ++ | |
System |
+ nanoTime()1, |
+
The System.nanoTime() method precision
may vary on different platforms.
- | |
Thread | getStackTrace(), | 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. | |
Thread.State | * | ||
ThreadLocal | remove()3 |
- ThreadLocal and InheritableThreadLocal
- are replaced by corresponding classes from the runtime library.3. | |
TypeNotPresentException | * | ||
java.lang.ref |
- SoftReference | * | + | +
Thread |
+ * (8 new methods) | +
+ The Thread.getId() method does not reflect the order in which threads are created.+ The Thread.getStackTrace() and Thread.getAllStackTraces()
+ methods return non-empty stack trace only for the current thread.+ Enable feature " Thread.getState " to support the Thread.getState() method, but it may
+ be able
+ to detect only NEW , RUNNABLE and TERMINATED states.3+ Enable features " Thread.setUncaughtExceptionHandler " and
+ "Thread.setDefaultUncaughtExceptionHandler " to support exception handlers for threads
+ created by translated code (in contrast to J2SE 5.0 the default UncaughtExceptionHandler
+ takes precedence over ThreadGroup )3.
+ |
+|
Thread.State |
+ * | ++ | |
Thread.UncaughtExceptionHandler2 |
+ * | ++ | |
ThreadLocal |
+ * (1 new method) | +Enable feature "ThreadLocal.remove " to use alternative ThreadLocal
+ and InheritableThreadLocal implementations with method
+ remove() 3.
+ |
+|
TypeNotPresentException |
+ * | ++ | |
java.lang.annotation |
+ * (all classes) | +* | ++ |
java.lang.instrument |
+ * | +* | ++ Bytecode instrumentation is not implemented. + | +
java.lang.management |
+ ManagementFactory |
+
+ getPlatformMBeanServer() |
+
+ The ManagementFactory.getPlatformMBeanServer() method simply returns
+ the first registered MBeanServer or creates it when no one exists.
+ An implementation of JMX 1.2 must be present in a classpath.
+ |
+
java.lang.ref |
+ SoftReference |
+ * | +
+ Enable feature "SoftReference.NullReferenceQueue " to
+ support null for the second parameter of
SoftReference(Object,ReferenceQueue)
- supports null for the second parameter
on all platforms3.
- |
WeakReference | * | + | +|
WeakReference |
+ * | +
+ Enable feature "WeakReference.NullReferenceQueue " to
+ support null for the second parameter of
WeakReference(Object,ReferenceQueue)
- supports null for the second parameter
on all platforms3.
- | |
java.lang.reflect |
- AccessibleObject | * | |
AnnotatedElement2 | * | ||
Constructor | * (11 new methods) | ||
Field | * (8 new methods) | ||
GenericArrayType | * | ||
GenericDeclaration2 | * | ||
GenericSignatureFormatError | * | ||
MalformedParameterizedTypeException | * | ||
Method | * (14 new methods) | ||
ParameterizedType | * | ||
Type2 | * | ||
TypeVariable | * | ||
WildcardType | * | ||
java.math | BigDecimal |
- BigDecimal(int), | The BigDecimal.setScale(int, int)
- method supports negative scales3. |
java.net | URL |
- openConnection(Proxy) ,- toURI()
- | The Proxy is ignored by the openConnection(Proxy) method. |
Proxy | * | ||
ProxySelector | * | ||
java.rmi.server | RemoteObjectInvocationHandler |
- * | |
java.text | DecimalFormat |
- isParseBigDecimal()3, |
- BigDecimal parsing and formatting precision is limited by
- java.lang.Double or java.lang.Long precision.
- |
java.util.nio | CharBuffer |
- append(CharSequence),
- | |
java.util | AbstractQueue1 |
- * | |
Arrays | * (21 new methods) | ||
Collections1 | * (13 new methods) - newSetFromMap(Map)4 - - | ||
EnumMap | * | ||
EnumSet | * | ||
Formatter | * | ||
LinkedList | * (5 new methods) | ||
PriorityQueue1 | * | ||
Queue1,2 | * | ||
UUID | * | ||
java.util.regex | Matcher |
- quoteReplacement(String), | |
MatchResult2 | * | ||
Pattern | quote(String) | ||
java.lang.reflect |
+ AccessibleObject |
+ * (4 new methods) | ++ |
AnnotatedElement2 |
+ * | ++ | |
Constructor |
+ * (11 new methods) | ++ | |
Field |
+ * (8 new methods) | ++ | |
GenericArrayType |
+ * | ++ | |
GenericDeclaration2 |
+ * | ++ | |
GenericSignatureFormatError |
+ * | ++ | |
MalformedParameterizedTypeException |
+ * | ++ | |
Method |
+ * (14 new methods) | ++ | |
ParameterizedType |
+ * | ++ | |
Type2 |
+ * | ++ | |
TypeVariable |
+ * | ++ | |
WildcardType |
+ * | ++ | |
java.math |
+ BigDecimal |
+
+ ZERO, ONE, TEN, |
+
+ Enable feature "BigDecimal.setScale " to support negative scales in method
+ BigDecimal.setScale(int, int) 3.
+ |
+
BigInteger |
+ TEN |
+ + | |
java.net |
+ HttpURLConnection |
+ * (6 new methods) | +
+ Enable features "HttpURLConnection.setChunkedStreamingMode ",
+ "HttpURLConnection.setFixedLengthStreamingMode "
+ to use the corresponding methods, but on Java 1.4 they will simply return.
+ Consider using alternative or writing own protocol handlers.
+ |
+
Proxy |
+ * | ++ | |
ProxySelector |
+ * | ++ | |
URL |
+ * (2 new methods) | +The Proxy is ignored by the
+ URL.openConnection(Proxy) method.
+ |
+|
URLConnection |
+ * (4 new methods) | +
+ Enable features "URLConnection.getConnectTimeout ", "URLConnection.setConnectTimeout ",
+ "URLConnection.getReadTimeout ", "URLConnection.setReadTimeout "
+ to use the corresponding methods, but on Java 1.4 they will simply return.
+ Consider using alternative or writing own protocol handlers.
+ |
+|
java.nio |
+ CharBuffer |
+ * (4 new methods) | ++ |
Charset |
+ * (1 new method) | +The Charset.defaultCharset() method returns UTF-8
+ if the default charset is unavailable (occurs on JDK 1.4.0).
+ |
+|
java.rmi.server |
+ RemoteObjectInvocationHandler |
+ * | ++ |
java.text |
+ DecimalFormat |
+ * (2 new methods) | +
+ Enable feature "DecimalFormat.setParseBigDecimal " to support the
+ DecimalFormat.setParseBigDecimal(boolean) method, but
+ parsing and formatting precision will still be limited by the java.lang.Double
+ or java.lang.Long precision3.
+ |
+
java.util |
+ AbstractQueue1 |
+ * | ++ |
ArrayDeque1,4 |
+ * | ++ | |
Arrays |
+ * (21 new methods) + copyOf(...) 4 (10 methods)+ copyOfRange(...) 4 (10 methods)
+ |
+ + | |
Collections1 |
+ * (13 new methods) + newSetFromMap(Map) 4
+ |
+ + | |
Deque1,2,4 |
+ * | ++ | |
EnumMap |
+ * | ++ | |
EnumSet |
+ * | ++ | |
Formatter |
+ * | ++ | |
LinkedList |
+ * (5 new methods) | ++ | |
PriorityQueue1 |
+ * | ++ | |
Properties |
+ * | ++ | |
Queue1,2 |
+ * | ++ | |
Timer |
+ * (3 new methods and constructors) | +
+ Enable feature "Timer.All " to use alternative Timer
+ and TimerTask implementations in order to be able to call Timer(String) ,
+ Timer(String, boolean) , and Timer.purge() 3.
+ |
+|
UUID |
+ * | ++ | |
java.util.concurrent, |
+ almost all classes1 | +almost all methods | +The LockSupport class may be unusable due to insufficient performance.
+ The Condition.awaitNanos(long) method has
+
+ little accuracy guarantees.
+ |
+
java.util.regex |
+ Matcher |
+
+ quoteReplacement(String), |
+ + |
MatchResult2 |
+ * | ++ | |
Pattern |
+ quote(String) |
+ + | |
javax.net.ssl |
+ HttpsURLConnection |
+ * (2 new methods) | ++ |
1 Supported via the
- Backport of JSR 166.
- 2 In most cases this type is being replaced with it's base type.
- 3 Supported only in advanced mode, i.e. when
- the advanced
option is specified.
- 4 Introduced in Java 6, but available only for 1.4 target.
+ Backport of JSR 166.
+ 2 In most cases this type is 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.
+
+ 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 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 may be specified via the backport 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.
Backport name form | +Example | +
---|---|
<universal backport package name> |
+ net.sf.retrotranslator.runtime |
+
<original package name>:<backport package name> |
+ java.util.concurrent:edu.emory.mathcs.backport.java.util.concurrent |
+
<original class name>:<backport class name> |
+ java.lang.StringBuilder:java.lang.StringBuffer |
+
<original method name>:<backport method name> |
+ java.lang.System.nanoTime:edu.emory.mathcs.backport.java.util.concurrent.helpers.Utils.nanoTime |
+
<original field name>:<backport field name> |
+ java.util.Collections.EMPTY_MAP:edu.emory.mathcs.backport.java.util.Collections.EMPTY_MAP |
+
- 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
+ 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_
(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
- java.math.BigDecimal
is placed into
-
+ 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
(leading underscore):
+ net.sf.retrotranslator.runtime.java.math._BigDecimal
class:
convertConstructorArguments
method that
- accepts constructor's arguments an returns an argument for a Java 1.4 constuctor.
- Another approach for constructor backporting is used by
-
- net.sf.retrotranslator.runtime.java.io._PrintStream
. There is a public static
+
convertConstructorArguments
method that
+ accepts constructor's arguments an returns an argument for a Java 1.4 constuctor.
+
+ 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 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.
+ argument1
...argumentN
methods and an optional public void initialize
method.
+ All the 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. If this approach does not work there is another flexible but not always supported one 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.
- 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, specify the following at the command line to make Retrotranslator use
- com.mycompany.internal.java.lang._String
and to rewrite all references to
- com.sun.org.apache.xerces.internal.*
with org.apache.xerces.*
:
- -backport com.mycompany.internal;com.sun.org.apache.xerces.internal:org.apache.xerces
-
- If you have written an extension that does not contain copyrighted code, you may send - a patch - under the Retrotranslator license. -
- Basically, only classes, methods, and fields listed above should work, and other features, - like formatted input, are not supported. Known issues: -
java -Djava.version=1.5.0 -Djava.specification.version=1.5 -Djava.class.version=49.0 ...
((Writer) new FileWriter("file.tmp")).append("Hello").close();
- 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. Modified: struts/struts2/trunk/backport/translate.bat URL: http://svn.apache.org/viewvc/struts/struts2/trunk/backport/translate.bat?rev=589617&r1=589616&r2=589617&view=diff ============================================================================== --- struts/struts2/trunk/backport/translate.bat (original) +++ struts/struts2/trunk/backport/translate.bat Mon Oct 29 06:12:30 2007 @@ -1,3 +1,3 @@ -java -jar retrotranslator-transformer-1.2.0.jar -advanced -srcjar ../lib/struts2-core-2.0.4.jar -destjar struts2-core-j4-2.0.4.jar -java -jar retrotranslator-transformer-1.2.0.jar -advanced -srcjar ../lib/struts2-api-2.0.4.jar -destjar struts2-api-j4-2.0.4.jar -java -jar retrotranslator-transformer-1.2.0.jar -advanced -srcjar ../lib/xwork-2.0.0.jar -destjar xwork-j4-2.0.0.jar +java -jar retrotranslator-transformer-1.2.3.jar -advanced -srcjar ../lib/struts2-core-2.1.1-SNAPSHOT.jar -destjar struts2-core-backport-2.1.1-SNAPSHOT.jar +java -jar retrotranslator-transformer-1.2.3.jar -advanced -srcjar ../lib/struts2-api-2.1.1-SNAPSHOT.jar -destjar struts2-api-backport-2.1.1-SNAPSHOT.jar +java -jar retrotranslator-transformer-1.2.3.jar -advanced -srcjar ../lib/xwork-2.1.1-SNAPSHOT.jar -destjar xwork-backport-2.1.1-SNAPSHOT.jar Modified: struts/struts2/trunk/core/pom.xml URL: http://svn.apache.org/viewvc/struts/struts2/trunk/core/pom.xml?rev=589617&r1=589616&r2=589617&view=diff ============================================================================== --- struts/struts2/trunk/core/pom.xml (original) +++ struts/struts2/trunk/core/pom.xml Mon Oct 29 06:12:30 2007 @@ -27,7 +27,7 @@org.apache.struts struts2-parent -2.1.0 +2.1.1-SNAPSHOT org.apache.struts struts2-core @@ -57,7 +57,7 @@@@ -291,7 +291,7 @@ com.opensymphony xwork -2.1.0 +2.1.1-SNAPSHOT sources Modified: struts/struts2/trunk/plugins/codebehind/pom.xml URL: http://svn.apache.org/viewvc/struts/struts2/trunk/plugins/codebehind/pom.xml?rev=589617&r1=589616&r2=589617&view=diff ============================================================================== --- struts/struts2/trunk/plugins/codebehind/pom.xml (original) +++ struts/struts2/trunk/plugins/codebehind/pom.xml Mon Oct 29 06:12:30 2007 @@ -27,7 +27,7 @@ com.opensymphony xwork -2.1.0 +2.1.1-SNAPSHOT org.apache.struts struts2-plugins -2.1.0 +2.1.1-SNAPSHOT org.apache.struts struts2-codebehind-plugin Modified: struts/struts2/trunk/plugins/config-browser/pom.xml URL: http://svn.apache.org/viewvc/struts/struts2/trunk/plugins/config-browser/pom.xml?rev=589617&r1=589616&r2=589617&view=diff ============================================================================== --- struts/struts2/trunk/plugins/config-browser/pom.xml (original) +++ struts/struts2/trunk/plugins/config-browser/pom.xml Mon Oct 29 06:12:30 2007 @@ -27,7 +27,7 @@org.apache.struts struts2-plugins -2.1.0 +2.1.1-SNAPSHOT org.apache.struts struts2-config-browser-plugin Modified: struts/struts2/trunk/plugins/dojo/pom.xml URL: http://svn.apache.org/viewvc/struts/struts2/trunk/plugins/dojo/pom.xml?rev=589617&r1=589616&r2=589617&view=diff ============================================================================== --- struts/struts2/trunk/plugins/dojo/pom.xml (original) +++ struts/struts2/trunk/plugins/dojo/pom.xml Mon Oct 29 06:12:30 2007 @@ -25,7 +25,7 @@struts2-plugins org.apache.struts -2.1.0 +2.1.1-SNAPSHOT 4.0.0 org.apache.struts Modified: struts/struts2/trunk/plugins/jasperreports/pom.xml URL: http://svn.apache.org/viewvc/struts/struts2/trunk/plugins/jasperreports/pom.xml?rev=589617&r1=589616&r2=589617&view=diff ============================================================================== --- struts/struts2/trunk/plugins/jasperreports/pom.xml (original) +++ struts/struts2/trunk/plugins/jasperreports/pom.xml Mon Oct 29 06:12:30 2007 @@ -27,7 +27,7 @@org.apache.struts struts2-plugins -2.1.0 +2.1.1-SNAPSHOT org.apache.struts struts2-jasperreports-plugin Modified: struts/struts2/trunk/plugins/jfreechart/pom.xml URL: http://svn.apache.org/viewvc/struts/struts2/trunk/plugins/jfreechart/pom.xml?rev=589617&r1=589616&r2=589617&view=diff ============================================================================== --- struts/struts2/trunk/plugins/jfreechart/pom.xml (original) +++ struts/struts2/trunk/plugins/jfreechart/pom.xml Mon Oct 29 06:12:30 2007 @@ -27,7 +27,7 @@org.apache.struts struts2-plugins -2.1.0 +2.1.1-SNAPSHOT org.apache.struts struts2-jfreechart-plugin Modified: struts/struts2/trunk/plugins/jsf/pom.xml URL: http://svn.apache.org/viewvc/struts/struts2/trunk/plugins/jsf/pom.xml?rev=589617&r1=589616&r2=589617&view=diff ============================================================================== --- struts/struts2/trunk/plugins/jsf/pom.xml (original) +++ struts/struts2/trunk/plugins/jsf/pom.xml Mon Oct 29 06:12:30 2007 @@ -27,7 +27,7 @@org.apache.struts struts2-plugins -2.1.0 +2.1.1-SNAPSHOT org.apache.struts struts2-jsf-plugin Modified: struts/struts2/trunk/plugins/pell-multipart/pom.xml URL: http://svn.apache.org/viewvc/struts/struts2/trunk/plugins/pell-multipart/pom.xml?rev=589617&r1=589616&r2=589617&view=diff ============================================================================== --- struts/struts2/trunk/plugins/pell-multipart/pom.xml (original) +++ struts/struts2/trunk/plugins/pell-multipart/pom.xml Mon Oct 29 06:12:30 2007 @@ -27,7 +27,7 @@org.apache.struts struts2-plugins -2.1.0 +2.1.1-SNAPSHOT org.apache.struts struts2-pell-multipart-plugin Modified: struts/struts2/trunk/plugins/plexus/pom.xml URL: http://svn.apache.org/viewvc/struts/struts2/trunk/plugins/plexus/pom.xml?rev=589617&r1=589616&r2=589617&view=diff ============================================================================== --- struts/struts2/trunk/plugins/plexus/pom.xml (original) +++ struts/struts2/trunk/plugins/plexus/pom.xml Mon Oct 29 06:12:30 2007 @@ -27,7 +27,7 @@org.apache.struts struts2-plugins -2.1.0 +2.1.1-SNAPSHOT org.apache.struts struts2-plexus-plugin Modified: struts/struts2/trunk/plugins/pom.xml URL: http://svn.apache.org/viewvc/struts/struts2/trunk/plugins/pom.xml?rev=589617&r1=589616&r2=589617&view=diff ============================================================================== --- struts/struts2/trunk/plugins/pom.xml (original) +++ struts/struts2/trunk/plugins/pom.xml Mon Oct 29 06:12:30 2007 @@ -27,7 +27,7 @@org.apache.struts struts2-parent -2.1.0 +2.1.1-SNAPSHOT org.apache.struts struts2-plugins Modified: struts/struts2/trunk/plugins/portlet/pom.xml URL: http://svn.apache.org/viewvc/struts/struts2/trunk/plugins/portlet/pom.xml?rev=589617&r1=589616&r2=589617&view=diff ============================================================================== --- struts/struts2/trunk/plugins/portlet/pom.xml (original) +++ struts/struts2/trunk/plugins/portlet/pom.xml Mon Oct 29 06:12:30 2007 @@ -27,7 +27,7 @@org.apache.struts struts2-plugins -2.1.0 +2.1.1-SNAPSHOT org.apache.struts struts2-portlet-plugin Modified: struts/struts2/trunk/plugins/sitegraph/pom.xml URL: http://svn.apache.org/viewvc/struts/struts2/trunk/plugins/sitegraph/pom.xml?rev=589617&r1=589616&r2=589617&view=diff ============================================================================== --- struts/struts2/trunk/plugins/sitegraph/pom.xml (original) +++ struts/struts2/trunk/plugins/sitegraph/pom.xml Mon Oct 29 06:12:30 2007 @@ -27,7 +27,7 @@org.apache.struts struts2-plugins -2.1.0 +2.1.1-SNAPSHOT org.apache.struts struts2-sitegraph-plugin Modified: struts/struts2/trunk/plugins/sitemesh/pom.xml URL: http://svn.apache.org/viewvc/struts/struts2/trunk/plugins/sitemesh/pom.xml?rev=589617&r1=589616&r2=589617&view=diff ============================================================================== --- struts/struts2/trunk/plugins/sitemesh/pom.xml (original) +++ struts/struts2/trunk/plugins/sitemesh/pom.xml Mon Oct 29 06:12:30 2007 @@ -27,7 +27,7 @@org.apache.struts struts2-plugins -2.1.0 +2.1.1-SNAPSHOT org.apache.struts struts2-sitemesh-plugin Modified: struts/struts2/trunk/plugins/spring/pom.xml URL: http://svn.apache.org/viewvc/struts/struts2/trunk/plugins/spring/pom.xml?rev=589617&r1=589616&r2=589617&view=diff ============================================================================== --- struts/struts2/trunk/plugins/spring/pom.xml (original) +++ struts/struts2/trunk/plugins/spring/pom.xml Mon Oct 29 06:12:30 2007 @@ -27,7 +27,7 @@org.apache.struts struts2-plugins -2.1.0 +2.1.1-SNAPSHOT org.apache.struts struts2-spring-plugin Modified: struts/struts2/trunk/plugins/struts1/pom.xml URL: http://svn.apache.org/viewvc/struts/struts2/trunk/plugins/struts1/pom.xml?rev=589617&r1=589616&r2=589617&view=diff ============================================================================== --- struts/struts2/trunk/plugins/struts1/pom.xml (original) +++ struts/struts2/trunk/plugins/struts1/pom.xml Mon Oct 29 06:12:30 2007 @@ -27,7 +27,7 @@org.apache.struts struts2-plugins -2.1.0 +2.1.1-SNAPSHOT org.apache.struts struts2-struts1-plugin Modified: struts/struts2/trunk/plugins/tiles/pom.xml URL: http://svn.apache.org/viewvc/struts/struts2/trunk/plugins/tiles/pom.xml?rev=589617&r1=589616&r2=589617&view=diff ============================================================================== --- struts/struts2/trunk/plugins/tiles/pom.xml (original) +++ struts/struts2/trunk/plugins/tiles/pom.xml Mon Oct 29 06:12:30 2007 @@ -27,7 +27,7 @@org.apache.struts struts2-plugins -2.1.0 +2.1.1-SNAPSHOT org.apache.struts struts2-tiles-plugin Modified: struts/struts2/trunk/pom.xml URL: http://svn.apache.org/viewvc/struts/struts2/trunk/pom.xml?rev=589617&r1=589616&r2=589617&view=diff ============================================================================== --- struts/struts2/trunk/pom.xml (original) +++ struts/struts2/trunk/pom.xml Mon Oct 29 06:12:30 2007 @@ -35,7 +35,7 @@4.0.0 org.apache.struts struts2-parent -2.1.0 +2.1.1-SNAPSHOT pom Struts 2 http://struts.apache.org/struts2