wicket-user-guide/src/main/asciidoc/versioningCaching/versioningCaching_2.adoc - wicket - Git at Google



 Stateful pages are versioned in order to support browser's back button: when this button is pressed Wicket must respond by rendering the same page instance previously used.

 A new page version is created when a stateful page is requested for the first time or when an existing instance is modified (for example changing its component hierarchy). To identify each page version Wicket uses a session-relative identifier called page id. This is a unique number and it is increased every time a new page version is created.

 In the final example of the previous chapter (project LifeCycleStages), you may have noticed the number appended at the end of URL. This number is the page id we are talking about:

 image::./img/page-id.png[]

 In this chapter we will use a revised version of this example project where the component hierarchy is modified inside the Link's _onClick()_ method. This is necessary because Wicket creates a new page version only if the page is modified before its method _onBeforeRender()_ is invoked. The code of the new home page is the following:

 [source,java]
 ----
 public class HomePage extends WebPage
 {
 	private static final long serialVersionUID = 1L;
 	private Label firstLabel;
 	private Label secondLabel;

 	public HomePage(){
 		firstLabel = new Label("label", "First label");
 		secondLabel = new Label("label", "Second label");

 		add(firstLabel);

 		add(new Link<Void>("reload"){
 			@Override
 			public void onClick() {
 				if(getPage().contains(firstLabel, true))
 					getPage().replace(secondLabel);
 				else
 					getPage().replace(firstLabel);
 			}
 		});

 	}
 }
 ----

 Now if we run the new example (project LifeCycleStagesRevisited) and we click on the “Reload” button, a new page version is created and the page id is increased by one:

 image::./img/reload-page.png[]

 If we press the back button the page version previously rendered (and serialized) will be retrieved (i.e. deserialized) and it will be used again to respond to our request (and page id is decremented):

 image::./img/browser-back.png[]

 NOTE: For more details about page storing you can take a look at paragraph "Page storing" from chapter "Wicket Internals" The content of this paragraph is from wiki page https://cwiki.apache.org/confluence/display/WICKET/Page+Storage.

 As we have stated at the beginning of this chapter, page versions are stored using Java serialization, therefore every object referenced inside a page must be serializable. In <<modelsforms.adoc#_model_chaining,paragraph 11.6>> we will see how to overcome this limit and work with non-serializable objects in our components using detachable Wicket models.

 === Using a specific page version with PageReference

 To retrieve a specific page version in our code we can use class _org.apache.wicket.PageReference_ by providing its constructor with the corresponding page id:

 [source,java]
 ----
 //load page version with page id = 3
 PageReference pageReference = new PageReference(3);
 //load the related page instance
 Page page = pageReference.getPage();
 ----

 To get the related page instance we must use the method getPage.

 === Turning off page versioning

 If for any reason we need to switch off versioning for a given page, we can call its method _setVersioned(false)_.

 === Pluggable serialization

 Wicket serializes pages using an implementation of interface _org.apache.wicket.serialize.ISerializer_. The default implementation is _org.apache.wicket.serialize.java.JavaSerializer_ and it uses the standard Java serialization mechanism based on classes _ObjectOutputStream_ and _ObjectInputStream_. However on internet we can find other interesting serialization libraries like https://github.com/EsotericSoftware/kryo[Kryo].

 We can set a custom serializer inside _init_ method accessing Wicket settings with _getFrameworkSettings()_:

 [source,java]
 ----
 @Override
 public void init()
 {
 	super.init();
 	getFrameworkSettings().setSerializer(yourSerializer);
 }
 ----

 A serializer based on Kryo library and another one based on Fast are provided by the WicketStuff project. You can find more information on this project, as well as the instructions to use its modules, in Appendix B.

 === Page caching

 By default Wicket persists versions of pages into a session-relative file on disk, but it uses a two-level cache to speed up the access. The first level of the cache contains all the pages involved in the current requests as we may visit more than one page during a single request, for example if we have been redirected with _setResponsePage_.
 The second level cache stores the last rendered page into a session-scoped variables.

 NOTE: Scoped variables will be introduced in <<requestProcessing.adoc#_storing_arbitrary_objects_with_metadata,chapter 9.4.6>> which is about Wicket metadata.

 The following picture is an overview of these two caching levels:

 image::./img/wicket-cache.png[]

 Wicket allows us to set the maximum size of the file used to store pages with setting class _org.apache.wicket.settings.StoreSettings_.
 This class provides the _setMaxSizePerSession(Bytes bytes)_ method to set the size of the file. The Bytes parameter is the maximum size allowed for this file:

 [source,java]
 ----
 @Override
 public void init()
 {
 	super.init();
 	getStoreSettings().setMaxSizePerSession(Bytes.kilobytes(500));
 }
 ----

 Class _org.apache.wicket.util.lang.Bytes_ is an utility class provided by Wicket to express size in bytes (for further details refer to the JavaDoc).

 NOTE: More insights on internal page storing will be covered in <<internals.adoc#_wicket_internals,chapter 26>>

 === Page expiration

 Page instances are not kept in the user session forever. They can be discarded when the limit set with the _setMaxSizePerSession_ method is reached or (more often) when user session expires. When we ask Wicket for a page id corresponding to a page instance removed from the session, we bump into a _PageExpiredException_ and we get the following default error page:

 image::./img/page-expired.png[]

 This error page can be customized with the _setPageExpiredErrorPage_ method of class _org.apache.wicket.settings.ApplicationSettings_:

 [source,java]
 ----
 @Override
 public void init()
 {
 	super.init();
 	getApplicationSettings().setPageExpiredErrorPage(
 				CustomExpiredErrorPage.class);
 }
 ----

 The page class provided as custom error page must have a public constructor with no argument or a constructor that takes as input a single _PageParameters_ argument (the page must be bookmarkable as described in <<urls.adoc#_pageparameters,paragraph 10.1.1>>).



	Stateful pages are versioned in order to support browser's back button: when this button is pressed Wicket must respond by rendering the same page instance previously used.

	A new page version is created when a stateful page is requested for the first time or when an existing instance is modified (for example changing its component hierarchy). To identify each page version Wicket uses a session-relative identifier called page id. This is a unique number and it is increased every time a new page version is created.

	In the final example of the previous chapter (project LifeCycleStages), you may have noticed the number appended at the end of URL. This number is the page id we are talking about:

	image::./img/page-id.png[]

	In this chapter we will use a revised version of this example project where the component hierarchy is modified inside the Link's _onClick()_ method. This is necessary because Wicket creates a new page version only if the page is modified before its method _onBeforeRender()_ is invoked. The code of the new home page is the following:

	[source,java]
	----
	public class HomePage extends WebPage
	{
	private static final long serialVersionUID = 1L;
	private Label firstLabel;
	private Label secondLabel;

	public HomePage(){
	firstLabel = new Label("label", "First label");
	secondLabel = new Label("label", "Second label");

	add(firstLabel);

	add(new Link<Void>("reload"){
	@Override
	public void onClick() {
	if(getPage().contains(firstLabel, true))
	getPage().replace(secondLabel);
	else
	getPage().replace(firstLabel);
	}
	});

	}
	}
	----

	Now if we run the new example (project LifeCycleStagesRevisited) and we click on the “Reload” button, a new page version is created and the page id is increased by one:

	image::./img/reload-page.png[]

	If we press the back button the page version previously rendered (and serialized) will be retrieved (i.e. deserialized) and it will be used again to respond to our request (and page id is decremented):

	image::./img/browser-back.png[]

	NOTE: For more details about page storing you can take a look at paragraph "Page storing" from chapter "Wicket Internals" The content of this paragraph is from wiki page https://cwiki.apache.org/confluence/display/WICKET/Page+Storage.

	As we have stated at the beginning of this chapter, page versions are stored using Java serialization, therefore every object referenced inside a page must be serializable. In <<modelsforms.adoc#_model_chaining,paragraph 11.6>> we will see how to overcome this limit and work with non-serializable objects in our components using detachable Wicket models.

	=== Using a specific page version with PageReference

	To retrieve a specific page version in our code we can use class _org.apache.wicket.PageReference_ by providing its constructor with the corresponding page id:

	[source,java]
	----
	//load page version with page id = 3
	PageReference pageReference = new PageReference(3);
	//load the related page instance
	Page page = pageReference.getPage();
	----

	To get the related page instance we must use the method getPage.

	=== Turning off page versioning

	If for any reason we need to switch off versioning for a given page, we can call its method _setVersioned(false)_.

	=== Pluggable serialization

	Wicket serializes pages using an implementation of interface _org.apache.wicket.serialize.ISerializer_. The default implementation is _org.apache.wicket.serialize.java.JavaSerializer_ and it uses the standard Java serialization mechanism based on classes _ObjectOutputStream_ and _ObjectInputStream_. However on internet we can find other interesting serialization libraries like https://github.com/EsotericSoftware/kryo[Kryo].

	We can set a custom serializer inside _init_ method accessing Wicket settings with _getFrameworkSettings()_:

	[source,java]
	----
	@Override
	public void init()
	{
	super.init();
	getFrameworkSettings().setSerializer(yourSerializer);
	}
	----

	A serializer based on Kryo library and another one based on Fast are provided by the WicketStuff project. You can find more information on this project, as well as the instructions to use its modules, in Appendix B.

	=== Page caching

	By default Wicket persists versions of pages into a session-relative file on disk, but it uses a two-level cache to speed up the access. The first level of the cache contains all the pages involved in the current requests as we may visit more than one page during a single request, for example if we have been redirected with _setResponsePage_.
	The second level cache stores the last rendered page into a session-scoped variables.

	NOTE: Scoped variables will be introduced in <<requestProcessing.adoc#_storing_arbitrary_objects_with_metadata,chapter 9.4.6>> which is about Wicket metadata.

	The following picture is an overview of these two caching levels:

	image::./img/wicket-cache.png[]

	Wicket allows us to set the maximum size of the file used to store pages with setting class _org.apache.wicket.settings.StoreSettings_.
	This class provides the _setMaxSizePerSession(Bytes bytes)_ method to set the size of the file. The Bytes parameter is the maximum size allowed for this file:

	[source,java]
	----
	@Override
	public void init()
	{
	super.init();
	getStoreSettings().setMaxSizePerSession(Bytes.kilobytes(500));
	}
	----

	Class _org.apache.wicket.util.lang.Bytes_ is an utility class provided by Wicket to express size in bytes (for further details refer to the JavaDoc).

	NOTE: More insights on internal page storing will be covered in <<internals.adoc#_wicket_internals,chapter 26>>

	=== Page expiration

	Page instances are not kept in the user session forever. They can be discarded when the limit set with the _setMaxSizePerSession_ method is reached or (more often) when user session expires. When we ask Wicket for a page id corresponding to a page instance removed from the session, we bump into a _PageExpiredException_ and we get the following default error page:

	image::./img/page-expired.png[]

	This error page can be customized with the _setPageExpiredErrorPage_ method of class _org.apache.wicket.settings.ApplicationSettings_:

	[source,java]
	----
	@Override
	public void init()
	{
	super.init();
	getApplicationSettings().setPageExpiredErrorPage(
	CustomExpiredErrorPage.class);
	}
	----

	The page class provided as custom error page must have a public constructor with no argument or a constructor that takes as input a single _PageParameters_ argument (the page must be bookmarkable as described in <<urls.adoc#_pageparameters,paragraph 10.1.1>>).