Release Notes
10g (10.1.3.1.0)/(10.1.3.4.0)
April 2009
This document provides information on:
For a detailed overview of the new features that this release provides, see http://www.oracle.com/technology/products/ias/toplink/technical/tl10g_fov.htm.
The Java Persistence API (JPA), part of the Java Enterprise Edition 5 (Java EE 5) Enterprise Java Beans (EJB) 3.0 specification, greatly simplifies Java persistence and provides an object-relational mapping approach that allows you to declaratively define how to map Java objects to relational database tables in a standard, portable way that works both inside a Java EE 5 application server and outside an EJB container in a Java Standard Edition (Java SE) 5 application.
TopLink Essentials is the JPA provider for the EJB 3.0 Reference Implementation. In addition to being JPA compliant, it also provides additional extensions beyond what is defined in the JPA specification. TopLink Essentials is also available as part of GlassFish, under the CDDL license. See https://glassfish.dev.java.net/javaee5/persistence/entity-persistence-support.html for complete information.
|
Note: TopLink Essentials is the default JPA persistence provider for EJB 3.0 JPA applications within Oracle Containers for J2EE (OC4J). |
When using TopLink JPA, you can access the API through extensions. For more information on TopLink extensions, see http://www.oracle.com/technology/products/ias/toplink/jpa/resources/toplink-jpa-extensions.html.
To obtain more information, to download the source (toplink-essentials-src.zip), and to download more recent builds, see the following:
http://www.oracle.com/technology/products/ias/toplink/jpa/index.html
"Understanding the EJB 3.0 JPA Entity Architecture" in the Oracle TopLink Developer's Guide
EJB 3.0 Support
The TopLink 10g (10.1.3.1.0) supports all but a small subset of the functionality specified in the EJB 3.0 specification. For more information on EJB 3.0 support, see http://www.oracle.com/technology/tech/java/ejb30.html.
For a detailed list of the modifications to the TopLink API that this release provides, see: http://www.oracle.com/technology/products/ias/toplink/doc/10131/api/api_mod_readme.htm.
The following table lists feature support deprecated as of 10g (10.1.3.1.0):
| Deprecated Feature | Description |
|---|---|
| JDO Preview | The original JDO preview support has been deprecated in favor of the new JPA functionality |
| TopLink SDK | The TopLink SDK has been deprecated. Use the TopLink EIS support to access non-relational data sources through JCA/J2CA resource adapters with XML or CCI data interactions. |
| JPA Preview | The 10.1.3.0.0 JPA preview has been replaced by TopLink Essentials, the open-source community edition of TopLink.
The JPA preview ( |
| IBM WebSphere CMP | Support for WebSphere Application Server CMP 3.5 has been deprecated. |
| BEA WebLogic CMP | Support for WebLogic Server CMP 6.x, 7.x, and 8.x has been deprecated. |
| Java Runtime Environment | Support for JRE 1.4.x has been deprecated. |
The following are known issues in Oracle TopLink:
When using Oracle TopLink with WebSphere Application Server 5.1, we recommend that your application be configured and deployed with the classloader mode set to PARENT_FIRST.
If, for any reason, your application must instead be configured with the classloader mode set to PARENT_LAST, you can:
Remove (or rename) the <JAVA_HOME>\lib\jaxp.properties file (where <JAVA_HOME> is typically <WEBSPHERE_INSTALL>\java\jre).
or
Place the xerces library included with the WebSphere installation after xmlparser2.jar in the in the same shared library. This file can be found in <WEBSPHERE_INSTALL>\java\jre\lib\xml.jar.
This section contains information on the following issues:
UnitOfWork.release() not Supported with External Transaction Control
ReportQuery Results for Aggregate Functions may be Truncated
Attribute Joining of 1:1 Mappings not Supported with Inheritance
Using Oracle Database Advanced Data Types may Fail with Some Data Sources
TopLink generates incorrect outer join for SQL Server v2005. The outer join syntax generated is correct for earlier versions of this database. To work around this limitation, reconfigure the database compatibility (refer to the SQLServer documentation for details). Alternatively, you can use a custom TopLink database platform.
A unit of work synchronized with a Java Transaction API (JTA) will throw an exception if it is released. If the current transaction requires its changes to not be persisted, the JTA transaction must be rolled back.
When in a container-demarcated transaction, call setRollbackOnly() on the EJB/session context:
Stateless
public class MySessionBean implements SomeInterface { . @Resource
SessionContext sc;
.
public void someMethod() {
...
sc.setRollbackOnly();
}
}
When in a bean-demarcated transaction then you call rollback() on the UserTransaction obtained from the EJB/session context:
Stateless
TransactionManagement(TransactionManagementType.BEAN)
public class MySessionBean implements SomeInterface {
.
@Resource
essionContext sc;
.
public void someMethod() {
sc.getUserTransaction().begin();
...
sc.getUserTransaction().rollback();
}
}
When using a ReportQuery to return calculated values, the data type of the column is used to convert the returned results. As a result, values returned for mapped attributes using average, variance, and standard deviation will be converted into the mapped attribute type and could result in loss of precision through truncation.
To work around this issue, use the field instead of the attribute's query key. For example:
Using the attribute's query key results in truncated value:
rq.addAverage("salary");
Use the database column instead to avoid truncation:
rq.addAverage("salary", eb.getField("SALARY.SALARY"));
It is not possible to execute a query on a class involved in an inheritance hierarchy which also has 1:1 joined attributes configured. This issue has already been addressed in TopLink Essentials and the solution will be available in the next release or a patch-set of this release.
When using Oracle9i and Oracle10g database platform-provided advanced data types with some data source implementations, failures may occur. The platform does not or cannot correctly unwrap the raw Oracle specific JDBC connection and cannot complete the necessary conversions. To avoid this issue, you can use TopLink internal connection pooling.
The returning policy, which allows values modified during INSERTs and UPDATEs to be returned and populated in cached objects, does not work in conjunction with numeric version optimistic locking. The value returned for all UPDATEs is 1 and does not provide meaningful locking protection.
Do not use numeric optimistic locking in conjunction with a returning policy.
TopLink assumes that date and time information returned from the server will use Timestamp. If the JDBC driver returns a String for the current date, TopLink will throw an exception. You should use a driver that returns Timestamp or change the policy to use local time instead of server time.
When configuring a custom sequence table for a session, TopLink Workbench will throw an exception and your edits will not be written to the sessions.xml when it is saved. As a workaround, configure sequencing at the project level. See "Configuring Sequencing at the Project Level" in the Oracle TopLink Developer's Guide for details.
This section contains information on the following issues:
When you generate class and method names that include non-ASCII characters, TopLink will throw an exception. This problem occurs when creating a JAXB 1.0 TopLink project from an XML schema that contains non-ASCII characters. Ensure that your XML schema does not contain any non-ASCII characters.
When using the Preserve Document option with an XML descriptor, you must also set the option on all other root descriptors.
TopLink supports only a single composite object mapping using the self (".") XPath. This does not restrict the number of composite object mappings, only the number of mappings where the composite object is mapped into the parent element instead of a child element.
When using document preservation (see "Configuring Document Preservation" in the Oracle TopLink Developer's Guide), only a root object can be marshaled. Attempting to marshal a non-root object with document preservation on will result in an exception.
This section contains information on the following issues:
When using TopLink Essentials in Oracle JDeveloper, TopLink now automatically adds the TopLink Essentials JPA library during entity generation from tables. When using earlier versions of Oracle JDeveloper with TopLink Essentials, if you explicitly enumerate the persistence provider in the persistence.xml to be Essentials, you must also include the toplink-essentials.jar in the "Add Contributors" dialog. To add the toplink-essentials.jar, right-click the deployment profile in the Application Navigator and select Properties. Then click the Add button to add the toplink-essentials.jar.
When launching Oracle TopLink Workbench workbench using JDK 1.6u1 on a Linux platform, the following output error may appear every 30 seconds:
java.util.prefs.FileSystemPreferences syncWorld WARNING: Couldn't flush user prefs: java.util.prefs.BackingStoreException: java.lang.IllegalArgumentException: indent-number.
This error appears due to a bug in the Sun JDK 1.6 (6396599). As a result of this bug, you cannot save your TopLink Workbench preferences. You can minimize the error log and continue to work, without incident, although the error will continually be written to the log.
By default, the TopLink installation allows only the user who performed the installation to access the installed files. If your TopLink installation is in a shared environment you must manually change the file permissions for all files in the <ORACLE_HOME> directory after completing the installer. Executable files require read and execute access; non-executable files require read access. Refer to your operating system documentation for information on setting file permissions.
After installing Oracle TopLink, the welcome page will appear in English – regardless of the language you selected during installation. To display your language-specific page, select the appropriate file in the <ORACLE_HOME>\toplink\doc\ folder.
This section includes information on the following issues:
The command for creating the project.xml file programatically, as listed in the Oracle TopLink Developer's Guide, is incorrect. The correct command is:
java -classpath toplink.jar;toplinkmw.jar;xmlparserv2.jar;ejb.jar;oracle.toplink.workbench.mappings.DeploymentXMLGenerator <MW_Project.mwp> <output file.xml>
In Table 7-1 TopLink Integration Support by Application Server Type, as listed in the Oracle TopLink Developer's Guide, it incorrectly states that TopLink provides EJB 2.1 CMP support with Weblogic Server 9.0.
For a complete up-to-date list of Oracle TopLink Support and Certifications, see http://www.oracle.com/technology/products/ias/toplink/technical/support/index.html.
Table: Resolved Issues for the Oracle TopLink 10g (10.1.3.4.0) lists the resolved issues in this patch set:
Resolved Issues for the Oracle TopLink 10g (10.1.3.4.0)
| Reference Number | Description |
|---|---|
|
4177824 |
Fixed pessimistic locking support on SqlServer. |
|
5709520 |
Using a temporal attribute defined in an embedded object in JPQL results in an EJBQLException. Exception Description: Unknown state or association field [attributeName] of class [embeddedClassName]. |
|
5899959 |
Fixed a concurrent query execution problem. |
|
6001602 |
Fix to Call to allow for deletes to be performed through Stored Procedures. Before this fix, it was possible for an exception to be thrown during the Delete. |
|
6001198 |
A |
|
6033380 |
When an aggregate object's parent is invalidated, and then the parent is re-read, the identity of the aggregate object is now maintained. |
|
6039935 |
Resolved very rare NullPointerException in |
|
6111278 |
Resolved TOPLINK-6069 error wheng |
|
6342301 |
In large unit of work transactions where indirection is used, a potential object leak no longer occurs for update queries cached on the descriptor query manager (descriptor). |
|
6450867 |
In a multiple table mapping scenario, querying on a superclass for a subclass instance using conforming on a |
|
6468350 |
In previous releases, when |
|
6643955 |
An RMI discovery manager hang no longer occurs when a session is configured to use Remote Command Management (RCM) and a peer sends an announcement with an incorrect or bad URL to connect back to. |
|
6671556 |
When refreshing an object graph in a unit of work where the parent object is valid, but related objects are invalid, the related objects are not refreshed and not validated. This no longer happens when the relationship mappings do not use indirection. |
|
6713854 |
When attempting to delete and recreate an Entity Bean with the same primary key in the same transaction, TopLink throws an Entity already exists exception. To avoid such an exception, users need to activate non deferred writes by setting the descriptor of the object in question and any objects that are dependent on this object to Defer Updated or Defer None. |
|
6722538 |
Named queries no longer reference their executing session, enabling garbage collection for unit of work instances. |
|
6742252 |
Resolved issue which caused a VM crash when reading from a row containing an |
Table: Resolved Issues for the Oracle TopLink 10g (10.1.3.3.0) lists the resolved issues in this patch set:
Resolved Issues for the Oracle TopLink 10g (10.1.3.3.0)
| Reference Number | Description |
|---|---|
|
5593818 |
In versions earlier than 10.1.3.3, users will encounter a |
|
5744223 |
Null pointer exceptions no longer occur when shutting down a server using JMS. |
|
5555181 |
When a Clustered JMS service fails, TopLink may stop receiving Cache coordination messages from the JMS Topic. Extra JMS connections may continue to stay alive. |
|
5885475 |
TopLink no longer throws a |
|
5711476 |
Field level locking now compares the fields correctly in the where clause. |
|
5857278 |
In TopLink Workbench, you can now delete a session broker when all managed sessions have been removed, including if you change the session name within the session broker beforehand. |
This section describes resolved issues in this release.
Table: Resolved Issues for the Oracle TopLink Foundation Library lists the resolved issues for the Oracle TopLink Foundation Library.
Table: Resolved Issues for the Oracle TopLink Workbench and JDeveloper Mapping Editor lists the resolved issues for the TopLink Workbench.
Resolved Issues for the Oracle TopLink Foundation Library
| Reference Number | Description |
|---|---|
|
TopLink ORM (Object-Relational) |
|
|
5156075 |
In specific circumstances, some deferred locks were not fully released when executing a query on a superclass, possibly causing "hung threads." These instances have been corrected. |
|
5013294 |
Enhanced ServerPlatform (
|
|
TopLink JAXB (Object-XML) |
|
|
5018872 |
TopLink now supports direct collection mappings of classes that have a nested composite object mapping, when using a SAX parser platform. |
|
5035551 |
TopLink now correctly marshals object graphs into XML when a composite object mapping exists where the XPath is self and the referenced descriptor has attribute mappings. |
|
5068662 |
Creating an XML composite direct collection mapping ( |
|
5112171 |
When creating an |
|
5203235 |
When using the SAX platform, the |
|
5256508 |
The XMLContent now allows you to specify the sessions configuration filename. In previous versions, TopLink supported naming the sessions configuration only as
|
|
5365650 |
Creating a |
|
Foundation Library |
|
|
5200555 |
TopLink no longer throws an exception (6044) when executing an |
|
5015459 |
SessionFactory ( |
|
5171059 |
In previous versions, if Attribute Level Change tracking was configured on a Aggregate mapping prior to the session Login, then the configuration would be lost. The Attribute Level Change tracking now be configured pre-login, and the behavior will continue post-login. |
|
5229648 |
In previous versions, some mappings (direct collection, direct map, and transformation mapping) on an isolated class did not produce isolated queries. This issue has been corrected; mappings on an isolated class will produce isolated queries. |
|
4241441 |
Oracle TopLink now includes Oracle Database-specific support for batch writing, when used in conjunction with optimist locking, to return the row count correctly. The new |
Resolved Issues for the Oracle TopLink Workbench and JDeveloper Mapping Editor
| Reference Number | Description |
|---|---|
|
5376828 |
Password is now encrypted properly in the |
|
5251396 |
Data source can be configured within sessions configuration editor (
|
|
5074239 |
In TopLink Workbench, when configuring an aggregate mapping, the selected fields now update properly on the Fields tab. |
|
5029955 |
TopLink Workbench no longer creates duplicate mappings in one-to-many mappings, when generating descriptors from tables that have identical names. |
|
5102113 |
For read-only descriptors, TopLink Workbench no longer displays a "multiple writable mappings" error. |
|
5016177 |
In TopLink Workbench, mapping, then unmapping an inherited attribute no longer throws an exception. |
|
5159194 |
TopLink Workbench correctly creates a type conversion mapping when mapping a |
|
5084680 |
The Manage Non-descriptor Classes dialog now displays a scroll bar for large projects. |
|
5129294, 5121242 |
Multiple issues regarding importing a 9.0.4.4 TopLink Workbench project have been resolved. In prior versions, importing projects that contained database tables with a schema may have caused an exception. Additionally, 9.0.4 projects with foreign reference mappings now import correctly. |
|
5148799 |
The target key for a one-to-one mapping is maintained when upgrading a 9.0.4 project. |
|
5176174 |
Table schema is maintained when upgrading prior TopLink Workbench projects. In prior versions, some primary key values were not maintained. |
|
5338610 |
TopLink Workbench works correctly with inner classes. Previously, an exception was generated indicating that the default constructor could not be used. |
|
4748625 |
TopLink correctly creates Java classes from table names with spaces. For example a table named ADDRESS 1 (with a space) will create a Java class named ADDRESS1 (without a space). |
|
4950088 |
Canceling the Expression Builder dialog no longer throws an exception |
Our goal is to make Oracle products, services, and supporting documentation accessible, with good usability, to the disabled community. To that end, our documentation includes features that make information available to users of assistive technology. This documentation is available in HTML format, and contains markup to facilitate access by the disabled community. Accessibility standards will continue to evolve over time, and Oracle is actively engaged with other market-leading technology vendors to address technical obstacles so that our documentation can be accessible to all of our customers. For more information, visit the Oracle Accessibility Program Web site at http://www.oracle.com/accessibility/.
Accessibility of Code Examples in Documentation
Screen readers may not always correctly read the code examples in this document. The conventions for writing code require that closing braces should appear on an otherwise empty line; however, some screen readers may not always read a line of text that consists solely of a bracket or brace.
Accessibility of Links to External Web Sites in Documentation
This documentation may contain links to Web sites of other companies or organizations that Oracle does not own or control. Oracle neither evaluates nor makes any representations regarding the accessibility of these Web sites.
TTY Access to Oracle Support Services
Oracle provides dedicated Text Telephone (TTY) access to Oracle Support Services within the United States of America 24 hours a day, seven days a week. For TTY support, call 800.446.2398.
Oracle TopLink Release Notes, 10g (10.1.3.1.0)/(10.1.3.4.0)
The Programs (which include both the software and documentation) contain proprietary information; they are provided under a license agreement containing restrictions on use and disclosure and are also protected by copyright, patent, and other intellectual and industrial property laws. Reverse engineering, disassembly, or decompilation of the Programs, except to the extent required to obtain interoperability with other independently created software or as specified by law, is prohibited.
The information contained in this document is subject to change without notice. If you find any problems in the documentation, please report them to us in writing. This document is not warranted to be error-free. Except as may be expressly permitted in your license agreement for these Programs, no part of these Programs may be reproduced or transmitted in any form or by any means, electronic or mechanical, for any purpose.
If the Programs are delivered to the United States Government or anyone licensing or using the Programs on behalf of the United States Government, the following notice is applicable:
U.S. GOVERNMENT RIGHTS Programs, software, databases, and related documentation and technical data delivered to U.S. Government customers are "commercial computer software" or "commercial technical data" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, use, duplication, disclosure, modification, and adaptation of the Programs, including documentation and technical data, shall be subject to the licensing restrictions set forth in the applicable Oracle license agreement, and, to the extent applicable, the additional rights set forth in FAR 52.227-19, Commercial Computer Software--Restricted Rights (June 1987). Oracle USA, Inc., 500 Oracle Parkway, Redwood City, CA 94065
The Programs are not intended for use in any nuclear, aviation, mass transit, medical, or other inherently dangerous applications. It shall be the licensee's responsibility to take all appropriate fail-safe, backup, redundancy and other measures to ensure the safe use of such applications if the Programs are used for such purposes, and we disclaim liability for any damages caused by such use of the Programs.
Oracle, JD Edwards, PeopleSoft, and Siebel are registered trademarks of Oracle Corporation and/or its affiliates. Other names may be trademarks of their respective owners.
The Programs may provide links to Web sites and access to content, products, and services from third parties. Oracle is not responsible for the availability of, or any content provided on, third-party Web sites. You bear all risks associated with the use of such content. If you choose to purchase any products or services from a third party, the relationship is directly between you and the third party. Oracle is not responsible for: (a) the quality of third-party products or services; or (b) fulfilling any of the terms of the agreement with the third party, including delivery of products or services and warranty obligations related to purchased products or services. Oracle is not responsible for any loss or damage of any sort that you may incur from dealing with any third party.