This chapter describes how you can use the Oracle Applications Logging Framework with Oracle Configurator and the Oracle Configuration Interface Object to provide a convenient and uniform interface for logging their activity.
This chapter covers the following topics:
This chapter provides basic information about logging the operations you perform with the CIO, especially those inside Configurator Extensions.
Oracle Configurator and the Oracle Configuration Interface Object use the Oracle Applications Logging Framework to provide a convenient and uniform interface for logging their activity.
For references to Oracle documentation about the Oracle Applications Logging Framework, see Troubleshooting.
Logging through the CIO requires these essential actions:
These actions are illustrated together by Example of Logging.
Note: Logging through the CIO is primarily intended for use within Configurator Extensions, but you can also use it in custom applications that use the CIO directly. See Logging for a Custom Application.
In order to enable the creation of log entries through the CIO you must set the following parameters for the Oracle Applications Logging Framework:
AFLOG_ENABLED, to turn on logging.
AFLOG_MODULE, to specify the Java packages or classes that you wish to log, using the parameters described in Values for AFLOG_MODULE.
AFLOG_LEVEL, to specify the level of entries that you wish to log, using the parameters described in Values for AFLOG_LEVEL.
AFLOG_FILENAME, to specify the file where middle-tier log messages are written.
AFLOG_ECHO, to optionally echo all filtered logging messages to STDERR.
These parameters can be set as middle-tier properties or as database profile options. The parameter names listed here are for middle-tier properties. See the Oracle E-Business Suite Developer's Guide for information on how to set these parameters as database profile options.
The table Values for AFLOG_MODULE lists the strings that you can include in the AFLOG_MODULE parameter to identify the Java packages or classes that you wish to log. The AFLOG_MODULE parameter is a comma-delimited filter against which the module names of log messages are compared.
| Value | Description |
|---|---|
| cz% | Logs with attribution to the log-writing method Configuration.writeCXLogEntry(). This setting logs all activity by Oracle Configurator during a configuration session, regardless of which class in your Configurator Extension or custom application caused the entry to be written. Allows you to examine the activity of your classes in the context of Oracle Configurator activity. The Oracle Applications Logging Framework ignores oracle.apps. at the beginning of a package name, so to specify oracle.apps.cz.cio, you only specify cz.cio. Examples: cz% cz.cio% |
| packagepath% | Logs with attribution to the methods in your own Configurator Extension or custom application classes that caused the entry to be written. This setting logs only activity by your Configurator Extension or custom application during a configuration session and omits the surrounding activity by Oracle Configurator. Examples: acme% acme.rocket% |
The table Values for AFLOG_LEVEL lists the Oracle Applications Logging Framework logging levels in order of increasing severity. You must specify one of the supported levels when enabling logging through the CIO.
| Value | Description |
|---|---|
| STATEMENT | Used for low-level progress reporting. |
| PROCEDURE | Used for API-level progress reporting. |
| EVENT | Used for high-level progress reporting. |
| EXCEPTION | Not supported. Indicates a handled internal software failure. |
| ERROR | Not supported. Indicates an external end user error. |
| UNEXPECTED | Not supported. Indicates unhandled internal software failure. |
Caution: Logging through the CIO does not support use of the more severe logging levels provided by the Oracle Applications Logging Framework, namely: EXCEPTION, ERROR, and UNEXPECTED.
See Troubleshooting for references to more information about AFLOG_MODULE.
Creating entries in the log requires performing these essential actions in your Configurator Extension or custom application code:
In the Oracle Applications Logging Framework, the term module refers to a Java class when it is applied to a Java framework, so that term is used for consistency in the descriptions in this section.
You test whether logging is enabled by calling the method Configuration.isCXLogEnabled(). The syntax for this method is as follows:
public final boolean isCXLogEnabled(module, logLevel)
Parameters for isCXLogEnabled() describes the parameters for this method. Notice that the parameter module can be either an Object or a String. There are separate signatures of isCXLogEnabled() for each data type.
The table Logging Through the CIO provides an example of how to use this method.
| Data Type | Parameter | Description |
|---|---|---|
| Object or String | module | If you pass an Object, this parameter specifies the Java class to which the log entry will attributed. The typical value for this parameter is the Java keyword this. If you pass a String, this parameter specifies the fully-qualified name of the Java class, including its package, to which the log entry will attributed. This form is provided for use with static methods, since Java technology does not allow the use of the keyword this in static methods. A runtime exception is raised if this parameter is null. This description also applies to the parameter of the same name in Parameters for writeCXLogEntry(). |
| int | logLevel | The level of detail at which logging is enabled. Must be one of the following constants:
The specified level must correspond to one of the supported levels specified for AFLOG_LEVEL, as listed in Values for AFLOG_LEVEL. For example, if you specify Configuration.CXLOG_STATEMENT for this parameter, then AFLOG_LEVEL must specify STATEMENT. A runtime exception is raised if this parameter specifies an unsupported level. This description also applies to the parameter of the same name in Parameters for writeCXLogEntry(). |
You write an entry by calling the method Configuration.writeCXLogEntry(). The syntax for this method is as follows:
public final void writeCXLogEntry(module, methodName, label, message, logLevel)
The table Parameters for writeCXLogEntry() describes the parameters for this method. Notice that the parameter module can be either an Object or a String. There are separate signatures of writeCXLogEntry() for each data type.
Logging Through the CIO provides an example of how to use this method.
| Data Type | Parameter | Description |
|---|---|---|
| Object or String | module | See the description of the parameter of the same name in Parameters for isCXLogEnabled(). |
| String | methodName | The name of your Java method that is calling writeCXLogEntry(). This name is written to the log. A runtime exception is raised if this parameter is null or consists of white space. |
| String | label | An optional string. Use to provide additional context for the entry in the log. |
| String | message | An optional string. Use to write the log message that describes the situation being logged. |
| int | logLevel | See the description of the parameter of the same name in Parameters for isCXLogEnabled(). |
When logging through the CIO, you should follow these practices:
When writing a log entry with writeCXLogEntry(), always wrap that invocation with a test that uses isCXLogEnabled(). This prevents the unnecessary invocation of writeCXLogEntry() when logging is not enabled, which can affect performance.
See Example of Logging for an example of this practice.
If you are handling an exception, you can add an explicit invocation of writeCXLogEntry() in the catch block of your exception handling routine, specifying any of the supported logging levels listed in Values for AFLOG_LEVEL. Note that the CIO logs exceptions even if you do not add this explicit invocation, but adding it may ease your debugging work.
Set the logLevel parameter for writeCXLogEntry() to the level that provides you with the most useful information. See the table Values for the logLevel Parameter for guidance.
The example Logging Through the CIO illustrates how your code can use the logging methods described in Creating Entries in the Log. These methods are highlighted typographically in . The example also highlights these requirements:
The methodName parameter must match the name of the enclosing method.
The logLevel parameter must agree with the setting of AFLOG_LEVEL, which is assumed to be STATEMENT, in this example.
package acme.code;
import oracle.apps.cz.cio.Configuration;
import oracle.apps.cz.cio.IRuntimeNode;
public class MyClass {
// ... other code here to interact with configuration ...
public void selectIt(IRuntimeNode rtNode) {
Configuration cfg = rtNode.getConfiguration();
// ... other code here to select a node ...
if (cfg.isCXLogEnabled(this, Configuration.CXLOG_STATEMENT)) {
cfg.writeCXLogEntry(this,
"selectIt",
null,
"Selecting a node.",
Configuration.CXLOG_STATEMENT);
}
}
}
Log File Entry When AFLOG_MODULE Includes cz% and Log File Entry When AFLOG_MODULE Includes acme% show the log entries produced by the code fragment in Logging Through the CIO, with differing settings for AFLOG_MODULE, as described in Enabling Logging Scope.
Log File Entry When AFLOG_MODULE Includes cz% shows the effect of setting AFLOG_MODULE to cz%.
Log File Entry When AFLOG_MODULE Includes acme% shows the effect of setting AFLOG_MODULE to acme%.
Log File Entry When AFLOG_MODULE Includes cz%
[Oct 28, 2004 9:53:58 AM PDT] : 1098982438703:Thread[HttpRequestHandler-94,5,main]: -1: -1: ap723jdv: 139.185.20.44: -1:-1: STATEMENT:[cz.cio.Configuration.writeCXLogEntry]:[null_4e9d2fd_2 1 2] CXLog> [acme.code.MyClass.selectIt] Selecting Option 1
In Log File Entry When AFLOG_MODULE Includes cz%:
The entry begins with standard Oracle Applications Logging Framework information.
[Oct 28, 2004 9:53:58 AM PDT] : 1098982438703:Thread[HttpRequestHandler-94,5,main]: -1: -1: ap723jdv: 139.185.20.44: -1:-1: STATEMENT
The next part of the entry shows the attributing class and method:
:[cz.cio.Configuration.writeCXLogEntry]
Notice that the attributing class and method are Configuration and writeCXLogEntry(), which are the ones that actually wrote the entry.
The final part of the entry shows the logging message (which begins with the standard logging footprint text for Oracle Configurator):
:[null_4e9d2fd_2 1 2] CXLog> [acme.code.MyClass.selectIt] Selecting a node.
Notice that the message includes the prefix CXLog> and the full path to your method that called writeCXLogEntry().
Log File Entry When AFLOG_MODULE Includes acme%
[Oct 28, 2004 9:53:58 AM PDT] : 1098982438703:Thread[HttpRequestHandler-94,5,main]:-1: -1: ap723jdv: 139.185.20.44: -1:-1: STATEMENT:[acme.code.MyClass.selectIt]:[null_4e9d2fd_2 1 3] Selecting Option 1
In Log File Entry When AFLOG_MODULE Includes acme%:
The entry begins with standard Oracle Applications Logging Framework information.
[Oct 28, 2004 9:53:58 AM PDT] : 1098982438703:Thread[HttpRequestHandler-94,5,main]: -1: -1: ap723jdv: 139.185.20.44: -1:-1: STATEMENT
The next part of the entry shows the attributing class and method:
:[acme.code.MyClass.selectIt]
Notice that the message shows the full path to your method that called writeCXLogEntry().
The final part of the entry shows the logging message (which begins with the standard logging footprint text for Oracle Configurator):
:[null_4e9d2fd_2 1 3] Selecting a node.
Notice that the message shows only the text that you passed as an argument to the message parameter of writeCXLogEntry().
Logging through the CIO is primarily intended for use within Configurator Extensions operating against a generated Oracle Configurator user interface, but you can also use logging in custom applications that use the CIO directly against a custom user interface.
Note: Custom applications that have previously used the CZLog object should instead use the logging framework described in this chapter. The CZLog object is now deprecated.
Logging through a custom application is similar to the logging described in this chapter, especially in Creating Entries in the Log and Values for AFLOG_LEVEL, but with the following differences:
You create an instance of the class oracle.apps.cz.utilities.NonCtxLogWriter, to be a logging object that takes the place of the Configuration object
You write entries to the log by using the interface oracle.apps.cz.utilities.LogWriter
For an example of custom logging, see the code fragment under Logging Through the CIO for a Custom Application, and compare it to the example code shown under Logging Through the CIO.
Logging Through the CIO for a Custom Application
package acme.code;
import oracle.apps.cz.cio.Configuration;
import oracle.apps.cz.cio.IRuntimeNode;
import oracle.apps.cz.utilities.NonCtxLogWriter;
import oracle.apps.cz.utilities.LogWriter;
public class MyClass {
// ... other code here to interact with configuration ...
public void selectIt(IRuntimeNode rtNode) {
Configuration cfg = rtNode.getConfiguration();
// ... other code here to select a node ...
// Create a logging object
NonCtxLogWriter nclw = new NonCtxLogWriter();
if (nclw.isEnabled(LogWriter.STATEMENT, this)) {
nclw.write(this,
"selectIt",
null,
"Selecting a node.",
LogWriter.STATEMENT);
}
}
}