test

JDK for Solaris Developer's Guide

Incompatibilities in the Java 2 Platform Standard Edition 5 (since 1.4.2)

J2SE 5 is strongly compatible with previous versions of the Java 2 Platform. Almost all existing programs should run on J2SE 5 without modification. However, there are some minor potential source and binary incompatibilities in the JRE and JDK that involve rare circumstances and corner cases that we are documenting here for completeness.

  1. Generification - Generification is the process of adding generic type parameters and arguments to existing classes and methods in a manner that's consistent with the specifications of those classes. JSR 14 specified the generification of many of the core libraries, in particular the collection classes and the Class class. In the 1.5 Beta 2 release, the effect of the core generification was propagated throughout the rest of the platform wherever possible.

    Most source code that uses generified classes, constructors, methods, and fields will continue to compile in 1.5, though some will not. The simplest workaround for code that fails to compile due to the generification changes is to specify -source 1.4 on the javac command line.

    For information about generics and the core generification, see JSR 14 and the generics tutorial (at http://java.sun.com/j2se/1.5/pdf/generics-tutorial.pdf).

  2. Virtual Machine - Previously, the default virtual machine (VM) for Solaris/SPARC was the client VM. However, many Solaris/SPARC boxes are used as servers, on which the server VM is more appropriate for performance reasons. Thus, as of 1.5, server-class Solaris/SPARC machines run the server VM by default. In general, the throughput of the server VM is much better than the client VM, but the startup time is somewhat worse. A server-class machine is currently defined to be one with 2 or more processors and 2 or more gigabytes of memory.

    For more information, see Server-Class Machine Detection (at http://java.sun.com/j2se/1.5.0/docs/guide/vm/server-class.html) and Garbage Collection Ergonomics at (http://java.sun.com/j2se/1.5.0/docs/guide/vm/gc-ergonomics.html).

  3. Virtual Machine - To reflect the class sharing feature introduced in 1.5, the java.vm.info property (which is reflected in the text displayed by java -version) now specifies the sharing mode. Any code that parses all the way to the end of the java.vm.info property value or the output of java -version might need to be changed.

    For more information, see bug 4964160 and Class Data Sharing (at http://java.sun.com/j2se/1.5.0/docs/guide/vm/class-data-sharing.html).

  4. Class Loader - Previously, it was possible to specify a non-binary class name to ClassLoader methods that take a String class name argument. This unintended behaviour was not compliant with the long-standing specification of class names. As of 1.5, parameter checking of these ClassLoader methods has been modified to comply with the specification, and any class name that is not a binary name is treated like any other unrecognized class name. Since the APIs that explicitly require or return class names (for example, Class.forName or Class.getName) use the binary name for reference types, it is unlikely that the typical user would have produced a class name that would have returned a Class.

    For more information, see the definition of binary name (at http://java.sun.com/docs/books/jls/second_edition/html/binaryComp.doc.html#59876) in the Java Language Specification, Second Edition (at http://java.sun.com/docs/books/jls/). Also see the evaluation of bug 4986512.

  5. Serialization - Changes in compiler-generated synthetics affect the default serial version UID, and therefore can cause serialization incompatibility when that UID is not explicitly overridden.

    For more information, see bug 4786115.

  6. Logging - Previously, the java.util.logging.Level(String name, int value, String resourceBundleName) constructor allowed a null name argument, but the parse method did not. In 1.5, the constructor now throws a NullPointerException when the name is null. The compatibility risk is mitigated in that you had to subclass Level to use this constructor and would get a NullPointerException when using a Level name of null for subsequent calls, except for simple calls such as toString.

    For more information, see bug 4625722.

  7. Apache - The org.apache classes, which have never been supported J2SE APIs but are used by the javax.xml package, have moved in 1.5 to com.sun.org.apache.package.internal so that they won't clash with more recent, developer-downloaded versions of the classes. Any applications that depend on the org.apache classes being part of the J2SE release must do one of the following to work in 1.5:

    • Code the application so it uses only the supported interfaces that are part of JAXP.

    • Download the org.apache.xalan classes from Apache.

    For more information, see bug 4740355.

  8. JAXP - The J2SE 1.4 platform included JAXP 1.1 (Crimson). The J2SE 1.5 platform includes JAXP 1.3 (Xerces). Crimson and Xerces are not simply different versions of the same codebase. Instead, they are entirely different implementations of the JAXP standard. So, while they both conform to the JAXP standard, there are some subtle differences between them.

    Although Crimson was small and fast, it was ultimately less functional than Xerces (an open-source implementation hosted at Apache). In addition, the JAXP standard has evolved from 1.1 to 1.3. These two factors combine to create compatibility issues.

    For details, see the JAXP Compatibility Guide for 1.5 at http://java.sun.com/j2se/1.5.0/docs/guide/xml/jaxp/JAXP-Compatibility_150.html.

  9. JAXP - The J2SE 1.4 platform supported the DOM Level 2 API. The J2SE 1.5 platform supports the DOM Level 3 family of APIs. New methods have been added to DOM Level 3 interfaces, so some existing applications using DOM Level 2 will not be able to compile with the new interfaces.

    Many DOM Level 2 applications will run if DOM Level 3 is substituted for DOM Level 2 in the class path; however, a small number will encounter a NoSuchMethodException. Therefore, some applications will not have binary compatibility.

    For details, see the JAXP Compatibility Guide for 1.5 at http://java.sun.com/j2se/1.5.0/docs/guide/xml/jaxp/JAXP-Compatibility_150.html.

  10. JAXP - The J2SE 1.4 platform supported the SAX 2.0 API. The J2SE 1.5 platform supports SAX 2.0.2. In general, SAX 2.0.2 is a bug-fix release, with no API changes. However, a few clarifications done as part of SAX 2.0.2 release are possible compatibility issues:

    • ErrorHandler, EntityResolver, ContentHandler, and DTDHandler can now be set to null by applications. SAX 2.0 required the XML processor to throw java.lang.NullPointerException in this case. This change is relevant to the XML processor because most parsers react to null by restoring the default settings.

    • DefaultHandler is a default implementation class for various handlers including EntityResolver. The resolveEntity method implementation in DefaultHandler is now declared as throws IOException, SAXException. Previously it could throw only SAXException.

    • The addition of java.io.IOException to the list of exceptions thrown by the resolveEntity method is a source-incompatible change. Specifically, code that invokes resolveEntity might compile successfully with SAX 2.0 but fail compilation with SAX 2.0.2 because it needs to handle IOException along with SAXException.

    For details, see the JAXP Compatibility Guide for 1.5 at http://java.sun.com/j2se/1.5.0/docs/guide/xml/jaxp/JAXP-Compatibility_150.html.

  11. JAXP - Previously, Xalan was the default transformer. Since the Apache community has agreed to make XSLTC the default processor for developing XSLT 2.0, XSLTC is the default transformer as of 1.5. Compatibility risks include:

    • Xalan has bugs that XSLTC does not, and vice-versa. Application code that has taken Xalan bugs into account is likely to fail.

    • XSLTC does not support all the extensions that Xalan does. These extensions are beyond the definition of the JAXP and XSLT specifications. For those users impacted by this, the work around of downloading the Xalan classes from Apache is still available. Also, going forward we expect to be supporting more and more extensions in XSLTC.

    For more information, see the JAXP Compatibility Guide for 1.5 at http://java.sun.com/j2se/1.5.0/docs/guide/xml/jaxp/JAXP-Compatibility_150.html.

  12. 2D - Previously, passing a null Image parameter to a Graphics.drawImage method resulted in a NullPointerException. As of 1.5, it doesn't. The new behavior allows applications that worked with the Microsoft VM to work with the standard VM. Any applications that depend on the NullPointerException need to be changed so that they'll work in 1.5.

  13. AWT - Previously, only containers that were focus cycle roots could provide a focus traversal policy. As of 1.5, any container can provide a focus traversal policy; the new FocusTraversalPolicyProvider property of Container indicates whether it does.

    The focus traversal policies provided with the Java platform have been changed in 1.5 to accommodate focus traversal policy providers. Specifically, when a policy encounters a focus traversal policy provider during forward (backward) traversal, it should not treat its components as belonging to the provided focus cycle root but should use the focus traversal policy of focus traversal policy provider to get next (previous) component. If the returned component is the same as the first (last) component returned by the focus traversal policy of the focus traversal policy provider, then invoking the policy should get the next (previous) component in the cycle after (before) the focus traversal policy provider. Calculation of first and last components in focus cycle roots should use the focus traversal policies of focus traversal policy providers when necessary (when a first or last component is itself a Container and a focus traversal policy provider).

    Because this change doesn't require any new methods in focus traversal policies, third-party focus traversal policies will continue to work, although they will not support the notion of providers.

    If you have written a focus traversal policy and wish to support providers, you need to make changes similar to the ones made to the platform-provided policies in 1.5.

    For more information, see the Focus Traversal Policy Providers section at http://java.sun.com/j2se/1.5.0/docs/api/java/awt/doc-files/FocusSpec.html #FocusTraversalPolicyProviders of the focus specification, and the AWT Focus Subsystem at http://java.sun.com/j2se/1.5.0/docs/api/java/awt/doc-files/FocusSpec.html.

  14. Drag and Drop - Previously, the only drag and drop (DnD) protocol supported on X11 was the Motif DnD protocol. In 1.5, the XDND protocol is also supported, and the Motif DnD protocol has been reimplemented to not depend on the Motif library. It's possible that regressions might be caused by the difference between the new Motif DnD protocol implementation and one provided by the Motif library. However, since the Motif library's implementation is buggy, it's believed that the new implementation is at least as high in quality, as well as better supported.

    For more information, see bug 4638443.

  15. Swing - Buttons with a customized background color might require code changes to be rendered as intended with the 1.5 Java look and feel theme, Ocean. The reason is that Ocean draws a gradient on buttons, by default. If you don't want the gradient, either set the contentAreaFilled property to true or set the background to a Color that is not a UIResource. In most cases this is as simple as: button.setBackground(Color.RED); If, for some reason, you are picking up a UIResource you can create a new Color that is not a UIResource like this: button.setBackground(new Color(oldColor));

    For more information, see bug 4908404.

  16. Swing - In JTree and JList it has always been the case that the user manipulates the lead index with the keyboard. For example, if the lead is on row four in a JList and you press the up key, this moves the lead to row three and selects the item there. With these components, then, the lead is considered the focused index. They pass information to their renderers indicating whether or not to draw the focus indicator for a given index, and this is based on whether that index is the lead.

    Prior to 1.5, JTable was doing the opposite and using the anchor index in the same manner that JTree and JList use the lead. A request to correct this was made as RFE number 4759422 and eventually fixed as part of 4303294. Now JTable is consistent with JList and JTree. This could affect developers that assumed the previous behavior. For example, consider an application that needs information on what is being shown as the focused cell in a JTable, and it assumes that to be the anchor. While this would be correct pre-1.5, it could now result in determining one index to be focused, when in reality some other index is displaying the focus rectangle.

    For more information, see bugs 4759422 and 4303294.

  17. JVMDI - As of 1.5 the Java Virtual Machine Debug Interface (JVMDI) is deprecated. JVMDI will be removed in the next major release. Any new development should use JVMTI. Existing tools should begin moving to JVMTI.

    For more information, see the JVMTI documentation (at http://java.sun.com/j2se/1.5.0/docs/guide/jvmti/index.html).

  18. JVMPI - As of 1.5 the Java Virtual Machine Profiling Interface (JVMPI) is deprecated. JVMPI will be removed in the next major release. Any new development should use JVMTI. Existing tools should begin moving to JVMTI.

    For more information, see the JVMTI documentation at http://java.sun.com/j2se/1.5.0/docs/guide/jvmti/index.html.