net.sourceforge.stripes.controller
Class FlashScope

java.lang.Object
  extended by java.util.AbstractMap<K,V>
      extended by java.util.HashMap<String,Object>
          extended by net.sourceforge.stripes.controller.FlashScope
All Implemented Interfaces:
Serializable, Cloneable, Map<String,Object>

public class FlashScope
extends HashMap<String,Object>
implements Serializable

A FlashScope is an object that can be used to store objects and make them available as request parameters during this request cycle and the next one. It is extremely useful when implementing the redirect-after-post pattern in which an ActionBean receives a POST, does some processing and then redirects to a JSP to display the outcome. FlashScopes make temporary use of session to store themselves briefly between two requests.

In general, use of the FlashScope should be intermediated by the ActionBeanContext, making it transparent to the rest of the application. Any object that is put into a FlashScope will be immediately exposed in the current request as a request attribute, and under certain conditions will also be exposed in the subsequent request as a request attribute.

To make values available to the subsequent request a parameter must be included in the redirect URL that identifies the flash scope to use (this avoids collisions where two concurrent requests in the same session might otherwise cause problems for one another). The Stripes RedirectResolution will automatically insert this parameter into the URL when a flash scope is present. Should you wish to issue redirects using a different mechanism you will need to add the parameter using code similar to the following:

FlashScope flash = FlashScope.getCurrent(request, false);
if (flash != null) {
    url.addParameter(StripesConstants.URL_KEY_FLASH_SCOPE_ID, flash.key());
}

The lifecycle of a FlashScope is managed is conjunction with the StripesFilter. FlashScopes are manufactured using lazy instantiation when FlashScope.getCurrent(request, true) is called. When a request is completed, the StripesFilter notifies the current FlashScope that the request is over, which causes it to record the time when the request terminated. On the subsequent request, if the flash scope is referenced by a URL parameter, then it is removed from session and it's contents are pushed into request attributes for the current request.

To ensure that orphaned FlashScopes do not consume increasing amounts of HttpSession memory, the StripesFilter, after each request, checks to see if any FlashScopes have recently expired. A FlashScope is expired when the length of time from the end of the request that created the FlashScope is greater than the timeout set on the FlashScope. The default timeout is 120 seconds (or two minutes), and can be varied by calling setTimeout(int) Since the timer starts when a request completes, and FlashScopes are only meant to live from the end of one request to the beginning of a subsequent request this value is set quite low.

Since:
Stripes 1.2
Author:
Tim Fennell
See Also:
Serialized Form

Nested Class Summary
 
Nested classes/interfaces inherited from class java.util.AbstractMap
AbstractMap.SimpleEntry<K,V>, AbstractMap.SimpleImmutableEntry<K,V>
 
Field Summary
static int DEFAULT_TIMEOUT_IN_SECONDS
          The default timeout for a flash scope.
 
Constructor Summary
protected FlashScope(HttpServletRequest request, Integer key)
          Protected constructor to prevent random creation of FlashScopes.
 
Method Summary
 long age()
          Returns the time in seconds since the request that generated this flash scope completed.
 void beginRequest(HttpServletRequest request)
           Called by StripesFilter to copy all the attributes from this flash scope to the given request.
 void completeRequest()
          Used by the StripesFilter to notify the flash scope that the request for which it is used has been completed.
static Collection<FlashScope> getAllFlashScopes(HttpServletRequest req)
          Gets the collection of all flash scopes present in the current session.
static FlashScope getCurrent(HttpServletRequest req, boolean create)
           Gets the current flash scope into which items can be stored temporarily.
static FlashScope getPrevious(HttpServletRequest req)
          Fetch the flash scope that was populated during the previous request, if one exists.
protected  Semaphore getSemaphore()
          Get the semaphore that is used to synchronize the calls to completeRequest() and beginRequest(HttpServletRequest) made by StripesFilter.
 int getTimeout()
          Returns the timeout in seconds after which the flash scope will be discarded.
 boolean isExpired()
          Returns true if the flash scope has expired and should be dereferenced to allow garbage collection.
 Integer key()
          Returns the key used to store this flash scope in the collection of flash scopes.
 void put(ActionBean bean)
          Stores an ActionBean into the flash scope.
 Object put(String name, Object value)
          Stores the provided value both in the flash scope a under the specified name, and in a request attribute with the specified name.
 void requestComplete()
          Deprecated. 
 void setTimeout(int timeout)
          Sets the timeout in seconds after which the flash scope will be discarded.
 
Methods inherited from class java.util.HashMap
clear, clone, containsKey, containsValue, entrySet, get, isEmpty, keySet, putAll, remove, size, values
 
Methods inherited from class java.util.AbstractMap
equals, hashCode, toString
 
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface java.util.Map
equals, hashCode
 

Field Detail

DEFAULT_TIMEOUT_IN_SECONDS

public static final int DEFAULT_TIMEOUT_IN_SECONDS
The default timeout for a flash scope.

See Also:
Constant Field Values
Constructor Detail

FlashScope

protected FlashScope(HttpServletRequest request,
                     Integer key)
Protected constructor to prevent random creation of FlashScopes. Uses the request to generate a key under which the flash scope will be stored, and can be identified by later.

Parameters:
request - the request for which this flash scope will be used.
key - the key by which this flash scope can be looked up in the map
Method Detail

getTimeout

public int getTimeout()
Returns the timeout in seconds after which the flash scope will be discarded.


setTimeout

public void setTimeout(int timeout)
Sets the timeout in seconds after which the flash scope will be discarded.


key

public Integer key()
Returns the key used to store this flash scope in the collection of flash scopes.


getSemaphore

protected Semaphore getSemaphore()
Get the semaphore that is used to synchronize the calls to completeRequest() and beginRequest(HttpServletRequest) made by StripesFilter.


requestComplete

@Deprecated
public void requestComplete()
Deprecated. 

Renamed to completeRequest().


completeRequest

public void completeRequest()

Used by the StripesFilter to notify the flash scope that the request for which it is used has been completed. The FlashScope uses this notification to start a timer, and also to null out it's reference to the request so that it can be garbage collected.

The timer is used to determine if a flash scope has been orphaned (i.e. the subsequent request was not made) after a period of time, so that it can be removed from session.


beginRequest

public void beginRequest(HttpServletRequest request)

Called by StripesFilter to copy all the attributes from this flash scope to the given request. beginRequest(HttpServletRequest) must never be called before completeRequest() is called. Since the two methods are normally called by different threads, synchronization of the calls is accomplished through use of a Semaphore.

Parameters:
request - The request to copy the flash scope attributes to

age

public long age()
Returns the time in seconds since the request that generated this flash scope completed. Will return 0 if this flash scope has not yet started to age.


isExpired

public boolean isExpired()
Returns true if the flash scope has expired and should be dereferenced to allow garbage collection. Returns false if the flash scope should be retained.

Returns:
true if the flash scope has expired, false otherwise

put

public Object put(String name,
                  Object value)
Stores the provided value both in the flash scope a under the specified name, and in a request attribute with the specified name. Allows flash scope attributes to be accessed seamlessly as request attributes during both the current request and the subsequent request.

Specified by:
put in interface Map<String,Object>
Overrides:
put in class HashMap<String,Object>
Parameters:
name - the name of the attribute to add to flash scope
value - the value to be added
Returns:
the previous object stored with the same name (possibly null)

put

public void put(ActionBean bean)
Stores an ActionBean into the flash scope. Additional checking is performed to see if the ActionBean is the currently resolved (main) ActionBean for the request. The result is that on the next request the ActionBean will appear in the request as if it was created on that request.

Parameters:
bean - an ActionBean that should be present in the next request

getAllFlashScopes

public static Collection<FlashScope> getAllFlashScopes(HttpServletRequest req)
Gets the collection of all flash scopes present in the current session.

Parameters:
req - the current request, needed to get access to the session
Returns:
a collection of flash scopes. Will return an empty collection if there are no flash scopes present.

getPrevious

public static FlashScope getPrevious(HttpServletRequest req)

Fetch the flash scope that was populated during the previous request, if one exists. This is only really intended for use by the StripesFilter and things which extend it, in order to grab a flash scope for a previous request and empty it's contents into request attributes.

NOTE: calling this method has the side-affect of removing the flash scope from the set of managed flash scopes!

Parameters:
req - the current request
Returns:
a FlashScope if one exists with the key provided.

getCurrent

public static FlashScope getCurrent(HttpServletRequest req,
                                    boolean create)

Gets the current flash scope into which items can be stored temporarily. If create is true, then a new one will be created.

It is assumed that the request object will be used by only one thread so access to the request is not synchronized. Access to the scopes map that is stored in the session and the static Random that is used to generate the keys for the map is synchronized.

Parameters:
req - the current request
create - if true then the FlashScope will be created when it does not exist already
Returns:
the current FlashScope, or null if it does not exist and create is false


? Copyright 2005-2006, Stripes Development Team.