wicket
Class Session

java.lang.Object
  wicket.Session

All Implemented Interfaces:

java.io.Serializable

Direct Known Subclasses:

WebSession

public abstract class Session
extends java.lang.Object
implements java.io.Serializable

Holds information about a user session, including some fixed number of most recent pages (and all their nested component information).

• Access via RequestCycle - The Session for a RequestCycle can be retrieved by calling RequestCycle.getSession().
• Access via Component - If a RequestCycle object is not available, the Session can be retrieved for a Component by calling Component.getSession(). As currently implemented, each Component does not itself have a reference to the session that contains it. However, the Page component at the root of the containment hierarchy does have a reference to the Session that holds the Page. So Component.getSession() traverses the component hierarchy to the root Page and then calls Component.getSession().
• Access via Thread Local - In the odd case where neither a RequestCycle nor a Component is available, the currently active Session for the calling thread can be retrieved by calling the static method Session.get(). This last form should only be used if the first two forms cannot be used since thread local access can involve a potentially more expensive hash map lookup.
• Locale - A session has a Locale property to support localization. The Locale for a session can be set by calling setLocale(Locale). The Locale for a Session determines how localized resources are found and loaded.
• Style - Besides having an appearance based on locale, resources can also have different looks in the same locale (a.k.a. "skins"). The style for a session determines the look which is used within the appopriate locale. The session style ("skin") can be set with the setStyle() method.
• Resource Loading - Based on the Session locale and style, searching for resources occurs in the following order (where sourcePath is set via the ApplicationSettings object for the current Application, and style and locale are Session properties):
  1. [sourcePath]/name[style][locale].[extension]
  2. [sourcePath]/name[locale].[extension]
  3. [sourcePath]/name[style].[extension]
  4. [sourcePath]/name.[extension]
  5. [classPath]/name[style][locale].[extension]
  6. [classPath]/name[locale].[extension]
  7. [classPath]/name[style].[extension]
  8. [classPath]/name.[extension]
  
• Session Properties - Arbitrary objects can be attached to a Session by installing a session factory on your Application class which creates custom Session subclasses that have typesafe properties specific to the application (see Application for details). To discourage non-typesafe access to Session properties, no setProperty() or getProperty() method is provided. In a clustered environment, you should take care to call the dirty() method when you change a property or youre own. This way the session will be reset again in the http session so that the http session knows the session is changed.
• Class Resolver - Sessions have a class resolver ( IClassResolver) implementation that is used to locate classes for components such as pages.
• Page Factory - A pluggable implementation of IPageFactory is used to instantiate pages for the session.
• Removal - Pages can be removed from the Session forcibly by calling remove(Page) or removeAll(), although such an action should rarely be necessary.
• Flash Messages- Flash messages are messages that are stored in session and are removed after they are displayed to the user. Session acts as a store for these messages because they can last across requests.

  Author:

  Jonathan Locke, Eelco Hillenius, Igor Vaynberg (ivaynberg)

  See Also:

  Serialized Form

  Nested Class Summary

  static interface

  Session.IPageMapVisitor Visitor interface for visiting page maps

  Field Summary

  static java.lang.String

  SESSION_ATTRIBUTE_NAME Name of session attribute under which this session is stored

  Constructor Summary

  protected

  Session(Application application) Constructor.

  Method Summary

  void	clear() Removes all pages from the session.
  PageMap	createAutoPageMap() Automatically creates a page map, giving it a session unique name.
  java.lang.String	createAutoPageMapName() With this call you can create a pagemap name but not create the pagemap itself already.
  protected void	detach() Any detach logic for session subclasses.
  protected void	dirty() Marks session state as dirty
  void	error(java.lang.String message) Registers an error feedback message for this session
  static boolean	exists() Checks if the Session threadlocal is set in this thread
  static Session	get() Get the session for the calling thread.
  Application	getApplication() Get the application that is currently working with this session.
  protected java.lang.Object	getAttribute(java.lang.String name) Gets the attribute value with the given name
  protected java.util.List	getAttributeNames()
  IAuthorizationStrategy	getAuthorizationStrategy()
  IClassResolver	getClassResolver()
  ClientInfo	getClientInfo() Gets the client info object for this session.
  IConverter	getConverter() Gets the converter instance.
  PageMap	getDefaultPageMap()
  FeedbackMessages	getFeedbackMessages() Gets feedback messages stored in session
  java.lang.String	getId() Gets the unique id for this session from the underlying SessionStore
  java.util.Locale	getLocale() Get this session's locale.
  java.io.Serializable	getMetaData(MetaDataKey key) Gets metadata for this session using the given key.
  Page	getPage(java.lang.String pageMapName, java.lang.String path, int versionNumber) THIS METHOD IS NOT PART OF THE WICKET PUBLIC API.
  IPageFactory	getPageFactory()
  IPageFactory	getPageFactory(Page page)
  java.util.List	getPageMaps()
  protected abstract IRequestCycleFactory	getRequestCycleFactory()
  protected ISessionStore	getSessionStore() Gets the session store.
  long	getSizeInBytes()
  java.lang.String	getStyle() Get the style (see Session).
  void	info(java.lang.String message) Registers an informational feedback message for this session
  void	init() Set the session for each PageMap
  void	invalidate() Invalidates this session.
  PageMap	newPageMap(java.lang.String name) Creates a new page map with a given name
  RequestCycle	newRequestCycle(Request request, Response response) THIS METHOD IS NOT PART OF THE WICKET PUBLIC API.
  PageMap	pageMapForName(java.lang.String pageMapName, boolean autoCreate) Gets a page map for the given name, automatically creating it if need be.
  protected void	removeAttribute(java.lang.String name) Removes the attribute with the given name.
  void	removePageMap(PageMap pageMap)
  static void	set(Session session) THIS METHOD IS NOT PART OF THE WICKET PUBLIC API.
  void	setApplication(Application application) THIS METHOD IS NOT PART OF THE WICKET PUBLIC API.
  protected void	setAttribute(java.lang.String name, java.lang.Object value) Adds or replaces the attribute with the given name and value.
  void	setClientInfo(ClientInfo clientInfo) THIS METHOD IS NOT PART OF THE WICKET PUBLIC API.
  void	setLocale(java.util.Locale locale) Set the locale for this session.
  void	setMetaData(MetaDataKey key, java.io.Serializable object) Sets the metadata for this session using the given key.
  Session	setStyle(java.lang.String style) Set the style (see Session).
  void	touch(Page page) THIS METHOD IS NOT PART OF THE WICKET PUBLIC API.
  static void	unset() THIS METHOD IS NOT PART OF THE WICKET PUBLIC API.
  protected void	update() Updates the session, e.g.
  void	visitPageMaps(Session.IPageMapVisitor visitor)
  void	warn(java.lang.String message) Registers a warning feedback message for this session

  Methods inherited from class java.lang.Object

  clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  Field Detail

  SESSION_ATTRIBUTE_NAME

  public static final java.lang.String SESSION_ATTRIBUTE_NAME

  Name of session attribute under which this session is stored

  See Also:

  Constant Field Values

  Constructor Detail

  Session

  protected Session(Application application)

  Constructor.

  Parameters:

  application - The application that this is a session of

  Method Detail

  get

  public static Session get()

  Get the session for the calling thread.

  Returns:

  Session for calling thread

  exists

  public static boolean exists()

  Checks if the Session threadlocal is set in this thread

  Returns:

  true if get() can return the instance of session, false otherwise

  set

  public static void set(Session session)

  THIS METHOD IS NOT PART OF THE WICKET PUBLIC API. DO NOT CALL IT.

  Sets session for calling thread.

  Parameters:

  session - The session

  unset

  public static void unset()

  THIS METHOD IS NOT PART OF THE WICKET PUBLIC API. DO NOT CALL IT.

  Clears the session for calling thread.

  clear

  public final void clear()

  Removes all pages from the session. Although this method should rarely be needed, it is available (possibly for security reasons).

  getApplication

  public final Application getApplication()

  Get the application that is currently working with this session.

  Returns:

  Returns the application.

  getAuthorizationStrategy

  public IAuthorizationStrategy getAuthorizationStrategy()

  Returns:

  The authorization strategy for this session

  getClassResolver

  public final IClassResolver getClassResolver()

  Returns:

  The class resolver for this Session

  getClientInfo

  public ClientInfo getClientInfo()

  Gets the client info object for this session. This method lazily gets the new agent info object for this session. It uses any cached or set (setClientInfo(ClientInfo)) client info object or uses RequestCycle.newClientInfo() to get the info object based on the current request when no client info object was set yet, and then caches the returned object; we can expect the client to stay the same for the whole session, and implementations of RequestCycle.newClientInfo() might be relatively expensive.

  Returns:

  the client info object based on this request

  getDefaultPageMap

  public final PageMap getDefaultPageMap()

  Returns:

  The default page map

  getId

  public final java.lang.String getId()

  Gets the unique id for this session from the underlying SessionStore

  Returns:

  The unique id for this session

  getLocale

  public java.util.Locale getLocale()

  Get this session's locale.

  Returns:

  This session's locale

  getMetaData

  public final java.io.Serializable getMetaData(MetaDataKey key)

  Gets metadata for this session using the given key.

  Parameters:

  key - The key for the data

  Returns:

  The metadata

  See Also:

  MetaDataKey

  getPage

  public final Page getPage(java.lang.String pageMapName,
                            java.lang.String path,
                            int versionNumber)

  THIS METHOD IS NOT PART OF THE WICKET PUBLIC API. DO NOT CALL IT. Get the page for the given path.

  Parameters:

  pageMapName - The name of the page map where the page is

  path - Component path

  versionNumber - The version of the page required

  Returns:

  The page based on the first path component (the page id), or null if the requested version of the page cannot be found.

  getPageFactory

  public final IPageFactory getPageFactory()

  Returns:

  The page factory for this session

  getPageFactory

  public final IPageFactory getPageFactory(Page page)

  Parameters:

  page - The page, or null if no page context is available

  Returns:

  The page factory for the page, or the default page factory if page was null

  pageMapForName

  public final PageMap pageMapForName(java.lang.String pageMapName,
                                      boolean autoCreate)

  Gets a page map for the given name, automatically creating it if need be.

  Parameters:

  pageMapName - Name of page map, or null for default page map

  autoCreate - True if the page map should be automatically created if it does not exist

  Returns:

  PageMap for name

  createAutoPageMap

  public final PageMap createAutoPageMap()

  Automatically creates a page map, giving it a session unique name.

  Returns:

  Created PageMap

  createAutoPageMapName

  public final java.lang.String createAutoPageMapName()

  With this call you can create a pagemap name but not create the pagemap itself already. It will give the first pagemap name where it couldn't find a current pagemap for. It will return the same name if you call it 2 times in a row.

  Returns:

  The created pagemap name

  getPageMaps

  public final java.util.List getPageMaps()

  Returns:

  A list of all PageMaps in this session.

  getSizeInBytes

  public final long getSizeInBytes()

  Returns:

  Size of this session, including all the pagemaps it contains

  getStyle

  public final java.lang.String getStyle()

  Get the style (see Session).

  Returns:

  Returns the style (see Session)

  init

  public final void init()

  Set the session for each PageMap

  invalidate

  public void invalidate()

  Invalidates this session.

  newPageMap

  public final PageMap newPageMap(java.lang.String name)

  Creates a new page map with a given name

  Parameters:

  name - The name for the new page map

  Returns:

  The newly created page map

  newRequestCycle

  public final RequestCycle newRequestCycle(Request request,
                                            Response response)

  THIS METHOD IS NOT PART OF THE WICKET PUBLIC API. DO NOT CALL IT. Creates a new RequestCycle for the given request and response using the session's request cycle factory.

  Parameters:

  request - The request

  response - The response

  Returns:

  The new request cycle.

  removePageMap

  public final void removePageMap(PageMap pageMap)

  Parameters:

  pageMap - Page map to remove

  setApplication

  public final void setApplication(Application application)

  THIS METHOD IS NOT PART OF THE WICKET PUBLIC API. DO NOT CALL IT.

  Sets the application that this session is associated with.

  Parameters:

  application - The application

  setClientInfo

  public final void setClientInfo(ClientInfo clientInfo)

  THIS METHOD IS NOT PART OF THE WICKET PUBLIC API. DO NOT CALL IT.

  Sets the client info object for this session. This will only work when getClientInfo() is not overriden.

  Parameters:

  clientInfo - the client info object

  setLocale

  public final void setLocale(java.util.Locale locale)

  Set the locale for this session.

  Parameters:

  locale - New locale

  setMetaData

  public final void setMetaData(MetaDataKey key,
                                java.io.Serializable object)

  Sets the metadata for this session using the given key. If the metadata object is not of the correct type for the metadata key, an IllegalArgumentException will be thrown. For information on creating MetaDataKeys, see MetaDataKey.

  Parameters:

  key - The singleton key for the metadata

  object - The metadata object

  Throws:

  java.lang.IllegalArgumentException

  See Also:

  MetaDataKey

  setStyle

  public final Session setStyle(java.lang.String style)

  Set the style (see Session).

  Parameters:

  style - The style to set.

  Returns:

  the Session object

  touch

  public final void touch(Page page)

  THIS METHOD IS NOT PART OF THE WICKET PUBLIC API. DO NOT CALL IT.

  The page will be 'touched' in the session. If it wasn't added yet to the pagemap, it will be added to the page map else it will set this page to the front. If another page was removed because of this it will be cleaned up.

  Parameters:

  page -

  visitPageMaps

  public final void visitPageMaps(Session.IPageMapVisitor visitor)

  Parameters:

  visitor - The visitor to call at each Page in this PageMap.

  info

  public final void info(java.lang.String message)

  Registers an informational feedback message for this session

  Parameters:

  message - The feedback message

  warn

  public final void warn(java.lang.String message)

  Registers a warning feedback message for this session

  Parameters:

  message - The feedback message

  error

  public final void error(java.lang.String message)

  Registers an error feedback message for this session

  Parameters:

  message - The feedback message

  getFeedbackMessages

  public final FeedbackMessages getFeedbackMessages()

  Gets feedback messages stored in session

  Returns:

  unmodifiable list of feedback messages

  getConverter

  public final IConverter getConverter()

  Gets the converter instance. This method returns the cached converter for the current locale. Whenever the locale is changed, the cached value is cleared and the converter will be recreated for the new locale on a next request.

  Returns:

  the converter

  detach

  protected void detach()

  Any detach logic for session subclasses. This is called on the end of handling a request, when the RequestCycle is about to be detached from the current thread.

  dirty

  protected final void dirty()

  Marks session state as dirty

  getAttribute

  protected final java.lang.Object getAttribute(java.lang.String name)

  Gets the attribute value with the given name

  Parameters:

  name - The name of the attribute to store

  Returns:

  The value of the attribute

  getAttributeNames

  protected final java.util.List getAttributeNames()

  Returns:

  List of attributes for this session

  getRequestCycleFactory

  protected abstract IRequestCycleFactory getRequestCycleFactory()

  Returns:

  Request cycle factory for this kind of session.

  getSessionStore

  protected ISessionStore getSessionStore()

  Gets the session store.

  Returns:

  the session store

  removeAttribute

  protected final void removeAttribute(java.lang.String name)

  Removes the attribute with the given name.

  Parameters:

  name - the name of the attribute to remove

  setAttribute

  protected final void setAttribute(java.lang.String name,
                                    java.lang.Object value)

  Adds or replaces the attribute with the given name and value.

  Parameters:

  name - The name of the attribute

  value - The value of the attribute

  update

  protected void update()

  Updates the session, e.g. for replication purposes.