Session Utilities

The OracleAS TopLink session provides several utilities to test and troubleshoot your application. This section introduces these tools and describes techniques for using them:

Logging SQL and Messages
Using the Profiler
Using the Integrity Checker
Using Exception Handlers

Logging SQL and Messages

OracleAS TopLink accesses the database using SQL strings that it generates internally. This feature enables applications to use the session methods, or to query objects without having to perform their own SQL translation.

If, for debugging purposes, you want to review a record of the SQL that is sent to the database, sessions provide these methods to log generated SQL to a writer. OracleAS TopLink disables SQL and message logging by default. To enable it, use the logMessages() method on the session. The default writer is a stream writer to System.out, but you can configure the log destination using the setLog() method on the session.

The session logs:

Debug print statements
Exceptions/error messages sent to system out
Any other output sent to the system log

Logging Chained Exceptions

The logging chained exception facility enables you to log causality when one exception causes another, as part of the standard stack back-trace. If you build your applications with JDK 1.4, causal chains appear automatically in your logs.

Logging and the Oracle Enterprise Manager 10g

You can view OracleAS TopLink logs with all the other Oracle Application Server 10g log files using the Oracle Enterprise Manager 10g.

For more information, see "Managing Log Files" in the Oracle Application Server Administrator's Guide.

If you install OracleAS TopLink in the same Oracle Home directory as Oracle Application Server, OracleAS TopLink logs appear automatically with the other Oracle Application Server component log files in the Oracle Enterprise Manager 10g. If you install OracleAS TopLink in a different Oracle Home directory, use the following procedure:

Locate the toplink.xml file in the <ORACLE_HOME>\toplink\config\ directory.
Ensure that the log path tag reflects the location of your OracleAS TopLink log file, and is properly configured.

For example:
```
- <log path="toplink/config/toplink.log"
   componentId="TOPLINK" encoding="utf-8">
```
Copy the toplink.xml file to the following directory:
```
<ORACLE_HOME>\diagnostics\config\registration\
```

Using the Profiler

The OracleAS TopLink Profiler is a high-level logging service. Instead of logging SQL statements, the Profiler logs a summary of each query you execute. The summary includes a performance breakdown of the query that enables you to identify performance bottlenecks. The Profiler also provides a report summarizing the query performance for an entire session.

Access Profiler reports and profiles through the Profile tab in the OracleAS TopLink Web Client, or create your own application or applet to view the Profiler logs.

For more information about the Web Client, see "OracleAS TopLink—Web Client".

Using the Integrity Checker

When you connect a session or add descriptors to a session after connection, OracleAS TopLink initializes and validates the descriptor information. The integrity checker allows you to customize the validation process. The integrity checker offers the following configuration options:

Catch All Exceptions

This option specifies whether the integrity checker catches all exceptions in the session. The settings for this option are catchExceptions (the default setting) and dontcatchExceptions.

Catch Instantiation Policy Exceptions

This option catches only errors that are associated with instantiation policy, and:

Throws the first error that it encounters, including the error stack trace
Validates the state of the database schema to ensure that it matches the information in the descriptors
Disables the instance creation check

Example 4-45 Using the Integrity Checker

session.getIntegrityChecker().checkDatabase();
session.getIntegrityChecker().catchExceptions();
session.getIntegrityChecker().dontCheckInstantiationPolicy();
session.login();

Using Exception Handlers

Exception handlers process database exceptions, usually to process connection timeouts or database failures. To use exception handlers, register an implementor of the ExceptionHandler interface with the session. If a database exception occurs during the execution of a query, the exception passes to the exception handler. The exception handler then either handles the exception, retries the query, or throws an unchecked exception.

For more information about exceptions, see Appendix C, "Troubleshooting".

Example 4-46 Implementing an Exception Handler

session.setExceptionHandler(newExceptionHandler(){
    public Object handleException(RuntimeException exception) {
        if ((exception instanceof DatabaseException) && 
            (exception.getMessage().equals("connection reset by peer."))) {
            DatabaseException dbex = (DatabaseException) exception;
            dbex.getAccessor().reestablishConnection             (dbex.getSession());
            return dbex.getSession().executeQuery(dbex.getQuery());
        }
        throw exception;
    }
});

Note:

Unhandled exceptions must be re-thrown by the handler code.