| java.lang.Object
 com.ecyrd.jspwiki.WikiSession
| WikiSession | | final public class WikiSession implements WikiEventListener(Code) | | 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:
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
com.ecyrd.jspwiki.event.WikiEventListener interface and listens for group add/change/delete events fired by
event sources the WikiSession is registered with. Normally,
com.ecyrd.jspwiki.auth.AuthenticationManager registers each WikiSession
with the
com.ecyrd.jspwiki.auth.authorize.GroupManager so it can catch group events. Thus, when a user is added to a
com.ecyrd.jspwiki.auth.authorize.Group , a corresponding
com.ecyrd.jspwiki.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 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.
author:
Andrew R. Jaquith |
| Method Summary | |
| final public void | actionPerformed(WikiEvent event)
Listens for WikiEvents generated by source objects such as the
GroupManager. | | final public void | addMessage(String message)
Adds a message to the generic list of messages associated with the
session. | | final public void | addMessage(String topic, String message)
Adds a message to the specific set of messages associated with the
session. | | final public void | clearMessages()
Clears all messages associated with this session. | | final public void | clearMessages(String topic)
Clears all messages associated with a session topic. | | final public static Object | doPrivileged(WikiSession session, PrivilegedAction action)
Wrapper for
javax.security.auth.Subject.doAsPrivileged(Subjectjava.security.PrivilegedExceptionActionjava.security.AccessControlContext) that executes an action with the privileges posssessed by a
WikiSession's Subject. | | final public Locale | getLocale()
Returns a cached Locale object for this user. | | final public LoginContext | getLoginContext(String application, CallbackHandler handler)
Creates and returns a new login context for this wiki session. | | final public Principal | getLoginPrincipal()
Returns the Principal used to log in to an authenticated session. | | final public String[] | getMessages()
Returns all generic messages associated with this session. | | final public String[] | getMessages(String topic)
Returns all messages associated with a session topic. | | final public Principal[] | getPrincipals()
Returns all user Principals associated with this session. | | final public Principal[] | getRoles()
Returns an array of Principal objects that represents the groups and
roles that the user associated with a WikiSession possesses. | | final public String | getStatus()
Returns the status of the wiki session as a text string. | | final public Principal | getUserPrincipal()
Returns the primary user Principal associated with this session. | | final public static WikiSession | getWikiSession(WikiEngine engine, HttpServletRequest request)
Static factory method that returns the WikiSession object associated with
the current HTTP request. | | final public static WikiSession | guestSession(WikiEngine engine)
Static factory method that creates a new "guest" session containing a single
user Principal
com.ecyrd.jspwiki.auth.WikiPrincipal.GUEST ,
plus the role principals
Role.ALL and
Role.ANONYMOUS . | | final public boolean | hasPrincipal(Principal principal)
Returns true if the WikiSession's Subject
possess a supplied Principal. | | final protected void | injectRolePrincipals()
Injects GroupPrincipal and Role objects into the user's Principal set
based on the groups and roles the user belongs to.
For Roles, the algorithm first calls the
Authorizer.getRoles to obtain the array of
Principals the authorizer knows about. | | final 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. | | final public void | invalidate()
Invalidates the WikiSession and resets its Subject's
Principals to the equivalent of a "guest session". | | final public boolean | isAnonymous()
Determines whether the current session is anonymous. | | final public boolean | isAsserted()
Returns true if the user is considered asserted via
a session cookie; that is, the Subject contains the Principal
Role.ASSERTED. | | final public boolean | isAuthenticated()
Returns the authentication status of the user's session. | | final protected boolean | isContainerStatusChanged(HttpServletRequest request)
Returns whether the HTTP servlet container's authentication status has
changed. | | final protected static boolean | isIPV4Address(String name)
Verifies whether a String represents an IPv4 address. | | final 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. | | final protected boolean | isNew()
Returns true if the wiki session is newly initialized. | | final public static void | removeWikiSession(WikiEngine engine, 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. | | final public static int | sessions(WikiEngine engine)
Returns the total number of active wiki sessions for a
particular wiki. | | final protected void | setNew(boolean isNew)
Sets the status of this wiki session. | | final protected void | updatePrincipals()
Updates the internally cached principals returned by
WikiSession.getUserPrincipal() and
WikiSession.getLoginPrincipal() . | | final public static Principal[] | userPrincipals(WikiEngine engine)
Returns Principals representing the current users known
to a particular wiki. |
| ANONYMOUS | | final public static String ANONYMOUS(Code) | | An anonymous user's session status.
|
| ASSERTED | | final public static String ASSERTED(Code) | | An asserted user's session status.
|
| AUTHENTICATED | | final public static String AUTHENTICATED(Code) | | An authenticated user's session status.
|
| addMessage | | final public void addMessage(String message)(Code) | | Adds a message to the generic list of messages associated with the
session. These messages retain their order of insertion and remain until
the
WikiSession.clearMessages() method is called.
Parameters:
message - the message to add; if null it is ignored. |
| addMessage | | final public void addMessage(String topic, String message)(Code) | | Adds a message to the specific set of messages associated with the
session. These messages retain their order of insertion and remain until
the
WikiSession.clearMessages() method is called.
Parameters:
topic - the topic to associate the message to;
Parameters:
message - the message to add |
| clearMessages | | final public void clearMessages()(Code) | | Clears all messages associated with this session.
|
| clearMessages | | final public void clearMessages(String topic)(Code) | | Clears all messages associated with a session topic.
Parameters:
topic - the topic whose messages should be cleared. |
| getLocale | | final public Locale getLocale()(Code) | | 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.
A cached Locale object
since:
2.5.96 |
| getLoginPrincipal | | final public Principal getLoginPrincipal()(Code) | | 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
com.ecyrd.jspwiki.auth.WikiPrincipal.GUEST .
the login Principal. If it is a PrincipalWrapper containing anexternally-provided Principal, the object returned is the Principal, notthe wrapper around it. |
| getMessages | | final public String[] getMessages()(Code) | | Returns all generic messages associated with this session.
The messages stored with the session persist throughout the
session unless they have been reset with
WikiSession.clearMessages() .
the current messsages. |
| getMessages | | final public String[] getMessages(String topic)(Code) | | Returns all messages associated with a session topic.
The messages stored with the session persist throughout the
session unless they have been reset with
WikiSession.clearMessages(String) .
the current messsages.
Parameters:
topic - The topic |
| getRoles | | final public Principal[] getRoles()(Code) | | 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.
an array of Principal objects corresponding to the roles theSubject possesses |
| getStatus | | final public String getStatus()(Code) | | Returns the status of the wiki session as a text string. Valid values are:
the user's session status |
| getUserPrincipal | | final public Principal getUserPrincipal()(Code) | | Returns the primary user Principal associated with this session. The
primary user principal is determined as follows: - If the
Subject's Principal set contains WikiPrincipals, the first WikiPrincipal
with type designator
WIKI_NAME or (alternatively)
FULL_NAME is the primary Principal.
- 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
com.ecyrd.jspwiki.auth.WikiPrincipal.GUEST .
the primary user Principal |
| getWikiSession | | final public static WikiSession getWikiSession(WikiEngine engine, HttpServletRequest request)(Code) | | 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
WikiSession.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
Parameters:
request - the servlet request object the existing (or newly created) wiki session |
| hasPrincipal | | final public boolean hasPrincipal(Principal principal)(Code) | | 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 the result |
| injectRolePrincipals | | final protected void injectRolePrincipals()(Code) | | Injects GroupPrincipal and Role objects into the user's Principal set
based on the groups and roles the user belongs to.
For Roles, the algorithm first calls the
Authorizer.getRoles to obtain the array of
Principals the authorizer knows about. Then, the method
Authorizer.isUserInRole(WikiSessionPrincipal) is
called for each Principal. If the user possesses the role,
an equivalent role Principal is injected into the user's
principal set.
Reloads user Principals into the suppplied WikiSession's Subject.
Existing Role principals are preserved; all other Principal
types are flushed and replaced by those returned by
com.ecyrd.jspwiki.auth.user.UserDatabase.getPrincipals(String) .
This method should generally be called after a user's
com.ecyrd.jspwiki.auth.user.UserProfile is saved. If the wiki session is null, or there is no matching user profile, the
method returns silently.
|
| injectUserProfilePrincipals | | final protected void injectUserProfilePrincipals()(Code) | | 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.
|
| invalidate | | final public void invalidate()(Code) | | Invalidates the WikiSession and resets its Subject's
Principals to the equivalent of a "guest session".
|
| isAnonymous | | final public boolean isAnonymous()(Code) | | 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.
whether the current user's identity is equivalent to an IPaddress |
| isAsserted | | final public boolean isAsserted()(Code) | | Returns true if the user is considered asserted via
a session cookie; that is, the Subject contains the Principal
Role.ASSERTED.
Returns true if the user is asserted |
| isAuthenticated | | final public boolean isAuthenticated()(Code) | | 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 true if the user is authenticated |
| isContainerStatusChanged | | final protected boolean isContainerStatusChanged(HttpServletRequest request)(Code) | | Returns whether the HTTP servlet container's authentication status has
changed. Used to detect whether the container has logged in a user since
the last call to this function. This method is stateful. After calling
this function, the cached values are set to those in the current request.
If the servlet request is null, this method always returns
false. Note that once a user authenticates, the container
status for the session will never change again, unless the
session is invalidated by timeout or logout.
Parameters:
request - the servlet request true if the status has changed, falseotherwise |
| isIPV4Address | | final protected static boolean isIPV4Address(String name)(Code) | | 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 the result |
| isInGroup | | final protected boolean isInGroup(Group group)(Code) | | 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 the result |
| isNew | | final protected boolean isNew()(Code) | | Returns true if the wiki session is newly initialized.
True, if this is a new session. |
| removeWikiSession | | final public static void removeWikiSession(WikiEngine engine, HttpServletRequest request)(Code) | | 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
Parameters:
request - the users's HTTP request |
| sessions | | final public static int sessions(WikiEngine engine)(Code) | | 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 the number of sessions |
| setNew | | final protected void setNew(boolean isNew)(Code) | | Sets the status of this wiki session.
Parameters:
isNew - whether this session should be considered "new". |
|
|