Application Server Integration Concepts

This section describes concepts unique to TopLink application server integration, including the following:

• Software Requirements

• XML Parser Platform Configuration

• Security Permissions

• Persistence Manager Migration

• Clustering

Software Requirements

To run a TopLink application within a J2EE container, your system must meet the following software requirements:

• An application server or J2EE container (see Table 7-1)

• XML parser (see "XML Parser Platform Configuration")

• A JDBC driver configured to connect with your local database system (for more information, see your database administrator)

• A Java development environment, such as:

  • Oracle JDeveloper

  • IBM WebSphere Studio Application Developer (WSAD)

  • Sun Java Development Kit (JDK) 1.3.1 or later. Oracle recommends using 1.4.2 (or later).

• Any other Java environment that is compatible with the Sun JDK 1.3.1 or later

• A command-line JVM executable (such as java.exe or jre.exe)

XML Parser Platform Configuration

The TopLink run-time environment uses an XML parser to do the following:

• Read and write XML configuration files (see "project.xml File" and "sessions.xml File")

• Read and write TopLink Workbench project files (see "Understanding TopLink Workbench")

• Perform object-to-XML transformations in EIS projects using XML records (see "Understanding EIS Mappings")

• Perform object-to-XML transformations in XML projects (see "Understanding XML Mappings")

Application servers use an XML parser to read deployment files such as ejb-jar.xml and <J2EE container>-ejb-jar.xml (see "Creating TopLink Files for Deployment").

To avoid XML parser conflicts, you must configure your TopLink application to use the same XML parser as that used by the application server on which you deploy your application.

Internally, TopLink accesses its XML parser using an instance of oracle.toplink.platform.xml.XMLPlatform class.

You can configure TopLink to use any XML parser for which an XMLPlatform class exists (see "Configuring XML Parser Platform").

You can also create your own XMLPlatform to provide access to an XML parser not currently supported by TopLink (see "Creating an XML Parser Platform").

Configuring XML Parser Platform

TopLink provides the XMLPlatform instances shown in Table 7-2.

Table 7-2 Supported XML Platforms

XMLPlatform...	Provides Access too...	Use With...
oracle.toplink.platform.xml.xdk. XDKPlatformFoot 1	XDKParser: this class provides access to the Oracle XML Developer's Kit (XDK) XML parser (see http://www.oracle.com/technology/tech/xml/xdkhome.html).	Oracle Containers for J2EE (OC4J)
oracle.toplink.platform.xml.jaxp. JAXPPlatform	JAXPParser: this class provides access to the Java SDK XML parser in the javax.xml.parsers package (see http://java.sun.com/j2ee/1.4/docs/tutorial/doc/JAXPIntro2.html).	BEA WebLogic Server IBM WebSphere Application Server

^Footnote 1 Default:

Note: To use an XML parser not listed in Table 7-2, create your own XMLPlatform (see "Creating an XML Parser Platform").

To configure your TopLink application to use a particular instance of the XMLPlatform class, set system property toplink.xml.platform to the fully qualified name of your XMLPlatform class as Example 7-1 shows.

Example 7-1 Configuring XML Platform

toplink.xml.platform=oracle.toplink.platform.xml.jaxp.JAXPPlatform

Creating an XML Parser Platform

Using the oracle.toplink.platform.xml classes included in the public source files shipped with TopLink (see "Using Public Source"), you can create your own instance of the oracle.toplink.platform.xml.XMLPlatform class to specify an XML parser not listed in Table 7-2.

After creating your XMLPlatform, configure TopLink to use it (see "Configuring XML Parser Platform").

XML Parser Limitations

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

Security Permissions

By default, when you run a TopLink-enabled application in a JVM configured with a nondefault java.lang.SecurityManager, the TopLink run-time environment executes certain internal functions by executing a PrivilegedAction with java.security.AccessController method doPrivileged. This ensures that you do not need to grant many permissions to TopLink for it to perform its most common operations. You need only grant certain permissions depending on the types of optional TopLink features you use.

For more information, see "Understanding Security Permissions".

If you run a TopLink-enabled application in a JVM without a nondefault SecurityManager, you do not need to set any permissions.

Persistence Manager Migration

From the perspective of an application server, TopLink is a persistence manager. You can configure an application server to use TopLink as the default persistence manager.

You can only use one persistence manager for all the CMP EJB in a JAR file.

TopLink provides automated support for migrating an existing J2EE application to use TopLink as the persistence manager. For more information, see the following:

• "Migrating OC4J Orion Persistence to OC4J TopLink Persistence"

• "Migrating BEA WebLogic Persistence to OC4J TopLink Persistence"

Clustering

Most application servers include a clustering service that you can use with your TopLink application. To use TopLink with an application server cluster, use this procedure:

1. Install the toplink.jar file (and include it in the classpath) on each application server in the cluster to which you deploy TopLink applications.

2. Configure TopLink cache consistency options appropriate for your application.

   For more information, see "Understanding the Cache".

   If you are deploying a CMP application, see also "Configuring cache-synchronization Properties".

3. Configure clustering on each application server.

   For more information, see your application server documentation.