org.apache.wicket
Class Session

java.lang.Object
  org.apache.wicket.Session

All Implemented Interfaces:

Serializable, IClusterable

Direct Known Subclasses:

WebSession

public abstract class Session
extends Object
implements IClusterable

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 appropriate 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 on your 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
  static class	Session.PageMapAccessMetaData meta data for recording map map access.

  Field Summary

  static MetaDataKey<Session.PageMapAccessMetaData>	PAGEMAP_ACCESS_MDK meta data key for missing body tags logging.
  static String	SESSION_ATTRIBUTE_NAME Name of session attribute under which this session is stored

  Constructor Summary

  protected	Session(Application application, Request request) Deprecated. Use #Session(Request)
  	Session(Request request) Constructor.

  Method Summary

  protected void	attach() Deprecated. will not be available in 1.5+
  void	bind() Force binding this session to the application's session store if not already done so.
  abstract void	cleanupFeedbackMessages() Cleans up all rendered feedback messages and any unrendered, dangling feedback messages there may be left after that.
  void	clear() Removes all pages from the session.
  IPageMap	createAutoPageMap() Automatically creates a page map, giving it a session unique name.
  String	createAutoPageMapName() With this call you can create a pagemap name but not create the pagemap itself already.
  protected int	currentCreateAutoPageMapCounter()
  protected void	detach() Any detach logic for session subclasses.
  void	dirty() Marks session state as dirty so that it will be flushed at the end of the request.
  void	error(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	findOrCreate() Locate the session for the client of this request in the ISessionStore or create a new one and attach it when none could be located and sets it as the current instance for this thread.
  static Session	findOrCreate(Request request, Response response)
  static Session	get() Get the session for the calling thread.
  Application	getApplication() Get the application that is currently working with this session.
  protected Object	getAttribute(String name) Gets the attribute value with the given name
  protected List<String>	getAttributeNames()
  IAuthorizationStrategy	getAuthorizationStrategy()
  protected String	getAutoPageMapNamePrefix()
  protected String	getAutoPageMapNameSuffix()
  IClassResolver	getClassResolver()
  ClientInfo	getClientInfo() Gets the client info object for this session.
  IPageMap	getDefaultPageMap()
  FeedbackMessages	getFeedbackMessages() Gets feedback messages stored in session
  String	getId() Gets the unique id for this session from the underlying SessionStore.
  Locale	getLocale() Get this session's locale.
  <M extends Serializable> M	getMetaData(MetaDataKey<M> key) Gets metadata for this session using the given key.
  Page	getPage(int pageId, int versionNumber) THIS METHOD IS NOT PART OF THE WICKET PUBLIC API.
  Page	getPage(String pageMapName, String componentPath, int versionNumber) THIS METHOD IS NOT PART OF THE WICKET PUBLIC API.
  IPageFactory	getPageFactory()
  List<IPageMap>	getPageMaps()
  protected ISessionStore	getSessionStore() Gets the session store.
  long	getSizeInBytes()
  String	getStyle() Get the style (see Session).
  protected void	incrementCreateAutoPageMapCounter()
  void	info(String message) Registers an informational feedback message for this session
  void	invalidate() Invalidates this session at the end of the current request.
  void	invalidateNow() Invalidates this session immediately.
  protected boolean	isCurrentRequestValid(RequestCycle lockedRequestCycle) When a regular request on certain page with certain version is being processed, we don't allow ajax requests to same page and version.
  boolean	isSessionInvalidated() Whether the session is invalid now, or will be invalidated by the end of the request.
  boolean	isTemporary() Whether this session is temporary.
  IPageMap	newPageMap(String name) Creates a new page map with a given name
  protected int	nextPageId()
  int	nextSequenceValue() Retrieves the next available session-unique value
  IPageMap	pageMapForName(String pageMapName, boolean autoCreate) Gets a page map for the given name, automatically creating it if need be.
  protected void	removeAttribute(String name) Removes the attribute with the given name.
  void	removePageMap(IPageMap pageMap)
  void	replaceSession() Replaces the underlying (Web)Session, invalidating the current one and creating a new one.
  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(String name, 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(Locale locale) Set the locale for this session.
  void	setMetaData(MetaDataKey<?> key, Serializable object) Sets the metadata for this session using the given key.
  Session	setStyle(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.
  void	untouch(Page page) THIS METHOD IS NOT PART OF THE WICKET PUBLIC API.
  protected void	update() Deprecated. obsolete method (was meant for internal book keeping really). Clients should override detach() instead.
  void	visitPageMaps(Session.IPageMapVisitor visitor)
  void	warn(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

  PAGEMAP_ACCESS_MDK

  public static final MetaDataKey<Session.PageMapAccessMetaData> PAGEMAP_ACCESS_MDK

  meta data key for missing body tags logging.

  SESSION_ATTRIBUTE_NAME

  public static final String SESSION_ATTRIBUTE_NAME

  Name of session attribute under which this session is stored

  See Also:

  Constant Field Values

  Constructor Detail

  Session

  public Session(Request request)

  Constructor. Note that RequestCycle is not available until this constructor returns.

  Parameters:

  request - The current request

  Session

  @Deprecated
  protected Session(Application application,
                               Request request)

  Deprecated. Use #Session(Request)

  Constructor. Note that RequestCycle is not available until this constructor returns.

  Parameters:

  application - The application that this is a session of

  request - The current request

  Method Detail

  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

  findOrCreate

  public static final Session findOrCreate()

  Locate the session for the client of this request in the ISessionStore or create a new one and attach it when none could be located and sets it as the current instance for this thread. Typically, clients never touch this method, but rather use get(), which does the locating implicitly when not yet set as a thread local.

  Returns:

  The session for the client of this request or a new, unbound

  findOrCreate

  public static Session findOrCreate(Request request,
                                     Response response)

  Parameters:

  response -

  request -

  Returns:

  The Session that is found in the current request or created if not.

  get

  public static Session get()

  Get the session for the calling thread.

  Returns:

  Session for calling thread

  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. Also triggers attach() being called.

  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.

  bind

  public final void bind()

  Force binding this session to the application's session store if not already done so.

  A Wicket application can operate in a session-less mode as long as stateless pages are used. Session objects will be then created for each request, but they will only live for that request. You can recognize temporary sessions by calling isTemporary() which basically checks whether the session's id is null. Hence, temporary sessions have no session id.

  By calling this method, the session will be bound (made not-temporary) if it was not bound yet. It is useful for cases where you want to be absolutely sure this session object will be available in next requests. If the session was already bound ( returns a session), this call will be a noop.

  cleanupFeedbackMessages

  public abstract void cleanupFeedbackMessages()

  Cleans up all rendered feedback messages and any unrendered, dangling feedback messages there may be left after that.

  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).

  createAutoPageMap

  public final IPageMap createAutoPageMap()

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

  Returns:

  Created PageMap

  currentCreateAutoPageMapCounter

  protected int currentCreateAutoPageMapCounter()

  incrementCreateAutoPageMapCounter

  protected void incrementCreateAutoPageMapCounter()

  createAutoPageMapName

  public final 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

  getAutoPageMapNamePrefix

  protected String getAutoPageMapNamePrefix()

  Returns:

  The prefixed string default "wicket-".

  getAutoPageMapNameSuffix

  protected String getAutoPageMapNameSuffix()

  Returns:

  The suffix default an empty string.

  error

  public final void error(String message)

  Registers an error feedback message for this session

  Parameters:

  message - The feedback message

  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 IPageMap getDefaultPageMap()

  Returns:

  The default page map

  getFeedbackMessages

  public final FeedbackMessages getFeedbackMessages()

  Gets feedback messages stored in session

  Returns:

  unmodifiable list of feedback messages

  getId

  public final String getId()

  Gets the unique id for this session from the underlying SessionStore. May be null if a concrete session is not yet created.

  Returns:

  The unique id for this session or null if it is a temporary session

  getLocale

  public Locale getLocale()

  Get this session's locale.

  Returns:

  This session's locale

  getMetaData

  public final <M extends Serializable> M getMetaData(MetaDataKey<M> key)

  Gets metadata for this session using the given key.

  Type Parameters:

  M - The type of the metadata.

  Parameters:

  key - The key for the data

  Returns:

  The metadata

  See Also:

  MetaDataKey

  isCurrentRequestValid

  protected boolean isCurrentRequestValid(RequestCycle lockedRequestCycle)

  When a regular request on certain page with certain version is being processed, we don't allow ajax requests to same page and version.

  Parameters:

  lockedRequestCycle -

  Returns:

  whether current request is valid or should be discarded

  getPage

  public final Page getPage(int pageId,
                            int versionNumber)

  THIS METHOD IS NOT PART OF THE WICKET PUBLIC API. DO NOT CALL IT. Returns the page with given id and versionNumber. It keeps asking pageMaps for given page until it finds one that contains it.

  Parameters:

  pageId -

  versionNumber -

  Returns:

  The page of that pageid and version, null if not found

  getPage

  public final Page getPage(String pageMapName,
                            String componentPath,
                            int versionNumber)

  THIS METHOD IS NOT PART OF THE WICKET PUBLIC API. DO NOT CALL IT. Get the page for the given path. FIXME javadoc - where does it look? where does it get the page from?

  Parameters:

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

  componentPath - 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

  getPageMaps

  public final List<IPageMap> 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 String getStyle()

  Get the style (see Session).

  Returns:

  Returns the style (see Session)

  info

  public final void info(String message)

  Registers an informational feedback message for this session

  Parameters:

  message - The feedback message

  invalidate

  public void invalidate()

  Invalidates this session at the end of the current request. If you need to invalidate the session immediately, you can do this by calling invalidateNow(), however this will remove all Wicket components from this session, which means that you will no longer be able to work with them.

  invalidateNow

  public void invalidateNow()

  Invalidates this session immediately. Calling this method will remove all Wicket components from this session, which means that you will no longer be able to work with them.

  replaceSession

  public void replaceSession()

  Replaces the underlying (Web)Session, invalidating the current one and creating a new one. By calling ISessionStore.invalidate(Request) and bind()

  Call upon login to protect against session fixation.

  See Also:

  "http://www.owasp.org/index.php/Session_Fixation"

  isSessionInvalidated

  public final boolean isSessionInvalidated()

  Whether the session is invalid now, or will be invalidated by the end of the request. Clients should rarely need to use this method if ever.

  Returns:

  Whether the session is invalid when the current request is done

  See Also:

  invalidate(), invalidateNow()

  isTemporary

  public final boolean isTemporary()

  Whether this session is temporary. A Wicket application can operate in a session-less mode as long as stateless pages are used. If this session object is temporary, it will not be available on a next request.

  Returns:

  Whether this session is temporary (which is the same as it's id being null)

  newPageMap

  public final IPageMap newPageMap(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

  pageMapForName

  public final IPageMap pageMapForName(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

  removePageMap

  public final void removePageMap(IPageMap 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 overridden.

  Parameters:

  clientInfo - the client info object

  setLocale

  public void setLocale(Locale locale)

  Set the locale for this session.

  Parameters:

  locale - New locale

  setMetaData

  public final void setMetaData(MetaDataKey<?> key,
                                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:

  IllegalArgumentException

  See Also:

  MetaDataKey

  setStyle

  public final Session setStyle(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 -

  untouch

  public final void untouch(Page page)

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

  This method will remove a page that was previously added via touch()

  Parameters:

  page -

  visitPageMaps

  public final void visitPageMaps(Session.IPageMapVisitor visitor)

  Parameters:

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

  warn

  public final void warn(String message)

  Registers a warning feedback message for this session

  Parameters:

  message - The feedback message

  attach

  @Deprecated
  protected void attach()

  Deprecated. will not be available in 1.5+

  Any attach logic for session subclasses. Called when a session is set for the thread.

  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

  public final void dirty()

  Marks session state as dirty so that it will be flushed at the end of the request.

  getAttribute

  protected final Object getAttribute(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 List<String> getAttributeNames()

  Returns:

  List of attributes for this session

  getSessionStore

  protected ISessionStore getSessionStore()

  Gets the session store.

  Returns:

  the session store

  removeAttribute

  protected final void removeAttribute(String name)

  Removes the attribute with the given name.

  Parameters:

  name - the name of the attribute to remove

  setAttribute

  protected final void setAttribute(String name,
                                    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

  @Deprecated
  protected final void update()

  Deprecated. obsolete method (was meant for internal book keeping really). Clients should override detach() instead.

  NOT TO BE CALLED BY FRAMEWORK USERS.

  nextPageId

  protected int nextPageId()

  Returns:

  the next page id

  nextSequenceValue

  public int nextSequenceValue()

  Retrieves the next available session-unique value

  Returns:

  session-unique value