org.apache.wiki
Class WikiSession

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

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

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:

• AUTHENTICATED
• ASSERTED
• ANONYMOUS

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