Chapter 2 J2EE 1.4 Compatibility Issues
The following topics are covered in this chapter:
Binary Compatibility
In this Application Server 8.1 release, the included Java SDK is The Java™
2 Platform, Enterprise Edition (J2EE™ platform), version 1.4 SDK. This version
of the J2EE SDK is upwards binary-compatible with J2EE SDK, v1.3, except for the incompatibilities
listed below. This means that, except for the noted incompatibilities, applications
built for version 1.3 run correctly in the Sun Java System Application Server 8.1 release.
For ease of reference, the version of the J2EE SDK included in this release is referred
to throughout this section as J2EE 1.4.
Source Compatibility
Downward source compatibility is not supported. If source files use new J2EE APIs, they are
not usable with an earlier version of the J2EE platform.
In general, the policy is as follows:
-
Maintenance releases do not introduce any new APIs, so they maintain
source-compatibility with one another. However, since J2EE is based on J2SE, a new
Application Server release may include a new version of J2SE. Refer to the document
on compatibility issues in J2SE for more information:
http://java.sun.com/j2se/1.4.2/compatibility.html
-
Functionality releases and major releases maintain upwards but not
downwards source-compatibility.
Deprecated APIs are
methods and classes that are supported only for backward compatibility, and the compiler
generates a warning message whenever one of these is used, unless the -nowarn command-line
option is used. It is recommended that programs be modified to eliminate the use of
deprecated methods and classes, though there are no current plans to remove such methods
and classes entirely from the system.
Incompatibilities in the J2EE 1.4 Platform (since the J2EE
1.3 release)
The Sun Java System Application Server 8.1 release is based on the Java 2 Platform, Enterprise Edition,
version 1.4. The Sun Java System Application Server 7 release is based on the Java 2
Platform, Enterprise Edition, version 1.3.
The Sun Java System Application Server 8.1 release is strongly compatible with previous versions
of the J2EE platform. Almost all existing programs should run on the Sun Java System Application Server 8.1 release
without modification. However, there are some minor potential incompatibilities that
involve rare circumstances and corner cases that we are documenting here for completeness.
-
Java Servlet Specification Version 2.4 ships with the Sun Java System Application Server 8.1 release,
and can be downloaded from the following URL:
http://java.sun.com/products/servlet/
Version
2.3 of the specification shipped with the J2EE 1.3 SDK. The following items discuss
compatibility issues between these releases.
-
HttpSessionListener sessionDestroyed method was previously
used to notify that a session was invalidated. As of this release, this method is
used to notify that a session is about to be invalidated so that it notifies before
the session invalidation. If the code assumed the previous behavior, it must be modified
to match the new behavior.
-
ServletRequest methods getRemotePort, getLocalName, getLocalAddr, getLocalPort
The
following methods are added in the ServletRequest interface
in this version of the specification. Be aware that this addition causes source incompatibility
in some cases, such as when a developer implements the ServletRequest interface.
In this case, ensure that all the new methods are implemented:
-
public int getRemotePort() returns the Internet Protocol (IP) source
port of the client or last proxy that sent the request.
-
public java.lang.String getLocalName() returns the host name of the
Internet Protocol (IP) interface on which the request was received.
-
public java.lang.String getLocalAddr() returns the Internet Protocol
(IP) address of the interface on which the request was received.
-
public int getLocalPort() returns the Internet Protocol (IP) port
number of the interface on which the request was received.
JavaServer Pages Specification 2.0 ships with the Sun Java System Application Server 8.1 release
and is downloadable from the following URL:
http://java.sun.com/products/jsp/
JSP Specification
1.2 shipped with the J2EE 1.3 SDK. Where possible, the JSP 2.0 Specification attempts
to be fully backward compatible with the JSP 1.2 Specification. In some cases, there
are ambiguities in the JSP 1.2 specification that have been clarified in the JSP 2.0
Specification. Because some JSP 1.2 containers behave differently, some applications
that rely on container-specific behavior may need to be adjusted to work correctly
in a JSP 2.0 environment.
The following is a list of known backward compatibility
issues of which
developers who use JSP technology should be aware:
-
Tag Library validators that are not namespace aware and that rely solely on the prefix
parameter might not correctly validate some JSP 2.0 pages. This is because the XML
view might contain tag library declarations in elements other than jsp:root, and might contain the same tag library declaration more than once, using
different prefixes. The uri parameter should always be used by tag library validators
instead. Existing JSP pages with existing tag libraries do not create any problems.
-
Users may observe differences in I18N behavior on some containers due primarily to ambiguity
in the JSP 1.2 specification. Where possible, steps were taken to minimize the impact
on backward compatibility and overall, the I18N abilities of technology have been
greatly improved.
In JSP specification versions previous to JSP 2.0, JSP
pages in XML syntax (“JSP documents”) and those in standard syntax determined
their page encoding in the same fashion, by examining the pageEncoding or contentType attributes of their page directive, defaulting to ISO-8859-1
if neither was present.
As of the JSP Specification v2.0, the page encoding for JSP documents is determined as described
in section 4.3.3 and appendix F.1 of the XML specification, and the pageEncoding attribute
of those pages is only checked to make sure it is consistent with the page encoding
determined as per the XML specification.
As a result of this change, JSP
documents that rely on their page encoding to be determined from their pageEncoding
attribute will no longer be decoded correctly. These JSP documents must be changed
to include an appropriate XML encoding declaration.
Additionally, in the
JSP 1.2 Specification, page encodings are determined on a per translation unit basis
whereas in the JSP 2.0 Specification, page encodings are determined on a per-file
basis. Therefore, if a.jsp statically includes b.jsp, and a page encoding is specified
in a.jsp but not in b.jsp, in the JSP 1.2 Specification a.jsp’s encoding is
used for b.jsp, but in the JSP 2.0 Specification, the default encoding is used for
b.jsp.
-
The type coercion rules (shown in Table JSP.1-11 in the JSP 2.0 Specification) have been reconciled
with the EL coercion rules. There are some exceptional conditions that no longer result
in an exception in the JSP 2.0 Specification. In particular, when passing an empty
String to an attribute of a numeric type, a translation error or a NumberFormatException used to occur, whereas in the JSP 2.0 Specification, a 0 is passed in
instead. See Table JSP.1-11 in the JSP 2.0 Specification for details. In general,
this is not expected to cause any problems because these would have been exceptional
conditions in the JSP 1.2 Specification and the specification allowed for these exceptions
to occur at either translation time or request time.
-
The JSP container uses the version of web.xml to determine the default
behavior of various container features. The following is a list of items of which
JSP developers should be aware when upgrading their web.xml file
from Servlet version 2.3 Specification to Servlet version 2.4 Specification.
-
EL expressions are
ignored by default in applications created with JSP 1.2 technology. When upgrading
a Web application to the JSP 2.0 Specification, EL expressions are interpreted by
default. The escape sequence \\$ can be used to escape EL expressions that should
not be interpreted by the container. Alternatively, the isELIgnored page directive
attribute, or the el-ignored configuration element can deactivate EL for entire translation
units. Users of JSTL 1.0 need to either upgrade their taglib/ imports to the JSTL
1.1 URIs, or they need to use the _rt versions of the tags (for example c_rt instead
of c, or fmt_rt instead of fmt).
-
Files with an extension of .jspx are interpreted as JSP documents
by default. Use the JSP configuration element is-xml to treat .jspx files as regular
JSP pages. There is no way to disassociate .jspx from the JSP container.
-
The escape sequence \\$ was not reserved in the JSP 1.2 Specification.
Any template text or attribute value that appeared as \\$ in the JSP 1.2 Specification
used to output \\$ but now outputs just $.
JAXP and SAX Incompatibilities
Sun Java System Application Server 8.1 supports JAXP 1.3, which in turn supports SAX 2.0.2. In SAX
2.0.2, DeclHandler.externalEntityDecl requires the parser to return
the absolute system identifier for consistency with DTDHandler.unparsedEntityDecl. This might cause some incompatibilities when migrating applications that
use SAX 2.0.0.
To migrate an application that uses SAX 2.0.0 to SAX 2.0.2 without changing
the previous behavior of externalEntityDecl, you can set the resolve-dtd-uris
feature to false. For example:
SAXParserFactory spf = SAXParserFactory.newInstance();
spf.setFeature("http://xml.org/sax/features/resolve-dtd-uris",false);
Other incompatibilities between SAX 2.0.0 and SAX 2.0.2 are documented in the JAXP Compatibility Guide.
Application Server 8.1 Options Incompatible with J2EE 1.4 Specification
Requirements
Sun Java System Application Server 8.1 is compatible with the Java 2 Platform, Enterprise Edition
specification by default. In this case, all portable J2EE programs run on the Application Server without
modification. However, as allowed by the J2EE compatibility requirements, it is possible
to configure applications to use features of the Sun Java System Application Server 8.1 that are not compatible
with the J2EE specification.
The pass-by-reference element
in the sun-ejb-jar.xml file only applies to remote calls. As
defined in the EJB 2.0 specification, section 5.4, calls to local interfaces use pass-by-reference
semantics.
If the pass-by-reference element is set to its default value of false, the parameter
passing semantics for calls to remote interfaces comply with the EJB 2.0 specification,
section 5.4. If set to true, remote calls involve pass-by-reference semantics instead
of pass-by-value semantics, contrary to this specification.
Portable programs cannot assume that a copy of the object is made during such
a call, and thus that it’s safe to modify the original. Nor can they assume
that a copy is not made, and thus that changes to the object are visible to both caller
and callee. When this flag is set to true, parameters and return values are considered
read-only. The behavior of a program that modifies such parameters or return values
is undefined. For more information about the pass-by-reference element, see the Sun Java System Application Server Enterprise Edition 8.1 2005Q2 Developer’s Guide.
Application Server 8.1 Options Contrary to J2EE 1.4 Specification
Recommendations
If the delegate attribute in the class-loader element of the sun-web.xml file
is set to its default value of true, classes and resources residing in container-wide
library JAR files are loaded in preference to classes and resources packaged within
the WAR file, contrary to what is recommended in the Servlet 2.3 specification, section
9.7.2. If set to false, the classloader delegation behavior complies with what is
recommended in the Servlet 2.3 specification, section 9.7.2.
Do not package portable programs that use the delegate attribute with the value
of true with any classes or interfaces that are a part of the J2EE specification.
The behavior of a program that includes such classes or interfaces in its WAR file
is undefined. For more information about the class-loader element, the Sun Java System Application Server Enterprise Edition 8.1 2005Q2 Developer’s Guide.
Download this book in PDF (952 KB)