Oracle® Developer Suite Release Notes
10g (9.0.4) for Windows, Linux, Solaris, and HP-UX
Part No. B10668-03
This chapter describes issues and workarounds for Oracle Application Server Containers for J2EE (OC4J). This chapter discusses the following topics:
You can access Oracle manuals mentioned in this document at the Oracle Technology Network (
This section describes configuration issues and their workarounds for OC4J. It features the following topics:
For useful information on configuring OC4J, see the Configuration Guide for OC4J which is available from Oracle Technology Network (
In the Oracle Application Server environment, you must explicitly specify the port ranges for iiops1 and iiops2 in the
In Oracle Application Server 10g (9.0.4), Oracle recommends creating specific
<library> elements in the global
application.xml file to load any libraries required by your application. Oracle recommends this as a way to ensure efficient loading and desired loading order. (Libraries are loaded in the order in which the
<library> elements are encountered.)
Note that in previous releases, you could put libraries into the
j2ee/home/lib directory, which by default had a
<library> element in
application.xml. This directory is now reserved for OC4J system libraries, and the
<library> element that points to it is no longer present in
application.xml by default. If you want to use a general library location, use
j2ee/home/applib. By default, there is now a
<library> element pointing to that location in
For general information about sharing libraries, refer to the Oracle Application Server Containers for J2EE User's Guide.
Out of Memory During Execution
If the OC4J process memory is growing consistently during program execution, then you may have references to invalid symbolic links in your global
application.xml file. This problem is usually characterized by a growth in the C heap and not a growth in Java object memory, as one would see with a more traditional Java object memory leak. OC4J loads all resources using the links in the
application.xml file. If these links are invalid, then the C heap continues to grow, causing OC4J to run out of memory. Ensure that all symbolic links are valid, and restart OC4J.
In addition, keep to a minimum the number of JAR files OC4J is configured to load. Eliminate all unused JAR files from the configuration and from the directories OC4J is configured to search. OC4J searches all JAR files for classes and resources, thereby causing the file cache to use extra memory and processor time.
You can control the loading more precisely if your
<library> elements in the
application.xml file point to the individual JAR and ZIP files that are needed, instead of to the directories where they reside.
Custom user manager classes deployed within Enterprise Java Beans (EJB) JAR files cannot be loaded by OC4J unless an explicit
<library> element exists in the
orion-application.xml file for the application. The
<library> element must point to the JAR file containing the custom user manager classes. To allow the custom user manager to be resolved and instantiated, create the necessary
<library> element, such as in the following example:
<orion-application ....> ... <library path="d:\oc4j904\j2ee\home\applications\XmlnewsEar\XmlnewsEjb.jar"/> ... </orion-application>
You must use the JNDI context that is passed in as an argument to your startup and shutdown methods. You cannot create your own.
You should separate your shutdown class from any archive files (WAR and EAR) that will be undeployed before shutdown.
OC4J creates an instance of your startup class and an instance of your shutdown class. These are separate instances. If you implement the startup and shutdown interfaces in the same class, OC4J creates two instances of that class. In this case, you cannot share non static fields between your startup class and your shutdown class.
You must have only one Java Developer's Kit (JDK) installed on your computer. Make sure that it is a version that OC4J supports:
OC4J Standalone does not include a JDK. If you are using OC4J Standalone, then you must provide your own JDK installation.
Some suppliers bundle a JDK with their products. If necessary, remove any old version(s), replace them with a supported version, and update the appropriate environment variables. Make sure that your
LIB on Windows) variables are all set to the officially supported version of JDK.
Note:On Solaris computers, Sun Microsystems supplies an old JDK under
Java does not support compiling Java code under JDK 1.4 and running it under JDK 1.3 (bug 2811379). If you try anyway, Java may throw one of the following error messages at runtime:
Unsupported major.minor version 48.0.
The major.minor version '48.0' is too recent for this tool to understand.
However, if you must generate class files using JDK 1.4 and run them using JDK 1.3, then you can use the following command to force a JDK 1.4 compiler to generate a class file that is compatible with JDK 1.3:
javac -target 1.3 hello.java
When you upgrade from JDK 1.3 to JDK 1.4, put all classes into packages.
The JDK 1.4 specification explicitly prohibits a class within a package from invoking a class not within a package. For this reason, some Java source code that compiles in JDK 1.3 will not compile in JDK 1.4. This error is identified by the following compiler message:
'.' expected import myClass
This message means that the Java compiler expects to find a package and class name and cannot parse a line that contains only a class name.
For details, see the Sun Microsystems compatibility document supplied with the JDK.
Oracle Application Server 10g (9.0.4) includes one demo per component. Additional demos are available for download from OTN at the following URL:
Navigate down from this index page to the component areas that contain the additional demos that you need.
This section describes issues for Java Server Pages (JSP), tag libraries, and related demos. It features the following topics:
Among the considerations in migrating to a Sun Microsystems JDK 1.4 environment, one is particularly important to servlet and JSP developers.
Sun Microsystems states, "The compiler now rejects import statements that import a type from the unnamed namespace." This change addresses security concerns and ambiguities with previous JDK versions. This means that you cannot invoke a class (a method of a class) that is not within a package. Any attempt to do so results in a fatal error at compilation time.
This issue especially affects JSP developers who invoke JavaBeans from their JSP pages, because such beans are often outside any package (although the JSP 2.0 specification now requires beans to be within packages, to satisfy the new compiler requirements). When JavaBeans outside of packages are invoked, JSP applications that were built and executed in an OC4J 9.0.3 / JDK 1.3.1 environment no longer work in an OC4J 9.0.4 / JDK 1.4 environment.
Until you update your application so that all JavaBeans and other invoked classes are within packages, you can revert to a JDK 1.3.1 environment to avoid this issue.
This issue is also discussed in Section 13.1.8, "Migrating Source Code from JDK 1.3 to JDK 1.4". For more information about the "classes not in packages" issue and other JDK 1.4 compatibility issues, refer to the following Web site:
Click the link "Incompatibilities Between Java 2 Platform, Standard Edition, v1.4.0 and v1.3".
For the filter functionality of Java Server Pages Standard Tag Library (JSTL) XML tags to work in OC4J, you must set the SAX driver when starting OC4J.
When starting OC4J standalone, use the following option in the command line:
When starting the Oracle Application Server, you can specify this setting through the system properties. See the Oracle Application Server documentation for details on where and how to make this specification.
If you do not set the property, then the JSTL demo
Filter.jsp gives the following exception:
javax.servlet.jsp.JspException: System property org.xml.sax.driver not specified
This section features the following topics:
-debug option has no effect on
ojspc output in Oracle Application Server 10g (9.0.4). If you specify -debug, the option is accepted but ignored.
ojspc, do not put any
.java files in or under the
/WEB-INF/lib directory or the
/WEB-INF/classes directories contain any
.java files, then ojspc occasionally creates one or more duplicate .class files at the top level of the archive during batch pretranslation.
This section describes changes and enhancements in the behavior of Java Edge Side Includes (JESI) tags in Oracle Application Server 10g (9.0.4). It features the following topics:
In prior versions of the JESI tag library, JESI tags always generated the same output regardless of whether the request was coming directly from a client, such as a browser, or from Oracle Web Cache. Therefore, in prior versions of the tag library, JESI tags required special conditional treatment if there was a possibility that the Oracle Web Cache might be down or unavailable at any time, because then the included pages and fragments would not have been inserted into the response.
In the OC4J 9.0.4 implementation, JESI tags correctly generate a full response, even without the presence of Oracle Web Cache, by falling back to the standard JSP "include" functionality for inclusion of fragments. For more information, see the Oracle Application Server Containers for J2EE JSP Tag Libraries and Utilities Reference.
In the OC4J 9.0.4 implementation, the JESI
personalize tag now puts single quotes around the string value of the default attribute (or, for backward compatibility, the value attribute). This behavior is more compliant with the ESI syntax. In versions prior to Oracle Application Server 10g (9.0.4), the user had to add single quotes as part of the attribute string value. You must edit pages containing
personalize tags that used to work prior to the 9.0.4 implementation to remove extra single quotes.
You can now place a fragment tag inside a page included through a
jsp:include standard action, if it is properly enclosed in a
template tag (which can be in the including page).
When OC4J encounters multiple
control tags, instead of throwing an exception, it ignores additional
template tags. OC4J executes only the first tag that it encounters. This feature allows placing
control tags into JSP-included pages. If a page is included in another page with
template tags of its own, then the second tag is ignored. At the same time, the included page can be executed independently.
The four permutations and their behavior are as follows:
control tag followed by a
control tag is acceptable. The second
control tag is ignored.
control tag followed by a
template tag is acceptable. The attributes of the
template tag are ignored.
template tag followed by a
control tag is acceptable. The
control tag is ignored.
template tag followed by a
template tag produces an error.
In the OC4J 9.0.4 and the OC4J 9.0.3 implementations, there must be no response output outside the
end tags of a
template tag. Additionally, you can now place
template tags in an included page, if there is no content output into the response outside the
You should carefully observe the JSP specification with respect to tag library descriptors, despite leniency in previous OC4J implementations.
The existing specification allows tag library descriptors only under
/WEB-INF/ for a given application.
In practice, in the OC4J 9.0.4 implementation (and previous implementations), tag library descriptors have been accepted anywhere under
application_root , despite the requirements of the specification.
In implementations under development, the specification is strictly enforced. Tag library descriptors are allowed only under
If you are adding tag library JAR files to the
/WEB-INF/lib directory while OC4J is running, then set
tags_reuse_default to "none" or "compiletime" to avoid a
If you are using tag library JAR files at the application level that are intended to supersede JAR files in the well-known tag library location (global level), then you must set the application loader to search local classes first. You can do this through the following setting in your application's
<web-app-class-loader search-local-classes-first="true" />
A JSP error message such as the example shown below indicates a truncated class file.
Some conditions in which this can occur include the following:
You are using JSP in a portal environment.
The computer is heavily loaded.
Use one of the following techniques to repair the error:
touch on the JSP file to cause the JSP to be recompiled.
Remove the corrupted class file, as indicated by the "
/modules/location/bizdir/jsp/bizdir.jsp" listing in the error message example.
Truncated Class File Error Message Example
500 Internal Server Error OracleJSP: JSP Error: ------------------------------------------------------------------------------- Request URI:/modules/location/bizdir/jsp/bizdir.jsp Exception: java.lang.ClassFormatError: _location/_bizdir/_jsp/_bizdir (Truncated class file) at java.lang.ClassLoader.defineClass0(Native Method) at java.lang.ClassLoader.defineClass(ClassLoader.java:493) at java.security.SecureClassLoader.defineClass(SecureClassLoader.java:111) at oracle.jsp.app.JspClassLoader.loadClass(JspClassLoader.java:682) at java.lang.ClassLoader.loadClass(ClassLoader.java:255) ...
This section describes release notes for servlets. It features the following topics:
With JDK 1.4, you are not allowed to invoke a class if it is not in a package if you are calling it from a class that is not in a package. The JSP release notes, Section 13.2.1, "Cannot Invoke Classes That Are Not in Packages" describes this issue in detail.
In OC4J, servlet invocation by class name is available as a convenience feature during development.
This feature is controlled through the
http.webdir.enable system property or the
servlet-webdir attribute of the
<orion-web-app> element in either the
global-web-application.xml file or the
This feature is documented in the Oracle Application Server Containers for J2EE Servlet Developer's Guide.
In the OC4J 9.0.4 implementation, invocation by class name is enabled by default, through the default settings
In a production environment, you must disable this feature by setting either
servlet-webdir="" (empty quotes).
This section describes release notes for EJBs. It features the following topics:
When you provide your URL on the client to access an EJB in the following form, you must always provide the port number. For example,
If you do not, then the
oc4j_inst always defaults to the home instance. (bug 3234351).
The message-driven bean (MDB) transaction timeout, as defined in the
transaction-timeout attribute in the
orion-ejb-jar.xml file, is an optional parameter. This attribute controls the transaction timeout interval (in seconds) for any container-managed transactional MDB that uses Oracle JMS. The default is one day (86,400 seconds). The MDB
transaction-timeout attribute applies only to CMT MDBs that use Oracle JMS as the JMS provider. This attribute setting has no effect on BMT MDBs or any MDBs that use OC4J JMS. (bug 3079322)
JMS behavior with Oracle Application Server — If the transaction has not completed in this time frame, then the transaction is rolled back and the message is redelivered to the
Destination object. After Oracle JMS attempts to redeliver the message (the default is five attempts), the message is moved to the exception queue. For more information, refer to the Oracle9i Application Developer's Guide—Advanced Queuing for Release 2 (9.2).
JMS behavior with OC4J — The transaction-timeout setting does not work for CMT MDBs that use OC4J JMS. The timeout is always one day and cannot be modified. When the timeout occurs, OC4J JMS redelivers the message indefinitely, until the delivery is successful. You cannot set a retry limit.
In addition, the global
transaction-timeout attribute defined in the
server.xml file does not have any effect on MDBs.
You must create and release the JMS connections for Oracle JMS in the MDB
onMessage() method, and not in the
ejbCreate() method. (bug 2967949).
If you modify your
orion-ejb-jar.xml file using the Oracle Enterprise Manager, then you must restart OC4J. Otherwise, if you are operating in the standalone environment and you modify your
orion-ejb-jar.xml file using an editor, then you must repackage the application and redeploy it to OC4J without restarting. (bug 3001543)
During EJB deployment in OC4J, you load the bean class to find out its methods so that you can generate EJB wrappers. Because the code in the static block is executed as the class is being loaded, the JNDI environment context is not yet set up. Even during runtime, the bean is in the "does not exist" stage. In this stage of the life cycle, the JNDI environment context is undefined, and the bean provider cannot rely on it to be available.
To work around this problem, set up and cache the context either during the construction of the bean, in the
ejbCreate() method, or in the
Under some conditions, the OPMN process monitoring software in Oracle Application Server may lose contact with an OC4J process. This can occur because of unexpected delays in the hearbeat protocol used by OPMN and OC4J to verify the proper functioning of the OC4J instance.
If this problem occurs sporadically, you can try increasing the ping timeout parameters as described in the following instructions.
However, if this occurs regularly, due to a consistent resource shortage, then you must increase the available hardware resources to solve the problem.
The following conditions can cause this problem:
An overloaded host processor.
One or more computation-intensive applications running in the OC4J instance.
Deployment of applications with large numbers (hundreds) of EJBs. Full garbage collections of large heaps can cause the OC4J process to become less responsive during the garbage collection phase. Although this should not occur during normal usage, deployment of large applications with many EJBs in a memory-constrained environment can trigger this behavior.
You can configure the behavior of the "ping protocol" between OPMN and OC4J in the
opmn.xml configuration file.
When OC4J exceeds the timeout intervals specified for the ping protocol, the process monitoring software decides that the OC4J process has stopped responding and, therefore, terminates the OC4J process.
If you suspect this behavior in an Oracle Application Server installation, then use the following steps to troubleshoot and work around:
When OC4J instances are "mysteriously" terminating, first increase diagnostic logging to determine if ping failures are triggering the termination:
Increase the OPMN logging level to 5 so that you can see the pings.
opmn/conf/opmn.xml, edit the following line:
log-file path="$ORACLE_HOME/opmn/logs/ipm.log" level="5" ...
Reload the daemon.
opmn/logs/ipm.log for the following line:
Process Ping Failed:OC4J~<instance name>~default_island~1 (opmnid)
The line above indicates that the memory and CPU resources of the current host are probably not sufficient to perform the operation within the currently specified ping timeout interval (used by OPMN to determine OC4J "responsiveness").
Change the settings as follows:
Increase the timeout and interval.
<ping timeout="60" interval="60"/>" <data id="reverseping-failed-ping-limit" value="5" />
Reload the daemon.
Restart the appropriate OC4J instance.
Repeat the top-level operation that caused the timeout failure.
You cannot mark a Container-Managed Persistence (CMP) entity bean as read-only if it has a Container-Managed Relationships (CMR) relationship to another entity bean that is not read-only.
If you invoke any EJB from an application client outside the EJB container, then Java Authentication and Authorization Service (JAAS) is not supported for the EJB. However, if you call the EJB from a servlet within the OC4J instance, then JAAS is supported.
The container may call the
EJBActivate() method multiple times when the bean is associated with several wrappers. (bug 3107168)
If you access an EJB in an application from an EJB in a different application, then you cannot use the RMIInitialContextFactory object. In this scenario, you must use a parent-child relationship between these applications, and you must use the default initial context factory object. (bug 2812150)
The JTA two-phase commit (2pc) function does not work with Oracle Database version 9.2. Instead, use Oracle Database version 126.96.36.199 or higher to enable the 2pc functionality. (bug 2668460)
Currently, inline SQL queries are not supported within the finder query string defined in the orion-ejb-jar.xml file. When modifying these queries, avoid inline SQL queries, such as:
SELECT * FROM (SELECT * FROM TEST1) A, (SELECT * FROM TEST2) B WHERE A.ID =B.ID
This section contains release notes for OC4J Services. It features the following topic:
This section describes release notes for the Java Object Cache (JOC). It describes the following topic:
The OC4J 9.0.4 implementation uses the file
javacache.xml for JOC configuration. In previous versions of JOC, configuration was done through the file
Note:f you install both a 9.0.4 release and a pre-9.0.4 release on the same host, you must ensure that the
This section contains release notes for DataDirect Connect for JDBC.
For additional information, refer to the following manuals:
Oracle Application Server Containers for J2EE Services Guide
DataDirect Connect for JDBC User's Guide and Reference
A customized version of DataDirect Connect for JDBC is shipped with Oracle Application Server to provide connectivity to non-Oracle databases. Do not use the DataDirect Connect for JDBC driver outside of Oracle Application Server.
This section describes important differences between the customized DataDirect Connect for JDBC driver and the standard version.
The customized DataDirect driver JAR file names use the
YM prefix. The following DataDirect JAR files are distributed with Oracle Application Server:
YMbase.jar YMinformix.jar YMsqlserver.jar YMutil.jar YMdb2.jar YMsybase.jar
The URL subprotocol prefix is
oracle. When you connect, use the correct subprotocol. For example:
The vendor message prefix is
The customized DataDirect driver is configured to run within Oracle Application Server. Attempting to use the customized DataDirect JDBC driver outside Oracle Application Server yields the following exception:
java.sql.SQLException: [oias][... JDBC Driver]
This section provides information for installing DataDirect Connect for JDBC.
Refer to the Oracle Application Server Containers for J2EE Services Guide for additional detail on setting up DataDirect with Oracle Application Server or OC4J.
The DataDirect driver is a ZIP file available at:
http://otn.oracle.com/ under the Oracle Application Server download area.
Unzip the DataDirect package as follows:
On Linux, Solaris, and HP-UX, run the following command:
On Windows, use WinZip or a similar tool to unzip the DataDirect package.
Note:n the following instructions, note these definitions:
Set up DataDirect according to the following instructions:
Unzip the contents of the DataDirect JDBC drivers to the directory
If it does not already exist, create the directory
Copy the DataDirect JDBC drivers in
/lib to the following directory:
Verify that the file
application.xml contains a library entry that references the
j2ee/home/applib location, as follows
Add data sources to the file
data-source.xml as described in the following examples, taken from the Oracle Application Server Containers for J2EE Services Guide.
Example DataDirect Data Source Entries
This section shows an example data source entry for each of the following non-Oracle databases:
Note:The OC4J 9.0.4 implementation does not work with non-Oracle data sources in the nonemulated case. That is, you cannot use a non-Oracle data source in a two-phase commit transaction.
You can also use vendor-specific data sources in the class attribute directly. That is, it is not necessary to use an OC4J-specific data source in the
Here is a data source configuration example for a SQLServer database.
<data-source class="com.evermind.sql.DriverManagerDataSource" name="MerantDS" location="jdbc/MerantCoreSSDS" xa-location="jdbc/xa/MerantSSXADS" ejb-location="jdbc/MerantSSDS" connection-driver="com.oracle.ias.jdbc.sqlserver.SQLServerDriver" username="test" password="secret" url="jdbc:sqlserver//hostname:port;User=test;Password=secret" inactivity-timeout="30" />
Here is a data source configuration example for a DB2 database:
<data-source class="com.evermind.sql.DriverManagerDataSource" name="MerantDS" location="jdbc/MerantDB2DS" xa-location="jdbc/xa/MerantDB2XADS" ejb-location="jdbc/MerantDB2DS" connection-driver="com.oracle.ias.jdbc.db2.DB2Driver" username="test" password="secret" url="jdbc:db2://hostname:port;LocationName=jdbc;CollectionId=default;" inactivity-timeout="30" />
Here is a data source configuration sample for a Sybase database:
<data-source class="com.evermind.sql.DriverManagerDataSource" name="MerantDS" location="jdbc/MerantCoreSybaseDS" xa-location="jdbc/xa/MerantSybaseXADS" ejb-location="jdbc/MerantSybaseDS" connection-driver="com.oracle.ias.jdbc.sybase.SybaseDriver" username="test" password="secret" url="jdbc:sybase://hostname:port;User=test;Password=secret" inactivity-timeout="30" />
This section describes known errors in the OC4J documentation in Oracle Application Server 10g (9.0.4). It features the following topics:
This section describes errata in the Oracle Application Server Containers for J2EE Servlet Developer's Guide.
The following note, which appears on page 6-6 of the 9.0.4 version of the Oracle Application Server Containers for J2EE Servlet Developer's Guide, is incorrect:
"Note: The OC4J JSP container does not currently support the persistence-path flag. It is for servlets only."
This flag actually is supported by the JSP container in the Oracle Application Server 10g (9.0.4) release.
This section describes errata in the JavaServer Pages Developer's Guide. It features the following topic:
The following item, which appears in the "Oracle HTTP Server and mod_oc4j" section in Chapter 2 of the Oracle Application Server Containers for J2EE Support for JavaServer Pages Developer's Guide, is incorrect:
"A mod_oc4j module can restart an OC4J instance automatically, if necessary."
In fact, OPMN, not
mod_oc4j, restarts OC4J processes automatically when it detects that they are unavailable (for several reasons).
This section describes known errors in the Oracle Application Server Containers for J2EE User's Guide. It features the following topic:
Add the following information to the Oracle Application Server Containers for J2EE User's Guide, Appendix A, "Additional Information". In the section "Elements Contained Within <application-server> of the server.xml file", add the following text describing the
<metric-collector> element specifies that OC4J sends a metric between 0 and 100, inclusive, to
mod_oc4j so that
mod_oc4j can make routing decisions to load-balance incoming requests to a list of available OC4J instances. The metric sent has a relative value only, where 0 means that the OC4J instance is very busy and 100 means that the OC4J instance is available (not busy). When configured for metric load balancing,
mod_oc4j routes first to the OC4J instance with the greater value.
The metric sent from OC4J to
mod_oc4j is used only when metric-based load balancing is specified for
mod_oc4j and when OC4J runs in an Oracle Application Server environment.
If you specify metric-based load balancing in
mod_oc4j and do not specify the
<metric-collector> element in
mod_oc4j expects OC4J to send metrics, but OC4J does not send metrics. In this case,
mod_oc4j reports the following warning message:
No run time metrics for oc4j(opmnid=%s) in notification Oc4jSelectMethod is configured to use run time metrics, please make sure OC4J side is configured accordingly. Default to 50.
In this case,
mod_oc4j uses the value 50 for each of the OC4J processes and continues.
Likewise, if you specify the
<metric-collector> element in
server.xml, but do not specify metric-based load balancing in
mod_oc4j, then OC4J sends metrics but
mod_oc4j is not configured to receive metrics. In this case,
mod_oc4j ignores the metrics and uses whatever the configured method is for load balancing. You specify the load balancing method with
Oc4jSelectMethod. If no
Oc4jSelectMethod is specified, then
mod_oc4j uses the default, which is
<metric-collector> element takes the following attribute:
classname attribute defines an interface for gathering and calculating a server-wide metric. Use
oracle.oc4j.server.DMSMetricCollector for the
classname attribute when using a DMS-noun-based metric collector. A
DMSMetricCollector instance takes several parameters. Details for the values for these parameters are available in the Oracle Application Server 10g Performance Guide.
<metric-collector classname="oracle.oc4j.server.DMSMetricCollector"> <init-param> <param-name> dms-noun </param-name> <param-value> /oc4j/default/WEBs/processRequest.time </param-value> </init-param> <init-param> <param-name> history-proportion </param-name> <param-value> 0.2 </param-value> </init-param> <init-param> <param-name> debug </param-name> <param-value> false </param-value> </init-param> </metric-collector>
For details on using the
<metric-collector> element and using metric-based load balancing with
mod_oc4j, see the Oracle Application Server 10g Performance Guide.