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.

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.

Back to top

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).

Back to top

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.

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).

Back to top

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.

Back to top

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:

Back to top

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.

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.

Back to top

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)

Back to top

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.

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).

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.

Resources

Learn

• Check the Rational Application Developer for WebSphere Software page on IBM® developerWorks® for links to product documentation, articles, tutorials, courses, downloads, and other useful areas.
  
  
• Explore the IBM Rational Application Developer Information Center for technical guidance.
  
  
• Learn about other applications in the IBM Rational Software Delivery Platform, including collaboration tools for parallel development and geographically dispersed teams, plus specialized software for architecture management, asset management, change and release management, integrated requirements management, process and portfolio management, and quality management. You can find product manuals, installation guides, and other documentation in the IBM Rational Online Documentation Center.
  
  
• Visit the Rational software area on developerWorks for technical resources and best practices for Rational Software Delivery Platform products.
  
  
• Explore Rational computer-based, Web-based, and instructor-led online courses. Hone your skills and learn more about Rational tools with these courses, which range from introductory to advanced. The courses on this catalog are available for purchase through computer-based training or Web-based training. Additionally, some "Getting Started" courses are available free of charge.
  
  
• Subscribe to the IBM developerWorks newsletter, a weekly update on the best of developerWorks tutorials, articles, downloads, community activities, webcasts and events.
  
  

Get products and technologies

• Download trial versions of Rational Application Developer.
  
  
• Download trial versions of IBM Rational software.
  
  
• Download these IBM product evaluation versions and get your hands on application development tools and middleware products from DB2®, Lotus®, Tivoli®, and WebSphere®.
  
  

Discuss

• Check out Rational Development Tools forum and the JavaServer Faces forum on developerWorks.
  
  
• Check out developerWorks blogs and get involved in the developerWorks community.
  
  

About the author

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

Comments (Undergoing maintenance)

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• Tracing information
• Technical architecture
• Installation
• Uninstalling the feature
• Application configuration
• JSF Trace view configuration
• Legend
• Debugging
• Resources
• About the author
• Comments

Next steps from IBM

• Try: Rational Application Developer for WebSphere Software
• Demo: Build, test and deploy JAX-WS Web services
• Webcast: Webcast: Develop innovative applications efficiently using the right application foundation in today's economy
• Briefing: Software development conference
• Buy: Rational Application Developer for WebSphere Software

My developerWorks community

Dig deeper into Rational on developerWorks

Rate a product. Write a review.

Write a review for Rational products today!

Special offers