Package org.apache.wiki

Class WikiSession

  • All Implemented Interfaces:
    java.util.EventListener, Session, WikiEventListener
    public class WikiSession
extends java.lang.Object
implements Session

    Default implementation for Session.

    In addition to methods for examining individual WikiSession objects, this class also contains a number of static methods for managing WikiSessions for an entire wiki. These methods allow callers to find, query and remove WikiSession objects, and to obtain a list of the current wiki session users.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      void actionPerformed​(WikiEvent event)
      Listens for WikiEvents generated by source objects such as the GroupManager, UserManager or AuthenticationManager.
      void addMessage​(java.lang.String message)
      Adds a message to the generic list of messages associated with the session.
      void addMessage​(java.lang.String topic, java.lang.String message)
      Adds a message to the specific set of messages associated with the session.
      void clearMessages()
      Clears all messages associated with this session.
      void clearMessages​(java.lang.String topic)
      Clears all messages associated with a session topic.
      java.util.Locale getLocale()
      Returns a cached Locale object for this user.
      java.security.Principal getLoginPrincipal()
      Returns the Principal used to log in to an authenticated session.
      java.lang.String[] getMessages()
      Returns all generic messages associated with this session.
      java.lang.String[] getMessages​(java.lang.String topic)
      Returns all messages associated with a session topic.
      java.security.Principal[] getPrincipals()
      Returns all user Principals associated with this session.
      java.security.Principal[] getRoles()
      Returns an array of Principal objects that represents the groups and roles that the user associated with a Session possesses.
      java.lang.String getStatus()
      Returns the status of the wiki session as a text string.
      javax.security.auth.Subject getSubject()
      Returns the Subject associated to the session.
      java.security.Principal getUserPrincipal()
      Returns the primary user Principal associated with this session.
      static Session getWikiSession​(Engine engine, javax.servlet.http.HttpServletRequest request)
      Static factory method that returns the Session object associated with the current HTTP request.
      static Session guestSession​(Engine engine)
      Static factory method that creates a new "guest" session containing a single user Principal WikiPrincipal.GUEST, plus the role principals Role.ALL and Role.ANONYMOUS.
      boolean hasPrincipal​(java.security.Principal principal)
      Returns true if the Session's Subject possess a supplied Principal.
      protected void injectGroupPrincipals()
      Injects GroupPrincipal objects into the user's Principal set based on the groups the user belongs to.
      protected void injectUserProfilePrincipals()
      Adds Principal objects to the Subject that correspond to the logged-in user's profile attributes for the wiki name, full name and login name.
      void invalidate()
      Invalidates the Session and resets its Subject's Principals to the equivalent of a "guest session".
      boolean isAnonymous()
      Determines whether the current session is anonymous.
      boolean isAsserted()
      Returns true if the user is considered asserted via a session cookie; that is, the Subject contains the Principal Role.ASSERTED.
      boolean isAuthenticated()
      Returns the authentication status of the user's session.
      protected boolean isInGroup​(Group group)
      Returns true if one of this WikiSession's user Principals can be shown to belong to a particular wiki group.
      static void removeWikiSession​(Engine engine, javax.servlet.http.HttpServletRequest request)
      Removes the wiki session associated with the user's HTTP request from the cache of wiki sessions, typically as part of a logout process.
      static int sessions​(Engine engine)
      Deprecated.
      use SessionMonitor.sessions() instead
      static java.security.Principal[] userPrincipals​(Engine engine)
      Deprecated.
      use SessionMonitor.userPrincipals() instead

      • Methods inherited from class java.lang.Object

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

    • Method Detail

      • isInGroup

        protected boolean isInGroup​(Group group)
        Returns true if one of this WikiSession's user Principals can be shown to belong to a particular wiki group. If the user is not authenticated, this method will always return false.
        Parameters:
        group - the group to test
        Returns:
        the result

      • isAsserted

        public boolean isAsserted()
        Returns true if the user is considered asserted via a session cookie; that is, the Subject contains the Principal Role.ASSERTED.
        Specified by:
        isAsserted in interface Session
        Returns:
        Returns true if the user is asserted

      • isAuthenticated

        public boolean isAuthenticated()
        Returns the authentication status of the user's session. The user is considered authenticated if the Subject contains the Principal Role.AUTHENTICATED. If this method determines that an earlier LoginModule did not inject Role.AUTHENTICATED, it will inject one if the user is not anonymous and not asserted.
        Specified by:
        isAuthenticated in interface Session
        Returns:
        Returns true if the user is authenticated

      • isAnonymous

        public boolean isAnonymous()

        Determines whether the current session is anonymous. This will be true if any of these conditions are true:

        The criteria above are listed in the order in which they are evaluated.

        Specified by:
        isAnonymous in interface Session
        Returns:
        whether the current user's identity is equivalent to an IP address

      • getLoginPrincipal

        public java.security.Principal getLoginPrincipal()

        Returns the Principal used to log in to an authenticated session. The login principal is determined by examining the Subject's Principal set for PrincipalWrappers or WikiPrincipals with type designator LOGIN_NAME; the first one found is the login principal. If one is not found, this method returns the first principal that isn't of type Role or GroupPrincipal. If neither of these conditions hold, this method returns WikiPrincipal.GUEST.

        Specified by:
        getLoginPrincipal in interface Session
        Returns:
        the login Principal. If it is a PrincipalWrapper containing an externally-provided Principal, the object returned is the Principal, not the wrapper around it.

      • getUserPrincipal

        public java.security.Principal getUserPrincipal()

        Returns the primary user Principal associated with this session. The primary user principal is determined as follows:

        1. If the Subject's Principal set contains WikiPrincipals, the first WikiPrincipal with type designator WIKI_NAME or (alternatively) FULL_NAME is the primary Principal.
        2. For all other cases, the first Principal in the Subject's principal collection that that isn't of type Role or GroupPrincipal is the primary.
        If no primary user Principal is found, this method returns WikiPrincipal.GUEST.
        Specified by:
        getUserPrincipal in interface Session
        Returns:
        the primary user Principal

      • getLocale

        public java.util.Locale getLocale()
        Returns a cached Locale object for this user. It's better to use WikiContext's corresponding getBundle() method, since that will actually react if the user changes the locale in the middle, but if that's not available (or, for some reason, you need the speed), this method can also be used. The Locale expires when the Session expires, and currently there is no way to reset the Locale.
        Specified by:
        getLocale in interface Session
        Returns:
        A cached Locale object

      • addMessage

        public void addMessage​(java.lang.String message)
        Adds a message to the generic list of messages associated with the session. These messages retain their order of insertion and remain until the Session.clearMessages() method is called.
        Specified by:
        addMessage in interface Session
        Parameters:
        message - the message to add; if null it is ignored.

      • addMessage

        public void addMessage​(java.lang.String topic,
                       java.lang.String message)
        Adds a message to the specific set of messages associated with the session. These messages retain their order of insertion and remain until the Session.clearMessages() method is called.
        Specified by:
        addMessage in interface Session
        Parameters:
        topic - the topic to associate the message to;
        message - the message to add

      • clearMessages

        public void clearMessages​(java.lang.String topic)
        Clears all messages associated with a session topic.
        Specified by:
        clearMessages in interface Session
        Parameters:
        topic - the topic whose messages should be cleared.

      • getMessages

        public java.lang.String[] getMessages()
        Returns all generic messages associated with this session. The messages stored with the session persist throughout the session unless they have been reset with Session.clearMessages().
        Specified by:
        getMessages in interface Session
        Returns:
        the current messages.

      • getMessages

        public java.lang.String[] getMessages​(java.lang.String topic)
        Returns all messages associated with a session topic. The messages stored with the session persist throughout the session unless they have been reset with Session.clearMessages(String).
        Specified by:
        getMessages in interface Session
        Parameters:
        topic - The topic
        Returns:
        the current messages.

      • getPrincipals

        public java.security.Principal[] getPrincipals()
        Returns all user Principals associated with this session. User principals are those in the Subject's principal collection that aren't of type Role or of type GroupPrincipal. This is a defensive copy.
        Specified by:
        getPrincipals in interface Session
        Returns:
        Returns the user principal
        See Also:
        AuthenticationManager.isUserPrincipal(Principal)

      • getRoles

        public java.security.Principal[] getRoles()
        Returns an array of Principal objects that represents the groups and roles that the user associated with a Session possesses. The array is built by iterating through the Subject's Principal set and extracting all Role and GroupPrincipal objects into a list. The list is returned as an array sorted in the natural order implied by each Principal's getName method. Note that this method does not consult the external Authorizer or GroupManager; it relies on the Principals that have been injected into the user's Subject at login time, or after group creation/modification/deletion.
        Specified by:
        getRoles in interface Session
        Returns:
        an array of Principal objects corresponding to the roles the Subject possesses

      • hasPrincipal

        public boolean hasPrincipal​(java.security.Principal principal)
        Returns true if the Session's Subject possess a supplied Principal. This method eliminates the need to externally request and inspect the JAAS subject.
        Specified by:
        hasPrincipal in interface Session
        Parameters:
        principal - the Principal to test
        Returns:
        the result

      • invalidate

        public void invalidate()
        Invalidates the Session and resets its Subject's Principals to the equivalent of a "guest session".
        Specified by:
        invalidate in interface Session

      • injectGroupPrincipals

        protected void injectGroupPrincipals()
        Injects GroupPrincipal objects into the user's Principal set based on the groups the user belongs to. For Groups, the algorithm first calls the Authorizer.getRoles() to obtain the array of GroupPrincipals the authorizer knows about. Then, the method Authorizer.isUserInRole(Session, Principal) is called for each Principal. If the user is a member of the group, an equivalent GroupPrincipal is injected into the user's principal set. Existing GroupPrincipals are flushed and replaced. This method should generally be called after a user's UserProfile is saved. If the wiki session is null, or there is no matching user profile, the method returns silently.

      • injectUserProfilePrincipals

        protected void injectUserProfilePrincipals()
        Adds Principal objects to the Subject that correspond to the logged-in user's profile attributes for the wiki name, full name and login name. These Principals will be WikiPrincipals, and they will replace all other WikiPrincipals in the Subject. Note: this method is never called during anonymous or asserted sessions.

      • getSubject

        public javax.security.auth.Subject getSubject()
        Returns the Subject associated to the session.
        Specified by:
        getSubject in interface Session
        Returns:
        Subject associated to the session.

      • removeWikiSession

        public static void removeWikiSession​(Engine engine,
                                     javax.servlet.http.HttpServletRequest request)
        Removes the wiki session associated with the user's HTTP request from the cache of wiki sessions, typically as part of a logout process.
        Parameters:
        engine - the wiki engine
        request - the user's HTTP request

      • getWikiSession

        public static Session getWikiSession​(Engine engine,
                                     javax.servlet.http.HttpServletRequest request)

        Static factory method that returns the Session object associated with the current HTTP request. This method looks up the associated HttpSession in an internal WeakHashMap and attempts to retrieve the WikiSession. If not found, one is created. This method is guaranteed to always return a Session, although the authentication status is unpredictable until the user attempts to log in. If the servlet request parameter is null, a synthetic guestSession(Engine) is returned.

        When a session is created, this method attaches a WikiEventListener to the GroupManager, UserManager and AuthenticationManager, so that changes to users, groups, logins, etc. are detected automatically.

        Parameters:
        engine - the engine
        request - the servlet request object
        Returns:
        the existing (or newly created) session

      • guestSession

        public static Session guestSession​(Engine engine)
        Static factory method that creates a new "guest" session containing a single user Principal WikiPrincipal.GUEST, plus the role principals Role.ALL and Role.ANONYMOUS. This method also adds the session as a listener for GroupManager, AuthenticationManager and UserManager events.
        Parameters:
        engine - the wiki engine
        Returns:
        the guest wiki session