Page History

Page maps

Page map is a part of Session. Basically it is used as an interface for storing pages and their versions. Page map stores instances of pages (including component tree) which were visited by user during the current session. So every time user goes to another page or changes page state, the page instance is stored in a page map. There can be one or more page maps in one http session where each page map corresponds to a browser tab (or a modal window if it contains a page and has had a separate page map set). Page maps are identified by their names.

In a sense, page maps can be viewed as an implementation detail of Session, since they are used only through IPageMap interface and some of their the functionality should be accessed only through Session.

...

class MyHomePage extends WebPage {

    public MyHomePage() {
        add(new Link("changeState", new Model()) {
            public void onClick() {
                // this changes link state and therefore page state
                this.setModelObject(new Random().nextInt());
            }
        });

        add(new Link("gotoNewPage") {
            public void onClick() {
                setResponsePage(new MyPageMyHomePage());
            }
        });
    }
}

Now if you go to home page, click once on "gotoNewPage" link, twice on "changeState" link and twice on "gotoNewPage" link again, the page map for the current session will look like this (it doesn't mean page map stores pages in a table or map):

...

The first instance of home page with id 0 and version 0 was created when you went to application home page (i.e. typed in browser a URL like http://localhost:8080/app^{Image Removed}). Then after clicking on "gotoNewPage" link, page with id 1 and version 0 was created and added to the page map. Next two clicks on "changeState" link added to the page map versions 1 and 2 of the home page. And finally two clicks on "gotoNewPage" link created and added another two home page instances to the page map.

...

So for example to access second version of page instance with id 1 the following URL will be used: http://localhost:8080/app/?wicket:interface=:1:2:::^{Image Removed}. If there is no page with specified id and version, then "Page Expired" page will be shown.

Similarly components like Links and Buttons, which provide callback to user code, use URLs which point to the page instance in a page map. For example "changeState " link on the second version of page with id 1 will have URL like this http://localhost:8080/app/?wicket:interface=:1:changeState:2:ILinkListener::^{Image Removed} When this link is clicked Wicket will call onClick() handler for this link on the page instance with id 1 and version 2.

...

• on opening tab in web-browser (see IPageSettings#getAutomaticMultiWindowSupport())
• on creating modal/popup window
• when using inline frames
• anywhere in code using PageMap#forName() method
• it's not normal usecase, but page map is also created whenever a URL is requested which contains name of not-existing page map. For example URL like http://localhost:8080/app/?wicket:interface=newPageMap:0::::^{Image Removed} will create page map with name "newPageMap".

Page maps are created by ISessionStores. There are two ISessionStore implementations bundled with Wicket, each of them create different page map implementations. HttpSessionStore creates AccessStackPageMap; SecondLevelCacheSessionStore (this is default in Wicket 1.3) creates SecondLevelCachePageMap.

From the API point of view there are several ways to create page map. The wrong way is to obtain ISessionStore instance (for example through Application#getSessionStore()) and ask it to create page map. It's shouldn't be done this way since all page map creation is "encapsulated" in Session class. There are several methods in Session for creating/getting a page map:

• pageMapForName(name, autoCreate),
• newPageMap(name)
• createAutoPageMap() (see WebPage#onNewBrowserWindow() method)
  There is also convenient static method in PageMap class PageMap#forName(pageMapName) which simply calls pageMapForName(name, autoCreate) with autoCreate parameter set to true. Probably the most common way to create/obtain page map in code, if you need one, is to do something like PageMap.forName("myPageMapName").

In this diagram Session#pageMapForName() first tries to get page map from ISessionStore and if the attempt fails, creates new one and puts it into the ISessionStore.

...

There is no methods in Session for removing pages from page map. Pages may be removed from page map when the page map which contains them is removed. In other cases removing pages from page map is responsibility of ISessionStore (for example HttpSessionStore use LeastRecentlyAccessedEvictionStrategy).

This is simplification since PageMap don't use ISessionStore directly.

...