7 Oracle TopLink

This chapter describes issues associated with Oracle TopLink (TopLink). It includes the following topic:

• Section 7.1, "General Issues and Workarounds"

• Section 7.2, "Documentation Errata"

7.1 General Issues and Workarounds

This section describes general issue and workaround. It includes the following topic:

• Section 7.1.1, "Links to Hosted Documentation and Web-Based Resources from TopLink Workbench"

• Section 7.1.2, "Using Non-ASCII Characters with a JAXB 1.0 TopLink Project"

• Section 7.1.3, "TopLink Workbench Look and Feel With Linux GTK"

• Section 7.1.4, "Unit of Work and JTA Transactions"

• Section 7.1.5, "UnitOfWork.release() not Supported with External Transaction Control"

• Section 7.1.6, "ReportQuery Results for Aggregate Functions may be Truncated"

• Section 7.1.7, "Attribute Joining of One-to-One Mappings not Supported with Inheritance"

• Section 7.1.8, "Using Oracle Database Advanced Data Types may Fail with Some Data Sources"

• Section 7.1.9, "Returning Policy with Optimistic Locking"

• Section 7.1.10, "Using Timestamp"

• Section 7.1.11, "Configuring Sequencing in sessions.xml"

• Section 7.1.12, "Marshalling a Non-root Object with Document Preservation"

7.1.1 Links to Hosted Documentation and Web-Based Resources from TopLink Workbench

When using the online help and the hosted documentation, TopLink Workbench requires an internet connection to OTN (Oracle Technology Network). Your PC must have a network connection (including any required proxy information) and an internet browser for use with the TopLink Workbench. If the TopLink Workbench is unable to connect to OTN, some links in the online help or the Welcome page may not work properly.

To configure preferences for an external browser for use with the TopLink Workbench, select Tools > Preferences > Help. Click Browse and select the location of your default Web browser. For more information on Help preferences, go to the Help menu and select Working With TopLink Workbench Preferences.

7.1.2 Using Non-ASCII Characters with a JAXB 1.0 TopLink Project

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.

7.1.3 TopLink Workbench Look and Feel With Linux GTK

When using TopLink Workbench on a PC using the Linux GTK look and feel, do not set the TopLink Workbench Look and Feel Preference to GTK+. Doing so may cause unexpected complications. Oracle recommends using the Metal, Oracle, or CD/Motif look and feel instead. Refer to "Working with TopLink Workbench Preferences" in Oracle TopLink Developer's Guide for complete information.

7.1.4 Unit of Work and JTA Transactions

If a unit of work is synchronized with a Java Transaction API (JTA), an exception will be thrown if it is released. If the current transaction requires that changes not be persisted, the JTA transaction must be rolled back. If you wish to have the transaction rolled back, do so with its API.

7.1.5 UnitOfWork.release() not Supported with External Transaction Control

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
{
    @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
    SessionContext sc;
    
    public void someMethod() 
    {
        sc.getUserTransaction().begin();
        ...
        sc.getUserTransaction().rollback();
    }
} 

7.1.6 ReportQuery Results for Aggregate Functions may be Truncated

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"));

7.1.7 Attribute Joining of One-to-One Mappings not Supported with Inheritance

It is not possible to execute a query on a class involved in an inheritance hierarchy which also has one-to-one 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.

7.1.8 Using Oracle Database Advanced Data Types may Fail with Some Data Sources

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.

7.1.9 Returning Policy with Optimistic Locking

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.

7.1.10 Using Timestamp

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.

7.1.11 Configuring Sequencing in sessions.xml

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.

7.1.12 Marshalling a Non-root Object with Document Preservation

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.

7.2 Documentation Errata

This section includes information on the following issue:

• Section 7.2.1, "Creating project.xml Programatically"

7.2.1 Creating project.xml Programatically

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>