89 Configuring a Session

89.2.1 How to Configure a Primary Mapping Project Using TopLink Workbench

To specify the primary TopLink project metadata for your session, use this procedure:

1. Select a server or database session in the Navigator. Its properties appear in the Editor.

2. Click the General tab. The General tab appears.

3. Click the Project subtab. The Project subtab appears.

   Figure 89-1 General Tab, Project Subtab, Primary Project Option

   
   Description of "Figure 89-1 General Tab, Project Subtab, Primary Project Option"
   
   

4. Select the following options:

   • Click Edit to define the primary project. The Edit PrimaryProject dialog box appears.

   • Select the Multiple Projects option to add additional projects to the session. See Section 89.5, "Configuring Multiple Mapping Projects" for more information.

   Figure 89-2 Edit Primary Project Dialog Box

   
   Description of "Figure 89-2 Edit Primary Project Dialog Box"
   
   

Use this information to enter date in each field of the Edit Primary Project dialog box:

89.2.2 How to Configure a Primary Mapping Project Using Java

Using Java, you can register descriptors with a session using the following API:

• Project API–Read your project.xml file (or instantiate your project class) and create your session using Project method createServerSession or createDatabaseSession.

• Session API–Add a descriptor or set of descriptors to a session using the DatabaseSession API that Table 89-4 lists. Descriptors should be registered before login, but independent sets of descriptors can be added after login.

89.4.1 How to Configure Logging Using TopLink Workbench

To specify the logging information for a session, use this procedure:

1. Select a database session in the Navigator. Its properties appear in the Editor.

2. Click the Logging tab. The Logging tab appears.

   Figure 89-3 Logging Tab

   
   Description of "Figure 89-3 Logging Tab"
   
   

Use the following information to enter data in each field of the Logging tab to select the profiler option to use with this session:

89.4.2 How to Configure Logging Using Session API in Java

If you use TopLink native logging (the default), then at run time, you can configure logging options using oracle.toplink.sessions.Session logging API.

The Session interface defines the following logging methods:

• setSessionLog–specify the type of logging to use (any implementor of oracle.toplink.logging.SessionLog)

• dontLogMessages–disable logging

• setLog–specify the java.io.Writer to which the session logs messages

• setLogLevel– specify the level at which the session logs using oracle.toplink.logging.SessionLog constants:

  • OFF

  • SEVERE

  • WARNING

  • INFO

  • CONFIG

  • FINE

  • FINER

  • FINEST

  • ALL

Example 89-1 illustrates how to configure a session to use java.util.logging package.

session.setSessionLog(new JavaLog());

Example 89-2 illustrates how to configure a session to use the server log that OC4J provides. For more information about server logging, see Section 87.2.6.1.3, "Server Logging".

session.setSessionLog(new OjdlLog());

Example 89-3 illustrates how to configure a session to log to a java.io.Writer:

session.setLog(myWriter);

89.4.3 How to Configure Logging Using Oracle Enterprise Manager

When you deploy a EclipseLink JPA or TopLink CMP application to Oracle Application Server, you can use Oracle Enterprise Manager to configure TopLink logging.

For more information, see the following:

• Section A.1, "TopLink Support for Oracle Application Server Manageability and Diagnosability""

• Oracle Fusion Middleware Administrator's Guide

89.4.4 How to Configure Logging in a Java EE Container

For a TopLink-enabled CMP application deployed to an application server, you do not configure a session directly. In this case, you specify the type of logging by configuring system property toplink.log.destination with one of the following values:

• fully qualified file specification (for example, C:\logs\toplink.log)–use TopLink native logging to write log messages to the specified file.

• JAVA–use java.util.logging package to write log messages to any destination you configure in the <JRE_HOME>/lib/logging.properties file.

• SERVER–use server logging to write log messages to the application server's log file (there is no separate TopLink log file in this case).

• SYSOUT–write log messages to System.out.

You can set the log level for TopLink standard (default) logging through the toplink.log.level system property.

To configure other logging options, use a customization-class (see Section 9.9.1.1, "Configuring pm-properties").

89.4.5 How to Configure a Session to use the java.util.logging Package

If you use java.util.logging package, then you configure logging options in the <JRE_HOME>/lib/logging.properties file. Messages are written to zero or multiple destinations based on this configuration file.

If you configure a session to use java.util.logging package, consider the following:

• logging.properties

• Formatters

• Namespace

handlers = java.util.logging.ConsoleHandler
java.util.logging.ConsoleHandler.level = CONFIG
java.util.logging.ConsoleHandler.formatter = oracle.toplink.logging.TopLinkSimpleFormatter
oracle.toplink.LoggingSession.connection.level = CONFIG

89.5.1 How to Configure Multiple Mapping Projects Using TopLink Workbench

To specify additional TopLink projects for your session, use this procedure:

1. Select a server or database session in the Navigator. Its properties appear in the Editor.

2. Click the General tab. The General tab appears.

3. Click the Project subtab. The Project subtab appears.

   Figure 89-4 General Tab, Project Subtab, Multiple Projects Options

   
   Description of "Figure 89-4 General Tab, Project Subtab, Multiple Projects Options"
   
   

4. Select Multiple Projects option. The Multiple Projects subtab appears.

5. Click the Multiple Projects subtab.

6. Figure 89-5 General Tab, Multiple Projects Subtab

   
   Description of "Figure 89-5 General Tab, Multiple Projects Subtab"
   
   

To add an additional mapping project to this session, click Add. For more information, see Section 89.2, "Configuring a Primary Mapping Project".

To remove TopLink mapping projects, select the project file and click Remove.

89.5.2 How to Configure Multiple Mapping Projects Using Java

Using Java, you can register descriptors from more than one project with a session using the DatabaseSession API that Table 89-9 lists. You can register descriptors before login, but you can add independent sets of descriptors after login.

89.6.1 How to Configure a Performance Profiler Using TopLink Workbench

To specify the type of profiler in a session, use this procedure:

1. Select a session in the Navigator. Its properties appear in the Editor.

2. Click the Options tab. The Options tab appears.

   Figure 89-6 Options Tab, Profiler Options

   
   Description of "Figure 89-6 Options Tab, Profiler Options"
   
   

Use the following information to select the profiler option to use with this session:

89.6.2 How to Configure a Performance Profiler Using Java

You can use Java to configure a session with a profiler using Session method setProfiler, as Example 89-5 shows.

session.setProfiler(new PerformanceProfiler());

To end a profiling session, use Session method clearProfiler.

89.7.1 How to Configure an Exception Handler Using TopLink Workbench

To specify the exception handler class in a session, use this procedure:

1. Select a session in the Navigator. Its properties appear in the Editor.

2. Click the Options tab. The Options tab appears.

   Figure 89-7 Options Tab, Exception Handler Field

   
   Description of "Figure 89-7 Options Tab, Exception Handler Field"
   
   

3. Complete the Exception Handler field.

Click Browse and select the exception handler class for this session.

89.7.2 How to Configure an Exception Handler Using Java

Example 89-6 shows an example exception handler implementation. In this implementation, the exception handler always tries to reestablish the connection if it has been reset by peer, but only retries a query if it is an instance of ReadQuery. Note that this exception handler either returns the result of the reexecuted ReadQuery or throws an exception.

session.setExceptionHandler(
  new ExceptionHandler() {
    public Object handleException(RuntimeException exception) {
      if (exception instanceof DatabaseException) {
        DatabaseException dbex = (DatabaseException) exception;
        if ((dbex.getInternalException() instanceof SQLException) && 
           (((SQLException) dbex.getInternalException()).getErrorCode() == MyDriver.CONNECTION_RESET_BY_PEER)) {
           dbex.getAccessor().reestablishConnection(dbex.getSession());
           if (dbex.getQuery() instanceof ReadQuery) {
             return dbex.getSession().executeQuery(dbex.getQuery(), dbex.getQuery().getTranslationRow());
           }
           throw exception;
        }
      }
      throw exception;
    }
  }
);

89.8.1 How to Configure Customizer Class Using TopLink Workbench

To specify the session customizer class in a session, use this procedure:

1. Select a session in the Navigator. Its properties appear in the Editor.

2. Click the Options tab. The Options tab appears.

   Figure 89-8 Options Tab, Session Customizer Class Field

   
   Description of "Figure 89-8 Options Tab, Session Customizer Class Field"
   
   

Click Browse and select the customizer class for this session.

89.8.2 How to Configure Customizer Class Using Java

When using Java, create a customize class that implements the oracle.toplink.tools.sessionconfiguration.SessionCustomizer interface. Example 89-7 illustrates the creation of the session customizer. The customize method contains the configuration of the Login owned by the Session with the appropriate transaction isolation.

import oracle.toplink.tools.sessionconfiguration.SessionCustomizer;
import oracle.toplink.sessions.Session;
import oracle.toplink.sessions.DatabaseLogin;

public class EmployeeSessionCustomizer implements SessionCustomizer {

    public void customize(Sesssion session) {
        DatabaseLogin login = (DatabaseLogin)session.getDatasourceLogin();
        login.setTransactionIsolation(DatabaseLogin.TRANSACTION_READ_UNCOMMITTED);
    }
}

89.9.1 How to Configure the Server Platform Using TopLink Workbench

To specify the server platform options for a session, use this procedure:

1. Select a session in the Navigator. Its properties appear in the Editor.

2. Click the General tab. The General tab appears.

3. Click the Server Platform subtab. The Server Platform subtab appears.

   Figure 89-9 General Tab, Server Platform Subtab

   
   Description of "Figure 89-9 General Tab, Server Platform Subtab"
   
   

Use the following information to enter data in each field of the Server Platform subtab:

89.9.2 How to Configure the Server Platform Using Java

When using Java, you must pass the session in a server platform constructor. Example 89-8 illustrates using a session customizer (see Section 13.4, "Using the Session Customizer Class") to configure a session with a server platform from the oracle.toplink.platform.server package.

import oracle.toplink.tools.sessionconfiguration.SessionCustomizer; 
...
public class MySessionCustomizer implements SessionCustomizer {
   public void customize (Session session) {
      Server server = (Server)session;
      server.setServerPlatform(new WebLogic_10_Platform(DatabaseSession)server)):
   }
}

89.10.1 How to Configure Session Event Listeners Using TopLink Workbench

Session Event Listeners

To specify the event listener class in a session, use this procedure:

1. Select a session in the Navigator. Its properties appear in the Editor.

2. Click the Options tab. The Options tab appears.

   Figure 89-10 Options Tab, Event Listeners field

   
   Description of "Figure 89-10 Options Tab, Event Listeners field"
   
   

To add a new event listener, click Add, then select the event listener class for this session.

To remove an existing event listener, select the Event Listener and click Remove.

89.10.2 How to Configure Session Event Listeners Using Java

Example 89-9 illustrates how to use Java to register a session event listener with a session. TopLink provides a SessionEventAdapter to simplify creating a SessionEventListener. The SessionEventAdapter provides a default implementation of all the methods of the SessionEventListener interface. You need only override the specific methods of interest. Typically, you would define session event listeners in a session customizer class (see Section 89.8, "Configuring a Session Customizer Class").

...
SessionEventAdapter myEventListener = new SessionEventAdapter() {
    // Listen for PostCommitUnitOfWork events
    public void postCommitUnitOfWork(SessionEvent event) {
        // Call the handler routine
        unitOfWorkCommitted();
    }
};
mySession.getEventManager().addListener(myEventListener);
...

For information on how to add logging to your listeners, see Section 87.2.6, "Logging".

89.11.1 How to Configure the Integrity Checker Using Java

As Example 89-10 shows, you can configure the integrity checker validation process.

session.getIntegrityChecker().setShouldCheckDatabase(true);
session.getIntegrityChecker().setShouldCatchExceptions(false);
session.getIntegrityChecker().setShouldCheckInstantiationPolicy(false);
session.login();

89.12.1 How to Configure Connection Policy Using TopLink Workbench

To specify the connection policy in a session, use this procedure:

1. Select a session in the Navigator. Its properties appear in the Editor.

2. Click the Connection Policy tab. The Connection Policy tab appears.

   Figure 89-11 Connection Policy Tab

   
   Description of "Figure 89-11 Connection Policy Tab"
   
   

89.12.2 How to Configure Connection Policy Using Java

To configure whether or not an exclusive connection is allocated to a particular isolated session, use ConnectionPolicy method setShouldUseExclusiveConnection.

To define a map of properties used to support an isolated session, use the following ConnectionPolicy methods:

• setProperty(Object key, Object value): Adds the property value to the Map under key, overwriting the existing value if key already exists in the Map.

• Object getProperty(Object key): Returns the value associated with key as an Object.

• boolean hasProperties: Returns true if one or more properties exist in the Map; otherwise returns false.

The TopLink runtime passes this Map into SessionEvent events PostAcquireExclusiveConnection and PreReleaseExclusiveConnection so that your implementation can make the appropriate PL/SQL calls to the underlying database platform (see Section 92.2, "Using PostAcquireExclusiveConnection Event Handler" and Section 92.3, "Using PreReleaseExclusiveConnection Event Handler").

To configure the session to use a named connection pool, use the ConnectionPool constructor that takes a String connection pool name as an argument:

Session clientSession = server.acquireClientSession(
    new ConnectionPolicy("myConnectionPool")
);

89.13.1 How to Configure Named Queries at the Session Level Using Java

You can store a query by name in a Session using Session method addQuery(String name, DatabaseQuery query).