Debug and troubleshoot JavaServer Faces applications by using JSFTrace in Rational Application Developer

JSFTrace helps developers get a better understanding of how JavaServer™ Faces technology works and how to debug their JSF applications faster and more efficiently. This article describes the JSFTrace feature introduced in IBM® Rational® Application Developer Version 7.5.4 and how to configure and use it for troubleshooting.

Yury Kats (ykats@us.ibm.com), Advisory Software Engineer, IBM

Yury Kats photoYury Kats is a developer in the IBM Rational Application Developer team, working on JSF implementation, components, and tooling.



24 September 2009

Also available in Chinese Russian Vietnamese

2In a JavaServer™ Faces (JSF) application, every request from the browser goes through a complex series of steps before a response can be generated. A series of these steps (or phases, as they are known in JSF) is called the JSF life cycle. Several conditions can influence what phases of the lifecycle get executed and, thus, what is being sent back to the browser in response to a request.

JSF developers often face problems when developing and debugging their applications. These problems can be attributed to either an inadequate understanding of a JSF life cycle or an inability to see everything that goes on during a JSF life cycle on the server.

A typical example of such a problem is when the user clicks a button on a JSF page, the developer expects that the application switches (navigates) to a different page, but instead, the same page is redisplayed to the user. The reason for lack of navigation is that the user provided incorrect information on the page is that JSF detected validation or conversion errors, and because of those errors, skipped the phase that's responsible for navigation. If the developer did not account for this possibility and did not add a special tag to the page to show errors (such as <h:messages>), both the user and the developer find themselves at a loss when trying to figure out why the same page was redisplayed.

IBM® Rational® Application Developer Version 7.5.4 introduces a JSF Trace feature that is designed to give the developer a sneak peak into the running JSF application. It collects information about the JSF life cycle and presents it in real time in an easy-to-understand form.

Tracing information

When you add JSF Tracing support to the application, the following information about JSF life cycle is collected and presented while your browser's request is being processed (see the example in Figure 1):

  • Incoming request, which includes request path information, parameters, header, and cookies
  • All life cycle phases that were executed, including this information about each phase:
    • Phase name
    • Approximate time spent in this phase
    • Before and after phase snapshot of objects in request, session, and application scopes
    • Before and after phase snapshot of the JSF view, including view attributes and the component tree (component type, ID, and values).
  • Messages that were logged (errors, warnings, informational messages)
  • Navigation that took place, including source and target pages, action that caused navigation, and an outcome of that action.

Collected tracing information is also decorated by using color, plus image, and font highlighting to point out the most important events during request processing, such as creation or modification of scoped objects (JSF-managed beans, for instance), component attributes, or components that were not rendered at all. See the "Legend" section that follows for details.

Figure 1. Trace view
Sample Trace view content

It is important to understand that tracing is very different from real debugging, because it presents "historic" data; that is, all objects shown in the view existed at some point in the past when information about them was collected, but they do not exist by the time they are shown in the tree. Therefore, it is not possible to inspect objects by using the JSF Trace view as you might be used to doing when debugging an application.

The JSF Trace feature provides limited support for real debugging (see "Debugging" which follows), but it should not be seen or treated as a debugging tool.


Technical architecture

The JSFTrace feature consists of two parts:

  • The JSF Trace view in Rational Application Developer
  • The jsf-trace.jar (Java™ Archive, or JAR) file in the application’s WEB-INF/lib folder

The jsf-trace.jar file installs a few JSF artifacts into your application (a PhaseListener and a NavigationHandler) that collect information when the application runs on the server. Collected information is then transmitted over a network connection to the JSF Trace view in Rational Application Developer, which interprets it and presents it in an easy-to-understand form. The JAR file and the view communicate with other over a network socket (host:port) that is configurable.

In addition to the JSF Trace view, a new JSF Trace console presents the raw information received over the network socket from the running application (see Figure2).

Figure 2. JSF Trace console
Sample Trace console content

Installation

To install tracing support into a JSF application:

  1. Open the JSF Trace view (by default, JSF Trace is configured to open automatically whenever you run a Faces page on the server). The view will show an informational message (because it cannot yet detect any data to present). See Figure 3.
  2. Click the Add Tracing support link.
  3. Optional: If you have more than one Web project in your workspace, you will be prompted to select what projects you want to add tracing to.
  4. An informational message will inform you of potential drawbacks of tracing and ask you to confirm that you want to add tracing to the project. After you confirm that you do, the jsf-trace.jar file will be added to the project's WEB-INF/lib folder.
Figure 3. JSF Trace setup
Initial Trace view content

With the JSF Trace view open and the jsf-trace.jar file added to the project, publish the project to the server of your choice and then request a page in a browser. The view will detect incoming communication from the running application and replace the informational message with the actual data being collected (as seen in Figure 1).


Uninstalling the feature

To disable JSF Trace in an application, either remove the jsf-trace.jar file from the project's WEB-INF/lib folder or set the web.xml context parameter com.ibm.faces.trace.ENABLED to false (see "Configuration," which follows). In both cases, no tracing information will be collected.

To disable JSF Trace in Rational Application Developer, close the JSF Trace view. When the view is closed, Rational Application Developer will not monitor incoming communication from running applications.


Application configuration

As Table 1 shows, the jsf-trace.jar file that is added to the project has several configuration settings that can be provided in application's web.xml file as context parameters:

Table 1. Parameters
Parameter nameDefault value (if context-param is not present)Description
com.ibm.faces.trace.ENABLEDtrueEnables or disables trace collection and communication.
Collection of trace data adds significant overhead to the application's performance, so it should never be used in production.
This parameter can be set to "false" to disable tracing.
Another way to disable tracing is to remove the jsf-trace.jar file from the application (see "Uninstalling the feature").
com.ibm.faces.trace.HOST127.0.0.1IP address or name of the machine where Rational Application Developer runs. If host name is used, it should be resolvable.
Technically, Rational Application Developer and the JSF application can run on different machines and still be able to communicate with each other. However, firewalls can block such communication.
com.ibm.faces.trace.PORT4444IP port on which to establish communication with Rational Application Developer. This setting should match with the JSF Trace view setting in Rational Application Developer (see "Preferences").
com.ibm.faces.trace.MAX_NESTING3Specifies how deep to go when resolving properties of scoped objects.
The larger this number, the longer it will take to collect information, to pass it to Rational Application Developer and to present in the view.
Use caution when increasing this number.
com.ibm.faces.trace.IGNORENo default

Recommended value:
com.ibm.,com.sun.,
javax.,org.,/

Note: The slash at the end is for older JSF implementations that kept view states in session under /jspname keys.
Comma-separated list of strings. If the scoped object's name started with any of the strings in the list, such an object will be ignored. Information about it won't be collected and won't be transmitted to the JSF Trace view.
When the JSF application runs, there is a fairly large number of objects in various scopes that do not belong to the actual application, but rather to the JSF implementation or the server container. Those objects rarely change and would rarely be interesting to you. Therefore, you can exclude them from tracing data to improve performance of collection and network traffic.
com.ibm.faces.trace.IGNORE_APPLICATION_SCOPEfalseWhen set to true, excludes all application scoped objects from the trace.
Can be used to improve performance (the less information there is to collect, the faster tracing will work).
com.ibm.faces.trace.IGNORE_SESSION_SCOPEfalseWhen set to true, excludes all session-scoped objects from the trace.
Can be used to improve performance (the less information there is to collect, the faster tracing will work).
com.ibm.faces.trace.IGNORE_REQUEST_SCOPEfalseWhen set to true, excludes all request-scoped objects from the trace.
Can be used to improve performance (the less information there is to collect, the faster tracing will work).
com.ibm.faces.trace.IGNORE_VIEW_ATTRIBUTESfalseWhen set to true, excludes all view attributes from the trace.
Can be used to improve performance (the less information there is to collect, the faster tracing will work).
com.ibm.faces.trace.IGNORE_VIEW_TREEfalseWhen set to true, excludes view tree (all components) from the trace.
Can be used to improve performance (the less information there is to collect, the faster tracing will work).
com.ibm.faces.trace.IGNORE_COMPONENT_VALUESfalseWhen set to true, trace won't ask components for their values.
Querying components values might have unexpected side effects, because the value binding would be evaluated when it wouldn't be by the regular JSF life cycle. This, in turn, could lead to a managed bean being created when it shouldn't be.
com.ibm.faces.trace.TRACE_UIDATAfalseWhen set to true, tracing of the UI Data components in the tree will iterate over the data model and collect information about components in each row (up to a maximum number of rows).
When set to false, tracing of the UI Data components will include only one instance of each component inside of UI Data.
com.ibm.faces.trace.MAX_UIDATA_ROWS10When com.ibm.faces.trace.TRACE_UIDATA is set to true, this parameter limits the number of UI Data's rows included in the trace. The larger this number, the longer it will take to collect information, to pass it to Rational Application Developer, and to present in the view.
Use caution when increasing this number.

JSF Trace view configuration

Preferences

JSF Trace view has several configuration settings available in the Preferences (see Figure 4) area of Rational Application Developer. To get to these settings, select Customize item from the view's menu, or use the usual path to Preferences: Window > Preferences > JSF Tools > Trace.

Figure 4. Preferences
Trace view configuration

These are the Preferences settings and what you need to know about them:

  • Communication port: Socket port to use to listen for incoming traffic. This should match the value of the com.ibm.faces.trace.PORT context parameter of the running application (see "Application configuration" for details).
  • System objects: If the scoped object name started with any of the strings in the list, such an object will be treated as "system object," meaning that the object does not belong to the actual application but rather to the JSF implementation or the server container. The view can be configured not to highlight system objects when their values are modified (to avoid irrelevant information) or not to show them at all (see "Filtering"). By default, all com.ibm, com.sun, javax, and org objects are treated as system objects.
  • Expand the tree to show new and changed objects. This automatically expands those branches of the tree that contain new or modified objects. Turning this setting off can improve the performance of the view.
  • Highlight new and changed objects. This automatically marks objects created and modified during request processing using different colors (see colors below)
  • New value color. Select a color to be used to mark objects that were created during a particular phase.
  • Changed value color. Select a color to be used to mark objects that were changed during a particular phase.
  • Highlight system objects. Specifies whether system objects (see above) should be highlighted when their values change.
  • Show view when content changes. If the view is open but hidden under other views in the perspective, it will be brought to the top whenever there is new trace information to be shown.
  • Show view when Faces page is ran on the server. Opens the view whenever the Run On Server operation is performed for a JSF page or project
  • Display explanation. Shows an informational message whenever the view is automatically opened, giving you an opportunity to opt out of using this function.

Filtering

Information presented in the JSF Trace view can be hidden by setting a filter. Select Filters in the view's menu to see a list of available filters and to turn individual filters on and off (see Figure 5). For example, application, session, and request scope filters will hide all objects in the corresponding scope from the view; whereas, the system objects filter will hide those objects that were configured as "system" in Preferences (see "Preferences").

Filters can be effectively used to reduce information overload in the view by hiding those objects that you are not interested in. For example, application-scoped objects rarely change, so you can hide them from the view completely.

Multiple filters can be enabled at the same time.

Figure 5. Filters
Filters for the Trace view

Legend

Tracing information presented in the view is decorated by using color, images, and font highlighting. Following decorations are available:

  • An object that was created during one of the life cycle phases is highlighted with green background (the color is configurable in Preferences)
  • A value that was changed during one of the life cycle phases is highlighted with yellow background (the color is configurable in Preferences)
  • A value that was created or changed during one of the lifecycle phases is shown in bold font.
  • A component that was not rendered is shown in the component tree in italic font.
  • A component that is invalid is shown in the component tree with a little red X icon. The icon is propagated to all components’ parents, up to the view node.
  • A phase where a breakpoint is set (see "Debugging") is shown with a little breakpoint icon (blue dot)

Debugging

All tracing features described until now did not require the server to be in debug mode. When using JSF Trace, you get to see a lot of information that is typical only for debugging (values for various objects, execution paths) while avoiding the overhead of real debugging.

There will be times, however, when you would still need to debug the application. In such cases, when the server is running in debug mode, JSF Trace provides two additional features geared specifically toward debugging:

  • JSF-specific breakpoints
  • Watches for scoped objects and view attributes

Breakpoints

Using JSF Trace view a breakpoint can be set before or after any of the phases of the JSF life cycle.

To set a breakpoint, either right-click on the "before" or "after" node in the tree for the phase that you are interested in or use the "Breakpoints" item in the view's menu (see Figure 6). After a breakpoint is set, a little icon will be shown on the phase icon in the view to indicate its presence. Breakpoints can be removed the same way that they were set.

When a breakpoint is hit, the application will be suspended and all of the usual debugging facilities will be available to you. For instance, the Variables view will automatically contain a FacesContext object in its current state. FacesContext is the root of all information about the JSF state; therefore, you will be able to find all aspects of the currently paused application by expanding various nodes of the FacesContext object.

Figure 6. Breakpoints menu
Setting breakpoints in JSF lifecycle

Watches

One of the most common tasks that you would perform when an application is paused is to check the state of one of the JSF-managed beans. Although all managed beans (and other scoped objects) can be found by looking at the FacesContext object available in the Variables view, finding the objects this way can be difficult and time-consuming. To help you with this task, the JSF Trace view allows for "watches" to be created for scoped objects and view attributes. After a watch is created, the object will automatically appear in the Expressions view.

Note:
Watch expressions are evaluated only when execution is suspended in the application code (in classes that are in the project's JavaSource folder, for example in your own managed beans). Expressions are not evaluated when the breakpoint is hit in core JSF code or in the jsf-trace.jar file.

To create a watch for an object, right-click on it in the view and select Add Watch Expression from the drop-down menu or use the Watches item in the view's menu (see Figure 7).

Figure 7. Watches menu
Adding watch expressions for JSF objects

You can modify or delete existing watches through the Expressions view.

Figure 8 shows the Watch Expression that was added for a request-scoped managed bean named "person" and the Variables view showing the current state of the FacesContext object.

Figure 8. Expressions and Variables views
Watch expressions and variables in Debug mode

Resources

Learn

Get products and technologies

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into Rational software on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Rational, Agile transformation
ArticleID=430360
ArticleTitle=Debug and troubleshoot JavaServer Faces applications by using JSFTrace in Rational Application Developer
publish-date=09242009