Performance and Debugging

AuditorInstaller Customizer for Debugging

Oracle SQLJ provides a special customizer, AuditorInstaller, that will insert sets of debugging statements, called auditors, into profiles specified on the SQLJ command line. These profiles must already exist from previous customization.

The debugging statements will execute during SQLJ runtime (when someone runs your application), displaying a trace of method calls and values returned.

Use the customizer harness -debug option, preceded by -P like any general customization option, to insert the debugging statements. (Syntax for this option is also discussed in "Invoking AuditorInstaller with the Customizer Harness -debug Option".)

About Auditors and Code Layers

When an application is customized, the Oracle customizer implements profiles in layers of code (typically less than five) for different levels of runtime functionality. The deepest layer uses straight Oracle JDBC calls and implements any of your SQLJ statements which can be executed through JDBC functionality. Each higher layer is a specialized layer for some kind of SQLJ functionality which is not supported by JDBC and so must be handled specially by the SQLJ runtime. For example, there is a layer for iterator conversion statements (CAST) used to convert JDBC result sets to SQLJ iterators. There is another layer for assignment statements (SET).

The functionality of the code layers is that at runtime each SQLJ executable statement is first passed to the shallowest layer, and then passed layer-by-layer until it reaches the layer that can handle it (usually the deepest layer, which executes all JDBC calls).

You can install debugging statements at only one layer during a single execution of AuditorInstaller. Each set of debugging statements installed at a particular layer of code is referred to as an individual auditor. During runtime, an auditor is activated whenever a call is passed to the layer at which the auditor is installed.

Any one of the specialized code layers above the JDBC layer is usually of no particular interest during debugging, so it is typical to install an auditor at either the deepest layer or the shallowest layer. If you install an auditor at the shallowest layer, its runtime debugging output will be a trace of method calls resulting from all of your SQLJ executable statements. If you install an auditor at the deepest layer, its runtime output will be a trace of method calls from all of your SQLJ executable statements that result in JDBC calls.

Use multiple executions of AuditorInstaller to install auditors at different levels. You might want to do that to install auditors at both the deepest layer and the shallowest layer, for example.

See "AuditorInstaller depth Option" for information about how to specify the layer at which to install an auditor.

Invoking AuditorInstaller with the Customizer Harness -debug Option

Following are examples of how to specify the Oracle customizer harness -debug option to run AuditorInstaller in its default mode:

sqlj -P-debug Foo_SJProfile0.ser Bar_SJProfile0.ser

sqlj -P-debug *.ser

sqlj -P-debug myappjar.jar

The -debug option results in the customizer harness instantiating and invoking the class sqlj.runtime.profile.util.AuditorInstaller, which does the work of inserting the debugging statements.

The -P-debug option is equivalent to -P-customizer=sqlj.runtime.profile.util.AuditorInstaller, overriding the customizer specified in the SQLJ -default-customizer option.

Note:

To run an application with auditors installed, the Oracle SQLJ file translator.zip must be in your CLASSPATH (normally, running a SQLJ application requires only runtime.zip, which is a subset of translator.zip).

It is important to realize that because the -debug option invokes a customizer, and only one customizer can run in any single running of SQLJ, you cannot do any other customization when you use this option.

You also cannot use -P-print and -P-debug at the same time because the -print option also invokes a special customizer.

Command-line syntax

sqlj -P-debug profile_list

Command-line example

sqlj -P-debug Foo_SJProfile*.ser

Properties file syntax

profile.debug (must also specify profiles in file list)

Properties file example

profile.debug (must also specify profiles in file list)

Default value

n/a

AuditorInstaller Options

Like any customizer, AuditorInstaller has its own options which can be set using the -P-C prefix on the SQLJ command line (or profile.C, instead of -P-C, in a SQLJ properties file).

AuditorInstaller supports the following options:

depth--Specify how deeply you want to go into the layers of runtime functionality in your profiles.
log--Specify the target file for runtime output of the debug statements of the installed auditor.
prefix--Specify a prefix for each line of runtime output that will result from this installation of debug statements.
uninstall--Removes the debug statements that were placed into the profiles during the most recent previous invocation of AuditorInstaller on those profiles.

AuditorInstaller depth Option

As discussed in "About Auditors and Code Layers", AuditorInstaller can install a set of debug statements, known as an auditor, at only a single layer of code during any one execution. The AuditorInstaller depth option allows you to specify which layer. Use multiple executions of AuditorInstaller to install auditors at different levels.

Layers are numbered in integers. The shallowest depth is layer 0 and a maximum depth of 2 or 3 is typical. The only depth settings typically used are 0 for the shallowest layer or -1 for the deepest layer. In fact, it is difficult to install an auditor at any other particular layer, because the layer numbers used for the various kinds of SQLJ executable statements are not publicized.

The depth option is sometimes used in conjunction with the prefix option. By running AuditorInstaller more than once, with different prefixes for different layers, you can see at runtime what information is coming from which layers.

If you do not set the depth option, or the specification exceeds the number of layers in a given profile, then an auditor will be installed at the deepest layer.

Command-line syntax

-P-Cdepth=n

Command-line example

-P-Cdepth=0

Properties file syntax

profile.Cdepth=n

Properties file example

profile.Cdepth=0

Default value

-1 (deepest layer)

AuditorInstaller log Option

Use the log option to specify an output file for runtime output that will result from the auditor that you are currently installing. Otherwise, standard output will be used--debug output will go to wherever SQLJ messages go.

When auditors write messages to an output file, they append; they do not overwrite. Therefore you can specify the same log file for multiple auditors without conflict (in fact, it is typical to have debug information from all layers of your application to go to the same log file in this way).

Command-line syntax

-P-Clog=log_file

Command-line example

-P-Clog=foo/bar/mylog.txt

Properties file syntax

profile.Clog=log_file

Properties file example

profile.Clog=foo/bar/mylog.txt

Default value

empty (use standard output)

AuditorInstaller prefix Option

Use the prefix option to specify a prefix for each line of runtime output resulting from the debug statements that are installed during this invocation of AuditorInstaller.

This option is often used in conjunction with the depth option. By running AuditorInstaller a number of times with different prefixes for different layers, you can easily see at runtime what information is coming from which layers.

Command-line syntax

-P-Cprefix="string"

Command-line example

-P-Cprefix="layer 2: "

Properties file syntax

profile.Cprefix="string"

Properties file example

profile.Cprefix="layer 2: "

Default value

empty

AuditorInstaller uninstall Option

Use the uninstall option to remove debug statements that were placed during previous invocations of AuditorInstaller. Each time you use the uninstall option, it will remove the auditor most recently installed.

To remove all auditors from a profile, run AuditorInstaller repeatedly until you get a message indicating that the profile was unchanged.

Command-line syntax

-P-Cuninstall

Command-line example

-P-Cuninstall

Properties file syntax

profile.Cuninstall

Properties file example

profile.Cuninstall

Default value

false

Full Command-Line Examples

Following are some full SQLJ command-line examples showing the specification of AuditorInstaller options.

Insert a set of debug statements, or auditor, into the deepest layer, with runtime output to standard output:

sqlj -P-debug MyApp_SJProfile*.ser

Insert an auditor into the deepest layer, with runtime output to log.txt:

sqlj -P-debug -P-Clog=foo/bar/log.txt MyApp_SJProfile*.ser

Insert an auditor into layer 0. Send runtime output to log.txt; prefix each line of runtime output with "Layer 0: " (the command below is a single wraparound line):

sqlj -P-debug -P-Clog=foo/bar/log.txt -P-Cdepth=0 -P-Cprefix="Layer 0: " 
MyApp_SJProfile*.ser

Uninstall an auditor (this uninstalls the auditor most recently installed; do it repeatedly to uninstall all auditors):

sqlj -P-debug -P-Cuninstall MyApp_SJProfile*.ser

AuditorInstaller Runtime Output

During runtime, debug statements placed by AuditorInstaller result in a trace of methods called and values returned. This is done for all profile layers that had debug statements installed. (There is no means of selective debug output at runtime.)

AuditorInstaller output relates to profiles only; there is currently no mapping to lines in your original .sqlj source file.

Following is a sample portion of AuditorInstaller runtime output. This is what the output might look like for a SQLJ SELECT INTO statement:

oracle.sqlj.runtime.OraProfile@1 . getProfileData (  ) 
oracle.sqlj.runtime.OraProfile@1 . getProfileData returned 
sqlj.runtime.profile.ref.ProfileDataImpl@2 
oracle.sqlj.runtime.OraProfile@1 . getStatement ( 0 ) 
oracle.sqlj.runtime.OraProfile@1 . getStatement returned 
oracle.sqlj.runtime.OraRTStatement@3 
oracle.sqlj.runtime.OraRTStatement@3 . setMaxRows ( 1000 ) 
oracle.sqlj.runtime.OraRTStatement@3 . setMaxRows returned  
oracle.sqlj.runtime.OraRTStatement@3 . setMaxFieldSize ( 3000 ) 
oracle.sqlj.runtime.OraRTStatement@3 . setMaxFieldSize returned  
oracle.sqlj.runtime.OraRTStatement@3 . setQueryTimeout ( 1000 ) 
oracle.sqlj.runtime.OraRTStatement@3 . setQueryTimeout returned  
oracle.sqlj.runtime.OraRTStatement@3 . setBigDecimal ( 1 , 5 ) 
oracle.sqlj.runtime.OraRTStatement@3 . setBigDecimal returned  
oracle.sqlj.runtime.OraRTStatement@3 . setBoolean ( 2 , false ) 
oracle.sqlj.runtime.OraRTStatement@3 . setBoolean returned  
oracle.sqlj.runtime.OraRTStatement@3 . executeRTQuery (  ) 
oracle.sqlj.runtime.OraRTStatement@3 . executeRTQuery returned 
oracle.sqlj.runtime.OraRTResultSet@6 
oracle.sqlj.runtime.OraRTStatement@3 . getWarnings (  ) 
oracle.sqlj.runtime.OraRTStatement@3 . getWarnings returned null 
oracle.sqlj.runtime.OraRTStatement@3 . executeComplete (  ) 
oracle.sqlj.runtime.OraRTStatement@3 . executeComplete returned  
oracle.sqlj.runtime.OraRTResultSet@6 . next (  ) 
oracle.sqlj.runtime.OraRTResultSet@6 . next returned true 
oracle.sqlj.runtime.OraRTResultSet@6 . getBigDecimal ( 1 ) 
oracle.sqlj.runtime.OraRTResultSet@6 . getBigDecimal returned 5 
oracle.sqlj.runtime.OraRTResultSet@6 . getDate ( 7 ) 
oracle.sqlj.runtime.OraRTResultSet@6 . getDate returned 1998-03-28

There are two lines for each method call--the first showing the call and input parameters, and the second showing the return value.

Note:
The classes you see in the oracle.sqlj.runtime package are SQLJ runtime classes with equivalent functionality to similarly named JDBC classes. For example, OraRTResultSet is the SQLJ runtime implementation of the JDBC ResultSet class, containing equivalent attributes and methods.