Difference between revisions of "Configuring a Session (ELUG)"

Latest revision as of 11:13, 23 July 2012

For the latest EclipseLink documentation, please see http://www.eclipse.org/eclipselink/documentation/

This table lists the types of EclipseLink sessions that you can configure and provides a cross-reference to the type-specific chapter that lists the configurable options supported by that type.

For more information, see the following:

• Introduction to EclipseLink Sessions
• Creating a Session

Configuring Common Session Options

This table lists the configurable options shared by two or more EclipseLink session types. In addition to the configurable options described here, you must also configure the options described for the specific Session Types, as shown in The Configuring EclipseLink Sessions table.

Configuring a Primary Mapping Project

The mapping project contains your EclipseLink mapping metadata (see Introduction to Projects), including descriptors and mappings. Each session is associated with at least one project so that the session can register the descriptors.

This table summarizes which sessions support a primary mapping project configuration.

Using the Workbench, you can export your mapping metadata as either a deployment XML file or as a Java class. Consequently, in a session, you can specify the mapping project as an XML file or as a Java class.

If you export your mapping metadata as a Java class, you must compile it and add it to the session configuration classpath before adding it to a session.

See Configuring Multiple Mapping Projects for information on configuring additional EclipseLink projects for the session.

How to Configure a Primary Mapping Project Using Workbench

To specify the primary EclipseLink 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.
   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.
   • Use the Multiple Projects option to add additional projects to the session.
     Edit Primary Project Dialog Box
     Edit Primary Project Dialog Box
     
     
5. Complete each field on the Edit Primary Project dialog box.

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

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 the following table lists. Descriptors should be registered before login, but independent sets of descriptors can be added after login.

DatabaseSession API for Registering Descriptors

Configuring a Session Login

A session login encapsulates details of data source access for any session that persists to a data source. The session login overrides any other login configuration.

This table summarizes which sessions support session login configuration.

The session login provides access to a variety of features, including the following:

• Connection configuration such as whether or not to use external connection pooling.
• Sequencing configuration (that overrides sequencing configuration made at the project level, if any).
• Miscellaneous options specific to your chosen data source.
• Properties (arbitrary, application-specific named values).

For more information, see the following:

• Data Source Login Types
• Configuring a Data Source Login

Configuring Logging

Use the EclipseLink logging framework to record EclipseLink behavior to a log file or session console.

This table summarizes which sessions support logging configuration.

By default, EclipseLink uses its own native logger. Alternatively, you can configure EclipseLink to use the java.util.logging package.

For more information, see Logging.

How to Configure Logging Using 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.
   Logging Tab
   Logging Tab
   
   
3. Complete the Logging fields on the 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:

How to Configure Logging Using Session API in Java

If you use EclipseLink native logging (the default), then at run time, you can configure logging options using org.eclipse.persistence.sessions.Session logging API.

The Session interface defines the following logging methods:

• setSessionLog – specify the type of logging to use (any implementor of org.eclipse.persistence.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 org.eclipse.persistence.logging.SessionLog constants:
  • OFF
  • SEVERE
  • WARNING
  • INFO
  • CONFIG
  • FINE
  • FINER
  • FINEST
  • ALL

This example illustrates how to configure a session to use java.util.logging package.

Configuring a Session to Use java.util.logging

session.setSessionLog(new JavaLog());

This example illustrates how to configure a session to use the server log that OC4J provides. For more information about server logging, see Server Logging.

Configuring a Session to Use Application Server Logging

session.setSessionLog(new OjdlLog());

This example illustrates how to configure a session to log to a java.io.Writer:

Configuring a Session to Log to a java.io.Writer

session.setLog(myWriter);

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

logging.properties

Configure the logging.properties file as this example illustrates:

java.util.logging Configuration in logging.properties

 handlers = java.util.logging.ConsoleHandler
 java.util.logging.ConsoleHandler.level = CONFIG
 java.util.logging.ConsoleHandler.formatter = org.eclipse.persistence.logging.LogFormatter
 org.eclipse.persistence.LoggingSession.connection.level = CONFIG

For information about the types of formatters available, see Formatters.

Formatters

EclipseLink provides two formatters: LogFormatter and XMLLogFormatter. They override the SimpleFormatter and XMLFormatter java.util.logging formatters and always log session and connection info when available. They also log thread and exception stack trace information at certain levels as specified by the logging level.

Namespace

Namespace is supported for java.util.logging. This table lists the static constants defined in org.eclipse.persistence.sessions.SessionLog for EclipseLink components and the corresponding strings in logging.properties.

Logging Property FIle Names

In the logging.properties names listed in the Logging Property FIle Names table, note that <sessionname> is the name of the session that the application is running in. For example, if the name of the session is MyApplication, then you would use org.eclipse.persistence.MyApplication.sql for the SQL logging property.

An application can also define its own namespace and write to it through the logging API, as long as the logger for that namespace is defined in the logging configuration. Otherwise messages are written to the parent logger, org.eclipse.persistence.<sessionname>.

Configuring Multiple Mapping Projects

Each session is associated with at least one mapping project. You can include additional EclipseLink mapping projects for a session.

This table summarizes which sessions support additional mapping project configuration.

How to Configure Multiple Mapping Projects Using Workbench

To specify additional EclipseLink 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.
   General Tab, Project Subtab, Multiple Projects Options
   
   
   
4. Select Multiple Projects option. The Multiple Projects subtab appears.
5. Click the Multiple Projects subtab.

   
   General Tab, Multiple Projects Subtab
   
   
   

6. To add an additional mapping project to this session, click Add. For more information, see Configuring a Primary Mapping Project.
   To remove EclipseLink mapping projects, select the project file and click Remove.

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 this table lists. You can register descriptors before login, but you can add independent sets of descriptors after login.

DatabaseSession API for Registering Descriptors

Configuring a Performance Profiler

To successfully improve the performance of an EclipseLink application, you must measure performance before and after each optimization. EclipseLink provides a variety of built-in performance measuring features (known as profilers) that you can configure at the session level.

This table summarizes which sessions support performance profiler configuration.

EclipseLink provides the following profilers:

• EclipseLink profiler: logs performance statistics for every executed query in a given session (see Measuring EclipseLink Performance with the EclipseLink Profiler)

How to Configure a Performance Profiler Using 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.
   Options Tab, Profiler Options
   
   
   
3. Complete the Profiler field on the tab.

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

How to Configure a Performance Profiler Using Java

You can use Java to configure a session with a profiler using Session method setProfiler, as this example shows.

Configuring a Session with an EclipseLink Profiler

session.setProfiler(new PerformanceProfiler());

To end a profiling session, use Session method clearProfiler.

Configuring an Exception Handler

You can associate a single exception handling class with each session. This class must implement the org.eclipse.persistence.exceptions.ExceptionHandler interface.

This table summarizes which sessions support exception handler configuration.

Session Support for Exception Handler Configuration

For an example exception handler implementation, see Using Java.

For more information, see Exception Handlers.

How to Configure an Exception Handler Using 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.
   Options Tab, Exception Handler Field
   
   
   
3. Complete the Exception Handler field.
4. Click Browse and select the exception handler class for this session.

How to Configure an Exception Handler Using Java

This example 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.

Implementing an Exception Handler

 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;
     }
   }
 );

Configuring a Session Customizer Class

A session customizer class is a Java class that implements the org.eclipse.persistence.internal.sessions.factories.SessionCustomizer interface and provides a default (zero-argument) constructor. You can use a session customizer to customize a session at run time on a loaded session before login occurs, similar to how you can use an amendment method to customize a descriptor) For example, you can use a session customizer class to define and register session event listeners with the session event manager (see Configuring Session Event Listeners).

This table summarizes which sessions support customizer class configuration.

Session Support for Customizer Class Configuration

For more information, see Session Customization.

How to Configure Customizer Class Using 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.
   Options Tab, Session Customizer Class Field
   
   
   
3. Complete the Session Customizer Class field.
4. Click Browse and select the customizer class for this session.

How to Configure Customizer Class Using Java

When using Java, create a customize class that implements the org.eclipse.persistence.internal.sessions.factories.SessionCustomizer interface. This example 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.

Creating a SessionCustomizer Class

 import  org.eclipse.persistence.internal.sessions.factories.SessionCustomizer;
 import org.eclipse.persistence.sessions.Session;
 import org.eclipse.persistence.sessions.DatabaseLogin;
 
 public class EmployeeSessionCustomizer implements SessionCustomizer {
 
     public void customize(Sesssion session) {
         DatabaseLogin login = (DatabaseLogin)session.getDatasourceLogin();
         login.setTransactionIsolation(DatabaseLogin.TRANSACTION_READ_UNCOMMITTED);
     }
 }