Skip Headers
Oracle® Application Server Release Notes
10g Release 2 (10.1.2) for hp-ux Itanium and Linux Itanium
B15871-05
  Go To Documentation Library
Home
Go To Table Of Contents
Contents
Go To Index
Index

Previous
Previous
 
Next
Next
 

7 Oracle Application Server TopLink

This chapter describes the general issues and workarounds in Oracle Application Server TopLink 10g (9.0.4.5). It includes the following topics:

7.1 Known Issues

The following issues exist in OracleAS TopLink 10g (9.0.4.5):

7.1.1 oracle.sql.TIMESTAMP

When using Oracle JDBC 9.0.1 driver, resultSet.getTimestamp(int) returns oracle.sql.TIMESTAMP, instead of java.sql.Timestamp. As a result, oracle.sql.TIMESTAMP is stored in DatabaseRow. Although OracleAS TopLink converts oracle.sql.TIMESTAMP to java.sql.Timestamp at a later stage for a successful read, serialization on an attribute of ValueHolderInterface type representing an object mapped to TIMESTAMP field will fail because DatabaseRow is an attribute of ValueHolder and oracle.sql.TIMESTAMP is not serializable.

7.1.2 XML Parser Dependencies

This section describes the following XML parser dependency issues:

7.1.2.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. Display the comment associated with the <ORACLE_HOME>/lib/xmlparserv2.jar file (where <ORACLE_HOME> is the directory in which you installed OracleAS TopLink).

    1. On Microsoft Windows, configure WinZip to display comments by selecting Options and then Configuration. Select the Miscellaneous tab, and ensure that the Show comments when opening Zip files check box is checked. Open the <ORACLE_HOME>\lib\xmlparserv2.jar file with WinZip.

    2. On UNIX, use the following file:

      unzip -l <ORACLE_HOME>/lib/xmlparserv2.jar

    The comment shows the build that this version of OracleAS XML Parser for Java v2 belongs to. .

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

7.1.2.2 OracleAS TopLink 10g (9.0.4.5) with BEA WebLogic Application Server, 8.1

When you install OracleAS TopLink in conjunction with the Oracle Application Server 10g Release 2 (10.1.2) installation, changes introduced to the OracleAS XML Parser for Java v2 in 10g Release 2 (10.1.2) can cause issues for users that use OracleAS TopLink 10g (9.0.4.5) in conjunction with BEA WebLogic Application Server, 8.1 (BEA CR136750).

You will encounter NoSuchMethodError associated with the constructor of the javax.xml.namespace.QName class. To resolve this problem, users must download the Sun Web Services Development Kit from Sun and place the jax-qname.jar file on their classpath before both the toplink.jar and the weblogic.jar entries.

To download the Sun Web Services Development Kit, navigate to http://www.sun.com/

7.1.2.3 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, then 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.

7.1.3 UTF-8 Encoding Exceptions

In 10g (9.0.4.5), 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.

7.1.4 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 restored, then 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 re-establishes the connection to the database, any attempt to reexecute a previously cached statement will fail.

7.1.5 Using Oracle Application Server TopLink with IBM WebSphere 5.1

When using OracleAS TopLink with WebSphere Application Server 5.1, we recommend that applications should be configured and deployed with their class loader mode set to PARENT_LAST.

To configure an application with its class loader mode set to PARENT_LAST, select one of the following options:

  • Remove (or rename) the <JAVA_HOME>/lib/jaxp.properties file, where <JAVA_HOME> refers to <WebShpere_Install>/java/jre.

  • Place the xerces library included in the WebSphere installation after xmlparserv2.jar in the same shared library. This file is located in <WebShpere_Install>/java/jre/lib/xml.jar.

7.1.6 OracleAS TopLink Mapping Workbench

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

7.1.6.1 Mapping Inherited Attributes

You cannot map inherited attributes on a descriptor whose superclass has no descriptor. You can select the root descriptor, but cannot map its attributes.

In order to map the project, import the superclass into the project. OracleAS TopLink Mapping Workbench creates a descriptor for the superclass. Then, deactivate this descriptor or remove it from the project.

7.1.6.2 Changing Classes in Code

If you change a descriptor to an interface or abstract class in code (outside of OracleAS TopLink Mapping Workbench), then when you refresh the class in OracleAS TopLink Mapping Workbench, you may get an ExternalClassNotFoundException.

For example, a project contains two descriptors: Employee and EmployeeInterface. Both are classes and Employee extends EmployeeInterface. Outside of OracleAS TopLink Mapping Workbench you edit the EmployeeInterface code to change it to an interface and make Employee implement the interface. When you refresh the classes in OracleAS TopLink Mapping Workbench, you will receive the error.

To avoid this situation, refresh EmployeeInterface first, then refresh Employee.

7.1.6.3 Refreshing Descriptors with Dependent Classes

When you refresh a descriptor, the OracleAS TopLink Mapping Workbench does not refresh dependent classes if they are not included in the OracleAS TopLink Mapping Workbench project.

For example, if you define a descriptor with an after load class and method which is not included in the OracleAS TopLink Mapping Workbench project and you change the after load class outside of the OracleAS TopLink Mapping Workbench, then when you refresh the descriptor, the OracleAS TopLink Mapping Workbench does not pick up the change.

To workaround this issue, add all dependent classes to the OracleAS TopLink Mapping Workbench project. Because you do not map them, right-click each dependent class and deselect the Activate Descriptor option. Now when you refresh the project, the OracleAS TopLink Mapping Workbench refreshes both descriptors and dependent classes.

7.1.6.4 OracleAS TopLink Sessions Editor Preferences

Before changing any other general preferences (such as the text editor location), you must select a default Look and Feel in the General Preferences dialog and click OK. Then reopen the General Preferences dialog and make any additional changes.

7.1.6.5 Classpath with Spaces in Directory Names

On the Microsoft Windows platform, if your classpath contains directories with names that have spaces in them, then the OracleAS TopLink Mapping Workbench may fail to start and displays the error Cannot Find Main Class.

If this is the case, then consider removing spaces from directory names in the JDBC, Oracle home, and JRE classpaths.

7.1.6.6 Icon Size

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

7.1.6.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 cancelled the process, the OracleAS TopLink Mapping Workbench did not overwrite any existing code.

In 10g (9.0.4.5), the OracleAS TopLink Mapping Workbench does not support generating Project Java Source for Descriptors mapped to inner classes.

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

7.1.6.8 Improper Set Method for Array Type Attributes

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

7.1.7 Using the OracleAS TopLink Web Client

The following issues exist with the OracleAS TopLink Web client:

7.1.8 OracleAS TopLink Examples

The following issues exist in the OracleAS TopLink Examples:

7.1.8.1 IBM WebSphere BMP Examples

The duplicate entries of ibm-application*.xmi in bmp.ear cause a Save Failure Exception when deploying the BMP example on IBM WebSphere 5.0.2. To correct this, comment out the following element inside build.ear in the build.xml file:


<metainf dir="${config.dir}">

    <include name="ibm-application*.xmi"/>

</metainf> 

7.1.8.2 Configuring Examples for RedHat

Running the configureExamples.sh on RedHat Enterprise Server 3.0 may cause a missing class for multipleCopy error. To correct this, modify the build.xml file to contain the absolute path to the toplink_customtasks.jar. For example:


<taskdef name="multipleCopy"

    classname="org.apache.tools.ant.taskdefs.MultipleCopy"

    classpath="<COMPLETE_ABSOLUTE_PATH>/customtasks.jar"/> 



where <COMPLETE_ABSOLUTE_PATH> = /home/iasuser/mwtesting/ant/lib/toplink_customtasks.jar

7.1.9 Problem On Red Hat Enterprise Linux AS/ES 3.0 Systems

Before running the configureExamples.sh script on a Red Hat Enterprise Linux AS/ES 3.0 system, complete the following steps:

  1. Open the $ORACLE_HOME/toplink/examples/build.xml file in a text editor.

  2. Search for the following string:

    
    <taskdef name="multipleCopy"
    
    
    
    
  3. Edit the section as follows, where oracle_home is the absolute path to the Oracle Home directory:

    
    <taskdef name="multipleCopy"
    
    classname="org.apache.tools.ant.taskdefs.MultipleCopy"
    
    classpath="oracle_home/ant/lib/toplink_customtasks.jar"/>
    
    
    
    

    For example, if /opt/oracle is the Oracle Home, edit the section as follows:

    
    <taskdef name="multipleCopy"
    
    classname="org.apache.tools.ant.taskdefs.MultipleCopy"
    
    classpath="/opt/oracle/ant/lib/toplink_customtasks.jar"/>
    
    
    
    

7.2 Documentation Errata

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

7.2.1 Parameterized SQL

The Oracle Application Server TopLink Application Developer's Guide incorrectly states that you cannot use batch writing and parameterized SQL together.

7.2.2 Sequencing Examples

The sequencing code examples (Example A-2 and Example A-3) in the Oracle Application Server TopLink Application Developer's Guide are incorrect. Example 3-22 and Example 3-23 illustrate the correct code examples for using sequencing with stored procedures.

7.2.3 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 to the web.xml file should be:

<ORACLE_HOME>/toplink/config/toplinkwc.When using the Web Client with OC4J, replace the path indicated in the document:

<ORACLE_HOME>/toplink/examples/oc4j/904/server/

with your local <J2EE_HOME> directory.

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.

7.2.4 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.

  • In Example B-4, the line:

    president.addPhoneNumber(homeNumber);

    should be:

    president.addPhoneNumber(homePhone);