feedback on the Tapestry User Guide (long)

[Blake Nicholson <ta...@package.com>]

I have been getting up to speed on Tapestry over the past two weeks and 
have some feedback on the User Guide (which I realize is a work in 
progress).  To make my biases clear, I have about three years of experience 
developing web applications, split 50/50 between WebObjects and 
JSP/Servlet-based solutions.


Chapter 1. Introduction (Engines, Services, and the Visit)
It is unclear to me how the Engine "occupies the same semantic space in 
Tapestry that the HttpSession does in the Servlet API."  Yes, the Visit and 
PageRecorders (which contain session-specific data) are stored in the 
Engine and the Engine in turn is stored in the HttpSession.  However, it 
seems to me that storing the Visit and PageRecorder data in the Engine is 
actually a bit of an arbitrary choice.

Couldn't a new SessionDataStore object be introduced to the framework to 
store the Visit and PageRecorder information and in turn be stored in the 
HttpSession?  Then you could use one instance of your Engine for all users 
of your application (assuming that the Engine is thread-safe) or you could 
use Engines out of a Pool as is done with stateless sessions.  Most of what 
is in the Engine appears to be independent of which Session it is 
associated with.  Is it correct to say that if the Visit and PageRecorder 
associated code were removed from the Engine, the Engine would no longer be 
Session specific?

I think the closest thing in a Tapestry application to the HttpSession 
would be the Visit object.  I understand that they are not equivalent since 
the PageRecorder information is not stored in the Visit object.  But as far 
as a place to hold onto custom session-persistent information, the Visit 
appears to be the place to do that.  One other idea would be to have a 
SessionDataStore that has all of the current PageRecorder handling code.  A 
Tapestry developer could then have their Visit object extend the 
SessionDataStore.  The Visit would either be accessible via the page as it 
is now or via the RequestCycle (rather than the Engine).


Chapter 2. Persistent Page Properties and Implementing Persistent Page 
Properties Manually
I found these two sections to be very unclear.  I did not have as much of a 
problem with the content as with the way that it's organized.  Maybe I'm 
missing something, but it seems to me that persistent page properties 
should be the exception, not the norm.

What about having the first page be about Page Properties.  This page could 
still talk about the statelessness of Servlets and JSPs and the awkward 
programming style it imposes on the developer.  A basic example could be 
shown that illustrates a simple page property with an instance variable and 
associated getter/setter (pretty much like Example 2.5).  We could 
highlight the use of the initialize method and why it's required (the fact 
that Pages are stored in a general Pool used by all Sessions).

The first page would continue on with the introduction of the 
<property-specification> tag.  The example from earlier in the page could 
be built upon by showing how we can eliminate all of the code from before 
by using a property-specification (as is done in Example 2.4 but without 
making the property persistent).  A note could be made that if a developer 
needs to access the getter and/or setter for a property they can add 
abstract methods to their page/component class.  The last part of this page 
would talk about how the initial-value attribute of a 
<property-specification> can only be used with primitives and Strings.  For 
more complex objects, the developer should not set an initial-value, but 
rather use the finishLoad method.

The second page would talk about Persistent Page Properties.  The transient 
vs. persistent distinction would be described.  The fact that persistent 
page properties need to be used very judiciously does not seem to be 
sufficiently emphasized.  As I said earlier, the docs and the examples 
throughout the Tapestry project often have fireObservedChange in the setter 
of a page/component property and I think this is misrepresentative of how 
often it should be used.  For example, several of the examples in the 
Component Reference invoke fireObservedChange in the setter of the 
property.  Whether or not a persistent page property would be appropriate 
depends upon the application.  I would lean more towards never using 
fireObservedChange in the Component Reference to avoid new developers 
making a property persistent unnecessarily.

The new Persistent Page Properties page would be similarly organized to the 
Page Properties section I describe above.  Here we would take our previous 
manual example and show what needs to change to make a property persistent 
(see Example 2.6).  Then we could show the <property-specification> for the 
persistent property and how the only difference from the transient property 
is the persistent="yes" attribute of the tag (this would match example 2.4).


Thank you to Howard and the other developers of Tapestry.  I think it is a 
great piece of work and the documentation (both standalone and javadoc) is 
very good.  I hope that you find my feedback helpful.  If people think my 
idea about reorganizing the page properties part of the User Guide is a 
good one, I would be happy to re-write those two pages.  I don't know how 
feasible re-factoring the Engine is due to the fact that would break some 
of the interfaces in the framework.


Thanks,
Blake