org.apache.beehive.netui.pageflow
Class Forward

Object
  extended by ForwardConfig
      extended by ActionForward
          extended by Forward
All Implemented Interfaces:
Serializable
Direct Known Subclasses:
InterceptorForward

public class Forward
extends ActionForward

An object of this type is returned from an action methods in a PageFlowController to determine the next URI to be displayed. It is constructed on the name of a forward defined by the @Jpf.Forward annotation, and resolves to the URI specified in that forward.

See Also:
Serialized Form

Field Summary
static int RETURN_TO_ACTION
          Deprecated. Use RETURN_TO_PREVIOUS_ACTION instead.
static int RETURN_TO_CURRENT_PAGE
           
static int RETURN_TO_NONE
           
static int RETURN_TO_PAGE
          Deprecated. Use RETURN_TO_CURRENT_PAGE or RETURN_TO_PREVIOUS_PAGE instead.
static int RETURN_TO_PREVIOUS_ACTION
           
static int RETURN_TO_PREVIOUS_PAGE
           
 
Fields inherited from class ForwardConfig
configured, contextRelative, module, name, path, redirect
 
Constructor Summary
protected Forward(ActionForward initFwd, ServletContext servletContext)
          Internal.
protected Forward(Forward init)
           
protected Forward(HttpServletRequest request)
           
  Forward(String forwardName)
          Constructor which accepts the name of a forward defined by the @Jpf.Forward annotation.
  Forward(String forwardName, Object outputFormBean)
          Constructor which accepts the name of a forward defined by the @Jpf.Forward annotation.
  Forward(String forwardName, String actionOutputName, Object actionOutputValue)
          Constructor which accepts the name of a forward defined by the @Jpf.Forward annotation.
  Forward(URI uri)
          Constructs a Forward that returns the given URI for getPath().
  Forward(URI uri, boolean doRedirect)
          Constructs a Forward that returns the given URI for getPath().
  Forward(URL url)
          Constructs a Forward that returns the given URL for getPath().
 
Method Summary
 void addActionOutput(String paramName, Object value)
          Adds an action output that will be made available in the request, through PageFlowUtils.getActionOutput(java.lang.String, javax.servlet.ServletRequest).
 void addOutputForm(Object formBean)
          Add a form bean that will be made available in the request (or user session, as appropriate) if this Forward is returned by an action method in a PageFlowController.
 void addPageInput(String paramName, Object value)
          Deprecated. Use addActionOutput(java.lang.String, java.lang.Object) instead.
 void addQueryParam(String paramName)
          Add a query parameter with no value to the URI returned by getPath().
 void addQueryParam(String paramName, String value)
          Add a query parameter to the URI returned by getPath().
 boolean doesResolve()
          Tell whether getPath() will be successful, i.e., whether one of the following two conditions is met: the name around which this object was constructed resolves to a path defined by a @Jpf.Forward, or this object was constructed around an explicit path, by Forward(URI) or Forward(URL).
 boolean doesRestoreQueryString()
          Tell whether this Forward will store the original query string on the page restored through Jpf.NavigateTo#previousAction.
protected  ActionForward findForward(String forwardName)
          Resolves the forward with the given name, from the stored ActionMapping if possible, or from the stored alternate ModuleConfig as a last resort.
 boolean forwardsToPageFlow()
          Tell whether the URI returned by getPath() is for a page flow.
 Map getActionOutputs()
          Get all action outputs that have been set on this Forward.
 ActionForm getFirstOutputForm(HttpServletRequest request)
          Get the first output form bean that was added to this Forward.
 ActionForm[] getOutputForms()
          Get all form-beans attached to this forward through addOutputForm(java.lang.Object) or Forward(String, Object).
 Map getPageInputs()
          Deprecated. Use getActionOutputs() instead.
 String getPath()
          Get the URI path associated with this object.
 String getQueryString()
          Get the query string that will be appended to the URI returned by getPath().
 int getReturnToType()
          Get the type of return, if this is a return-to type.
 String getReturnToTypeAsString()
          Get the type of return as a String, if this is a return-to type.
 boolean hasExplicitRedirectValue()
          Tell whether this Forward was configured explicitly (through Jpf.Forward.redirect(), setRedirect(boolean)), or Forward(URI, boolean)) to perform a redirect.
 void initialize(ActionMapping mapping, FlowController flowController)
          Deprecated. Use initialize(ActionMapping, FlowController, ServletRequest) instead.
 void initialize(ActionMapping mapping, FlowController flowController, ServletRequest request)
          Set the current ActionMapping and associated FlowController.
 boolean isExternalRedirect()
          Tell whether this is a redirect to a URI outside of the current web application.
 boolean isNestedReturn()
          Tell whether returning this forward from an action method will cause a return from a nested PageFlowController.
 boolean isRedirect()
          Tell whether the URI resolved by this Forward should be redirected to.
 boolean isReturnToAction()
          Tell whether returning this forward from an action method will cause the previous action to be re-run.
 boolean isReturnToPage()
          Tell whether returning this forward from an action method will cause a previous page to be displayed.
 void setAlternateModuleConfig(ModuleConfig mc)
          Set an alternate ModuleConfig from which to resolve forwards if they are not resolved from the stored ActionMapping (and its stored ModuleConfig).
 void setExternalRedirect(boolean externalRedirect)
          Specify that this is a redirect to a URI outside of the current web application.
 void setPath(String contextRelativePath)
          Set the path to be returned by getPath().
 void setQueryString(String queryString)
          Set the query string that will be appended to the URI returned by getPath().
 void setRedirect(boolean doRedirect)
          Set whether the URI resolved by this Forward should be redirected to.
 
Methods inherited from class ForwardConfig
freeze, getContextRelative, getModule, getName, getRedirect, setContextRelative, setModule, setName, toString
 
Methods inherited from class Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

RETURN_TO_NONE

public static final int RETURN_TO_NONE
See Also:
Constant Field Values

RETURN_TO_CURRENT_PAGE

public static final int RETURN_TO_CURRENT_PAGE
See Also:
Constant Field Values

RETURN_TO_PREVIOUS_PAGE

public static final int RETURN_TO_PREVIOUS_PAGE
See Also:
Constant Field Values

RETURN_TO_PREVIOUS_ACTION

public static final int RETURN_TO_PREVIOUS_ACTION
See Also:
Constant Field Values

RETURN_TO_PAGE

public static final int RETURN_TO_PAGE
Deprecated. Use RETURN_TO_CURRENT_PAGE or RETURN_TO_PREVIOUS_PAGE instead.
See Also:
Constant Field Values

RETURN_TO_ACTION

public static final int RETURN_TO_ACTION
Deprecated. Use RETURN_TO_PREVIOUS_ACTION instead.
See Also:
Constant Field Values
Constructor Detail

Forward

protected Forward(Forward init)

Forward

protected Forward(HttpServletRequest request)

Forward

public Forward(String forwardName)
Constructor which accepts the name of a forward defined by the @Jpf.Forward annotation. The values returned from getPath(), ForwardConfig.getRedirect() and ForwardConfig.contextRelative are resolved from this forward.

Parameters:
forwardName - the name of the forward (@Jpf.Forward) to resolve.

Forward

public Forward(String forwardName,
               Object outputFormBean)
Constructor which accepts the name of a forward defined by the @Jpf.Forward annotation. The values returned from getPath(), ForwardConfig.getRedirect() and ForwardConfig.contextRelative are resolved from this forward. Also accepts a form bean to make available in the request (or user session, as appropriate).

Parameters:
forwardName - the name of the forward (@Jpf.Forward) to resolve.
outputFormBean - a form bean instance to make available in the request (or user session, as appropriate). See addOutputForm(java.lang.Object) for details about how this manifests itself.

Forward

public Forward(String forwardName,
               String actionOutputName,
               Object actionOutputValue)
Constructor which accepts the name of a forward defined by the @Jpf.Forward annotation. The values returned from getPath(), ForwardConfig.getRedirect() and ForwardConfig.contextRelative are resolved from this forward. Also accepts a named action output to make available in the request, through PageFlowUtils.getActionOutput(java.lang.String, javax.servlet.ServletRequest)..

Parameters:
forwardName - the name of the forward (@Jpf.Forward) to resolve.
actionOutputName - the name of a action output to make available in the request.
actionOutputValue - the action output object to make available in the request.

Forward

public Forward(URI uri)
Constructs a Forward that returns the given URI for getPath(). By default the Forward will cause server forward (not a browser redirect); to change this, use setRedirect(boolean).

Parameters:
uri - the URI to return for getPath().

Forward

public Forward(URI uri,
               boolean doRedirect)
Constructs a Forward that returns the given URI for getPath().

Parameters:
uri - the URI to return for getPath().
doRedirect - set to true if this Forward should cause a browser redirect; false if it should cause a server forward.

Forward

public Forward(URL url)
Constructs a Forward that returns the given URL for getPath(). Because the URL path is absolute by nature, this Forward will cause a browser redirect.

Parameters:
url - the URL to return for getPath().

Forward

protected Forward(ActionForward initFwd,
                  ServletContext servletContext)
Internal. Initialize from an existing Struts ActionForward.

Method Detail

setRedirect

public void setRedirect(boolean doRedirect)
Set whether the URI resolved by this Forward should be redirected to.

Overrides:
setRedirect in class ForwardConfig
Parameters:
doRedirect - if true, the controller will send a browser redirect to the URI for this Forward; otherwise, it will do a server forward to the URI.

isRedirect

public boolean isRedirect()
Tell whether the URI resolved by this Forward should be redirected to.

Returns:
true if the controller will send a browser redirect to the URI for this Forward; false if it will do a server forward to the URI.

addOutputForm

public final void addOutputForm(Object formBean)
Add a form bean that will be made available in the request (or user session, as appropriate) if this Forward is returned by an action method in a PageFlowController. Specifically, each form bean is stored as a request attribute with a name determined by PageFlowUtils.getFormBeanName(org.apache.struts.action.ActionForm, javax.servlet.http.HttpServletRequest).

Parameters:
formBean - the form bean instance to add.

getOutputForms

public final ActionForm[] getOutputForms()
Get all form-beans attached to this forward through addOutputForm(java.lang.Object) or Forward(String, Object).

Returns:
an array of ActionForm instances that are attached to this forward.

getFirstOutputForm

public ActionForm getFirstOutputForm(HttpServletRequest request)
Get the first output form bean that was added to this Forward.


doesResolve

public boolean doesResolve()
Tell whether getPath() will be successful, i.e., whether one of the following two conditions is met:

Returns:
true if this forward does resolve to a URI path.

findForward

protected ActionForward findForward(String forwardName)
Resolves the forward with the given name, from the stored ActionMapping if possible, or from the stored alternate ModuleConfig as a last resort.

Parameters:
forwardName - the name of the forward to resolve.
Returns:
the resolved ActionForward, or null if none is found.

setAlternateModuleConfig

public void setAlternateModuleConfig(ModuleConfig mc)
Set an alternate ModuleConfig from which to resolve forwards if they are not resolved from the stored ActionMapping (and its stored ModuleConfig).


initialize

public void initialize(ActionMapping mapping,
                       FlowController flowController)
Deprecated. Use initialize(ActionMapping, FlowController, ServletRequest) instead.

Set the current ActionMapping and associated FlowController. Normally, this method is called by the framework, but you can use it to initialize the Forward object in order to call getPath().

Parameters:
mapping - the current ActionMapping; this can be obtained from FlowController.getMapping().
flowController - the object in which to look for referenced return-form members.

initialize

public void initialize(ActionMapping mapping,
                       FlowController flowController,
                       ServletRequest request)
Set the current ActionMapping and associated FlowController. Normally, this method is called by the framework, but you can use it to initialize the Forward object in order to call getPath().

Parameters:
mapping - the current ActionMapping; this can be obtained from FlowController.getMapping().
flowController - the object in which to look for referenced return-form members.

setPath

public void setPath(String contextRelativePath)
Set the path to be returned by getPath(). This overrides any path or forward name set in a constructor.

Overrides:
setPath in class ForwardConfig
Parameters:
contextRelativePath - the path to be returned by getPath().

hasExplicitRedirectValue

public boolean hasExplicitRedirectValue()
Tell whether this Forward was configured explicitly (through Jpf.Forward.redirect(), setRedirect(boolean)), or Forward(URI, boolean)) to perform a redirect. Otherwise, a redirect is implied by a URI that does not resolve to the current server.


getPath

public String getPath()
Get the URI path associated with this object. Resolve it from the name of a forward (@Jpf.Forward) if necessary.

Overrides:
getPath in class ForwardConfig
Returns:
a String that is the URI path.
See Also:
Forward(String), Forward(String, Object), Forward(URI), Forward(URL), setPath(java.lang.String)

isNestedReturn

public boolean isNestedReturn()
Tell whether returning this forward from an action method will cause a return from a nested PageFlowController.

Returns:
true if this forward will cause a return from nesting.

isReturnToPage

public boolean isReturnToPage()
Tell whether returning this forward from an action method will cause a previous page to be displayed.

Returns:
true if returning this forward from an action method will cause a previous page to be displayed.

isReturnToAction

public boolean isReturnToAction()
Tell whether returning this forward from an action method will cause the previous action to be re-run.

Returns:
true if returning this forward from an action method will cause the previous action to be re-run, i.e., whether the URI returned by getPath() will end in "previous-action-name.do".

isExternalRedirect

public boolean isExternalRedirect()
Tell whether this is a redirect to a URI outside of the current web application.


setExternalRedirect

public void setExternalRedirect(boolean externalRedirect)
Specify that this is a redirect to a URI outside of the current web application.


doesRestoreQueryString

public boolean doesRestoreQueryString()
Tell whether this Forward will store the original query string on the page restored through Jpf.NavigateTo#previousAction.


forwardsToPageFlow

public boolean forwardsToPageFlow()
Tell whether the URI returned by getPath() is for a page flow.

Returns:
true if the URI returned by getPath() is for a page flow, i.e., if it ends in ".jpf".

setQueryString

public void setQueryString(String queryString)
Set the query string that will be appended to the URI returned by getPath().

Parameters:
queryString - the query string that will be appended to the URI. If this string does not start with '?', then this character will be prepended; if the string is null, the query string will be removed.

getQueryString

public String getQueryString()
Get the query string that will be appended to the URI returned by getPath().

Returns:
the query string that will be appended to the URI, or null if there is no query string.

addQueryParam

public void addQueryParam(String paramName,
                          String value)
Add a query parameter to the URI returned by getPath().

Parameters:
paramName - the name of the query parameter.
value - the value of the query parameter, or null if there is no value.

addQueryParam

public final void addQueryParam(String paramName)
Add a query parameter with no value to the URI returned by getPath().

Parameters:
paramName - the name of the query parameter.

addPageInput

public void addPageInput(String paramName,
                         Object value)
Deprecated. Use addActionOutput(java.lang.String, java.lang.Object) instead.

Adds an action output that will be made available in the request, through PageFlowUtils.getActionOutput(java.lang.String, javax.servlet.ServletRequest).

Parameters:
paramName - the name of the action output.
value - the action output value.

addActionOutput

public void addActionOutput(String paramName,
                            Object value)
Adds an action output that will be made available in the request, through PageFlowUtils.getActionOutput(java.lang.String, javax.servlet.ServletRequest).

Parameters:
paramName - the name of the action output.
value - the action output value.

getPageInputs

public Map getPageInputs()
Deprecated. Use getActionOutputs() instead.

Get all action outputs that have been set on this Forward.

Returns:
a Map of name/value pairs representing all action outputs.
See Also:
addActionOutput(java.lang.String, java.lang.Object)

getActionOutputs

public Map getActionOutputs()
Get all action outputs that have been set on this Forward.

Returns:
a Map of name/value pairs representing all action outputs.
See Also:
addActionOutput(java.lang.String, java.lang.Object)

getReturnToType

public int getReturnToType()
Get the type of return, if this is a return-to type.

Returns:
one of the following values: RETURN_TO_CURRENT_PAGE, RETURN_TO_PREVIOUS_PAGE, RETURN_TO_PAGE, RETURN_TO_PREVIOUS_ACTION, RETURN_TO_ACTION, or RETURN_TO_NONE if this Forward is not a return-to type.
See Also:
isReturnToAction(), isReturnToPage()

getReturnToTypeAsString

public String getReturnToTypeAsString()
Get the type of return as a String, if this is a return-to type.

Returns:
one of the following values: currentPage, previousPage, page, (deprecated), previousAction, action (deprecated), or null if this is not a return-to type.
See Also:
isReturnToAction(), isReturnToPage()