[wicket] 02/03: WICKET-6883 updated internals chapter exposing the default IPageStore chain

[ad...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

adelbene pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/wicket.git

commit 5e06a7b08b7ea9ff393f11adad5d9181965689ac
Author: Andrea Del Bene <ad...@apache.org>
AuthorDate: Mon May 10 23:12:38 2021 +0200

    WICKET-6883 updated internals chapter exposing the default IPageStore
    chain
---
 .../src/main/asciidoc/internals/pagestoring.adoc   | 39 +++++++++++-----------
 .../versioningCaching/versioningCaching_2.adoc     |  2 +-
 2 files changed, 20 insertions(+), 21 deletions(-)

diff --git a/wicket-user-guide/src/main/asciidoc/internals/pagestoring.adoc b/wicket-user-guide/src/main/asciidoc/internals/pagestoring.adoc
index 4bb85b9..b866f23 100644
--- a/wicket-user-guide/src/main/asciidoc/internals/pagestoring.adoc
+++ b/wicket-user-guide/src/main/asciidoc/internals/pagestoring.adoc
@@ -9,42 +9,41 @@ image::../img/page-storage.png[]
 === IPageManager
 
 _org.apache.wicket.page.IPageManager_'s task is to manage which pages have been used in a request and store their last state in the backing stores, namely _IPageStore_.
-The default implementation _org.apache.wicket.page.PageManager_ uses a chaing of page stores to collect all stateful pages which have been used in the request cycle (more than one page can be used in a single request if for example _setResponsePage()_ or _RestartResponseException_ is used).
-At the end of the request all collected page instances are being stored in the first level cache - http session. They are stored as metadata in the http session and passed to an underlying _IPageStore_.
-When the next http request is handled, _IPageProvider_ will ask for page with specific id and _PageManager_ will look first in the http session and if no match is found then it will delegate to any further IPageStore. At the end of the second request the http session based cache is being overwritten completely with the newly used page instances.
+The default implementation _org.apache.wicket.page.PageManager_ uses a chain of _IPageStore_ to collect all stateful pages which have been used in the request cycle and store them for a later use. 
 
-To setup another _IPageManager_ implementation use _org.apache.wicket.Application.setPageManagerProvider(IPageManagerProvider)_.
-The custom _IPageManager_ implementation may use a custom chain of _IPageStore_s as needed.
+NOTE: Keep in mind that more than one page can be used in a single request if, for example, _setResponsePage()_ or _RestartResponseException_ are used.
 
-=== IPageStore
+As said on <<versioningCaching.adoc#_page_caching,paragraph 8.2.4>> stateful pages are stored in a session-relative file using a two-levels cache to speedup the access. This process is made possible by the different implementations of _IPageStore_ that are part of the default chain and that will be introduced in the next paragraph.
 
-_org.apache.wicket.pageStore.IPageStore_'s role is to mediate the storing and loading of pages done by the underlying _IDataStore_. The default implementation _org.apache.wicket.pageStore.DefaultPageStore_ pre-processes the pages before passing them to _IDataStore.storeData(String, int, byte)_ and to post-processes them after _IDataStore.getData(String, int)_. The processing consists of transforming the page instance to _org.apache.wicket.pageStore.DefaultPageStore.SerializedPage_. This  [...]
+NOTE: Wicket gets the default _IPageManager_ using a supplier interface called _IPageManagerProvider_,hence to use a custom _IPageManager_ implementation we must register a specific _IPageManagerProvider_ via _org.apache.wicket.Application.setPageManagerProvider(IPageManagerProvider)_.
+
+=== Default IPageStore chain
+
+_org.apache.wicket.pageStore.IPageStore_'s role is to mediate the storing and loading of page instances. The default chain of _IPageStore_ used by Wicket contains the following ordered list of _IDataStore_:
+
+* *RequestPageStore:* collect all page instances involved in the last request. During the detach stage, stateful pages are passed to the othr steps of the chain to be persisted on file. 
+* *InSessionPageStore:* with _InSessionPageStore_ the default chain keeps the last rendered page instance into the HTTP session for fast access. 
+* *SerializingPageStore:* _SerializingPageStore_ turns page instances into a more serialization-friendly format represented by class _org.apache.wicket.pageStore.SerializedPage_. This is a struct of:
 
 [source,java]
 ----
 {
-   sessionId: String,
+   pageType: String,
    pageId : int,
    data : byte[]
 }
 ----
 
-i.e. this is the serialized page instance (data) plus additional information needed to be able to easily find it later (sessionId, pageId).
-
-When a _SerializedPage_ has to be stored _DefaultPageStore_ stores it in a application scoped cache ({sessionId, pageId} -> SerializedPage) and additionally gives it to the underlying _IDataStore.storeData(sessionId, pageId, data)_. The application scoped cache is used as second level cache. Getting a page from it is slower than the http session based cache in _PageStoreManager_ because the page has to be deserialized, but is faster than the underlying _IDataStore_ which stores the page  [...]
+i.e. this is the serialized page instance (data) plus additional information needed to be able to easily find it later (pageId, pageType).
 
-The size of the application scoped cache is configurable via _org.apache.wicket.settings.StoreSettings.setInmemoryCacheSize(int)_.
+* *AsynchronousPageStore:* The role of _AsynchronousPageStore_ is to detach the http worker thread from waiting for the write of the page bytes to the disk. To disable it use: _org.apache.wicket.settings.StoreSettings.setAsynchronous(false)_. _AsynchronousPageStore_ can delay the storage of page's bytes for at most _org.apache.wicket.settings.StoreSettings.setAsynchronousQueueCapacity(int)_ pages. If this capacity is exceeded then the page's bytes are written synchronously to the backing [...]
 
-=== IDataStore
+* *CryptingPageStore:* page instances might contain sensible informations, therefore it's important to have the chance to encrypt their content before persist them on disk. _CryptingPageStore_ encrypts _SerializedPage_'s with a 256 bit AES before passing them to the underling _DiskPageStore_. Buy default this stage is disabled and not added to the default chain. To change this behavior we can use _org.apache.wicket.settings.StoreSettings.setEncrypted_.
 
-_org.apache.wicket.pageStore.IDataStore_ is used to persist Wicket pages (as bytes) to a persistent store like e.g. files or databases. The default implementation is _org.apache.wicket.pageStore.DiskDataStore_ which as its name says stores the pages in files. The location of the folder where the files are stored is configurable via _org.apache.wicket.settings.StoreSettings.setFileStoreFolder(File)_, by default the web container's work folder is used (ServletContext attribute 'javax.servl [...]
+* *DiskPageStore:* stores _SerializedPage_ on a session-scoped file on disk. The location of the folder where the files are stored is configurable via _org.apache.wicket.settings.StoreSettings.setFileStoreFolder(File)_, by default the web container's work folder is used (ServletContext attribute 'javax.servlet.context.tempdir'). In this folder a sub-folder is created named _'applicationName-filestore'_. 
 This folder contains a sub-folder for each active http session. This session folder contains a single file named 'data' which contains the bytes for the pages. The size of this 'data' file is configurable via _org.apache.wicket.settings.StoreSettings.setMaxSizePerSession(Bytes)_. When this size is exceeded the newly stored files overwrite the oldest ones.
 
-=== AsynchronousDataStore
-
-By default Wicket wraps _DiskDataStore_ with _org.apache.wicket.pageStore.AsynchronousDataStore_. The role of _AsynchronousDataStore_ is to detach the http worker thread from waiting for the write of the page bytes to the disk.
-To disable it use: _org.apache.wicket.settings.StoreSettings.setAsynchronous(false)_. AsynchronousDataStore can delay the storage of page's bytes for at most _org.apache.wicket.settings.StoreSettings.setAsynchronousQueueCapacity(int)_ pages. If this capacity is exceeded then the page's bytes are written synchronously to the backing _IDataStore_.
-
+ 
 === DebugDiskDataStore
 
 Wicket provides an extension of _DiskDataStore_ that can be used to browse the content of the 'data' files created by _DiskDataStore_. This extension can be found in wicket-devutils.jar and needs to be enabled in the _init_-method of your application via 
@@ -81,7 +80,7 @@ MyApp#init()
 
 === DebugBar
 
-Further insights which can be valueable during debugging can be retrieved using the _org.apache.wicket.devutils.debugbar.DebugBar_ from wicket-devutils.jar. It's a panel which you simply add:
+Further insights which can be valuable during debugging can be retrieved using the _org.apache.wicket.devutils.debugbar.DebugBar_ from wicket-devutils.jar. It's a panel which you simply add:
 
 Java: 
 [source,java]
diff --git a/wicket-user-guide/src/main/asciidoc/versioningCaching/versioningCaching_2.adoc b/wicket-user-guide/src/main/asciidoc/versioningCaching/versioningCaching_2.adoc
index 67d35d1..a2e1887 100644
--- a/wicket-user-guide/src/main/asciidoc/versioningCaching/versioningCaching_2.adoc
+++ b/wicket-user-guide/src/main/asciidoc/versioningCaching/versioningCaching_2.adoc
@@ -113,7 +113,7 @@ public void init()
 
 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 handling will be covered in <<internals.adoc,chapter 26>> 
+NOTE: More insights on internal page storing will be covered in <<internals.adoc#_wicket_internals,chapter 26>> 
 
 === Page expiration