How to setup FacesTrace
If you’ve ever been caught trying to debug a Java Server Faces (JSF) 1.0 or 1.1 problem you know that you either get the “stack trace from hell” or too little output – in either case you don’t have what you need to troubleshoot. The problems that produce no helpful output (the kind you usually use the <h:messages></h:messages> tag to output to your JSP) are the ones that can be especially tricky. Since JSF gives no indication as to what actually went wrong, you’re stuck with various and tedious debugging techniques to troubleshoot a problem that is originating within the JSF life cycle. Luckily, there is a handy tool to help see inside the black box that is the JSF life cycle. FacesTrace is a very simple tool that visualizes the steps in the JSF life cycle, which ones passed or failed, and how long each step took to execute.
I believe that FacesTrace used to be a stand-alone tool but now is part of the PrimeFaces framework. I could not find a download of just FacesTrace anywhere on that site though, which was very confusing. I downloaded the PrimeFaces framework but it was devoid of anything specifically related to FacesTrace. I did find that you can download the facestrace.jar from SourceForge, which is where I suggest you get it from. The version this blog is based on is 1.0.1.
David Geary and Cay Horstmann recommend FacesTrace in their book Core JavaServer Faces 2nd Edition, but they’re missing a few steps in the setup. Even so, the full setup is dead simple. I couldn’t find that anyone else had documented it, so I’ve done that here. The steps are below. I’m assuming you’re familiar with a JSF application and you just want to use FacesTrace in it.
- Download facestrace.jar from here.
- Copy facestrace.jar to the WEB-INF/lib folder of your web app.
- Extract facesTrace.css from the facestrace.jar to where you store CSS files in your web app.
That’s it for the setup. Now you can use FacesTrace in any of your JSF pages with a couple more easy steps. The steps below specify things you must add to each JSP in which you want to use FacesTrace.
1. Add the FacesTrace taglib:
<%@ taglib uri="http://facestrace.sourceforge.net" prefix="ft" %>
2. Link to the FacesTrace CSS file (use the location specific to where you extracted the file):
<link href="<%=request.getContextPath()%>/theme/facesTrace.css" rel="stylesheet" type="text/css">
4. Add the FacesTrace trace tag in an appropriate place on your JSP page:
When you run your app and navigate to the page where you enabled FacesTrace you’ll see something like the image below:
The green boxes under the “Request Lifecycle” header represent the major steps in JSF’s lifecycle. Notice that each box contains the name of the lifecycle step and how long it took to execute. Boxes are green if the step succeeded and red if they did not.
The blue headers are clickable and will expand when clicked on. Another cool feature is under the “Component Tree” heading. Under this you can explore the JSF component model for the page, complete with component id’s and values. An example is below.
The rest of the interface is self-explanatory. I haven’t used FacesTrace much yet, but it’s worth adding to your app just in case you need it. If nothing else, playing around with it for some time will enhance your understanding of JSF!
As always, if I’ve been unclear, left something out, or you have some other question, please leave a comment on this post and I will respond soon.