Page History

Most instance variables in Tapestry are automatically cleared at the end of each request. This is important, as it pertains to how Tapestry pages are shared, over time, by many users.

However, you often want to store some data on a single page, and have access to it in later requests to that same page, without having to store it in a database between requests. (To store values across multiple pages, see Session Storage Persistent Page Data.)

Making page data persist across requests to a single page is accomplished with the @Persist annotation. This annotation is applied to private instance fields of components:

  @Persist
  private int value;

Such annotated fields will retain their state between requests. Generally, speaking, this means that the value is stored into the session (but other approaches are possible).

...

The value for each field is the strategy used to store the field between requests.

Session Strategy

{float:right|background=#eee|padding=0 1em}
    *JumpStart Demo:*
    [Storing Data in a Page|http://jumpstart.doublenegative.com.au/jumpstart/examples/state/storingdatainapage]
    [Passing Data Between Pages|http://jumpstart.doublenegative.com.au/jumpstart/examples/state/passingdatabetweenpages]
{float}

A suitably long session attribute name is used; it incorporates the name of the page, the nested component id, and the name of the field.

  @Persist
  private int value;

Flash Strategy

The flash strategy stores information in the session as well, just for not very long. Values are stored into the session, but then deleted from the session as they are first used to restore a page's state.

The flash is typically used to store temporary messages that should only be displayed to the user once.

  @Persist(PersistenceConstants.FLASH)
  private int value;

Client Strategy

The field is persisted onto the client; you will see an additional query parameter in each URL (or an extra hidden field in each form).

...

Use client persistence with care, and store a minimal amount of data. Try to store the identity (that is, primary key) of an object, rather than the object itself.

  @Persist(PersistenceConstants.CLIENT)
  private int value;

Hibernate Entity Strategy

Entity persistence is provided by the tapestry-hibernate module (which extends Tapestry with new features).

In Entity persistence, the field should store a Hibernate entity instance.

  @Persist(HibernatePersistenceConstants.ENTITY)
  private User user;

The value stored in the HttpSession is a token for the entity: its Java class name and primary key. When the field is restored in a later request, the entity is re-instantiated using that data.

...

The tapestry-jpa module uses a similar strategy. However, at the current time it can only store a persisted entity (one that has been saved to the database and has a primary key).

  @Persist(JpaPersistenceConstants.ENTITY)
  private Account account;

Persistence Strategy Inheritance

By default the value for the Persist annotation is the empty string. When this is true, then the actual strategy to be used is determined by a search up the component hierarchy.

...

The method discardPersistentFieldChanges() of ComponentResources will discard all persistent fields for the page, regardless of which strategy is used to store the property. This will not affect the page in memory, but takes effect for subsequent requests.

  @Persist(HibernatePersistenceConstants.ENTITY)
  private User user;

  @Persist(JpaPersistenceConstants.ENTITY)
  private Account account;