Oracle® Fusion Middleware Portal Development Guide for Oracle WebLogic Portal 10g Release 3 (10.3.5) Part Number E14243-08 |
|
|
View PDF |
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.
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 Section 14.2.2, "Turning Debug Output On and Off."
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:
Use the com.bea.p13n.util.debug.Debug
class to add debugging information calls to your WLP code. The Debug class lets you:
Turn debugging on and off without recompiling code.
Enable debugging output for a single class or entire package.
Discover where debugging messages are coming from.
Example 14-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).
Example 14-1 Using Debug in a Class
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 Section 14.2.4, "Directing Output to a File."
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 Section 14.2.6, "Example debug.properties File."
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
Tip:
Technically, you can set the debug property to any value except false
, off
, no
or 0
(these are values that can be used to turn logging off). For clarity and consistency, Oracle suggests that you use the values on
and off
in the debug.properties
file.
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 Section 14.2.6, "Example debug.properties 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 ...
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.
You enable output of WLP class debug information by either creating a debug.properties
file or by using a system variable, as described in Section 14.2, "Configuring and Enabling Debug."
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
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 Section 14.2, "Configuring and Enabling Debug."
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:
Section 14.3.2, "WLP Core Services Classes with Debug Support"
Section 14.3.3, "WLP Virtual Content Repository Classes with Debug Support"
Section 14.3.5, "WLP Administration Console Classes with Debug Support"
The following table lists the WLP Framework classes that support debugging and their associated features.
Note:
The WLP classes listed in the table below include only debug Level 1 output.
Table 14-1 WLP Framework Classes That Support Debug
Feature | Class |
---|---|
WSRP - Transport |
com.bea.wsrp.bind.markup |
WSRP - URL Rewriting |
|
Portlet Containers - Beehive |
|
Portlet Containers - Struts |
|
Portlet Containers - JSF |
|
Portlet Containers - JSP |
com.bea.netuix.servlets.controls.content.JspContent |
Portlet Containers - Clipper |
|
Portlet Containers - Browser |
Note: There is no debug for the Portlet Containers - Browser feature. However, the control is rendered using a |
Portlet Containers - Java (168/286) |
com.bea.portlet.container |
Framework - Caching |
|
Framework - Threading |
|
Framework - LAF |
|
Framework - Customization |
com.bea.netuix.application Note: Supporting database query properties files are under |
Framework - Async |
Note: Because debug output is highly verbose, you should use the ajax and ajaxRequest debug switches judiciously, enabling these switches only when told to do so by the users who will be interpreting the debug output. To gain a better understanding of the debug output, we recommend that you view the debug output along with the source code for the debug statements. |
Framework - Control Tree, Lifecycle |
|
Framework - File Poller |
|
Framework - Timing |
netuix.timing |
Framework - Events |
|
Framework - Preferences |
|
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.
Table 14-2 WLP Framework Command Line Environmental Switches That Support Debug
Feature | Command Line Switch |
---|---|
WSRP - Security |
|
The following table lists the WLP Core Services classes that support debugging, along with their associated features and debug levels.
Note:
For WLP Core Services classes, Level 2 output includes additional information that is not included in Level 1 output. To view all debugging information, you must enable both Level 1 and Level 2 debugging.
Table 14-3 WLP Core Services Classes That Support Debug
Feature | Level 1 | Level 2 |
---|---|---|
Cache |
|
|
Entitlements |
|
|
Rules Expression |
N/A |
|
Job Manager |
|
N/A |
Quiescence |
com.bea.p13n.management.quiescence.QuiescenceManagementServiceImpl |
|
Rules |
N/A |
|
Credential Vault |
N/A |
N/A |
SSO |
com.bea.p13n.security.sso.services.AuthServletFilter |
com.bea.p13n.security.sso.services.UsernameTokenService |
Util JDBC |
com.bea.p13n.util.jdbc.SequencerFactory |
com.bea.p13n.util.jdbc.internal.JdbcSequencer |
Tracked Anonymous |
com.bea.p13n.usermgmt.profile.internal.TrackedAnonymousLocator |
|
PropertySetManager |
|
|
Entity Property Manager |
com.bea.p13n.property.internal.EntityPropertyManagerImpl |
com.bea.p13n.property.internal.EntityPropertyCacheImpl |
Property Set Web Service |
com.bea.p13n.property.webservice.internal.PropertySetWebServiceImpl |
N/A |
Rules Manager |
com.bea.p13n.rules.manager.internal.RulesManagerImpl |
com.bea.p13n.rules.manager.internal.RuleSetPersistenceManager |
Realm Configuration |
com.bea.p13n.usermgmt.config.internal.RealmConfigurationImpl |
N/A |
User Profile Manager |
com.bea.p13n.usermgmt.profile.internal.ProfileManagerImpl |
N/A |
Group Profile Manager |
com.bea.p13n.usermgmt.profile.internal.GroupProfileManagerImpl |
N/A |
Mixed Profile Manager |
com.bea.p13n.usermgmt.profile.internal.MixedProfileManagerImpl |
N/A |
Custom Profile Manager |
com.bea.p13n.usermgmt.profile.internal.CustomProfileManagerImpl |
N/A |
Event Service |
|
|
Internal Data Refresh Proxy |
|
|
Analytics |
|
com.bea.analytics.AnalyticsP13nEventListener |
The following table lists the WLP Virtual Content Repository classes that support debugging and their associated features.
Note:
For WLP Virtual Content Repository classes, Level 2 output includes all of the information included in Level 1, but at a more verbose level. Additionally, Level 2 includes information that is not included in Level 1 output.
Table 14-4 WLP Virtual Content Repository Classes That Support Debug
Feature or Component | Level 1 | Level 2 |
---|---|---|
Repository Capabilities |
com.bea.content.federated.internal.CapabilityManagerImpl |
N/A |
Node Activities |
com.bea.content.federated.internal.NodeManagerImpl |
N/A |
Search Activities |
com.bea.content.federated.internal.SearchManagerImpl |
N/A |
Type Management Activities |
com.bea.content.federated.internal.TypeManagerImpl |
N/A |
Versioning Activities |
com.bea.content.federated.internal.VersionManagerImpl |
N/A |
Repository Management Activities |
com.bea.content.federated.internal.VirtualRepositoryManagerImpl |
N/A |
Workflow Activities |
com.bea.content.federated.internal.WorkflowManagerImpl |
N/A |
Node activities |
com.bea.content.federated.internal.delegate.NodeLogic |
N/A |
Type Management Activities |
com.bea.content.federated.internal.delegate.ObjectClassLogic |
N/A |
Repository Management Activities |
com.bea.content.federated.internal.delegate.RepositoryLogic |
N/A |
Search activities |
com.bea.content.federated.internal.delegate.SearchLogic |
N/A |
Versioning Activities |
com.bea.content.federated.internal.delegate.VersionLogic |
N/A |
Workflow Activities |
com.bea.content.federated.internal.delegate.WorkflowLogic |
N/A |
SPI Node Operations |
N/A |
spi.com.bea.content.federated.internal.filter.logging.NOPSLoggingFilter |
SPI Type Operations |
N/A |
spi.com.bea.content.federated.internal.filter.logging.OCOPSLoggingFilter |
SPI Repository Management Operations |
N/A |
spi.com.bea.content.federated.internal.filter.logging.RCOPSLoggingFilter |
SPI Search Operations |
N/A |
spi.com.bea.content.federated.internal.filter.logging.SOPSLoggingFilter |
SPI Workflow Operations |
N/A |
spi.com.bea.content.federated.internal.filter.logging.WOPSLoggingFilter |
The following table lists the Oracle WebCenter Content related classes that support debugging and their associated features.
Table 14-5 WLP WebCenter Content Related Classes That Support Debug
Feature or Component | Level 3 |
---|---|
Shows WebCenter Content calls, including timing information |
request.com.oracle.content.spi.ucm.UCMBridge |
Shows stack traces when calls are made to WebCenter Content (would typically be used in conjunction with the other one) |
requesttrace.com.oracle.content.spi.ucm.UCMBridge |
Debug timing |
timing.com.bea.content.federated.internal.filter.logging.* |
The following table lists the WLP Administration Console classes that support debugging, along with their associated features and debug levels.
Table 14-6 WLP Administration Console Classes That Support Debug
Feature | Level 1 | Level 2 |
---|---|---|
General Navigation, Menus, and Componentization |
|
|
Help |
N/A |
|
Portal Management |
com.bea.jsptools.portal.helpers.PortletHelper |
|
Content Management |
N/A |
com.bea.jsptools.content.ContentTreeBuilder |
Role Editor |
N/A |
roleTools.expressions.RoleExpressionsController |
Delegated Administration |
|
|
Entitlements |
|
ventTools.policies.VentBrowsePoliciesController |
User/Group Management |
|
|
Service Administration |
com.bea.jsptools.serviceadmin.wsrp.importTool.ImportProcessor |
|
Visitor Tools |
|
|