
================================================================================
			JWAD (Java Web-App Debugger) 
--------------------------------------------------------------------------------
			Version: 1.0.1
			Developer: Barney Marispini (Solarbox)
================================================================================


Table of Contents
--------------------------------------------------------------------------------

1) Overview
	A)	What is JWAD?
	B)	In two seconds or less, how does JWAD actually work?
	C)	Who is it intended for?
	D)	Who wrote it and why?
	E)	Is it actually free?
	F)	How often do I need to check for updates?

2) What's New?
	A)	Features
	B)	Bug Fixes

3) Requirements
	A)	What are the minimum requirements?

4) Installation
	A)	How and where do I install JWAD?

5) FAQs
	A)	How do I use it?
	B)	Do I have to add the custom tag to every page I want to debug?
	C)	What exactly do the "jwad-server.war" and "jwad-client.jar" 
		files do?
	D)	Does it work with Struts and JavaServer Faces?
	E)	Can I control the number and order of modules (scopes) 
		displayed in the JWAD console?
	F)	Do I have to add and remove JWAD every time I deploy to and 
		from production?

6) Troubleshooting
	A)	Why don't I see the JWAD debugger console on the page?
	B)	Why doesn't the JWAD debugger console appear exactly where I 
		placed it in my JSF page?
	C)	Why do I only see the class name and hashcode for a displayed 
		value (for example, com.solarbox.Example@12345)?

7) Future Versions
	A)	What new features are being considered for the next version 
		of JWAD?


1) Overview
--------------------------------------------------------------------------------

	A)	What is JWAD?

			JWAD (pronounced "JAY-wad") stands for Java Web-App 
			Debugger. It's a handy utility for displaying Java 
			objects hidden in the various scopes of a web application 
			(page, request, session, and application). It prints the 
			key/values of attributes, parameters, cookies, headers, 
			etc. in a user-friendly DTHML console.

	B)	In two seconds or less, how does JWAD actually work?

			Conceptually, JWAD is very simple. It checks every scope, 
			groups the objects into categories, and then iterates 
			their properties. The result is a DHTML console printed 
			to the page.  

	C)	Who is it intended for?

			JWAD is intended for any developer building a Java web 
			application. It's easy to install, simple to use, and 
			greatly simplifies the debugging of JSPs.  

	D)	Who wrote it and why?

			JWAD was developed by Barney Marispini of Solarbox. 
			While it was originally intended solely for personal use, 
			it evolved into something worth sharing with the entire 
			Java development community. JWAD is a must-have for every 
			Java developer toolbox.  

	E)	Is it actually free?

			Yes, it is free for both personal and commercial use. 
			The only catch is that it cannot be decompiled, reverse-
			engineered, repackaged, or sold for gain.  

	F)	How often do I need to check for updates?

			Never. The JWAD console automatically checks for updates 
			and then notifies you of newer versions. It's entirely 
			up to you as to whether you want to upgrade. 


2) What's New?
--------------------------------------------------------------------------------

	A)	Features

			There are no new features.

	B)	Bug Fixes

			• Cookie Sorting
				Fixed a minor bug that caused a ClassCastException to be thrown 
				when attempting to sort multiple cookies. The fix was very simple.
				Just needed to pass an explicit comparator to Arrays.sort() 
				since Cookie does not implement the Comparable interface.

			• JWAD Logging
				Removed JWAD logging so users don't see JWAD-specific statements 
				mixed in their log files.


3) Requirements
--------------------------------------------------------------------------------

	A)	What are the minimum requirements?

			JWAD requires at a minimum, Java SE 5 and Java EE 1.4. 
			JWAD does not use EJBs; therefore, you do not need an 
			application server. A simple JSP/Servlet container such 
			as Tomcat or Resin will work fine; although, you can use 
			an application server if you'd like (JBoss, WebLogic, 
			WebSphere, etc.).


4) Installation
--------------------------------------------------------------------------------

	A)	How and where do I install JWAD?

			JWAD consists of two files...
				• jwad-server.war
					This WAR simply serves the images, styles, 
					and scripts necessary to run the DTHML 
					console. The reason it is deployed as a 
					separate web-app is to simplify 
					installation. Were it not so, JWAD-specific 
					artifacts would be scattered throughout 
					your domain's web application. The intent 
					was to be non-intrusive.
				• jwad-client.jar
					This JAR contains all the Java code 
					necessary to access the various objects in 
					their respective scopes. It simply gets the 
					objects, categorizes, and then prints them 
					to the output stream.

			Once downloaded and extracted...
				1.	Copy the "jwad-client.jar" to your web-app's 
					"WEB-INF/lib" folder.

				2.	If necessary...
						• Modify your ANT build script.

				3.	Add the following context parameters to your 
					"web.xml" deployment descriptor. Be sure to 
					replace the [domain] and [port] placeholders 
					with your own corresponding values.

						<context-param>
							<param-name>jwadEnabled</param-name>
							<param-value>true</param-value>
						</context-param>
						<context-param>
							<param-name>jwadServer</param-name>
							<param-value>http://www.[domain].com:[port]</param-value>
						</context-param>

						Note: You may optionally omit the 
						"jwadServer" context parameter 
						altogether if the "jwad-server.war" 
						is deployed on the same server as 
						your domain web application (the one 
						with "jwad-client.jar").

				4.	Add the following taglib declaration and 
					custom tag include to your JSP template 
					(or pages).

						<%@ taglib uri="http://www.solarbox.com/tags/jwad" prefix="jwad" %>
						<jwad:debugger />

						Note: To control the number or order 
						of modules (scopes) displayed in the 
						JWAD console, use the optional "modules" 
						attribute of the <jwad:debugger /> 
						custom tag. Acceptable (comma-separated) 
						values include the following...
							• Page
							• Request
							• Session
							• Application

				5. Deploy the "jwad-server.war" to your web container.

				6. Deploy your domain's web-app.

				That's it! JWAD is ready to use. 


5) FAQs
--------------------------------------------------------------------------------

	A)	How do I use it?

			Once installed, simply add the custom tag to your page. 
			The JWAD DTHML console will appear exactly at the point 
			of insertion. Once the page loads, select the scope and 
			then the category.

	B)	Do I have to add the custom tag to every page I want to debug?

			Yes, but you can avoid having to do that if you template 
			your website. There are lots of excellent template 
			frameworks (Tiles, Velocity, etc.) to choose from. Pick 
			the one that best fits your needs (or roll your own) and 
			then add the JWAD custom tag include to your main template 
			page.  

	C)	What exactly do the "jwad-server.war" and "jwad-client.jar" files do?

			The "jwad-server.war" simply serves the images, styles, 
			and scripts necessary to run the DTHML console. The reason 
			it has to be deployed as a separate web-app is to simplify 
			installation. Were it not so, JWAD-specific artifacts would 
			be littered throughout your domain's web application. The 
			intent was to be non-intrusive.

			The "jwad-client.jar" contains all the Java code necessary 
			to access the various objects in their respective scopes. 
			It simply gets the objects, categorizes, and then prints 
			them to the output stream. 

	D)	Does it work with Struts and JavaServer Faces?

			Yes, it works with both. For the most part, JWAD should 
			work with any web framework. 

	E)	Can I control the number and order of modules (scopes) displayed 
		in the JWAD console?

			As a matter of fact, you can! The optional "modules" 
			attribute of the <jwad:debugger /> custom tag can be used 
			to specify a comma-separated list of modules (scopes) in 
			any order or number. Acceptable values include the 
			following...
				• Page
				• Request
				• Session
				• Application

	F)	Do I have to add and remove JWAD every time I deploy to and from 
		production?

			No. JWAD can be toggled off and on directly from the 
			"web.xml" deployment descriptor. Therefore, you never have 
			to worry about removing the custom tag JWAD includes from 
			any of your JSPs when migrating to and from production. 


6) Troubleshooting
--------------------------------------------------------------------------------

	A)	Why don't I see the JWAD debugger console on the page?

			There are two reasons why this might happen. Either the 
			JWAD custom tag include is not included on that specific 
			page or the "jwadEnabled" context parameter specified in 
			the deployment descriptor is set to false.

	B)	Why doesn't the JWAD debugger console appear exactly where I 
		placed it in my JSF page?

			Most likely, JavaServer Faces is throwing the console 
			outside the component tree because it's not wrapped as 
			a JSF component. To fix it, simply wrap the JWAD debugger 
			console in JSF "verbatim" tags.

				<f:verbatim>
					<jwad:debugger />
				</f:verbatim>

	C)	Why do I only see the class name and hashcode for a displayed 
		value (for example, com.solarbox.Example@12345)?

			Under the hood, when JWAD encounters an object, it calls 
			that object's toString() method. Therefore, objects will 
			only display meaningful information if their toString() 
			method has been properly overridden.

			To get the most out of JWAD be sure to override every 
			object's toString() method placed into a scope. When you 
			think about it, that's what the toString() method was 
			intended for - debugging purposes.

			As a best practice, I strongly recommend using the 
			commons-lang API provided by the Apache Software 
			Foundation for overriding your toString() methods. 
			The advantage is that it's only one line of code and 
			it automatically keeps your method up-to-date. You 
			don't have to worry about updating your toString() 
			methods as you add and remove attributes from your 
			objects because that one line of code uses reflection 
			to dynamically print those attributes when invoked. 


7) Future Versions
--------------------------------------------------------------------------------

	A)	What new features are being considered for the next version of JWAD?

			There are actually several new features being considered 
			at the moment. User feedback will have a tremendous 
			influence as to what direction JWAD takes.

			Some ideas currently considered include...
				• The ability to search the various scopes for a 
				  specific object.
				• The ability to view additional deployment 
				  descriptor elements such as listeners, tag 
				  libraries, servlet init parameters, security 
				  information, etc.
				• A mechanism for displaying client-side 
				  attributes such as JavaScript/CSS/Flash support 
				  versions, browser configurations, viewable screen 
				  dimensions, etc.


--------------------------------------------------------------------------------
Copyright ©2007, Solarbox - All Rights Reserved.
