documentation for t:saveState

[Simon Kitching <sk...@obsidium.com>]

Hi,

There's some great documentation on the saveState component on the 
myfaces wiki. The tomahawk.tld file isn't bad. The comments on the 
UISaveState class are minimal.

I'd like to improve the class javadoc by including a little of the wiki 
content. Obviously including all of it is not relevant, but the tld and 
javadoc are the first places people (like me) will look for help on the 
component.

Here's an initial stab at it. Any feedback welcome..

===========
Provides the ability to store a model value inside the view's component 
tree.

JSF provides three scopes for managed beans and therefore all the model 
objects that the managed beans reference:  request, session, 
application. However a common requirement is a way for a model object to 
have a scope that is tied to the duration of the current view; that is 
longer than the request scope but shorter than session scope.

This component simply holds a reference to an arbitrary object specified 
by the value property. Because this object is an ordinary component 
whose scope is the current view, the reference to the model 
automatically has that same scope.

When the value is an EL expression, then after the view is restored the 
recreated target object is stored at the specified location.

The object being saved must either:
  * implement java.io.Serializable, or
  * implement javax.faces.component.StateHolder and have a default
    constructor.
===========

Is there anything else important about saveState that needs to be noted?

Thanks,

Simon

Re: documentation for t:saveState

[Sean Schofield <se...@gmail.com>]

Sounds good.  (I am no SaveState expert though.)  Basically anything
is better then the empty javadoc we have for most classes now!

sean

On 11/16/05, Simon Kitching <sk...@obsidium.com> wrote:
> Hi,
>
> There's some great documentation on the saveState component on the
> myfaces wiki. The tomahawk.tld file isn't bad. The comments on the
> UISaveState class are minimal.
>
> I'd like to improve the class javadoc by including a little of the wiki
> content. Obviously including all of it is not relevant, but the tld and
> javadoc are the first places people (like me) will look for help on the
> component.
>
> Here's an initial stab at it. Any feedback welcome..
>
> ===========
> Provides the ability to store a model value inside the view's component
> tree.
>
> JSF provides three scopes for managed beans and therefore all the model
> objects that the managed beans reference:  request, session,
> application. However a common requirement is a way for a model object to
> have a scope that is tied to the duration of the current view; that is
> longer than the request scope but shorter than session scope.
>
> This component simply holds a reference to an arbitrary object specified
> by the value property. Because this object is an ordinary component
> whose scope is the current view, the reference to the model
> automatically has that same scope.
>
> When the value is an EL expression, then after the view is restored the
> recreated target object is stored at the specified location.
>
> The object being saved must either:
>   * implement java.io.Serializable, or
>   * implement javax.faces.component.StateHolder and have a default
>     constructor.
> ===========
>
> Is there anything else important about saveState that needs to be noted?
>
> Thanks,
>
> Simon
>