Portal Development Guide

Obtaining Debug Information

This chapter explains how to obtain debug information from public WLP classes and add debugging calls to your own code. This chapter includes the following sections:

For details on how to use Oracle Enterprise Pack for Eclipse to debug your web application project, see "Deploying or Debugging the Application" in Oracle Fusion Middleware Quick Start Guide for Oracle WebLogic Portal.

Introduction

The class com.bea.p13n.util.debug.Debug is used throughout WLP classes to print information that can be useful in debugging. You can use the Debug class in your own code. By default, debugging is turned off. For information on turning debug output on and off, see Turning Debug Output On and Off on page 11-3.

Configuring and Enabling Debug

The com.bea.p13n.util.debug.Debug class provides methods for printing and information messages from WLP code. This section explains how to use Debug in your own code and to turn Debug output on and off. This section includes these topics:

Using Debug in Your WLP Code

Use the com.bea.p13n.util.debug.Debug class to add debugging information calls to your WLP code. The Debug class lets you:

Listing 11-1 illustrates the basic pattern for using Debug in your classes. For detailed information on Debug methods, refer to the Javadoc (Oracle Fusion Middleware Java API Reference for Oracle WebLogic Portal).

   package com.bea.example;
   import com.bea.p13n.util.debug.Debug;
   class MyClass 
   {
     // Instance of debug object for debugging (if turned on)
     // Using this pattern makes it easy to know the debug "switch"
     // for any class
     private static final Debug debug = Debug.getInstance( MyClass.class );
 
     MyClass()
     {
         // debug class creation event
         debug.here()
     }
     void myMethod()
     {
       // output a debugging message along with class, method & line number
       debug.out("This is some message");
       
       // output a debugging message followed by object value
       // use this rather than ("message" + val) to avoid
       // expression evaluation (string concatenation) when debug is off
       debug.out("The value is:", val);
 
       // Avoid expression evaluations by using debug.ON or debug.isOn()
       if (debug.ON)
       {
          Object thing = doSomeCalculations();
          debug.out( "The thing " + thing + " is the calculation result." );
       }
     }
   }
 

The output includes class, method, line number, and variable information. When debugging is turned on, the debug output for the above example looks something like this.

*** com.bea.example.MyClass.(MyClass.java:<13>) ***
[com.bea.example.MyClass.myMmethod():18] This is some message
[com.bea.example.MyClass.myMmethod():23] The value is 42
[com.bea.example.MyClass.myMmethod():29] The thing kryten is the calculation result.

By default, output is sent to System.err. For information on directing the output to a file, see Directing Output to a File on page 11-5.

Turning Debug Output On and Off

Debug messages are turned off by default. To switch debugging on, create a file named debug.properties in the directory where your domain’s startup scripts reside. For an example debug.properties file, see Example debug.properties File on page 11-6.

Alternately, you can set the Java system property debug.properties to the name of your debug properties file. For example:

java -Ddebug.properties=/home/me/mydebug.properties ...
com.bea.example.MyClass: on

Package-Level Debugging

To turn on debugging for all of the classes in a package, set the debug property usePackageNames to on. Then, you can turn on debugging for an entire package (and its child packages). For example, to turn on debugging for all classes in the com.bea.example.* package, add the following to debug.properties:

# turn on debugging by package names
usePackageNames: on

# turn on debugging for everything under com.bea.example package
# Note that you do not use wildcards, just mention the package
com.bea.example: on

Using package names enables you to have finer control because more specific names take precedence over less specific names. For example, if you want to turn on debugging for the entire com.bea.example.* package except for MyClass and the com.bea.example.internal package (with the exception of one class), add the following to debug.properties:

# turn on package names for debugging
usePackageNames: on

# turn on debugging for everyting under com.bea.example package
com.bea.example: on

# turn off debugging for MyClass
com.bea.example.MyClass: off

# turn off debugging in the entire internal package
com.bea.example.internal: off

# Except turn debugging back on for internal.DebugThisClass
com.bea.example.internal.DebugThisClass: on

For an example debug.properties file, see Example debug.properties File on page 11-6

Directing Output to a File

By default, Debug output is sent to System.err. To redirect debug output to a file, set the debug property out.file to the name of an output file. The debug output will be appended to the end of that file unless you also set out.file.append=off, in which case the file is deleted first. For example:

# append output to mydebug.log file rather than System.err
out.file = mydebug.log

# send this debugging to mydebug.log
com.bea.example.DebugMeToFile: on

If you want to direct output by using system properties instead of the debug.properties file, you can do so by adding a debug prefix to the property name. For example:

 java -Ddebug.out.file=mydebug.log -Ddebug.com.bea.example.MyClass=on  ... 

Reloading Debug Properties

For performance reasons, Debug is by default not reloadable. The debug properties settings are in effect for the life of the JVM. To change the debugging configuration (for example, to change which classes or packages are turned on or off), you normally have to restart the JVM with different debug properties.

You can change the default reloading behavior with the debug property reloadable set to on in debug.properties or with -Ddebug.reloadable=on on the Java command line. If reloadable is set when the JVM is initially started, then debugging properties that are loaded from debug.properties (or system properties) can be changed at runtime without restarting the JVM. The reloadable property itself can not be changed at runtime; it must be set at JVM startup to take effect.

To change debug properties at runtime, edit the debug.properties file and call Debug.reload() from a JSP page or other runtime component.

Note that reloadable debug can be convenient for development, but even when it is not outputting any messages it does come at some cost, and thus should not be used in production or other performance-sensitive systems, such as load or performance tests.

Example debug.properties File

You enable output of WLP class debug information by either creating a debug.properties file or by using a system variable, as described in Configuring and Enabling Debug on page 11-1.

Following is an example of a debug.properties file, including enabled Level 1 and Level 2 debugging for WLP Virtual Content Repository classes.

# Example properties file for WebLogicPortal debug output

# Place this file in the directory where you start the server
# (the domain directory) or set -Ddebug.properties=debugFileName.
# The presence of this file turns debug on overall, and the
# properties in here control what debug is output.

# Most properties are booleans, and convention is to use "on" or "off" for the values

# Debug can be reloadable - use debug.jsp to change things at runtime
# The default is off.
reloadable: off


# append output to mydebug.log file rather than System.err
#out.file = D:/debugOutput
#out.file.append= off

# Turn on debug for entire packages (recursively) rather than only naming 
# desired classes.  This is normally desired as it allows for debugging
# whole sets of things, without having to name individual classes
# The default is off.
usePackageNames: off


# Example debug configurations

# Debugging for an individual class
#com.bea.netuix.servlets.manager.PortalServlet: on

com.bea.content.federated.internal.CapabilityManagerImpl: on
com.bea.content.federated.internal.NodeManagerImpl: on
com.bea.content.federated.internal.SearchManagerImpl: on
com.bea.content.federated.internal.TypeManagerImpl: on
com.bea.content.federated.internal.VersionManagerImpl: on
com.bea.content.federated.internal.VirtualRepositoryManagerImpl: on
com.bea.content.federated.internal.WorkflowManagerImpl: on
com.bea.content.federated.internal.delegate.NodeLogic: on
com.bea.content.federated.internal.delegate.ObjectClassLogic: on
com.bea.content.federated.internal.delegate.RepositoryLogic: on
com.bea.content.federated.internal.delegate.SearchLogic: on
com.bea.content.federated.internal.delegate.VersionLogic: on
com.bea.content.federated.internal.delegate.WorkflowLogic: on


spi.com.bea.content.federated.internal.filter.logging.NOPSLoggingFilter: on
spi.com.bea.content.federated.internal.filter.logging.OCOPSLoggingFilter: on
spi.com.bea.content.federated.internal.filter.logging.RCOPSLoggingFilter: on
spi.com.bea.content.federated.internal.filter.logging.SOPSLoggingFilter: on
spi.com.bea.content.federated.internal.filter.logging.WOPSLoggingFilter: on


# Debug an entire package
#com.bea.qa.apps.controls: on


# This setup turns on debug for the entire com.bea.netuix.servlets package,
# but excludes com.bea.netuix.servlets.l10n (and its subpackages).
#com.bea.netuix.servlets: on
#com.bea.netuix.servlets.l10n: off

Public WLP Class Debug Reference

Many of the public WLP classes use Debug methods to produce information that might be helpful when debugging an application. You enable WLP class debug information by editing a debug.properties file (or by using a System variable), as described in Configuring and Enabling Debug on page 11-1.

This section lists the public WLP classes that use Debug methods to output informational messages. The classes are grouped by feature/functional area.

This section contains the following sections:

WLP Framework Classes with Debug Support

The following table lists the WLP Framework classes that support debugging and their associated features.

The following table lists WLP Framework features and the command line environmental JVM switches that you can use to debug them. Note that the WSRP security debugging feature uses a Oracle WebLogic Server pattern of accessing debug information with system properties.

WLP Core Services Classes with Debug Support

The following table lists the WLP Core Services classes that support debugging, along with their associated features and debug levels.

WLP Virtual Content Repository Classes with Debug Support

The following table lists the WLP Virtual Content Repository classes that support debugging and their associated features.

WLP UCM Classes with Debug Support

The following table lists the UCM related classes that support debugging and their associated features.

WLP Administration Console Classes with Debug Support

The following table lists the WLP Administration Console classes that support debugging, along with their associated features and debug levels.