Package org.apache.wicket

Class Session

  • All Implemented Interfaces:
    java.io.Serializable, IEventSink, IFeedbackContributor, IMetadataContext<java.io.Serializable,​Session>, org.apache.wicket.util.io.IClusterable
    Direct Known Subclasses:
    WebSession
    public abstract class Session
extends java.lang.Object
implements org.apache.wicket.util.io.IClusterable, IEventSink, IMetadataContext<java.io.Serializable,​Session>, IFeedbackContributor
    Holds information about a user session, including some fixed number of most recent pages (and all their nested component information).
    • Access - the Session can be retrieved either by Component.getSession() or by directly calling the static method Session.get(). All classes which extend directly or indirectly WebMarkupContainer can also use its convenience method WebMarkupContainer.getWebSession()
    • 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 clear(), 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

    • Constructor Summary

      Constructors 
      Constructor Description
      Session​(org.apache.wicket.request.Request request)
      Constructor.

    • Method Summary

      All Methods Static Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and Type Method Description
      void bind()
      Force binding this session to the application's session store if not already done so.
      void changeSessionId()
      Change the id of the underlying (Web)Session if this last one is permanent.
      void clear()
      Removes all pages from the session.
      void debug​(java.io.Serializable message)
      Registers an debug feedback message for this session
      void detach()
      Any detach logic for session subclasses.
      void dirty()
      Marks session state as dirty so that it will be (re)stored in the ISessionStore at the end of the request.
      void dirty​(boolean forced)
      Marks session state as dirty so that it will be re-stored in the ISessionStore at the end of the request.
      void error​(java.io.Serializable message)
      Registers an error feedback message for this session
      static boolean exists()
      Checks existence of a Session associated with the current thread.
      void fatal​(java.io.Serializable message)
      Registers an fatal feedback message for this session
      protected abstract java.lang.String generateNewSessionId()
      Change the id of the underlying (Web)Session.
      static Session get()
      Returns session associated to current thread.
      Application getApplication()
      Get the application that is currently working with this session.
      java.io.Serializable getAttribute​(java.lang.String name)
      Gets the attribute value with the given name
      java.util.List<java.lang.String> getAttributeNames()  
      IAuthorizationStrategy getAuthorizationStrategy()  
      IClassResolver getClassResolver()  
      abstract ClientInfo getClientInfo()
      Gets the client info object for this session.
      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.
      <M extends java.io.Serializable>
      M      		 getMetaData​(MetaDataKey<M> key)
      Gets metadata for this session using the given key.
      IPageFactory getPageFactory()  
      IPageManager getPageManager()
      Returns the IPageManager instance.
      protected ISessionStore getSessionStore()
      Gets the session store.
      long getSizeInBytes()  
      java.lang.String getStyle()
      Get the style (see Session).
      void info​(java.io.Serializable message)
      Registers an informational feedback message for this session
      void internalDetach()
      NOT PART OF PUBLIC API, DO NOT CALL Detaches internal state of Session
      void invalidate()
      Invalidates this session at the end of the current request.
      void invalidateNow()
      Invalidates this session immediately.
      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.
      protected PageAccessSynchronizer newPageAccessSynchronizer​(org.apache.wicket.util.time.Duration timeout)
      Factory method for PageAccessSynchronizer instances
      int nextPageId()  
      int nextSequenceValue()
      Retrieves the next available session-unique value
      void onEvent​(IEvent<?> event)
      Called when an event is sent to this sink
      void onInvalidate()
      A callback method that is executed when the user session is invalidated either by explicit call to invalidate() or due to HttpSession expiration.
      void removeAttribute​(java.lang.String name)
      Removes the attribute with the given name.
      void replaceSession()
      Replaces the underlying (Web)Session, invalidating the current one and creating a new one.
      Session setAttribute​(java.lang.String name, java.io.Serializable value)
      Adds or replaces the attribute with the given name and value.
      Session setClientInfo​(ClientInfo clientInfo)
      THIS METHOD IS NOT PART OF THE WICKET PUBLIC API.
      Session setLocale​(java.util.Locale locale)
      Set the locale for this session.
      <M extends java.io.Serializable>
      Session      		 setMetaData​(MetaDataKey<M> key, M object)
      Sets the metadata for this session using the given key.
      Session setStyle​(java.lang.String style)
      Set the style (see Session).
      void success​(java.io.Serializable message)
      Registers an success feedback message for this session
      void warn​(java.io.Serializable 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

      • clientInfo

        protected ClientInfo clientInfo
        Cached instance of agent info which is typically designated by calling getClientInfo().

    • Constructor Detail

      • Session

        public Session​(org.apache.wicket.request.Request request)
        Constructor. Note that RequestCycle is not available until this constructor returns.
        Parameters:
        request - The current request

    • Method Detail

      • exists

        public static boolean exists()
        Checks existence of a Session associated with the current thread.
        Returns:
        true if get() can return the instance of session, false otherwise

      • get

        public static Session get()
        Returns session associated to current thread. Always returns a session during a request cycle, even though the session might be temporary
        Returns:
        session.

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

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

      • error

        public final void error​(java.io.Serializable message)
        Registers an error feedback message for this session
        Specified by:
        error in interface IFeedbackContributor
        Parameters:
        message - The feedback message

      • fatal

        public final void fatal​(java.io.Serializable message)
        Registers an fatal feedback message for this session
        Specified by:
        fatal in interface IFeedbackContributor
        Parameters:
        message - The feedback message

      • debug

        public final void debug​(java.io.Serializable message)
        Registers an debug feedback message for this session
        Specified by:
        debug in interface IFeedbackContributor
        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 abstract 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.
        Returns:
        the client info object based on this request

      • getFeedbackMessages

        public final FeedbackMessages getFeedbackMessages()
        Gets feedback messages stored in session
        Returns:
        unmodifiable list of feedback messages

      • getId

        public final java.lang.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 java.util.Locale getLocale()
        Get this session's locale.
        Returns:
        This session's locale

      • getMetaData

        public final <M extends java.io.Serializable> M getMetaData​(MetaDataKey<M> key)
        Gets metadata for this session using the given key.
        Specified by:
        getMetaData in interface IMetadataContext<java.io.Serializable,​Session>
        Type Parameters:
        M - The type of the metadata.
        Parameters:
        key - The key for the data
        Returns:
        The metadata
        See Also:
        MetaDataKey

      • getPageFactory

        public IPageFactory getPageFactory()
        Returns:
        The page factory for this session

      • getSizeInBytes

        public final long getSizeInBytes()
        Returns:
        Size of this session

      • getStyle

        public final java.lang.String getStyle()
        Get the style (see Session).
        Returns:
        Returns the style (see Session)

      • info

        public final void info​(java.io.Serializable message)
        Registers an informational feedback message for this session
        Specified by:
        info in interface IFeedbackContributor
        Parameters:
        message - The feedback message

      • success

        public final void success​(java.io.Serializable message)
        Registers an success feedback message for this session
        Specified by:
        success in interface IFeedbackContributor
        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() If you are looking for a mean against session fixation attack, consider to use changeSessionId().

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

      • setClientInfo

        public final Session 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 Session setLocale​(java.util.Locale locale)
        Set the locale for this session.
        Parameters:
        locale - New locale

      • setMetaData

        public final <M extends java.io.Serializable> Session setMetaData​(MetaDataKey<M> key,
                                                                  M 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.
        Specified by:
        setMetaData in interface IMetadataContext<java.io.Serializable,​Session>
        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

      • warn

        public final void warn​(java.io.Serializable message)
        Registers a warning feedback message for this session
        Specified by:
        warn in interface IFeedbackContributor
        Parameters:
        message - The feedback message

      • detach

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

      • internalDetach

        public void internalDetach()
        NOT PART OF PUBLIC API, DO NOT CALL Detaches internal state of Session

      • dirty

        public final void dirty()
        Marks session state as dirty so that it will be (re)stored in the ISessionStore at the end of the request. Note: binds the session if it is temporary

      • dirty

        public final void dirty​(boolean forced)
        Marks session state as dirty so that it will be re-stored in the ISessionStore at the end of the request.
        Parameters:
        forced - A flag indicating whether the session should be marked as dirty even when it is temporary. If true the Session will be bound.

      • getAttribute

        public final java.io.Serializable 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

        public final java.util.List<java.lang.String> getAttributeNames()
        Returns:
        List of attributes for this session

      • getSessionStore

        protected ISessionStore getSessionStore()
        Gets the session store.
        Returns:
        the session store

      • removeAttribute

        public final void removeAttribute​(java.lang.String name)
        Removes the attribute with the given name.
        Parameters:
        name - the name of the attribute to remove

      • setAttribute

        public final Session setAttribute​(java.lang.String name,
                                  java.io.Serializable 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

      • nextSequenceValue

        public int nextSequenceValue()
        Retrieves the next available session-unique value
        Returns:
        session-unique value

      • nextPageId

        public int nextPageId()
        Returns:
        the next page id

      • onEvent

        public void onEvent​(IEvent<?> event)
        Called when an event is sent to this sink
        Specified by:
        onEvent in interface IEventSink

      • onInvalidate

        public void onInvalidate()
        A callback method that is executed when the user session is invalidated either by explicit call to invalidate() or due to HttpSession expiration.

        In case of session expiration this method is called in a non-worker thread, i.e. there are no thread locals exported for the Application, RequestCycle and Session. The Session is the current instance. The Application can be found by using Application.get(String). There is no way to get a reference to a RequestCycle

      • changeSessionId

        public void changeSessionId()
        Change the id of the underlying (Web)Session if this last one is permanent.

        Call upon login to protect against session fixation.

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

      • generateNewSessionId

        protected abstract java.lang.String generateNewSessionId()
        Change the id of the underlying (Web)Session.
        Returns:
        the new session id value.

      • newPageAccessSynchronizer

        protected PageAccessSynchronizer newPageAccessSynchronizer​(org.apache.wicket.util.time.Duration timeout)
        Factory method for PageAccessSynchronizer instances
        Parameters:
        timeout - The configured timeout. See RequestCycleSettings.getTimeout()
        Returns:
        A new instance of PageAccessSynchronizer