com.ecyrd.jspwiki
Class WikiSession

java.lang.Object
  extended by com.ecyrd.jspwiki.WikiSession
All Implemented Interfaces:
WikiEventListener

public 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.

Version:
$Revision: 2.21 $ $Date: 2006/06/17 23:09:03 $
Author:
Andrew R. Jaquith

Field Summary
protected static String ALL
           
static String ANONYMOUS
           
static String ASSERTED
           
static String AUTHENTICATED
           
protected static int DOT
           
protected static org.apache.log4j.Logger log
           
protected  String m_cachedCookieIdentity
           
protected  String m_cachedRemoteUser
           
protected  Principal m_cachedUserPrincipal
           
protected static int NINE
           
protected static int ONE
           
 
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.
 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.
 String getStatus()
          Returns the status of the session as a text string.
 Subject getSubject()
          Returns the Subject representing the user.
 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()
          Factory method that creates a new "guest" session containing a single user Principal,
 void invalidate()
          Invalidates the WikiSession and resets its Subject's Principal set to the equivalent of a "guest session".
 boolean isAnonymous()
          Determines whether the current session is anonymous.
 boolean isAuthenticated()
          Returns the authentication status of the user's session.
protected  boolean isContainerStatusChanged(javax.servlet.http.HttpServletRequest request)
          Returns whether the Http servlet container's authentication status has changed.
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 IP address.
protected  boolean isNew()
          Returns true if the wiki session is newly initialized.
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.
protected  void setNew(boolean isNew)
          Sets the status of this wiki session.
 void setSubject(Subject subject)
          Sets the Subject representing the user.
static Principal[] userPrincipals(WikiEngine engine)
          Returns Principals representing the current users known to the 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
See Also:
Constant Field Values

ASSERTED

public static final String ASSERTED
See Also:
Constant Field Values

AUTHENTICATED

public static final String AUTHENTICATED
See Also:
Constant Field Values

m_cachedCookieIdentity

protected String m_cachedCookieIdentity

m_cachedRemoteUser

protected String m_cachedRemoteUser

m_cachedUserPrincipal

protected Principal m_cachedUserPrincipal

ONE

protected static int ONE

NINE

protected static int NINE

DOT

protected static int DOT

log

protected static org.apache.log4j.Logger log

ALL

protected static final String ALL
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.

Parameters:
group - the group to test
Returns:
the result

isNew

protected boolean isNew()
Returns true if the wiki session is newly initialized.


setNew

protected void setNew(boolean isNew)
Sets the status of this wiki session.

Parameters:
isNew - whether this session should be considered "new".

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;

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.

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 FULL_NAME or (alternatively) WIKI_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

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 messsages.

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).

Returns:
the current messsages.

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

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 current wiki engine
request - the users's HTTP request

setSubject

public void setSubject(Subject subject)
Sets the Subject representing the user.

Parameters:
subject -

getSubject

public Subject getSubject()
Returns the Subject representing the user.

Returns:
the subject

actionPerformed

public void actionPerformed(WikiEvent event)
Listens for WikiEvents generated by source objects such as the GroupManager.

Specified by:
actionPerformed in interface WikiEventListener
Parameters:
event - the event
See Also:
WikiEventListener.actionPerformed(com.ecyrd.jspwiki.event.WikiEvent)

invalidate

public void invalidate()
Invalidates the WikiSession and resets its Subject's Principal set to the equivalent of a "guest session".


isContainerStatusChanged

protected boolean isContainerStatusChanged(javax.servlet.http.HttpServletRequest request)
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.

Parameters:
request - the current servlet request
Returns:
true if the status has changed, false otherwise

getStatus

public String getStatus()

Returns the status of the session as a text string. Valid values are:

Returns:
the 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()is returned.

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

guestSession

public static WikiSession guestSession()
Factory method that creates a new "guest" session containing a single user Principal,

Returns:
the guest wiki session

sessions

public static int sessions(WikiEngine engine)
Returns the total number of active wiki sessions.

Parameters:
engine - the current wiki session
Returns:
the number of sessions

userPrincipals

public static Principal[] userPrincipals(WikiEngine engine)
Returns Principals representing the current users known to the wiki. Each Principal will correspond to the value returned by each WikiSession's getUserPrincipal() method.

Parameters:
engine - the wiki engine
Returns:
an array of Principal objects

isIPV4Address

protected static boolean isIPV4Address(String name)
Verifies whether a String represents an IP address. The algorithm is extremely efficient and does not allocate any objects.

Parameters:
name - the address to test
Returns:
the result