# com.bea.wlw.netui.pageflow
FlowController Class

public abstract class FlowController
extends `Action`
implements ActionResolver, `HttpSessionBindingListener`, `PageFlowConstants`, `Serializable`

Base class for user-written flow controllers - PageFlowControllers and Global.app.

Hierarchy
  `Object`
  `Action`
  `FlowController`

All Implemented Interfaces
  `EventListener`, `HttpSessionBindingListener`, `PageFlowConstants`, `Serializable`

Direct Known Subclasses
  `GlobalApp`, `PageFlowController`

## Field Summary

Fields from org.apache.struts.action`.`Action``
`ACTION_SERVLET_KEY, APPLICATION_KEY, DATA_SOURCE_KEY, defaultLocale, ERROR_KEY, EXCEPTION_KEY, FORM_BEANS_KEY, FORWARDS_KEY, LOCALE_KEY, MAPPING_KEY, MAPPINGS_KEY, MESSAGE_KEY, MESSAGES_KEY, MULTIPART_KEY, PLUG_INS_KEY, REQUEST_PROCESSOR_KEY, servlet, SERVLET_KEY, TRANSACTION_TOKEN_KEY`

Fields from interface com.bea.wlw.netui.pageflow`.`PageFlowConstants``
``ACTION_EXTENSION`, `ACTION_EXTENSION_LEN`, `ACTION_OVERRIDE`, `BEGIN_ACTION_NAME`, `BEGIN_ACTION_PATH`, `DEFAULT_FORWARD_OVERFLOW_COUNT`, `DEFAULT_NESTING_OVERFLOW_COUNT`, `FORWARD_OVERFLOW_COUNT_PARAM`, `GLOBALAPP_CLASSNAME`, `GLOBALAPP_MEMBER_NAME`, `GLOBALAPP_MODULE_CONTEXT_PATH`, `GLOBALAPP_SOURCEFILE_NAME`, `INTERNAL_VAR_PREFIX`, `ISNESTABLE_VAR_NAME`, `JPF_EXTENSION`, `JPF_MODULE_CONFIG_EXTENSION`, `JPF_MODULE_CONFIG_GEN_DIR`, `JPF_MODULE_CONFIG_PREFIX`, `NESTING_OVERFLOW_COUNT_PARAM`, `PROCESS_ROLES_FAILED_ATTR`, `WEBINF_DIR``

## Constructor Summary

FlowController() Default constructor.

## Method Summary

`protected synchronized void` | `afterAction`() Callback that occurs after any user action method is invoked.
`protected boolean` | `alwaysTrackPreviousAction`() When the current page flow does not use a `@jpf:forward` with a `return-to="previousAction"` attribute, the following methods always return `null` by default.
`protected boolean` | `alwaysTrackPreviousPage`() When the current page flow does not use a `@jpf:forward` with either a `return-to="currentPage"` or a `return-to="previousPage"` attribute, the following methods always return `null` by default.
`protected synchronized void` | `beforeAction`() Callback that occurs before any user action method is invoked.
`public abstract void` | `ensureFailover`(`HttpServletRequest` request) Ensures that any changes to this FlowController will be replicated in a cluster (for failover), even if the replication scheme uses a change-detection algorithm that relies on HttpSession.setAttribute to be aware of changes.
`public `ActionForward`` | `execute`(`ActionMapping` mapping, `ActionForm` form, `HttpServletRequest` request, `HttpServletResponse` response) Perform decision logic to determine the next URI to be displayed.
`protected `Method`` | `getActionMethod`(`String` methodName, `Class` argType) Get an action handler method of the given name/signature .
`public `String`[]` | `getActions`() Get a list of the names of actions handled by methods in this PageFlowController.
`protected `String`` | `getCurrentActionName`() Get the name of the current action being executed.
`public abstract `String`` | `getDisplayName`()
`protected final `ActionMapping`` | `getMapping`() Get the current Struts ActionMapping, which is information from the Struts-XML <action> tag that corresponds to the current page flow action being executed.
`public `ModuleConfig`` | `getModuleConfig`(`ServletContext` context, `HttpServletRequest` request) Gets the Struts module configuration associated with this controller.
`public abstract `String`` | `getModulePath`() Get the Struts module path for this controller.
`protected final `HttpServletRequest`` | `getRequest`() Get the current HttpServletRequest.
`protected final `HttpServletResponse`` | `getResponse`() Get the current HttpServletResponse.
`public `ActionServlet`` | `getServlet`() Get the current Struts ActionServlet.
`protected final `HttpSession`` | `getSession`() Get the current user session.
`protected synchronized `ActionForward`` | `handleException`(`Throwable` ex, `ActionMapping` mapping, `String` actionName, `ActionForm` form, `HttpServletRequest` request, `HttpServletResponse` response) Handle the given exception - invoke user code if appropriate and return a destination URI.
`protected `ActionForward`` | `invokeActionMethod`(`Method` method, `ActionForm` arg) Invoke the given action handler method, passing it an argument if appropriate.
`public boolean` | `isAction`(`String` name) Tell whether a given String is the name of an action handled by a method in this PageFlowController.
`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.
`public boolean` | `isPageFlow`() Tell whether this is a `PageFlowController```.
`public void` | `login`(`String` username, `String` password) Log in the user, using "weak" username/password authentication.
`public void` | `logout`(boolean invalidateSessions) Log out the current user.
`protected void` | `onCreate`() Callback that is invoked when this controller instance is created.
`protected void` | `onDestroy`() Callback that is invoked when this controller instance is "destroyed", i.e., removed from the user session.
`protected void` | `onDestroy`(`HttpSession` session) Callback that is invoked when this controller instance is "destroyed", i.e., removed from the user session.
`public `String`` | `resolveAction`(`String` actionName, `ActionForm` form) Call an action and return the result URI.
`public static `Locale`` | `retrieveUserLocale`(`HttpServletRequest` request, `String` locale)
`protected void` | `sendError`(`String` errText, `HttpServletResponse` response) Send a Page Flow error to the browser.
`public void` | `valueBound`(`HttpSessionBindingEvent` event) Callback when this FlowController is added to the user session.
`public void` | `valueUnbound`(`HttpSessionBindingEvent` event) Callback when this FlowController is removed from the user session.

Methods from `org.apache.struts.action.`Action``
`execute, generateToken, getDataSource, getDataSource, getLocale, getResources, getResources, getResources, isCancelled, isTokenValid, isTokenValid, perform, perform, resetToken, saveErrors, saveMessages, saveToken, setLocale, toHex`

Methods from class `java.lang.`Object``
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Methods from interface `javax.servlet.http.`HttpSessionBindingListener``
`valueBound, valueUnbound`

## Constructor Detail

### FlowController

    public FlowController()

  Default constructor.

## Method Detail

### afterAction() Method

    protected synchronized void afterAction()
         throws Exception

Callback that occurs after any user action method is invoked. `FlowController.getRequest()```, `FlowController.getResponse()```, `FlowController.getSession()```, and `FlowController.getMapping()``` may all be used during this method. The action that was run can be discovered by calling ActionMapping.getPath()`` on the value returned from `FlowController.getMapping()```.

#### Exceptions

``Exception``

### alwaysTrackPreviousAction() Method

    protected boolean alwaysTrackPreviousAction()

When the current page flow does not use a `@jpf:forward` with a `return-to="previousAction"` attribute, the following methods always return `null` by default.

- getPreviousActionInfo
- getPreviousActionURI
- getPreviousForm

Override `alwaysTrackPreviousAction` (which always returns `false`) to enable these methods in all cases.

#### Returns

`true` if the previous action should always be tracked, regardless of whether `return-to="previousAction"` is used.

Related Topics

``PageFlowController.getPreviousActionInfo()``
``PageFlowController.getPreviousActionURI()``
``PageFlowController.getPreviousForm()``

### alwaysTrackPreviousPage() Method

    protected boolean alwaysTrackPreviousPage()

When the current page flow does not use a `@jpf:forward` with either a `return-to="currentPage"` or a `return-to="previousPage"` attribute, the following methods always return `null` by default.

- getCurrentPageInfo
- getPreviousPageInfo
- getCurrentForwardPath
- getPreviousForwardPath

Override `alwaysTrackPreviousPage` (which always returns `false`) to enable these methods in all cases.

#### Returns

`true` if the previous page should always be tracked, regardless of whether `return-to="currentPage"` or `return-to="previousPage"` is used.

Related Topics

``PageFlowController.getCurrentPageInfo()``
``PageFlowController.getPreviousPageInfo()``
``PageFlowController.getCurrentForwardPath()``
``PageFlowController.getPreviousForwardPath()``

### beforeAction() Method

    protected synchronized void beforeAction()
         throws Exception

Callback that occurs before any user action method is invoked. `FlowController.getRequest()```, `FlowController.getResponse()```, `FlowController.getSession()```, and `FlowController.getMapping()``` may all be used during this method. The action to be run can be discovered by calling ActionMapping.getPath()`` on the value returned from `FlowController.getMapping()```.

#### Exceptions

``Exception``

### ensureFailover(HttpServletRequest) Method

    public abstract void ensureFailover(HttpServletRequest request)

Ensures that any changes to this FlowController will be replicated in a cluster (for failover), even if the replication scheme uses a change-detection algorithm that relies on HttpSession.setAttribute to be aware of changes.

#### Parameters

request
  the current HttpServletRequest

### execute(ActionMapping, ActionForm, HttpServletRequest, HttpServletResponse) Method

    public ActionForward execute(ActionMapping mapping,
                                 ActionForm form,
                                 HttpServletRequest request,
                                 HttpServletResponse response)
         throws Exception

Perform decision logic to determine the next URI to be displayed.

Overrides
  Action.execute(ActionMapping, ActionForm, HttpServletRequest, HttpServletResponse)

#### Parameters

mapping
  the Struts ActionMapping for the current action being processed.

form
  the form-bean (if any) associated with the Struts action being processed. May be null.

request
  the current HttpServletRequest.

response
  the current HttpServletResponse.

#### Returns

a Struts ActionForward object that specifies the next URI to be displayed.

#### Exceptions

``Exception``
  if an Exception was thrown during user action-handling code.

### getActionMethod(String, Class) Method

    protected Method getActionMethod(String methodName,
                                     Class argType)

Get an action handler method of the given name/signature .

#### Parameters

methodName
  the name of the action handler method to query.

argType
  the type of the argument to the action handler method; if `null`, the method takes no arguments.

#### Returns

the desired Method, or `null` if it doesn't exist.

### getActions() Method

    public String[] getActions()

Get a list of the names of actions handled by methods in this PageFlowController.

#### Returns

a String array containing the names of actions handled by methods in this PageFlowController.

### getCurrentActionName() Method

    protected String getCurrentActionName()

Get the name of the current action being executed. This call is only valid during `FlowController.execute(ActionMapping, ActionForm, HttpServletRequest, HttpServletResponse)``` (where any user action method is invoked), and during the lifecycle methods `FlowController.beforeAction()``` and `FlowController.afterAction()```.

#### Returns

the name of the current action being executed.

### getDisplayName() Method

    public abstract String getDisplayName()

### getMapping() Method

    protected final ActionMapping getMapping()

Get the current Struts ActionMapping, which is information from the Struts-XML <action> tag that corresponds to the current page flow action being executed. This call is only valid during `FlowController.execute(ActionMapping, ActionForm, HttpServletRequest, HttpServletResponse)``` (where any user action method is invoked), and during the lifecycle methods `FlowController.beforeAction()``` and `FlowController.afterAction()```.

#### Returns

the current Struts ActionMapping.

### getModuleConfig(ServletContext, HttpServletRequest) Method

    public ModuleConfig getModuleConfig(ServletContext context,
                                        HttpServletRequest request)

Gets the Struts module configuration associated with this controller.

#### Parameters

context
  the current ServletContext.

#### Returns

the Struts ModuleConfig for this controller.

### getModulePath() Method

    public abstract String getModulePath()

Get the Struts module path for this controller.

#### Returns

a String that is the Struts module path for this controller - the parent directory for a `PageFlowController``` and "/-global" for Global.app.

### getRequest() Method

    protected final HttpServletRequest getRequest()

Get the current HttpServletRequest. This call is only valid during `FlowController.execute(ActionMapping, ActionForm, HttpServletRequest, HttpServletResponse)``` (where any user action method is invoked), and during the lifecycle methods `FlowController.onCreate()```, `FlowController.beforeAction()```, `FlowController.afterAction()```.

#### Returns

the current HttpServletRequest.

### getResponse() Method

    protected final HttpServletResponse getResponse()

Get the current HttpServletResponse. This call is only valid during `FlowController.execute(ActionMapping, ActionForm, HttpServletRequest, HttpServletResponse)``` (where any user action method is invoked), and during the lifecycle methods `FlowController.onCreate()```, `FlowController.beforeAction()```, `FlowController.afterAction()```.

#### Returns

the current HttpServletResponse.

### getServlet() Method

    public ActionServlet getServlet()

Get the current Struts ActionServlet.

Overrides
  Action.getServlet()

#### Returns

the ActionServlet.

### getSession() Method

    protected final HttpSession getSession()

Get the current user session. This call is only valid during `FlowController.execute(ActionMapping, ActionForm, HttpServletRequest, HttpServletResponse)``` (where any user action method is invoked), and during the lifecycle methods `FlowController.onCreate()```, `FlowController.onDestroy()```, `FlowController.beforeAction()```, `FlowController.afterAction()```.

#### Returns

the HttpSession for the current user session.

### handleException(Throwable, ActionMapping, String, ActionForm, HttpServletRequest, HttpServletResponse) Method

    protected synchronized ActionForward handleException(Throwable ex,
                                                         ActionMapping mapping,
                                                         String actionName,
                                                         ActionForm form,
                                                         HttpServletRequest request,
                                                         HttpServletResponse response)
         throws Exception

Handle the given exception - invoke user code if appropriate and return a destination URI.

#### Parameters

ex
  the Exception to handle.

mapping
  the Struts action mapping for current Struts action being processed.

actionName
  the name of the Struts action being processed.

form
  the form-bean (if any) associated with the Struts action being processed. May be null.

request
  the current HttpServletRequest.

response
  the current HttpServletResponse.

#### Returns

a Struts ActionForward object that specifies the URI that should be displayed.

#### Exceptions

``Exception``
  if another Exception is thrown during handling of `ex`.

### invokeActionMethod(Method, ActionForm) Method

    protected ActionForward invokeActionMethod(Method method,
                                               ActionForm arg)
         throws Exception

Invoke the given action handler method, passing it an argument if appropriate.

#### Parameters

method
  the action handler method to invoke.

arg
  the form-bean to pass; may be `null`.

#### Returns

the ActionForward returned by the action handler method.

#### Exceptions

``Exception``
  if an Exception was raised in user code.

### isAction(String) Method

    public boolean isAction(String name)

Tell whether a given String is the name of an action handled by a method in this PageFlowController.

#### Parameters

name
  the action-name to query.

#### Returns

`true` if `name` is the name of an action handled by a method in this PageFlowController.

### isNestable() Method

    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 using the `@jpf:controller nested="true"` annotation.

#### Returns

`true` if this PageFlowController can be nested.

### isPageFlow() Method

    public boolean isPageFlow()

Tell whether this is a `PageFlowController```.

#### Returns

`true` if this is a `PageFlowController```.

### login(String, String) Method

    public void login(String username,
                      String password)
         throws LoginException

Log in the user, using "weak" username/password authentication.

#### Parameters

username
  the user's login name

password
  the user's password

#### Exceptions

``LoginException``
  if the authentication failed

### logout(boolean) Method

    public void logout(boolean invalidateSessions)

Log out the current user. This causes the user to be removed from Servlet Session (on all single-signon webapps) as well as from the thread.

#### Parameters

invalidateSessions
  if true, the session is invalidated (on all single-signon webapps); otherwise the session and its data are left intact (except for authentication information used internally by the server). To invalidate the session in only the current webapp, set this parameter to `false` and call `FlowController.getSession()```.invalidate().

### onCreate() Method

    protected void onCreate()
         throws Exception

Callback that is invoked when this controller instance is created. `FlowController.getRequest()```, `FlowController.getResponse()```, `FlowController.getSession()``` may all be used during this method.

#### Exceptions

``Exception``

### onDestroy() Method

DEPRECATED `com.bea.wlw.netui.pageflow.FlowController.onDestroy(javax.servlet.http.HttpSession)``` should be used instead.

    protected void onDestroy()

Callback that is invoked when this controller instance is "destroyed", i.e., removed from the user session. `FlowController.getRequest()```, `FlowController.getResponse()```, and `FlowController.getMapping()``` may not be used during this method, since it may be called due to session termination outside of a request. `FlowController.getSession()``` also may not be used, but the session is passed as an argument to `FlowController.onDestroy(HttpSession)```, which should be used in place of this method.

### onDestroy(HttpSession) Method

    protected void onDestroy(HttpSession session)

Callback that is invoked when this controller instance is "destroyed", i.e., removed from the user session. `FlowController.getRequest()```, `FlowController.getResponse()```, and `FlowController.getMapping()``` may not be used during this method, since it may be called due to session termination outside of a request. `FlowController.getSession()``` also may not be used, but the session is passed as an argument.
Note that this method is not synchronized.

### resolveAction(String, ActionForm) Method

    public String resolveAction(String actionName,
                                ActionForm form)
         throws Exception

Call an action and return the result URI.

#### Parameters

actionName
  the name of the action to run.

form
  the form bean instance to pass to the action, or `null` if none should be passed.

#### Returns

the result webapp-relative URI, as a String.

#### Exceptions

``Exception``
  if the action method throws an Exception.

### retrieveUserLocale(HttpServletRequest, String) Method

    public static Locale retrieveUserLocale(HttpServletRequest request,
                                            String locale)

### sendError(String, HttpServletResponse) Method

    protected void sendError(String errText,
                             HttpServletResponse response)
         throws IOException

Send a Page Flow error to the browser.

#### Parameters

errText
  the error message to display.

response
  the current HttpServletResponse.

#### Exceptions

``IOException``

### valueBound(HttpSessionBindingEvent) Method

    public void valueBound(HttpSessionBindingEvent event)

Callback when this FlowController is added to the user session.

### valueUnbound(HttpSessionBindingEvent) Method

    public void valueUnbound(HttpSessionBindingEvent event)

Callback when this FlowController is removed from the user session. Causes `FlowController.onDestroy()``` to be called.