The JavaTM Tutorial

| Start of Tutorial > Start of Trail > Start of Lesson | Search Feedback Form

Trail: JDK(TM) 1.1 -- And Beyond!
Lesson: Migrating to 1.1

## JDK 1.1 Compability

### Binary Compatibility

JDK 1.1.x is upwards binary-compatible with 1.0.x except for these incompatibilities. This means that class files built with a 1.0.x compiler (such as 1.0.2) will run correctly in 1.1.x.

Downward binary compatibility is generally supported, though not guaranteed. That is, class files built with a 1.1.x compiler, but relying only on APIs defined in 1.0.x, will generally run on 1.0.x versions of the Java Virtual Machine, but this "downwards" compatibility has not been extensively tested and cannot be guaranteed. Of course, if the class files depend on any new 1.1.x APIs, those files will not work on 1.0.x systems.

In general, the JavaSoft policy is that:

- Bug-fix releases (e.g. 1.1.1, 1.1.2) within a family (1.1.x) will maintain both upward and downward binary-compatibility with each other.

- Functionality releases (e.g. 1.1, 1.2) within a family (1.x) will maintain upward but not necessarily downward binary-compatibility with each other.

- Major releases (e.g. 2.0, 3.0) will not necessarily maintain any binary compatibility.

### Source Compatibility

JDK 1.1.x is upwards source-compatible with 1.0.x, except for these incompatibilities. This means that source files written to use the language features and APIs defined for 1.0.x can be compiled in 1.1.x and will run in 1.1.x.

Downward source compatibility is not supported. If source files use new language features or APIs in JDK 1.1.x, they will not be usable with an earlier version of Java.

In general, the JavaSoft policy is that:

- Bug-fix releases do not introduce any new language features or APIs, so they maintain source-compatibility in both directions.

- Functionality releases and major releases maintain upwards but not downwards source-compatibility.

In JDK 1.1 we have introduced the concept of deprecated API. These are methods and classes that are supported only for backwards compatibility, and the compiler will generate a warning message whenever one of these is used. It is recommended that programs be modified to eliminate the use of deprecated methods and classes, but it has not been determined whether the deprecated elements will ever be removed entirely from the system.

### Incompatibilities in JDK 1.1.x

There are rare cases where upward incompatibility from 1.0.x to 1.1.x cannot be avoided. For example, occasionally an API has to be eliminated because of some potential security breach that it exposes. This affects both binary and source compatibility.

The following is intended to be a complete list of all cases where a program that works under 1.0.x would fail to work under 1.1.x. If you know of other broad areas of incompatibility, please notify us (at address at the bottom of the page).

1. Some APIs in the sun.* packages have changed. These APIs are not intended to be used directly by developers. They are there to support the java.* packages. Developers importing from sun.* do so entirely at their own risk.

2. The compiler, javac, now writes its error messages to standard error instead of standard output. This would only affect programs which exec the compiler.

3. The following methods have been changed to conform to the Java Language Specification, section 20.10.15. Previously these methods returned machine-specific results.
   in `java.io.Printstream`
   `print(double)`
   `println(double)`
   in `java.lang.Double`
   `toString`
   in `java.lang.String`
   `valueOf(double)`

   The following methods have been changed to conform to the Java Language Specification, section 20.9.16. Previously these methods returned machine-specific results.

   in `java.io.Printstream`
   `print(float)`
   `println(float)`
   in `java.lang.Float`
   `toString`
   in `java.lang.String`
   `valueOf(float)`

4. The standard input, output, and error streams `System.in`, `System.out`, and `System.err` are now `final`. Applets cannot change their values. The following methods have been added to class System so that applications, but not applets, can reassign standard in, standard out, and standard err.
   `
   public static void setIn(InputStream in)
   public static void setOut(PrintStream out)
   public static void setErr(PrintStream err)
   `

5. Several bug fixes in the AWT might result in incompatible behavior in programs that have a graphical user interface (GUI). See Incompatible Changes in the 1.1 AWT API for details.

6. The method `checkPropertyAccess(String prop, String defval)` in `java.lang.SecurityManager` has been removed in this release. It is a useless method that was inadvertently included in JDK 1.0.2; it should never have been included.

7. Invalid code that used to run in 1.0.x might not run in 1.1.x. By "invalid", we mean code that relies on 1.0.x implementation bugs that are important to fix.

   - The 1.1.2 VM contains a security bugfix to the verifier that checks that the maximum number of locals specified for a byte-compiled method is large enough to accomodate the parameters to the method. However, code generated by compilers prior to 1.0prebeta1 would not always set the maxlocals correctly. Such erroneous code will be rejected by the 1.1.2 VM with the error `java.lang.ClassFormatError: Arguments can't fit into locals`.

   - The 1.0.2 VM did not check that a class implementing an interface in fact implements all the interface's methods. The 1.1.x VM correctly checks that, and causes certain classes to fail, even though these classes can be loaded in 1.0.2. This fix is put in so that the VM now gives better error messages.

   - In JDK 1.0.2, Integer.parseInt("80000000", 16) throws a NumberFormatException. Someone used this to generate a bit mask for IP address verification. In this case, 80000000 is out of the range of integer representation. In 1.1.x, the program should use Integer.parseInt("-80000000", 16) instead.

8. The 1.0.x Java compiler used incorrect linkage semantics for invocations of super methods. In particular, the 1.0.x compiler produced code for super invocations that instructed a Java Virtual Machine to invoke exactly the specified method of the specified class, as determined by the compiler's understanding of the class hierarchy at compile time.

   Unfortunately, this meaning of super invocation does not account for binary-compatible changes to classes, such as inserting new classes into the type hierarchy, or overriding the specified method in a class between the source class and target class of the super invocation. (This bug is described in The Java Language Specification, section 13.4.5.)

   Some Java APIs in JDK 1.1 contain exactly such binary-compatible changes. As a result, 1.0.x code compiled with the incorrect super semantics can behave unpredictably on 1.1 Java Virtual Machines, if they use these APIs via super invocation. This is because the new overriding methods may be necessary for correct operation of the updated class (for example, taking a lock before invoking the next method).

   The 1.1 (non-optimizing) Java compiler uses the correct semantics for super invocations. It records the fact that it uses the correct semantics by setting a flag in a generated class file; older compilers do not set this flag. A 1.0.2 or later Java Virtual Machines uses the correct super semantics for code in a class file when it finds this flag set. In all other cases, an old or new Virtual Machine will use the old, incorrect semantics for super invocation. (The possibility that some intermediate super methods were inlined means that a Java Virtual Machine cannot attempt to "correct" the semantics of super invocation in unflagged binaries at run time.)

9. Class name resolution changed in JDK 1.1 such that classes within packages of the same name can no longer be referenced if their names aren't fully qualified in a way that make them unique.

| Start of Tutorial > Start of Trail > Start of Lesson | Search Feedback Form

Copyright 1995-2001 Sun Microsystems, Inc. All rights reserved.