WikiSession (Apache JSPWiki 2.11.0.M6 API)

java.lang.Object
- org.apache.wiki.WikiSession

All Implemented Interfaces:

EventListener, WikiEventListener
```
public final class WikiSession
extends Object
implements WikiEventListener
```
Represents a long-running wiki session, with an associated user Principal, user Subject, and authentication status. This class is initialized with minimal, default-deny values: authentication is set to false, and the user principal is set to null.

The WikiSession class allows callers to:
- Obtain the authentication status of the user via isAnonymous() and isAuthenticated()
- Query the session for Principals representing the user's identity via getLoginPrincipal(), getUserPrincipal() and getPrincipals()
- Store, retrieve and clear UI messages via addMessage(String), getMessages(String) and clearMessages(String)
To keep track of the Principals each user posseses, each WikiSession stores a JAAS Subject. Various login processes add or remove Principals when users authenticate or log out.

WikiSession implements the WikiEventListener interface and listens for group add/change/delete events fired by event sources the WikiSession is registered with. Normally, AuthenticationManager registers each WikiSession with the GroupManager so it can catch group events. Thus, when a user is added to a Group, a corresponding GroupPrincipal is injected into the Subject's Principal set. Likewise, when the user is removed from the Group or the Group is deleted, the GroupPrincipal is removed from the Subject. The effect that this strategy produces is extremely beneficial: when someone adds a user to a wiki group, that user immediately gains the privileges associated with that group; he or she does not need to re-authenticate.

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.

WikiSession encloses a protected static class, SessionMonitor, to keep track of WikiSessions registered with each wiki.

Field Summary

Fields
Modifier and Type	Field and Description
`static String`	`ANONYMOUS` An anonymous user's session status.
`static String`	`ASSERTED` An asserted user's session status.
`static String`	`AUTHENTICATED` An authenticated user's session status.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`actionPerformed(WikiEvent event)` Listens for WikiEvents generated by source objects such as the GroupManager.
`void`	`addMessage(String message)` Adds a message to the generic list of messages associated with the session.
`void`	`addMessage(String topic, 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(String topic)` Clears all messages associated with a session topic.
`static Object`	`doPrivileged(WikiSession session, PrivilegedAction<?> action)` Wrapper for `Subject.doAsPrivileged(Subject, java.security.PrivilegedExceptionAction, java.security.AccessControlContext)` that executes an action with the privileges posssessed by a WikiSession's Subject.
`Locale`	`getLocale()` Returns a cached Locale object for this user.
`Principal`	`getLoginPrincipal()` Returns the Principal used to log in to an authenticated session.
`String[]`	`getMessages()` Returns all generic messages associated with this session.
`String[]`	`getMessages(String topic)` Returns all messages associated with a session topic.
`Principal[]`	`getPrincipals()` Returns all user Principals associated with this session.
`Principal[]`	`getRoles()` Returns an array of Principal objects that represents the groups and roles that the user associated with a WikiSession possesses.
`String`	`getStatus()` Returns the status of the wiki session as a text string.
`Principal`	`getUserPrincipal()` Returns the primary user Principal associated with this session.
`static WikiSession`	`getWikiSession(WikiEngine engine, javax.servlet.http.HttpServletRequest request)` Static factory method that returns the WikiSession object associated with the current HTTP request.
`static WikiSession`	`guestSession(WikiEngine 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(Principal principal)` Returns `true` if the WikiSession'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 WikiSession 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.
`protected static boolean`	`isIPV4Address(String name)` Verifies whether a String represents an IPv4 address.
`static void`	`removeWikiSession(WikiEngine 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(WikiEngine engine)` Returns the total number of active wiki sessions for a particular wiki.
`static Principal[]`	`userPrincipals(WikiEngine engine)` Returns Principals representing the current users known to a particular wiki.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - ANONYMOUS
```
public static final String ANONYMOUS
```
    An anonymous user's session status.
    
    See Also:
    
    Constant Field Values
  - ASSERTED
```
public static final String ASSERTED
```
    An asserted user's session status.
    
    See Also:
    
    Constant Field Values
  - AUTHENTICATED
```
public static final String AUTHENTICATED
```
    An authenticated user's session status.
    
    See Also:
    
    Constant Field Values
- 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.
    
    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.
    
    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 session's Principal set contains Role.ANONYMOUS
    - The session's Principal set contains WikiPrincipal.GUEST
    - The Principal returned by getUserPrincipal() evaluates to an IP address.
    The criteria above are listed in the order in which they are evaluated.
    Returns:
    
    whether the current user's identity is equivalent to an IP address
  - getLoginPrincipal
```
public 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.
    
    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 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.
    Returns:
    
    the primary user Principal
  - getLocale
```
public 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 WikiSession expires, and currently there is no way to reset the Locale.
    
    Returns:
    
    A cached Locale object
    
    Since:
    
    2.5.96
  - addMessage
```
public void addMessage(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 clearMessages() method is called.
    
    Parameters:
    
    message - the message to add; if null it is ignored.
  - addMessage
```
public void addMessage(String topic,
                       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 clearMessages() method is called.
    
    Parameters:
    
    topic - the topic to associate the message to;
    
    message - the message to add
  - clearMessages
```
public void clearMessages()
```
    Clears all messages associated with this session.
  - clearMessages
```
public void clearMessages(String topic)
```
    Clears all messages associated with a session topic.
    
    Parameters:
    
    topic - the topic whose messages should be cleared.
  - getMessages
```
public 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 clearMessages().
    
    Returns:
    
    the current messages.
  - getMessages
```
public String[] getMessages(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 clearMessages(String).
    
    Parameters:
    
    topic - The topic
    
    Returns:
    
    the current messages.
  - getPrincipals
```
public 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.
    
    Returns:
    
    Returns the user principal
    
    See Also:
    
    AuthenticationManager.isUserPrincipal(Principal)
  - getRoles
```
public Principal[] getRoles()
```
    Returns an array of Principal objects that represents the groups and roles that the user associated with a WikiSession 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.
    
    Returns:
    
    an array of Principal objects corresponding to the roles the Subject possesses
  - removeWikiSession
```
public static void removeWikiSession(WikiEngine 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 users's HTTP request
  - hasPrincipal
```
public boolean hasPrincipal(Principal principal)
```
    Returns true if the WikiSession's Subject possess a supplied Principal. This method eliminates the need to externally request and inspect the JAAS subject.
    
    Parameters:
    
    principal - the Principal to test
    
    Returns:
    
    the result
  - actionPerformed
```
public void actionPerformed(WikiEvent event)
```
    Listens for WikiEvents generated by source objects such as the GroupManager. This method adds Principals to the private Subject managed by the WikiSession.
    
    Specified by:
    
    actionPerformed in interface WikiEventListener
    
    Parameters:
    
    event - a WikiEvent object
    
    See Also:
    
    WikiEventListener.actionPerformed(org.apache.wiki.event.WikiEvent)
  - invalidate
```
public void invalidate()
```
    Invalidates the WikiSession and resets its Subject's Principals to the equivalent of a "guest 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 GroupManager.getRoles() to obtain the array of GroupPrincipals the authorizer knows about. Then, the method GroupManager.isUserInRole(WikiSession, 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.
  - getStatus
```
public String getStatus()
```
    Returns the status of the wiki session as a text string. Valid values are:
    Returns:
    
    the user's session status
  - getWikiSession
```
public static WikiSession getWikiSession(WikiEngine engine,
                                         javax.servlet.http.HttpServletRequest request)
```
    Static factory method that returns the WikiSession 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 WikiSession, although the authentication status is unpredictable until the user attempts to log in. If the servlet request parameter is null, a synthetic guestSession(WikiEngine)is returned.
    
    When a session is created, this method attaches a WikiEventListener to the GroupManager so that changes to groups are detected automatically.
    
    Parameters:
    
    engine - the wiki engine
    
    request - the servlet request object
    
    Returns:
    
    the existing (or newly created) wiki session
  - guestSession
```
public static WikiSession guestSession(WikiEngine 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
  - sessions
```
public static int sessions(WikiEngine engine)
```
    Returns the total number of active wiki sessions for a particular wiki. This method delegates to the wiki's SessionMonitor.sessions() method.
    
    Parameters:
    
    engine - the wiki session
    
    Returns:
    
    the number of sessions
  - userPrincipals
```
public static Principal[] userPrincipals(WikiEngine engine)
```
    Returns Principals representing the current users known to a particular wiki. Each Principal will correspond to the value returned by each WikiSession's getUserPrincipal() method. This method delegates to SessionMonitor.userPrincipals().
    
    Parameters:
    
    engine - the wiki engine
    
    Returns:
    
    an array of Principal objects, sorted by name
  - doPrivileged
```
public static Object doPrivileged(WikiSession session,
                                  PrivilegedAction<?> action)
                           throws AccessControlException
```
    Wrapper for Subject.doAsPrivileged(Subject, java.security.PrivilegedExceptionAction, java.security.AccessControlContext) that executes an action with the privileges posssessed by a WikiSession's Subject. The action executes with a null AccessControlContext, which has the effect of running it "cleanly" without the AccessControlContexts of the caller.
    
    Parameters:
    
    session - the wiki session
    
    action - the privileged action
    
    Returns:
    
    the result of the privileged action; may be null
    
    Throws:
    
    AccessControlException - if the action is not permitted by the security policy
  - isIPV4Address
```
protected static boolean isIPV4Address(String name)
```
    Verifies whether a String represents an IPv4 address. The algorithm is extremely efficient and does not allocate any objects.
    
    Parameters:
    
    name - the address to test
    
    Returns:
    
    the result

Class WikiSession

Field Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

ANONYMOUS

ASSERTED

AUTHENTICATED

Method Detail

isInGroup

isAsserted

isAuthenticated

isAnonymous

getLoginPrincipal

getUserPrincipal

getLocale

addMessage

addMessage

clearMessages

clearMessages

getMessages

getMessages

getPrincipals

getRoles

removeWikiSession

hasPrincipal

actionPerformed

invalidate

injectGroupPrincipals

injectUserProfilePrincipals

getStatus

getWikiSession

guestSession

sessions

userPrincipals

doPrivileged

isIPV4Address