@PreserveOnRefresh - Purpose and need?

Question

I have a doubt regarding the purpose of @PreserveOnRefresh annotation. What is the purpose of this particular annotation and what are the scenarios in which it has to be use

Answer 1

The other answer is not quite correct as noted in the comments (summarized here).

Vaadin 7

This Answer applies to Vaadin 7.

Vaadin 6 is different in some ways.

Session Is On-going

As soon as a user’s browser reaches your Vaadin app, a Servlet session is created. The VaadinSession contains a wrapper around that Servlet session, reachable via VaadinSession.getSession().

The session continues until a time-out occurs, you explicitly close it, user quits the browser app, or other such terminating event. But the user hitting the Reload/Refresh feature is not such a terminating event.

Reload/Refresh Button

While that session is on-going, the user may click/tap the Reload/Refresh icon feature in the web browser. By default this causes your current UI subclass object to be replaced by a new fresh UI subclass object.

To your user, it appears your app has restarted. But actually your app was not interrupted, only the content in that particular browser window/tab was discarded. Your app (your VaadinSession) lives on.

Your app may have had other browser windows/tabs open, each with their own UI subclass object. Those other windows/tabs would still be running with the same UI object. All of those running UI instances are tied to the same VaadinSession.

Retain UI Object on Reload/Refresh

You may or may not want your UI subclass object discarded on a Reload/Refresh of the browser window/tab, depending on the nature of your particular app.

Do you want the user to be able to do a "do over", to start again from scratch? If so, keep this default behavior. Do not apply the annotation.

If you want to change the effect of a browser Reload/Refresh to keep the UI object and its state, apply the PreserveOnRefresh annotation. Easy, almost like magic.

Two Levels Of Scope

In Vaadin 7, you may store state either at the level of a browser window/tab (a UI instance) or app-wide (on VaadinSession).

If you want some data to survive the discarding of a UI object, store that data on the VaadinSession by calling the get/setAttribute methods. For example, you would keep user login/authentication information on the VaadinSession.

To learn more these two levels of scope, including crucial information about thread-safety, see this other question, how to put data in session variable and get the data in different page in vaadin?.

Diagram

This diagram shows the session hierarchy. The upper three levels (Servlet Container, ServletContext, and HttpSession) are all standard Servlet technology. Below those are the Vaadin-specific levels.

Answer 2

When the enduser does press F5 (or click Refresh) in the web browser, then the behaviours is:

With @PreserveOnRefresh -> Use the same session, just refresh the UI from the server state

Without @PreserveOnRefresh -> Vaadin is creating a new session for the user and the user is shown the "first" page of your application

So usually the @PreserveOnRefresh is the intended behaviour, otherwise the user is logged out when he clicks on refresh