org.apache.beehive.netui.pageflow
Class PageFlowController

Object
  extended by PageFlowManagedObject
      extended by FlowController
          extended by PageFlowController
All Implemented Interfaces:
Serializable, EventListener, HttpSessionBindingListener, ActionResolver, InternalConstants, PageFlowConstants

public abstract class PageFlowController
extends FlowController
implements InternalConstants

Base class for controller logic, exception handlers, and state associated with a particular web directory path. The class is configured through the @Jpf.Controller annotation.

When a page flow request (the page flow URI itself, or any ".do" or page URI in the directory path), arrives, an instance of the associated PageFlowController class is set as the current page flow, and remains stored in the session until a different one becomes active ("long lived" page flows stay in the session indefinitely; see longLived on @Jpf.Controller).

The page flow class handles actions that are most commonly raised by user interaction with pages. The actions are handled by action methods or action annotations that determine the next URI to be displayed, after optionally performing arbitrary logic.

If the PageFlowController is a "nested page flow" (nested is set to true on @Jpf.Controller), then this is a reusable, modular flow that can be "nested" during other flows. It has entry points (actions with optional form bean arguments), and exit points (@Jpf.Forward, @Jpf.SimpleAction, or @Jpf.ConditionalForward annotations that have returnAction attributes).

The page flow class also handles exceptions thrown by actions or during page execution (see catches on @Jpf.Controller). Unhandled exceptions are handled in order by declared SharedFlowControllers (see sharedFlowRefs on @Jpf.Controller).

Properties in the current page flow instance can be accessed from JSP 2.0-style expressions like this one: ${pageFlow.someProperty}.

There may only be one page flow in any package.

See Also:
SharedFlowController, Serialized Form

Field Summary
 
Fields inherited from class FlowController
defaultLocale
 
Fields inherited from interface InternalConstants
ACTION_EXTENSION_LEN, ACTION_OVERRIDE_PREFIX, ANNOTATION_QUALIFIER, ATTR_PREFIX, BACKING_CLASS_IMPLICIT_OBJECT, BEGIN_ACTION_PATH, CURRENT_JPF_ATTR, CURRENT_LONGLIVED_ATTR, FACES_BACKING_ATTR, FACES_BACKING_EXTENSION, FACES_EXTENSION, FACES_EXTENSION_DOT, GLOBALAPP_CLASSNAME, GLOBALAPP_MEMBER_NAME, GLOBALAPP_MODULE_CONTEXT_PATH, INTERNAL_VAR_PREFIX, JSF_EXTENSION, JSF_EXTENSION_DOT, MESSAGE_IS_EXPRESSION_PREFIX, MESSAGE_IS_EXPRESSION_PREFIX_LENGTH, NETUI_CONFIG_PATH, RETURN_ACTION_VIEW_RENDERER_PARAM, RETURNING_FORM_ATTR, RETURNING_FROM_NESTING_ATTR, SHARED_FLOW_ATTR_PREFIX, SHARED_FLOW_EXTENSION, SHARED_FLOW_MODULE_PREFIX, SHARED_FLOW_MODULE_PREFIX_LEN, SHARED_FLOW_ROOT_MODULE, WEBINF_DIR
 
Fields inherited from interface PageFlowConstants
ACTION_EXTENSION, ACTION_OVERRIDE, AUTO_VIEW_RENDER_FORWARD_NAME, BEGIN_ACTION_NAME, DEFAULT_FORWARD_OVERFLOW_COUNT, DEFAULT_NESTING_OVERFLOW_COUNT, DEFAULT_VIEW_RENDERING_EXTENSION, FORWARD_OVERFLOW_COUNT_PARAM, GLOBALAPP_CLASSNAME, GLOBALAPP_SOURCEFILE_NAME, JPF_EXTENSION, JPF_MODULE_CONFIG_EXTENSION, JPF_MODULE_CONFIG_GEN_DIR, JPF_MODULE_CONFIG_PREFIX, NESTING_OVERFLOW_COUNT_PARAM, PAGEFLOW_EXTENSION, PAGEFLOW_MODULE_CONFIG_EXTENSION, PAGEFLOW_MODULE_CONFIG_GEN_DIR, PAGEFLOW_MODULE_CONFIG_PREFIX, SECURE_FORWARDS_PARAM, VIEW_RENDERER_ATTRIBUTE_NAME, VIEW_RENDERER_URI_COMMAND, VIEW_RENDERING_EXTENSION_PARAM
 
Constructor Summary
protected PageFlowController()
          Default constructor.
 
Method Summary
 void create(HttpServletRequest request, HttpServletResponse response, ServletContext servletContext)
          This is a framework method for initializing a newly-created page flow, and should not normally be called directly.
 void ensureFailover(HttpServletRequest request)
           Ensure that any changes to this object will be replicated in a cluster (for failover), even if the replication scheme uses a change-detection algorithm that relies on HttpSession.setAttribute(String, Object) to be aware of changes.
 ActionForward exitNesting(HttpServletRequest request, HttpServletResponse response, ActionMapping mapping, ActionForm form)
           
 String getCurrentForwardPath()
          Get the webapp-relative URI for the most recent page (in this page flow) shown to the user.
protected  PreviousPageInfo getCurrentPageInfo()
          Get information about the most recent page (in this page flow) shown to the user.
 String getDisplayName()
          Get the display name of this page flow.
 String getModulePath()
          Get the Struts module path for this page flow.
protected  PreviousActionInfo getPreviousActionInfo()
          Get information about the most recent action run in this page flow.
protected  String getPreviousActionURI()
          Get the URI for the most recent action in this PageFlowController.
protected  ActionForm getPreviousForm()
          Deprecated. This method may return an ActionForm wrapper when the form bean type does not extend ActionForm. Use getPreviousFormBean() instead.
protected  Object getPreviousFormBean()
          Get the submitted form bean from the most recent action execution in this PageFlowController.
protected  String getPreviousForwardPath()
          Get the webapp-relative URI for the previous page (in this page flow) shown to the user.
protected  PreviousPageInfo getPreviousPageInfo()
          Get information about the previous page (in this page flow) shown to the user.
 PreviousPageInfo getPreviousPageInfoLegacy(PageFlowController curJpf, HttpServletRequest request)
          Deprecated. This method will be removed without replacement in the next release.
 SharedFlowController getSharedFlow(String sharedFlowName)
          Get a shared flow, based on its name as defined in this page flow's sharedFlowRefs attribute on @Jpf.Controller.
protected  Map getSharedFlows()
          Get the a map of shared flow name to shared flow instance.
protected  String getTaxonomy()
          Get the "resource taxonomy": a period-separated list that starts with the current web application name, continues through all of this PageFlowController's parent directories, and ends with this PageFlowController's class name.
 String getURI()
          Get the URI for addressing this PageFlowController.
protected  ActionForward internalExecute(ActionMapping mapping, ActionForm form, HttpServletRequest request, HttpServletResponse response)
          Internal method used to execute an action on a FlowController.
protected  boolean isLongLived()
          Tell whether this is a "long lived" page flow.
protected  boolean isNestable()
          Tell whether this PageFlowController can be "nested", i.e., if it can be invoked from another page flow with the intention of returning to the original one.
 boolean isPageFlow()
          Tell whether this is a PageFlowController.
 boolean isPreviousActionInfoDisabled()
           
 boolean isPreviousPageInfoDisabled()
           
protected  void onExitNesting()
          Callback that is invoked when this controller instance is exiting nesting through a return action.
 void persistInSession(HttpServletRequest request, HttpServletResponse response)
          Store this object in the user session, in the appropriate place.
 void removeFromSession(HttpServletRequest request)
          Remove this instance from the session.
 void removeSharedFlow(String sharedFlowName)
          Remove a shared flow from the session, based on its name as defined in this page flow's sharedFlowRefs attribute on @Jpf.Controller.
 void savePreviousPageInfo(ActionForward forward, ActionForm form, ActionMapping mapping, HttpServletRequest request, ServletContext servletContext, boolean isSpecialForward)
          Store information about recent pages displayed.
 PreviousPageInfo theCurrentPageInfo()
          This is a non-property public accessor that will return the property value currrentPageInfo.
 PreviousActionInfo thePreviousActionInfo()
          This is a non-property public accessor that will return the property value previousActionInfo.
 PreviousPageInfo thePreviousPageInfo()
          This is a non-property public accessor that will return the property value previousPageInfo.
 Map theSharedFlows()
          This is a non-property public accessor that will return the property value sharedFlows.
 void valueUnbound(HttpSessionBindingEvent event)
          Callback when this object is removed from the user session.
 
Methods inherited from class FlowController
addActionError, addActionErrorExpression, addValidationError, addValidationError, afterAction, alwaysTrackPreviousAction, alwaysTrackPreviousPage, beforeAction, execute, generateToken, generateToken, getActionMapping, getActionMethod, getActions, getActionURI, getCurrentActionName, getDataSource, getDataSource, getDefaultLocale, getFormBean, getLocale, getLocale, getMapping, getMessageResources, getMessageResources, getModuleConfig, getModuleConfig, getRequest, getResources, getResources, getResources, getResponse, getRewrittenActionURI, getServlet, getSession, getUserPrincipal, handleException, invokeActionMethod, invokeExceptionHandler, isAction, isCancelled, isTokenValid, isTokenValid, isTokenValid, isTokenValid, isUserInRole, login, logout, lookup, lookup, onCreate, onDestroy, onDestroy, onRefresh, refresh, reinitialize, remove, resetToken, resetToken, resolveAction, resolveAction, retrieveUserLocale, saveActionErrors, saveErrors, saveMessages, saveToken, sendError, sendError, setLocale, setLocale, theModuleConfig
 
Methods inherited from class PageFlowManagedObject
fieldIsUninitialized, getCreateTime, getServletContext, initializeField, valueBound
 
Methods inherited from class Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

PageFlowController

protected PageFlowController()
Default constructor.

Method Detail

getModulePath

public String getModulePath()
Get the Struts module path for this page flow.

Specified by:
getModulePath in interface ActionResolver
Specified by:
getModulePath in class FlowController
Returns:
a String that is the Struts module path for this controller, and which is also the directory path from the web application root to this PageFlowController (not including the action filename).

getURI

public String getURI()
Get the URI for addressing this PageFlowController.

Specified by:
getURI in interface ActionResolver
Returns:
a String that is the URI which will execute the begin action on this PageFlowController.

isNestable

protected boolean isNestable()
Tell whether this PageFlowController can be "nested", i.e., if it can be invoked from another page flow with the intention of returning to the original one. Page flows are declared to be nested by specifying nested=true on the @Jpf.Controller annotation.

Returns:
true if this PageFlowController can be nested.

isLongLived

protected boolean isLongLived()
Tell whether this is a "long lived" page flow. Once it is invoked, a long lived page flow is never removed from the session unless FlowController.remove() is called. Navigating to another page flow hides the current long lived controller, but does not remove it.


removeFromSession

public void removeFromSession(HttpServletRequest request)
Remove this instance from the session. When inside a page flow action, FlowController.remove() may be called instead. This method is synchronized in order to maintain single threaded semantics for the Page Flow's FlowController.onDestroy(javax.servlet.http.HttpSession) lifecycle method.

Specified by:
removeFromSession in class PageFlowManagedObject

isPageFlow

public boolean isPageFlow()
Tell whether this is a PageFlowController.

Specified by:
isPageFlow in interface ActionResolver
Overrides:
isPageFlow in class FlowController
Returns:
true.

persistInSession

public void persistInSession(HttpServletRequest request,
                             HttpServletResponse response)
Store this object in the user session, in the appropriate place. Used by the framework; normally should not be called directly.

Specified by:
persistInSession in class PageFlowManagedObject

ensureFailover

public void ensureFailover(HttpServletRequest request)

Ensure that any changes to this object will be replicated in a cluster (for failover), even if the replication scheme uses a change-detection algorithm that relies on HttpSession.setAttribute(String, Object) to be aware of changes. This method is used by the framework and should not be called directly in most cases.

Note, this method ultimately causes the Page Flow to be persisted in the StorageHandler for this web application.

Specified by:
ensureFailover in class PageFlowManagedObject
Parameters:
request - the current HttpServletRequest

internalExecute

protected ActionForward internalExecute(ActionMapping mapping,
                                        ActionForm form,
                                        HttpServletRequest request,
                                        HttpServletResponse response)
                                 throws Exception
Description copied from class: FlowController
Internal method used to execute an action on a FlowController. This is where the magic generally happens as the FlowController.beforeAction(), login, action execution (simple and normal), and FlowController.afterAction() are all executed by this method. This method is considered internal and should not be invoked direclty.

Overrides:
internalExecute in class FlowController
Throws:
Exception

getSharedFlows

protected Map getSharedFlows()
Get the a map of shared flow name to shared flow instance.

Returns:
a Map of shared flow name (string) to shared flow instance (SharedFlowController).

theSharedFlows

public final Map theSharedFlows()
This is a non-property public accessor that will return the property value sharedFlows. This is a non-property method because properties are exposed to databinding and that would expose internal data structures to attack.

Returns:
a Map of shared flow name (string) to shared flow instance (SharedFlowController).

getSharedFlow

public SharedFlowController getSharedFlow(String sharedFlowName)
Get a shared flow, based on its name as defined in this page flow's sharedFlowRefs attribute on @Jpf.Controller. To retrieve any shared flow based on its class name, use PageFlowUtils.getSharedFlow(java.lang.String, javax.servlet.http.HttpServletRequest).

Parameters:
sharedFlowName - the name of the shared flow, as in this page flows's sharedFlowRefs attribute on the @Jpf.Controller annotation.
Returns:
the SharedFlowController with the given name.

removeSharedFlow

public void removeSharedFlow(String sharedFlowName)
Remove a shared flow from the session, based on its name as defined in this page flow's sharedFlowRefs attribute on @Jpf.Controller. To remove any shared flow based on its class name, use PageFlowUtils.removeSharedFlow(java.lang.String, javax.servlet.http.HttpServletRequest).

Parameters:
sharedFlowName - the name of the shared flow, as in this page flows's sharedFlowRefs attribute on the @Jpf.Controller annotation.

create

public final void create(HttpServletRequest request,
                         HttpServletResponse response,
                         ServletContext servletContext)
This is a framework method for initializing a newly-created page flow, and should not normally be called directly.

Overrides:
create in class FlowController

getTaxonomy

protected String getTaxonomy()
Get the "resource taxonomy": a period-separated list that starts with the current web application name, continues through all of this PageFlowController's parent directories, and ends with this PageFlowController's class name.


getPreviousForm

protected ActionForm getPreviousForm()
Deprecated. This method may return an ActionForm wrapper when the form bean type does not extend ActionForm. Use getPreviousFormBean() instead.

Get the submitted form bean from the most recent action execution in this PageFlowController.

Note: if the current page flow does not contain a @Jpf.Forward or a @Jpf.SimpleAction with navigateTo=Jpf.NavigateTo.previousAction, then this method will always return null by default. To enable it in this situation, add the following method to the page flow:

protected boolean alwaysTrackPreviousAction()
{
    return true;
}

Returns:
the ActionForm instance from the most recent action execution, or null if there was no form bean submitted.
See Also:
getPreviousPageInfo(), getCurrentPageInfo(), getPreviousActionInfo(), getPreviousActionURI(), getPreviousForwardPath(), getCurrentForwardPath()

getPreviousFormBean

protected Object getPreviousFormBean()
Get the submitted form bean from the most recent action execution in this PageFlowController.

Note: if the current page flow does not contain a @Jpf.Forward or a @Jpf.SimpleAction with navigateTo=Jpf.NavigateTo.previousAction, then this method will always return null by default. To enable it in this situation, add the following method to the page flow:

protected boolean alwaysTrackPreviousAction()
{
    return true;
}

Returns:
the form bean instance from the most recent action execution, or null if there was no form bean submitted.
See Also:
getPreviousPageInfo(), getCurrentPageInfo(), getPreviousActionInfo(), getPreviousActionURI(), getPreviousForwardPath(), getCurrentForwardPath()

getPreviousActionURI

protected String getPreviousActionURI()
Get the URI for the most recent action in this PageFlowController.

Note: if the current page flow does not use a @Jpf.Forward, @Jpf.SimpleAction, or @Jpf.ConditionalForward with navigateTo=previousAction, then this method will always return null by default. To enable it in this situation, add the following method to the page flow:

protected boolean alwaysTrackPreviousAction()
{
    return true;
}

Returns:
a String that is the most recent URI.
See Also:
getPreviousPageInfo(), getCurrentPageInfo(), getPreviousActionInfo(), getPreviousFormBean(), getPreviousForwardPath(), getCurrentForwardPath()

getCurrentForwardPath

public String getCurrentForwardPath()
Get the webapp-relative URI for the most recent page (in this page flow) shown to the user.

Note: if the current page flow does not use a @Jpf.Forward, @Jpf.SimpleAction, or @Jpf.ConditionalForward with navigateTo=currentPage or navigateTo=previousPage, then this method will always return null by default. To enable it in this situation, add the following method to the page flow:

protected boolean alwaysTrackPreviousPage()
{
    return true;
}

Returns:
a String that is the URI path for the most recent page shown to the user.
See Also:
getPreviousPageInfo(), getCurrentPageInfo(), getPreviousActionInfo(), getPreviousActionURI(), getPreviousFormBean(), getPreviousForwardPath()

getPreviousForwardPath

protected String getPreviousForwardPath()
Get the webapp-relative URI for the previous page (in this page flow) shown to the user. The previous page is the one shown before the most recent page.

Note: if the current page flow does not use a @Jpf.Forward, @Jpf.SimpleAction, or @Jpf.ConditionalForward with navigateTo=currentPage or navigateTo=previousPage, then this method will always return null by default. To enable it in this situation, add the following method to the page flow:

protected boolean alwaysTrackPreviousPage()
{
    return true;
}

Returns:
a String that is the URI path for the previous page shown to the user.
See Also:
getPreviousPageInfo(), getCurrentPageInfo(), getPreviousActionInfo(), getPreviousActionURI(), getPreviousFormBean(), getCurrentForwardPath()

getPreviousPageInfoLegacy

public final PreviousPageInfo getPreviousPageInfoLegacy(PageFlowController curJpf,
                                                        HttpServletRequest request)
Deprecated. This method will be removed without replacement in the next release.

Get a legacy PreviousPageInfo.

Specified by:
getPreviousPageInfoLegacy in class FlowController

getCurrentPageInfo

protected final PreviousPageInfo getCurrentPageInfo()
Get information about the most recent page (in this page flow) shown to the user.

Note: if the current page flow does not use a @Jpf.Forward, @Jpf.SimpleAction, or @Jpf.ConditionalForward with navigateTo=currentPage or navigateTo=previousPage, then this method will always return null by default. To enable it in this situation, add the following method to the page flow:

protected boolean alwaysTrackPreviousPage()
{
    return true;
}

Returns:
a PreviousPageInfo with information about the most recent page shown to the user.
See Also:
getPreviousPageInfo(), getPreviousActionInfo(), getPreviousActionURI(), getPreviousFormBean(), getPreviousForwardPath(), getCurrentForwardPath()

theCurrentPageInfo

public final PreviousPageInfo theCurrentPageInfo()
This is a non-property public accessor that will return the property value currrentPageInfo. This is a non-property method because properties are exposed to databinding and that would expose internal data structures to attack.

Returns:
a PreviousPageInfo with information about the most recent page shown to the user.

getPreviousPageInfo

protected final PreviousPageInfo getPreviousPageInfo()
Get information about the previous page (in this page flow) shown to the user. The previous page is the one shown before the most recent page.

Note: if the current page flow does not use a @Jpf.Forward, @Jpf.SimpleAction, or @Jpf.ConditionalForward with navigateTo=currentPage or navigateTo=previousPage, then this method will always return null by default. To enable it in this situation, add the following method to the page flow:

Returns:
a PreviousPageInfo with information about the previous page shown to the user.
See Also:
getCurrentPageInfo(), getPreviousActionInfo(), getPreviousActionURI(), getPreviousFormBean(), getPreviousForwardPath(), getCurrentForwardPath()

thePreviousPageInfo

public final PreviousPageInfo thePreviousPageInfo()
This is a non-property public accessor that will return the property value previousPageInfo. This is a non-property method because properties are exposed to databinding and that would expose internal data structures to attack.

Returns:
a PreviousPageInfo with information about the previous page shown to the user.

getPreviousActionInfo

protected final PreviousActionInfo getPreviousActionInfo()
Get information about the most recent action run in this page flow.

Note: if the current page flow does not use a @Jpf.Forward, @Jpf.SimpleAction, or @Jpf.ConditionalForward with navigateTo=previousAction, then this method will always return null by default. To enable it in this situation, add the following method to the page flow:

protected boolean alwaysTrackPreviousAction()
{
    return true;
}

Returns:
a PreviousActionInfo with information about the most recent action run in this page flow.
See Also:
getPreviousPageInfo(), getCurrentPageInfo(), getPreviousActionURI(), getPreviousFormBean(), getPreviousForwardPath(), getCurrentForwardPath()

thePreviousActionInfo

public final PreviousActionInfo thePreviousActionInfo()
This is a non-property public accessor that will return the property value previousActionInfo. This is a non-property method because properties are exposed to databinding and that would expose internal data structures to attack.

Returns:
a PreviousActionInfo with information about the most recent action run in this page flow.

getDisplayName

public String getDisplayName()
Get the display name of this page flow.

Specified by:
getDisplayName in class PageFlowManagedObject
Returns:
the display name (the URI) of this page flow.

isPreviousActionInfoDisabled

public boolean isPreviousActionInfoDisabled()

isPreviousPageInfoDisabled

public boolean isPreviousPageInfoDisabled()

savePreviousPageInfo

public void savePreviousPageInfo(ActionForward forward,
                                 ActionForm form,
                                 ActionMapping mapping,
                                 HttpServletRequest request,
                                 ServletContext servletContext,
                                 boolean isSpecialForward)
Store information about recent pages displayed. This is a framework-invoked method that should not normally be called directly.

Overrides:
savePreviousPageInfo in class FlowController

valueUnbound

public void valueUnbound(HttpSessionBindingEvent event)
Callback when this object is removed from the user session. Causes FlowController.onDestroy() to be called. This is a framework-invoked method that should not be called directly.

Specified by:
valueUnbound in interface HttpSessionBindingListener
Overrides:
valueUnbound in class PageFlowManagedObject

exitNesting

public ActionForward exitNesting(HttpServletRequest request,
                                 HttpServletResponse response,
                                 ActionMapping mapping,
                                 ActionForm form)

onExitNesting

protected void onExitNesting()
                      throws Exception
Callback that is invoked when this controller instance is exiting nesting through a return action. FlowController.getRequest(), FlowController.getResponse(), FlowController.getSession() may all be used during this method.

Throws:
Exception