9
OracleAS TopLink

This chapter describes issues with OracleAS TopLink. It includes the following topics:

• Section 9.1, "General Issues and Workarounds"

• Section 9.2, "Documentation Errata"

9.1 General Issues and Workarounds

This section describes general issues and their workarounds for OracleAS TopLink. It includes the following topics:

• Section 9.1.1, "New Package Names"

• Section 9.1.2, "API Modifications"

• Section 9.1.3, "OracleAS TopLink Examples"

• Section 9.1.4, "EJB QL Parsing and Running JSPs on BEA WebLogic 8.1 Service Pack 1"

• Section 9.1.5, "XML Parser Dependencies"

• Section 9.1.6, "UTF-8 Encoding Exceptions"

• Section 9.1.7, "SAXParseException Error Message"

• Section 9.1.8, "Using OracleAS TopLink - Web Client with Right-to-left Languages"

• Section 9.1.9, "Prepared Statements may Fail to Execute After a loss of Communication to the Database"

• Section 9.1.10, "OracleAS TopLink Mapping Workbench"

9.1.1 New Package Names

Beginning with Release 2 (9.0.3), the base package for the entire structure became oracle.toplink. Use the Package Rename tool to upgrade any existing application source code and OracleAS TopLink Mapping Workbench project that refers to a pre-Release 2 (9.0.3) versions.

Note: If you are upgrading from a version previous to Release 2 (9.0.3), you must convert the package names before opening your project(s) in OracleAS TopLink 10g (9.0.4).

For more information on the Package Rename tool, see the Oracle Application Server TopLink Getting Started Guide.

9.1.2 API Modifications

In 10g (9.0.4), OracleAS TopLink modified the API as follows:

• For DatabasePlatform.initializePreallocatedSequences(): use DatabaseSession.getSequencingControl().initializePreallocated() instead.

• DatabasePlatform.setUsesNativeSequencing(boolean) is now marked as INTERNAL and should not be used by users. Use DatabaseSession.getSequencingControl().shouldUseNativeSequencing() and shouldUseTableSequencing() instead.

• Changes to oracle.toplink.tools.codegen. To maintain existing code, use the following:
  • For AttributeDefinition, use ReflectiveAttributeDefinition instead.

  • For MethodDefinition, use ReflectiveMethodDefinition instead.

  Additional code definition implementations include NonreflectiveMethodDefinition and NonreflectiveAttributeDefinition.

• Added RemoteCORBAConnection.scrollableCursorPreviousObject.

• Added RemoteEJBConnection.scrollableCursorPreviousObject.

• Added RemoteJMSConnection.scrollableCursorPreviousObject.

• Added RemoteRMIConnection.scrollableCursorPreviousObject.

9.1.3 OracleAS TopLink Examples

If you attempt to run the EJB 1.1 CMP Single Bean example with BEA Weblogic 6.1 on the Sybase SQL Server, Sybase throws a SQL error.

9.1.4 EJB QL Parsing and Running JSPs on BEA WebLogic 8.1 Service Pack 1

In OracleAS TopLink 10g (9.0.4), OracleAS TopLink builds and parses against ANTLR 2.70. BEA WebLogic 8.1 Service Pack 1 ships with ANTLR 2.72. Using OracleAS TopLink EJB QL parsing and running JSPs simultaneously in the same application with BEA WebLogic 8.1 SP1 causes parsing problems due to incompatibilities between the ANTLR versions. Consider the following:

• Section 9.1.4.1, "EJB QL parsing"

• Section 9.1.4.2, "Running JSPs"

9.1.4.1 EJB QL parsing

To use OracleAS TopLink EJB QL parsing with BEA WebLogic 8.1 SP1, without running JSPs simultaneously, place the antlr.jar file (version 2.70 provided with the OracleAS TopLink install), as the first item in the class path.

9.1.4.2 Running JSPs

To run JSPs with OracleAS TopLink with BEA WebLogic 8.1 SP1, without EJB QL simultaneously, remove the antlr.jar file (version 2.70) from the class path.

9.1.5 XML Parser Dependencies

Consider the following XML parser dependency issues:

• Section 9.1.5.1, "OC4J XML Parser Dependency"

• Section 9.1.5.2, "Crimson XML Parser Issue"

9.1.5.1 OC4J XML Parser Dependency

By default, both OC4J and OracleAS TopLink use the OracleAS XML Parser for Java v2. When using OC4J and OracleAS TopLink together, ensure that both use the same version of OracleAS XML Parser for Java v2. Failure to do so may result in XML parsing failures and application errors.

To determine what version of OracleAS XML Parser for Java v2 is used in your OracleAS TopLink installation:

1. Start WinZip

2. Configure WinZip to display comments: select Options > Configuration, select the Miscellaneous tab, and ensure that the "Show comments when opening Zip files" check box is checked.

3. Using WinZip, navigate to the <ORACLE_HOME>\lib directory (where <ORACLE_HOME> is the directory in which you installed OracleAS TopLink) and open the xmlparserv2.jar file.

   A window opens with a comment that shows the build that this version of OracleAS XML Parser for Java v2 belongs to. For example: Label: XDK_MAIN_SOLARIS_031006.

4. Ensure that this build is the same as the build associated with the OracleAS XML Parser for Java v2 used in OC4J.

9.1.5.2 Crimson XML Parser Issue

Crimson (http://xml.apache.org/crimson/) is the XML parser supplied in the Java 2 Platform, Standard Edition (J2SE) and in some JAXP reference implementations.

If you use Crimson with the JAXP API to parse XML files whose system identifier is not a fully qualified URL, then XML parsing will fail with a "not valid URL" exception.

Other XML parsers defer validation of the system identifier URL until it is specifically referenced.

If you are experiencing this problem, consider one of the following alternatives:

• Ensure that your XML files use a fully qualified system identifier URL.

• Use another XML parser (such as the OracleAS XML Parser for Java v2).

9.1.6 UTF-8 Encoding Exceptions

In 10g (9.0.4), OracleAS TopLink only supports UTF-8 encoding. The SAXParseException with OracleAS TopLink Exception, Error Code 9006 occurs if you attempt to read a non-UTF-8 formatted XML file.

9.1.7 SAXParseException Error Message

• The markup in the document preceding the root element must be well-formed.

• Start of root element expected.

If any of these exceptions occurs, assess the possibility that UTF-8 encoding is the issue.

9.1.8 Using OracleAS TopLink - Web Client with Right-to-left Languages

The OracleAS TopLink - Web Client does not correctly display text for some right-to-left languages.

9.1.9 Prepared Statements may Fail to Execute After a loss of Communication to the Database

If you configure a Login or Query to use statement caching and communication to the database is lost and then restored, previously cached statements may fail to execute.

For example, it is a common practice to define an exception handler and register it with a Session using Session.setExceptionHandler(). When the exception handler is invoked to handle a loss of communication and the handler reestablishes the connection to the database, any attempt to re-execute a previously cached statement will fail.

9.1.10 OracleAS TopLink Mapping Workbench

The following issues exist in OracleAS TopLink Mapping Workbench 10g (9.0.4):

• Section 9.1.10.1, "Migrating Projects from Earlier Versions"

• Section 9.1.10.2, "JDK Issue with Microsoft Windows and ATI Video Cards"

• Section 9.1.10.3, "Using Mapped Network Drives with Windows XP"

• Section 9.1.10.4, "Using JAWS"

• Section 9.1.10.5, "Icon Size"

• Section 9.1.10.6, "Referencing Large Class paths"

• Section 9.1.10.6, "Referencing Large Class paths"

• Section 9.1.10.7, "Generating Source Code"

• Section 9.1.10.8, "Multiple Levels of Joining"

• Section 9.1.10.9, "Unsupported JREs"

• Section 9.1.10.10, "Invalid Warning Message"

• Section 9.1.10.11, "Improper Set Method for Array Type Attributes"

• Section 9.1.10.12, "Canceling in Expression Builder May Still Modify a Query"

• Section 9.1.10.13, "Multiple Mappings to Primary Key Field can Affect how the OracleAS TopLink Mapping Workbench Generates the ejb-jar.xml File"

• Section 9.1.10.14, "Code Generated Project Class Uses String Values for All Types in Expressions"

9.1.10.1 Migrating Projects from Earlier Versions

If you are migrating an OracleAS TopLink Mapping Workbench project from a version prior to version 3.6, contact Oracle Support Services support for assistance at:

http://metalink.oracle.com

9.1.10.2 JDK Issue with Microsoft Windows and ATI Video Cards

On Microsoft Windows platforms, Java 2D functionality in J2SE 1.4.1 can cause a system crash (blue screen). Although the JDK 1.4.1_02 release fixes this bug, some non-Java applications may trigger a system crash. If you still encounter this problem when you run the OracleAS TopLink Mapping Workbench, update your ATI driver.

The latest drivers for a particular card are usually available on the web site of your computer, video card, or video chip manufacturer. For more information, also see the J2SE 1.4.1 release documentation at:

http://java.sun.com/j2se/1.4.1/relnotes.html

9.1.10.3 Using Mapped Network Drives with Windows XP

On Microsoft Windows XP platforms with mapped network drives, the OracleAS TopLink Mapping Workbench File Chooser dialogs (such as Save File or Open File) may experience slow responses for opening and traversing directory trees. Unmapping the network drives to eliminate this behavior.

9.1.10.4 Using JAWS

Due to limitations in JAWS 4.5.1, input field labels in the OracleAS TopLink Mapping Workbench are not read properly. Oracle recommends using JAWS 3.7 and version 103 Access Bridge for maximum accessibility.

9.1.10.5 Icon Size

Changing the icon size of the OracleAS TopLink Mapping Workbench toolbar may cause the application to fail at the next startup. You must edit the workbench.xml file and change small-icon="false" to "true".

9.1.10.6 Referencing Large Class paths

Referencing an extremely large directory (such as your root directory) or .jar file in your project's classpath may considerably slow the class chooser dialog and negatively impact performance.

9.1.10.7 Generating Source Code

If you attempt to generate source code for a descriptor but cancel the process before the OracleAS TopLink Mapping Workbench writes the new source code, a dialog indicates that the source code was successfully updated. However, if you canceled the process, the OracleAS TopLink Mapping Workbench did not overwrite any existing code.

In 10g (9.0.4), the OracleAS TopLink Mapping Workbench does not support generation of code for inner classes.

If you attempt to generate source code from a table with BLOBs, the generated Java code may contain errors in type the type definition and method parameters. You must edit the source code to eliminate the errors.

9.1.10.8 Multiple Levels of Joining

If you select Use Joining for a one-to-one mapping in the OracleAS TopLink Mapping Workbench, the generated SQL is incorrect and will return null instances.

Example 9-1

Customer has three objects linked by a 1:1 mapping: Customer has an Address; 
Address has a Country. Each class is mapped to a different table: Customer to 
CUSTOMER; Address to ADDRESS; Country to COUNTRY. With the Use Joining option, 
the OracleAS TopLink Mapping Workbench generates incorrect queries.

To join the relationships correctly, use the following syntax:

readAllByExample.addJoinedAttribute("address"); 
readAllByExample.addJoinedAttribute(tpBuilder.get("address").get("country"));

9.1.10.9 Unsupported JREs

Do not use the OracleAS TopLink Mapping Workbench with the Sun JRE 1.4. Refer to the Oracle Application Server TopLink Getting Started Guide for complete information on supported platforms.

9.1.10.10 Invalid Warning Message

When creating a variable one-to-one mapping, the OracleAS TopLink Mapping Workbench may incorrectly show the following warning message in the status bar:

The following specified Query Key Names are no longer valid: xxx

where xxx is a name of query key specified in Query Key Associations tab of mapping. This warning may be safely ignored.

9.1.10.11 Improper Set Method for Array Type Attributes

The OracleAS TopLink Mapping Workbench does not generate proper set method for array type attributes.

9.1.10.12 Canceling in Expression Builder May Still Modify a Query

When using the OracleAS TopLink Mapping Workbench Expression Builder, it is possible to inadvertently modify a query even if you select cancel to discard your changes.

For example, if you create a nested compound query, edit the query to remove the compound component, and then press Cancel to discard the changes, the changes are still applied. If this occurs, you must edit the query again and replace the inadvertently removed compound component.

9.1.10.13 Multiple Mappings to Primary Key Field can Affect how the OracleAS TopLink Mapping Workbench Generates the ejb-jar.xml File

When using the OracleAS TopLink Mapping Workbench to create EJB 2.0 CMP bean descriptors, avoid creating multiple mappings to the bean's primary key field. If such a descriptor contains multiple mappings to its primary key field, the required direct-to-field mapping must be the last primary key mapping in the descriptor. If it is not, the OracleAS TopLink Mapping Workbench will fail to write the primary-key-field element to the ejb-jar.xml file.

For example, if the descriptor contains a direct-to-field mapping for the primary key followed by a one-to-one mapping using the primary key as a foreign key, then the primary-key-field element is not written to the ejb-jar.xml file.

9.1.10.14 Code Generated Project Class Uses String Values for All Types in Expressions

When you define an expression in the OracleAS TopLink Mapping Workbench, you can select the type of any literal value. If you export the project Java source, all literal values are written out as String type.

For example, if you define a query with a literal value (100000) of type Long and then export the project Java source, the literal value is written out as a String type.

Example 9-2 Query in Exported Project Java Source

ReadObjectQuery namedQuery0 = new 
ReadObjectQuery(examples.sessions.threetier.model.Employee.class);
namedQuery0.setName("testQuery");
...
namedQuery0.setSelectionCriteria(expBuilder0.get("salary").equal("100000"));
descriptor.getQueryManager().addQuery("testQuery", namedQuery0);

9.2 Documentation Errata

This section describes known errors in the documentation. It includes the following topics:

• Section 9.2.1, "Configuring the OracleAS TopLink Web Client"

• Section 9.2.2, "OracleAS TopLink Mapping Workbench Tutorial"

9.2.1 Configuring the OracleAS TopLink Web Client

In the "Configuring the Web Client" section of the Oracle Application Server TopLink Application Developer's Guide, the correct path of the web.xml file should be: <ORACLE_HOME>\toplink\config\toplinkwc.

When using the Web Client with Oracle Application Server Containers for J2EE, substitute your local <J2EE_HOME> directory in place of the <ORACLE_HOME>\toplink\examples\oc4j\904\server\ indicated in the document.

To deploy to BEA WebLogic, you must also define a reference to this datasource in the <ORACLE_HOME>\toplink\config\toplinkwc\
weblogic.xml file, as follows:

<reference-descriptor>
  <resource-description>
    <res-ref-name>jdbc/DataSourceName</res-ref-name>
    <jndi-name>jdbc/DataSourceName</jndi-name>
  </resource-description>
</reference-descriptor>

In the "Configuring the Application Server" section, the first step of the procedure (where you are instructed to copy the toplinkwc.ear file to an application server-specific directory) is not required. When you run the assembleWebClient script located in the <ORACLE_HOME>\toplink\bin directory, the system assembles and deploys the toplinkwc.ear file for you, as specified in the build.properties file.

9.2.2 OracleAS TopLink Mapping Workbench Tutorial

When completing the tutorials in the Oracle Application Server TopLink Mapping Workbench User's Guide, be aware of the following changes:

• To use sequencing, in addition to creating the sequence table from the OracleAS TopLink Mapping Workbench, you must also create the sequence table in the database.

• When creating the sequence table, use size 38 for both SEQ_NAME and SEQ_COUNT.

• When implementing inheritance for the BaseProject descriptor, ensure that the Read Subclass On Query option is selected.

• Figure B-49 incorrectly omits the BaseProject class indicator type. Although BaseProject is an abstract class and does not require an indicator value, it is listed on the Inheritance tab.