Session (Apache JSPWiki public API 2.11.2 API)

All Superinterfaces:

java.util.EventListener, WikiEventListener
```
public interface Session
extends WikiEventListener
```
Represents a long-running wiki session, with an associated user Principal, user Subject, and authentication status. The sesion is initialized with minimal, default-deny values: authentication is set to false, and the user principal is set to null.

The Session 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 Session stores a JAAS Subject. Various login processes add or remove Principals when users authenticate or log out.

Session extends the WikiEventListener interface and listens for group add/change/delete events fired by event sources the Session is registered with: org.apache.wiki.auth.AuthenticationManager, org.apache.wiki.auth.UserManager and org.apache.wiki.auth.authorize.GroupManager, so it can catch group events. Thus, when a user is added to a org.apache.wiki.auth.authorize.Group, a corresponding org.apache.wiki.auth.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 Session objects, this class also contains a number of static methods for managing Sessions for an entire wiki. These methods allow callers to find, query and remove Session objects, and to obtain a list of the current wiki session users.

Field Summary

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

Method Summary

All Methods Static Methods Instance Methods Abstract Methods Default Methods
Modifier and Type	Method and Description
`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.
`static java.lang.Object`	`doPrivileged(Session session, java.security.PrivilegedAction<?> action)` Wrapper for `Subject.doAsPrivileged(Subject, PrivilegedAction, java.security.AccessControlContext)` that executes an action with the privileges posssessed by a Session's Subject.
`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.
`boolean`	`hasPrincipal(java.security.Principal principal)` Returns `true` if the Session's Subject possess a supplied Principal.
`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.

Methods inherited from interface org.apache.wiki.event.WikiEventListener
actionPerformed

- Field Detail
  - ANONYMOUS
```
static final java.lang.String ANONYMOUS
```
    An anonymous user's session status.
    
    See Also:
    
    Constant Field Values
  - ASSERTED
```
static final java.lang.String ASSERTED
```
    An asserted user's session status.
    
    See Also:
    
    Constant Field Values
  - AUTHENTICATED
```
static final java.lang.String AUTHENTICATED
```
    An authenticated user's session status.
    
    See Also:
    
    Constant Field Values
- Method Detail
  - isAsserted
```
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
```
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
```
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 org.apache.wiki.auth.authorize.Role#ANONYMOUS
    - The session's Principal set contains org.apache.wiki.auth.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
```
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 org.apache.wiki.auth.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
```
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 org.apache.wiki.auth.WikiPrincipal#GUEST.
    Returns:
    
    the primary user Principal
  - getLocale
```
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.
    
    Returns:
    
    A cached Locale object
    
    Since:
    
    2.5.96
  - addMessage
```
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 clearMessages() method is called.
    
    Parameters:
    
    message - the message to add; if null it is ignored.
  - addMessage
```
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 clearMessages() method is called.
    
    Parameters:
    
    topic - the topic to associate the message to;
    
    message - the message to add
  - clearMessages
```
void clearMessages()
```
    Clears all messages associated with this session.
  - clearMessages
```
void clearMessages(java.lang.String topic)
```
    Clears all messages associated with a session topic.
    
    Parameters:
    
    topic - the topic whose messages should be cleared.
  - getMessages
```
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 clearMessages().
    
    Returns:
    
    the current messages.
  - getMessages
```
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 clearMessages(String).
    
    Parameters:
    
    topic - The topic
    
    Returns:
    
    the current messages.
  - getPrincipals
```
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.
    
    Returns:
    
    Returns the user principal
    
    See Also:
    
    org.apache.wiki.auth.AuthenticationManager#isUserPrincipal(Principal)
  - getRoles
```
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.
    
    Returns:
    
    an array of Principal objects corresponding to the roles the Subject possesses
  - hasPrincipal
```
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.
    
    Parameters:
    
    principal - the Principal to test
    
    Returns:
    
    the result
  - invalidate
```
void invalidate()
```
    Invalidates the Session and resets its Subject's Principals to the equivalent of a "guest session".
  - getStatus
```
java.lang.String getStatus()
```
    Returns the status of the wiki session as a text string. Valid values are:
    Returns:
    
    the user's session status
  - getSubject
```
javax.security.auth.Subject getSubject()
```
    Returns the Subject associated to the session.
    
    Returns:
    
    Subject associated to the session.
  - doPrivileged
```
static java.lang.Object doPrivileged(Session session,
                                     java.security.PrivilegedAction<?> action)
                              throws java.security.AccessControlException
```
    Wrapper for Subject.doAsPrivileged(Subject, PrivilegedAction, java.security.AccessControlContext) that executes an action with the privileges posssessed by a Session'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:
    
    java.security.AccessControlException - if the action is not permitted by the security policy

Interface Session

Field Summary

Method Summary

Methods inherited from interface org.apache.wiki.event.WikiEventListener

Field Detail

ANONYMOUS

ASSERTED

AUTHENTICATED

Method Detail

isAsserted

isAuthenticated

isAnonymous

getLoginPrincipal

getUserPrincipal

getLocale

addMessage

addMessage

clearMessages

clearMessages

getMessages

getMessages

getPrincipals

getRoles

hasPrincipal

invalidate

getStatus

getSubject

doPrivileged