|
Oracle® Application Server TopLink Application Developer's Guide
10g Release 2 (10.1.2) Part No. B15901-01 |
|
 Previous |
 Next |
|
Oracle® Application Server TopLink Application Developer's Guide
10g Release 2 (10.1.2) Part No. B15901-01 |
|
|
Previous |
Next |
OracleAS TopLink provides two ways to preconfigure your sessions: You can export and compile Java source code from OracleAS TopLink Mapping Workbench, or you can use the OracleAS TopLink Sessions Editor to build a session configuration file, the sessions.xml file. For the following reasons, we recommend you use the sessions.xml file to deploy an OracleAS TopLink application:
It is easy to create and maintain in the OracleAS TopLink Sessions Editor.
It is easy to troubleshoot.
It provides access to most session configuration options.
It offers excellent flexibility, including the ability to modify deployed applications.
This section describes the sessions.xml file and illustrates the options that are available when you build the file. This section discusses editing the file manually, but the simplest way to build the sessions.xml file is to use OracleAS TopLink Sessions Editor in OracleAS TopLink Mapping Workbench.
This section explains how to configure the sessions.xml file, and includes discussions on:
For more information about creating configuration files in OracleAS TopLink Mapping Workbench, see "Understanding the OracleAS TopLink Sessions Editor" in the Oracle Application Server TopLink Mapping Workbench User's Guide.
The Document Type Definition (DTD) of the sessions.xml file defines the file structure. If you use the OracleAS TopLink Sessions Editor, you need not concern yourself with that structure. However, if you do create or edit the file, you must understand its structure.
The main structure of the sessions.xml file is the toplink-configuration element. This element includes all session configuration options. Within the toplink-configuration element, you configure sessions and session brokers. The session broker contains only sessions defined in the sessions.xml file; the bulk of session configuration occurs within the session element.
Example 4-1 offers a navigational view of the sessions.xml file, illustrating the structure of the file:
Example 4-1 Navigating the sessions.xml File
<toplink-configuration> <session> <name> <project-class> or <project-xml> <session-type> <login> [Login Options including Sequencing and Cache Sysnchronization] <uses-external-connection-pool> <uses-external-transaction-controller> </login> <event-listener-class> <profiler-class> <data-source> <external-transaction-controller-class> <exception-handler-class> <connection-pool> [Connection Pool Options] </connection-pool> <enable-logging> [Logging Options] </enable-logging>> </session> </toplink-configuration>
The sessions.xml file begins with a header section that describes the file and specifies the location of the DTD for file validation.
If you use third-party parsers to parse the sessions.xml file, be aware that some parsers require a fully qualified path to the DTD in the XML header. If you are using such a parser, include the full path to the DTD in the system identifier, as follows:
<!DOCTYPE toplink-configuration PUBLIC "-//Oracle Corp.//DTD TopLink Sessions 9.0.4//EN" "file://<ORACLE_HOME>/toplink/config/dtds/sessions_9_0_4.dtd">
The Crimson parser (http://xml.apache.org/crimson/) is the Java XML parser supplied with the Java 2 Platform, Standard Edition (J2SE) and in some JAXP reference implementations. If you use the Crimson parser with the JAXP API to parse XML files whose system identifier is not a fully qualified URL, 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 experience 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 Oracle XML Parser for Java v2.
The toplink-configuration element is the root XML element for the sessions.xml file. It encapsulates the rest of the session configuration information.
The session element contains configuration information for an OracleAS TopLink session. It includes several tags that specify the options for the session. The sessions.xml file normally contains at least one session element and can include several elements if the application requires it.
The session element supports the configuration tags listed in Table 4-1.
Table 4-1 Tags Within the Session Element
| Tag | Description |
|---|---|
name
|
Specifies the name of the session. Assign a unique name to each session in the sessions.xml file to enable the session manager to retrieve it correctly.
The |
project-class
|
Specifies the name of the class that contains the OracleAS TopLink project metadata. Use this tag (and not the project-xml tag) to deploy a project that uses exported and compiled Java code.
Specify the fully qualified Java class name, but do not include the |
project-xml
|
Specifies the name of the XML file that contains the OracleAS TopLink project metadata. Use this tag (and not the project-class tag) to deploy your project that uses an exported XML file.
Specify the fully qualified file name, including the .xml extension. |
Example 4-3 Using a Project Class Element
<toplink-configuration> <session> <name>mysession</name> <project-class>com.mycompany.MyProject</project-class> ... </session> </toplink-configuration>
Example 4-4 Using the project.xml File
<toplink-configuration> <session> <name>mysession</name> <project-xml>C:/myproject/myproject.xml</project-xml> ... </session> </toplink-configuration>
In addition to the preceding tags, the session element includes several tags that contain session configuration information:
The session-type element appears inside of a session element and specifies the session type with the tags listed in Table 4-2.
Table 4-2 Tags Within the Session-Type Element
The login element tags listed in Table 4-3 are optional for the session. If you do not include the login element in the sessions.xml file, set a default login in OracleAS TopLink Mapping Workbench.
Table 4-3 Basic Configuration Tags Within the Login Element
| Tag | Description |
|---|---|
license-path
|
Specifies the license path for pre-TopLink 4.6 licensing. Because OracleAS TopLink no longer requires this tag, it does not process this element. If you are using the sessions.xml file from an OracleAS TopLink version that required a licence file, this tag will not prevent the sessions.xml file from running under the current version of OracleAS TopLink, but you should consider rebuilding your sessions.xml file.
Note: If you are using a sessions.xml file from an older version of OracleAS TopLink, you can delete this tag. |
driver-class
|
Specifies the JDBC driver class to use to log in to the database.
The |
connection-url
|
Specifies the JDBC connection URL for the database.
This tag is optional. Do not use the |
data-source
|
Specifies the datasource name if you are using a JNDI datasource.
This tag is optional. Do not use the |
platform-class
|
Specifies the OracleAS TopLink platform class for the session. This tag is optional.
For more information about platform classes, see "SDK Platform and Sequencing". |
user-name
|
The user name to log in to the database.
The |
password
|
The password to log in to the database.
The |
encrypted-password
|
The password of the user name used to log into the database.
The |
encryption-class- name
|
When you use an encrypted password, select the specific encryption class.
The |
Example 4-7 Basic Configuration Using JDBC
<session> <name>myServerSession</name> <project-class>com.mycompany.MyProject</project-class> <session-type> <server-session/> </session-type> <login> <license-path>C:/myproject/license/</license-path> <driver-class>oracle.jdbc.driver.OracleDriver</driver-class> <connection-url>jdbc:oracle:thin@dbserver:1521:dbname</connection-url> <platform-class>oracle.toplink.internal.databaseaccess.OraclePlatform</platform-class> <user-name>scott</user-name> <password>tiger</password> </login> ... </session>
Example 4-8 Basic Configuration Using a Datasource
<session> <name>myServerSession</name> <project-class>com.mycompany.MyProject</project-class> <session-type> <server-session/> </session-type> <login> <data-source>jdbc/MyApplicationDS</data-source> <platform-class>oracle.toplink.internal.databaseaccess.OraclePlatform</platform-class> </login> ... </session>
The login element offers several optional tags that enable you to customize your session login.
Optional tags that the login element offers include:
encryption-class-name: Specifies the name of the custom class used to encrypt and decrypt the password. The encryption-class-name must be fully qualified, and the class must be on the classpath.
encrypted-password: Specifies the encrypted password.
Other optional login tags accept TRUE or FALSE as valid values. Table 4-4 describes these tags.
Table 4-4 Optional Tags Within the Login Element
| Tag | Description |
|---|---|
should-bind-all-parameters
|
Enables parameter binding for all parameters. Use parameter binding with statement caching.
The default value is FALSE. For more information about Parameter Binding, see "Binding and Parameterized SQL". |
should-cache-all-statements
|
Enables statement caching. The default value is FALSE.
Statement caching requires you to set the |
uses-byte-array-binding
|
Specifies whether OracleAS TopLink uses binding for byte arrays. The default value is FALSE. |
uses-string-binding
|
Specifies whether OracleAS TopLink uses binding for String objects. The default value is FALSE. |
uses-streams-for-binding
|
Specifies whether OracleAS TopLink uses streams for binding byte array parameters. The default value is FALSE. |
should-force-field-names-to-uppercase
|
Specifies whether OracleAS TopLink converts field names to uppercase when generating SQL. The default value is FALSE. |
should-optimize-data-conversion
|
Specifies whether the session should optimize driver-level data conversion. The default value is TRUE. |
should-trim-strings
|
Specifies whether OracleAS TopLink removes any trailing white spaces from the end of strings. The default value is TRUE. |
uses-batch-writing
|
Specifies whether the session uses batch writing to write to the database. The default value is FALSE. |
uses-jdbc20-batch-writing
|
Specifies whether the database connections of the database use JDBC 2.0 batch writing or OracleAS TopLink batch writing. The default value is TRUE.
If you enable this option, enable the |
uses-external-connection-pool
|
Specifies whether the session uses external connection pooling. The default value is FALSE. |
uses-native-sql
|
Specifies whether the session uses database-specific SQL grammar. The default value is FALSE. |
uses-external-transaction-controller
|
Specifies whether the session uses an external transaction controller. The default value is FALSE. |
non-jts-connection-url
|
Specifies the URL for sequencing connection pooling. Used in conjunction with the non-jts-datasource tag when you set the uses-sequence-connection-pool tag to TRUE.
|
non-jts-datasource
|
Specifies the non-JTS datasource for the sequencing connection pool. Used in conjunction with the non-jts-connection-url tag when you set the uses-sequence-connection-pool tag to TRUE.
|
uses-sequence-connection-pool
|
Specifies whether the session creates and uses a separate connection pool for sequencing. The default value is FALSE. If you set this element to TRUE, you must also configure the non-jts-connection-url and non-jts-datasource tags.
|
You can configure sequencing as part of the session login, although it is not a requirement. If you do not configure sequencing in the sessions.xml file, then the application uses the configuration that is specified in OracleAS TopLink Mapping Workbench project.
Configure sequencing in the sessions.xml file when you want to use custom sequencing for a given session.
Table 4-5 lists the elements you use to configure sequencing in the sessions.xml file. All these elements are optional.
Table 4-5 Optional Sequencing Configuration Tags Within Login
| Tag | Description |
|---|---|
uses-native-sequencing
|
Specifies whether the session uses native sequencing. This tag accepts TRUE or FALSE as values. The default is FALSE.
Note that not all database platforms support native sequencing. |
sequence-preallocation-size
|
Specifies the sequence preallocation size. If you use native sequencing, this value must match the sequence preallocation size set on your database.
The default value is 50. |
sequence-table
|
For table sequencing, specifies the name of the sequencing table.
The default name is |
sequence-name-field
|
For table sequencing, specifies the column in the sequencing table that contains the names of the sequenced objects.
The default name is |
sequence-counter-field
|
For table sequencing, specifies the column in the sequence table that stores the current sequence count for each sequenced object.
The default name is |
For more information, see "Sequencing".
Example 4-9 Configuring Native Sequencing
<session> <login> ... <uses-native-sequencing>true</uses-native-sequencing> <sequence-preallocation-size>50</sequence-preallocation-size> </login> ... </session>
Example 4-10 Configuring Table-Based Sequencing
<session> ... <login> <uses-native-sequencing>false</uses-native-sequencing> <sequence-table>SEQUENCE</sequence-table> <sequence-name-field>SEQ_NAME</sequence-name-field> <sequence-counter-field>SEQ_COUNT</sequence-counter-field> </login> ... </session>
You configure cache synchronization as part of the login. Use the cache-synchronization-manager element and the tags listed in Table 4-6 to configure cache-synchronization for your application.
Table 4-6 Cache Synchronization Manager Configuration Tags
| Tag | Description |
|---|---|
clustering-service
|
Specifies the class name of the clustering service.
This tag is required for cache synchronization. |
multicast-port
|
Specifies the port for listening for connection messages over IP multicast. Ensure that all servers in your OracleAS TopLink cache synchronization group use the same multicast port.
This tag is required only if you also use the |
multicast-group-address
|
Specifies the IP address for sending connection messages over IP multicast. Ensure that all servers in your OracleAS TopLink cache synchronization group use the same multicast address.
This tag is required only if you also use the |
packet-time-to-live
|
Specifies the number of network hops that cache synchronization discovery packets traverse.
This optional tag defaults to 2. |
is-asynchronous
|
Specifies whether cache synchronization is performed asynchronously (TRUE) or synchronously (FALSE).
This optional tag defaults to TRUE. |
should-remove-connection-on-error
|
Specifies whether OracleAS TopLink removes a remote connection if a communications exception occurs with a remote server.
This optional tag defaults to FALSE. |
jndi-user-name
|
Specifies the user name to use for binding the Cache Synchronization Manager into JNDI. Use this tag to support JNDI in non application server applications.
This optional tag requires the |
jndi-password
|
Specifies the password to use for binding the cache synchronization manager into JNDI. Use this tag to support JNDI in non application server applications.
This optional tag requires the |
jms-topic-connection-factory-name
|
Specifies the topic connection factory name for JMS cache synchronization. This tag is required only when you use JMS cache synchronization. |
jms-topic-name
|
Specifies the topic name for JMS cache synchronization. This tag is required only when you use JMS cache synchronization. |
naming-service-initial-context-factory-name
|
Specifies the initial context factory for accessing JNDI. Use this tag only if OracleAS TopLink encounters difficulties connecting to JNDI or JMS. |
naming-service-url
|
Specifies the URL of the naming service that supports cache synchronization.
The value for this element depends on how you implement cache synchronization: For JNDI clustering services, this is the scheme, host IP address, and port of the JNDI service. For the RMI clustering service, this is the host IP address and port of the RMI registry. This optional tag may resolve problems that occur when you implement cache synchronization inside an application server with a JNDI clustering service. If you do not encounter any problems, do not use this tag. |
Example 4-11 Using the Cache Synchronization Manager
<session> ... <login> <cache-synchronization-manager> <clustering-service>oracle.toplink.remote.rmi.RMIClusteringService</clustering-service> <multicast-port>6020</multicast-port> <multicast-group-address>226.18.6.18</multicast-group-address> <is-asynchronous>true</is-asynchronous> <should-remove-connection-on-error>true</should-remove-connection-on-error> <naming-service-url>localhost:1099</naming-service-url> </cache-synchronization-manager> </login> ... </session>
If your applications need to know when session events take place, use event listeners to register for event notification. Event listeners can be configured in the sessions.xml file.
The event-listener-class tag enables you to configure listener classes that either implement the oracle.toplink.sessions.SessionEventListener interface, or extend the oracle.toplink.sessions.SessionEventAdapter class. Configure multiple event listener classes by including multiple event-listener-class tags and specifying the implementing class name for each tag.
OracleAS TopLink automatically registers event listeners in the sessions.xml file with the session event manager.
For more information, see "Customizing Session Events".
Example 4-12 Setting the Event Listener Class in Code
package examples;
import oracle.toplink.sessions.*;
public class MyEventListener extends SessionEventAdapter {
public void preLogin(SessionEvent event) {
Session session = event.getSession();
/* custom code goes here */
}
}
Example 4-13 Setting the Event Listener Class in the sessions.xml File
<session> ... <event-listener-class>examples.MyEventListener</event-listener-class> ... </session>
OracleAS TopLink registers the examples.MyEventListener class with the session event manager for the session. OracleAS TopLink invokes the MyEventListener class preLogin method when the preLogin event occurs on the session.
OracleAS TopLink provides a profiler to optimize your application and identify performance bottlenecks. To implement the performance profiler, use the profiler-class tag to include the performance profiler in your session.
Example 4-14 Implementing the Performance Profiler in the sessions.xml File
<session> ... <profiler-class>oracle.toplink.tools.profiler.PerformanceProfiler</profiler-class> ... </session>
The profiler-class tag supports any class that implements the oracle.toplink.sessions.SessionProfiler interface. Because of this, you can build your own profiler and add it to your session—provided that your profiler implements the oracle.toplink.sessions.SessionProfiler interface.
|
Note: You can implement only one profiler a session. |
If your system includes external transactions (under JTA, for example), specify an OracleAS TopLink external transaction controller using the external-transaction-controller-class tag.
To use an external transaction controller, specify the following in the session login:
The external transaction controller
A datasource on the session
An external connection pool
Example 4-15 Configuring the External Transaction Controller
<session> ... <login> ... <uses-external-transaction-controller>true</uses-external-transaction-controller> <data-source>jdbc/MyApplicationDS</data-source> <uses-external-connection-pool>true</uses-external-connection-pool> ... </login> <external-transaction-controller-class>oracle.toplink.jts.oracle9i.Oracle9iJTSExternalTransactionController</external-transaction-controller-class> ... </session>
The exception-handler-class tag specifies a class that handles exceptions for the session. This tag accepts any class that implements the oracle.toplink.exceptions.ExceptionHandler.
You can explicitly configure a single connection pool or multiple connection pools for your OracleAS TopLink application with the connection-pool element in the sessions.xml file. If you do not configure a connection pool for a session, then the session uses the default connection pool that you defined for the project.
Define a login for each connection-pool that you define manually. Table 4-7 lists the elements you use to configure the connection-pool element in the sessions.xml file.
For more information about configuring the connection pool for the project, see "Working with Connection Pools" in the Oracle Application Server TopLink Mapping Workbench User's Guide.
For more information about configuring a login, see "login Element".
Table 4-7 Connection Pool Element Tags
| Tag | Description |
|---|---|
is-read-connection-pool
|
Specifies whether the connection pool contains read connections (true) - (nontransactional) or for write connections (false) - (transactional).
The |
name
|
Specifies the name of the connection pool. If the name is the same as another existing OracleAS TopLink connection pool (such as the default OracleAS TopLink read pool), then the existing connection pool is replaced with the new one.
The |
max-connections
|
Specifies the maximum number of database connections that the connection pool can use.
This tag is optional and accepts integer values. The default is 10. |
min-connections
|
Specifies the minimum number of database connections that the connection pool should use at startup.
This tag is optional and accepts integer values. The default is 5. |
Example 4-18 Configuring the Connection Pool Element
<session> ... <connection-pool> <is-read-connection-pool>true</is-read-connection-pool> <name>additionalReadPool</name> <max-connections>20</max-connections> <min-connections>10</min-connections> <login> ... </login> </connection-pool> ... </session>
OracleAS TopLink does not automatically enable logging for a session unless you explicitly request it. To enable logging in a session, include the enable-logging element as part of your session definition in the sessions.xml file and set it to TRUE.
After you enable logging, you can customize the logging behavior on the session by including one or more logging options in the sessions.xml file. The available logging options appear in Table 4-8, and accept TRUE or FALSE as arguments.
Table 4-8 Logging Option Tags
| Tag | Description |
|---|---|
log-debug
|
Specifies whether the session logs debug information in addition to standard log entries. |
log-exceptions
|
Specifies whether the session logs uncaught exception messages. |
log-exception-stacktrace
|
Specifies whether the session logs exception stack traces. |
print-session
|
Specifies whether the session logs session identifiers. |
print-thread
|
Specifies whether the session logs thread identifiers. |
print-connection
|
Specifies whether the session logs connection identifiers. |
print-date
|
Specifies whether the session logs the date and time of each log entry. |
Example 4-19 Configuring Logging and Logging Options
<session> ... <enable-logging>true</enable-logging> <logging-options> <log-debug>false</log-debug> <log-exceptions>true</log-exceptions> <log-exception-stacktrace>true</log-exception-stacktrace> <print-session>true</print-session> <print-thread>false</print-thread> <print-connection>true</print-connection> <print-date>true</print-date> </logging-options> ... </session>
The session broker enables client applications to view several databases through a single session. The session-broker element enables you to configure a session broker in the sessions.xml file, as follows:
Configure the session broker sessions in the sessions.xml file. These sessions are the database sessions or server sessions that the session broker uses to communicate with the databases.
Add the session broker to the sessions.xml file using the session-broker element.
Populate the session-broker element with a name and the sessions that you configured in the sessions.xml file.
Example 4-20 Configuring a Session Broker in the sessions.xml File
/* Configure the sessions for the SessionBroker */ <session> <name>EmployeeSession</name> ... </session> <session> <name>ProjectSession</name> ... </session> /* Configure the SessionBroker */ <session-broker> /* Name the SessionBroker */ <name>EmployeeAndProjectBroker</name> /* Specify the sessions contained in the SessionBroker */ <session-name>EmployeeSession</session-name> <session-name>ProjectSession</session-name> </session-broker> ...
OracleAS TopLink J2EE integration includes support for JTA external connection pools and external transaction controllers. To enable a JTA external transaction controller, set the login to use an external transaction controller, and configure the following in your sessions.xml file:
A JTA DataSource (in the login element)
An external connection pool (in the login element)
An external transaction controller (in the session element)
For more information about the OracleAS TopLink JTA integration, see "J2EE Integration".
Example 4-21 Configuring for JTA in the sessions.xml File
<session> ... <login> ... <uses-external-transaction-controller>true </uses-external-transaction-controller> <data-source>jdbc/MyApplicationDS</data-source> <uses-external-connection-pool>true</uses-external-connection-pool> ... </login> <external-transaction-controller-class> oracle.toplink.jts.oracle9i.Oracle9iJTSExternalTransactionController </external-transaction-controller-class> ... </session>
Example 4-22 Configuring for JTA in Code
DatabaseLogin login = null; project = null; // note that useExternalConnectionPooling and useExternalTransactionController // must be set before Session is created project = new SomeProject(); login = project.getLogin(); login.useExternalConnectionPooling(); login.useExternalTransactionController(); // usually, other login configuration such as user, password, JDBC URL comes // from the project but these can also be set here session = new Session(project); // other session configuration, as necessary, such as logging session.SetExternalTransactionController( new SomeJTSExternalTransactionController() ); session.login();
