com.jcorporate.expresso.core.controller
Class Controller

java.lang.Object
  org.apache.struts.action.Action
      com.jcorporate.expresso.core.controller.Controller

All Implemented Interfaces:

Serializable

Direct Known Subclasses:

DBController

public abstract class Controller

extends org.apache.struts.action.Action

implements Serializable

A sequence of interaction with a user is defined as a "Controller".

An Expresso controller is best thought of as a finite state machine. The only real difference is that because of the stateless nature of the web, anybody can reach any state with using the "state" parameter in the URL.

Usually for a web deployment environment, you would derive your own controller from DBController, which adds a database-backed Security matrix to the controller's base capabilities. Controllers (and DBControllers) do not necessarily need to be run inside a servlet environment. If they never downcast their ControllerResponse object to ServletControllerResponse, the Controller can also be used in products such as Expresso Webservices, or

See the Expresso Developer's Guide for more information on creating and using a Controller.

A Controller takes a series of parameters (optional) and then provides a series of Blocks, Inputs, Outputs, and Transitions to the client

An Input specifies a piece of information we want FROM the client An Output is a piece of information we supply TO the client A Transition is an action the client can take from this point - e.g. further controllers that are followups to this controller A Block is a collection of Inputs, Outputs, Transitions or other Blocks

See Also:

DBController, SecureIfSetController, Serialized Form

Field Summary

static String	CONTROLLER_PARAM_KEY key for putting controller into parameter map
static String	CTL_SUCC_CTL
static String	CTL_SUCC_STATE
static String	CTL_SUCC_TRAN
protected org.apache.log4j.Logger	mLog if subclass calls getLogger(), this will create logger with subclass name
static String	NEWSTATE_EXCEPTION_KEY New state exception key
static String	ORIGINAL_URL_KEY Controller original URL key
static String	REQUEST_KEY Controller request key
static String	RESPONSE_KEY Controller response key
static String	RETURN_TO_SENDER_TRAN
static String	STATE_ERR_CTL
static String	STATE_ERR_STATE
static String	STATE_ERR_TRAN
static String	STATE_PARAM_KEY key for putting state into parameter map
static String	STATE_SUCC_CTL
static String	STATE_SUCC_STATE
static String	STATE_SUCC_TRAN

Fields inherited from class 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

Constructor Summary

Controller()
Default constructor

Method Summary

protected void	addFinalState(State newFinalState) The constructor of the child object should call addFinalState to define the last state to be executed for this controller.
protected void	addPromptTransitions(State nextState, ControllerResponse response) If nextState is a prompt state (as determined by the addStatePairing method) then add a 'next' and 'previous' transitions as required.
protected void	addRegDomainParamtoSession(HttpServletRequest req, ControllerRequest creq, String regDomain) ???????????????????????
protected void	addRequestedURLtoSession(HttpServletRequest req, ControllerRequest creq)
protected void	addState(State newState) The constructor of the child object should call addState to define each of the states available in this method.
protected void	addStatePairing(State promptState, State handleState, String stateFormClass) The constructor of the child object should call this method with a pairing of State objects.
protected void	endTimer(long beginTimer, HttpServletRequest request) Used for logging time of requests.
org.apache.struts.action.ActionForward	execute(org.apache.struts.action.ActionMapping mapping, org.apache.struts.action.ActionForm form, HttpServletRequest request, HttpServletResponse response) Process the specified HTTP request, and create the corresponding HTTP response (or forward to another web component that will create it).
protected org.apache.struts.action.ActionForm	findControllerForm(ControllerRequest request) Return the Struts ActionForm associated with this controller as specified in the Struts config file.
protected String	generateToken(ControllerRequest request) Generate a new transaction token, to be used for enforcing a single request for a particular transaction.
protected org.apache.struts.action.ActionForward	getActionForward(ServletControllerRequest req, org.apache.struts.config.ActionConfig mapping, ControllerResponse res) Determine the forward appropriate for this controller/state, either from parameters or from configuration files, or from remapping based on past extensions like .xsl
protected Transition	getControllerChainingTransition() Return the transition that will be executed once this controller completes without errors.
protected Transition	getControllerSecurityTransition() Return the transition that will be executed if any state in this controller cannot be run because the user does not have sufficient authorization.
State	getFinalState() Return the final state for this controller.
String	getInitialState() Get the initial state in a controller.
org.apache.log4j.Logger	getLogger() Call from subclass to log into Category with subclass name will create logger with subclass name as necessary.
static String[]	getParamValues(ServletControllerRequest request, String paramName) Fetches array of parameter values from underlying HTTP request; use this in a web app to access the underlying parameters in the HTTP request which have the same name; parameters with the same name are not reflected in the hashtable maintained by ControllerRequest;
protected String	getRequestURL(HttpServletRequest req) recreate requested URL; never null, though could be empty string
protected String	getSchema() Get the name of the schema object that this Controller belongs to
Stack	getSchemaHierarchy() Deprecated. 7/04; v5.5. just name changed. see getSchemaStack
protected Schema	getSchemaInstance() Retrieve a full instance of the Schema object that is associated with this controller
Stack	getSchemaStack() Retrieve a stack of all schemas. hands out actual object instance; singleton for this controller.
State	getState(String stateName) Return a specific state
Hashtable	getStates() Return the hashtable of valid states for this controller
protected String	getString(String stringCode) Convenience version, uses default locale of default db context IMPORTANT: in general, if there's a ControllerResponse object available, use ControllerResponse.getString(String) instead, this is able to return the local language by considering the user's locale.
protected String	getString(String stringCode, Object[] args) Convenience version, uses default locale of default db context IMPORTANT: In general, if there's a ControllerResponse object available, use ControllerResponse.getString(String) instead, this is able to return the local language by considering the user's locale.
String	getTitle() Return the title of this Controller
protected void	handleException(HttpServletRequest req, ControllerRequest creq, String dbName, String userName, Throwable theException) Handle an exception error that is not otherwise caught or handled by the Controller instance itself.
static Controller	instantiate(String className) Factory method to create an Controller from it's name Do not call this function directly!
protected boolean	isFinalState(String newState) Return True if the passed in state was added to this controller as a final state.
protected boolean	isHandleState(State nextState) Return True if the passed in state was added to this controller as a handle state.
protected boolean	isPromptState(State nextState) Return True if the passed in state was added to this controller as a prompt state.
protected boolean	isTokenValid(ControllerRequest request) Return true if there is a transaction token stored in the user's current session, and the value submitted as a request parameter with this action matches it.
protected StateForm	loadStateForm(State nextState, org.apache.struts.action.ActionForm controllerForm) Return the state's form with data from the controller's form.
ControllerResponse	newState(String newState, ControllerRequest myRequest) This is the method where all of the real work of the controller is done.
protected String	nextHandleState(State nextState) Return the name of the handle state that is associated with the passed in prompt state.
protected String	nextPromptState(State nextState) Return the name of the prompt state that is 'next' to the passed in prompt state in the sequence for this controller.
protected void	populateStateForm(StateForm stateForm, ControllerRequest request) Populate the state form with any matching request parameters.
protected void	postPerform(State nextState, ControllerRequest request, ControllerResponse response) Template Method, allowing a subclass to into actions after the invocation of any state in this controller.
protected void	prePerform(State nextState, ControllerRequest request, ControllerResponse response) Template Method, allowing a subclass to do an action after any state in this controller is performed.
protected String	previousPromptState(State nextState) Return the name of the prompt state that is 'previous' to the passed in prompt state in the sequence for this controller.
protected void	processRequestTransitions(State nextState, ControllerRequest request) This method picks up the following routing parameters from the current request and builds transition objects from them before the state is invoked.
protected Transition	processTransitions(ControllerRequest request, ControllerResponse response, State nextState) This method is the traffic cop that determines which transition to execute after a state completes.
void	redirectRequest(ControllerRequest request, ControllerResponse response, String redirectURL) redirect response so that URL changes in client browser
protected void	redirectRequest(HttpServletResponse response, String redirectURL) redirect response so that URL changes in client browser
protected org.apache.struts.config.ForwardConfig	remapFromExtension(org.apache.struts.config.ForwardConfig fwd, org.apache.struts.config.ActionConfig mapping, ServletControllerRequest req) if the extension in the current forward is ".xsl" or ".xslt", remap the forward to "xml", and set a parameter for the xsl style sheet.
protected void	resetToken(ControllerRequest request) Reset the saved transaction token in the user's session.
protected void	saveToken(ControllerRequest request) Save a new transaction token in the user's current session, creating a new session if necessary.
protected void	setControllerChainingTransition(Transition newControllerChainingTransition) Set the transition that will be executed when this controller completes successfully.
protected void	setControllerSecurityTransition(Transition newControllerSecurityTransition) Set the transition that will be executed when a user attempts to run a state he doesn't have authorization on.
ControllerResponse	setCurrentState(String newState, ControllerRequest params) Convenience method to be able to access the state as a property from a JSP.
void	setInitialState(String newInitialState) Set what state to invoke if no state parameter is set.
protected void	setSchema(Class schemaClass) Identical to setSchema(String) but provides a typesafe way of passing parameters.
protected void	setSchema(String schemaClass) Tell this Controller object what Schema it belongs to.
void	setupDefaultValues(String dbName) Allows for DBCreate to set up proper default values for views, etc.
protected void	setupReturnToSender(State nextState, ControllerRequest request) This method is called before a state executes.
protected void	setupSubclassLog() setup a subclass logger separately from the base controller logger.
boolean	stateAllowed(String newState, ControllerRequest params) Is this state allowed for the current user?
protected void	transition(String newState, Class externalController, ControllerRequest req, ControllerResponse res) convenience method for transition to other controller
protected void	transition(String newState, ControllerRequest req, ControllerResponse res)
protected void	transition(String newState, ControllerRequest req, ControllerResponse res, boolean clear) Transition to an internal state.
protected void	unloadStateForm(StateForm stateForm, org.apache.struts.action.ActionForm controllerForm) Move the state's form data back into the controller's form.

Methods inherited from class org.apache.struts.action.Action

execute, generateToken, getDataSource, getDataSource, getLocale, getResources, getResources, getResources, getServlet, isCancelled, isTokenValid, isTokenValid, perform, perform, resetToken, saveErrors, saveMessages, saveToken, setLocale, setServlet, toHex

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

mLog

protected org.apache.log4j.Logger mLog

if subclass calls getLogger(), this will create logger with subclass name

RESPONSE_KEY

public static final String RESPONSE_KEY

Controller response key

See Also:

Constant Field Values

ORIGINAL_URL_KEY

public static final String ORIGINAL_URL_KEY

Controller original URL key

See Also:

Constant Field Values

REQUEST_KEY

public static final String REQUEST_KEY

Controller request key

See Also:

Constant Field Values

NEWSTATE_EXCEPTION_KEY

public static final String NEWSTATE_EXCEPTION_KEY

New state exception key

See Also:

Constant Field Values

CTL_SUCC_TRAN

public static final String CTL_SUCC_TRAN

See Also:

Constant Field Values

CTL_SUCC_CTL

public static final String CTL_SUCC_CTL

See Also:

Constant Field Values

CTL_SUCC_STATE

public static final String CTL_SUCC_STATE

See Also:

Constant Field Values

STATE_SUCC_TRAN

public static final String STATE_SUCC_TRAN

See Also:

Constant Field Values

STATE_SUCC_CTL

public static final String STATE_SUCC_CTL

See Also:

Constant Field Values

STATE_SUCC_STATE

public static final String STATE_SUCC_STATE

See Also:

Constant Field Values

STATE_ERR_TRAN

public static final String STATE_ERR_TRAN

See Also:

Constant Field Values

STATE_ERR_CTL

public static final String STATE_ERR_CTL

See Also:

Constant Field Values

STATE_ERR_STATE

public static final String STATE_ERR_STATE

See Also:

Constant Field Values

RETURN_TO_SENDER_TRAN

public static final String RETURN_TO_SENDER_TRAN

See Also:

Constant Field Values

STATE_PARAM_KEY

public static final String STATE_PARAM_KEY

key for putting state into parameter map

See Also:

Constant Field Values

CONTROLLER_PARAM_KEY

public static final String CONTROLLER_PARAM_KEY

key for putting controller into parameter map

See Also:

Constant Field Values

Constructor Detail

Controller

public Controller()

Default constructor

Method Detail

addFinalState

protected void addFinalState(State newFinalState)
                      throws NonHandleableException

The constructor of the child object should call addFinalState to define the last state to be executed for this controller. Once the final state is added then no other states can be added via the addStatePairing method.

Parameters:

newFinalState - the new state to use as your final state.

Throws:

NonHandleableException - if you send it an improper final state.

addPromptTransitions

protected void addPromptTransitions(State nextState,
                                    ControllerResponse response)
                             throws ControllerException

If nextState is a prompt state (as determined by the addStatePairing method) then add a 'next' and 'previous' transitions as required. A 'next' transition will refer to a prompt state's associated validate state. A 'previous' transition will refer to the prompt state that precedes the passed in state. The 'previous' state will not be added to the response if if the passed in state is the first one (iniial state) in this controller.

Parameters:

nextState - in this controller the new state add

response - the ControllerResponse that these transitions will be added to.

Throws:

ControllerException - upon error.

addState

protected void addState(State newState)

The constructor of the child object should call addState to define each of the states available in this method.

Parameters:

newState - The State object to be added to the list of states for this controller

addStatePairing

protected void addStatePairing(State promptState,
                               State handleState,
                               String stateFormClass)
                        throws NonHandleableException

The constructor of the child object should call this method with a pairing of State objects. The sequence of calls to this method determine the runtime ordering of states.

Parameters:

promptState - The state that is part of the 'prompting' workflow

handleState - The state that is part of the 'processing' workflow

stateFormClass - The ActionForm name to use

Throws:

NonHandleableException - if there's an error in pairing. Usually caused by a java.lang.IllegalArumentException

findControllerForm

protected org.apache.struts.action.ActionForm findControllerForm(ControllerRequest request)
                                                          throws ControllerException

Return the Struts ActionForm associated with this controller as specified in the Struts config file. Struts would have already created and populated this form and put it either in the request or session scope.

Parameters:

request - The ControllerRequest object

Returns:

The appropriate ActionForm for this controller request

Throws:

ControllerException - if unable to find the Controller Form.

getControllerChainingTransition

protected Transition getControllerChainingTransition()

Return the transition that will be executed once this controller completes without errors. The controller 'completes' once the final state (as defined using addFinalState) returns without errors in the error collection.

Returns:

The Transition for this controller chaining setup.

getControllerSecurityTransition

protected Transition getControllerSecurityTransition()

Return the transition that will be executed if any state in this controller cannot be run because the user does not have sufficient authorization.

Returns:

The ControllerSecurity Transition

getFinalState

public State getFinalState()

Return the final state for this controller. See addFinalState().

Returns:

the "Final" state for this workflow.

getInitialState

public String getInitialState()

Get the initial state in a controller. This is the state to use if there is no state parameter specified in the requesting URL or execution container.

Returns:

The name of the State to use as default for this controller

getSchema

protected final String getSchema()

Get the name of the schema object that this Controller belongs to

Returns:

The schema class name associated with this controller

getSchemaInstance

protected Schema getSchemaInstance()

Retrieve a full instance of the Schema object that is associated with this controller

Returns:

Schema instance.

getSchemaHierarchy

public Stack getSchemaHierarchy()

Deprecated. 7/04; v5.5. just name changed. see getSchemaStack

Retrieve a stack of all schemas in a 'derived sense'

Returns:

java.util.Stack with the schema hierarchy ending in ExpressoSchema at the bottom.

getSchemaStack

public Stack getSchemaStack()

Retrieve a stack of all schemas. hands out actual object instance; singleton for this controller.

Returns:

java.util.Stack with the schema hierarchy ending in ExpressoSchema at the bottom. never null.

getState

public final State getState(String stateName)

Return a specific state

Parameters:

stateName - The name of the state to retrieve

Returns:

the Instantiated State.

getStates

public final Hashtable getStates()

Return the hashtable of valid states for this controller

Returns:

a Hashtable of states for this controller

getString

protected String getString(String stringCode)

Convenience version, uses default locale of default db context

IMPORTANT: in general, if there's a ControllerResponse object available, use ControllerResponse.getString(String) instead, this is able to return the local language by considering the user's locale.

Parameters:

stringCode - The properties file string code to retrieve

Returns:

translated string, or if not found, the stringCode

getString

protected String getString(String stringCode,
                           Object[] args)

Convenience version, uses default locale of default db context

IMPORTANT: In general, if there's a ControllerResponse object available, use ControllerResponse.getString(String) instead, this is able to return the local language by considering the user's locale.

Parameters:

stringCode - The properties file string code to retrieve

args - The Object array for i18n formatting.

Returns:

translated string, or if not found, the stringCode

getTitle

public String getTitle()

Return the title of this Controller

Returns:

java.lang.String The Title of the controller

handleException

protected void handleException(HttpServletRequest req,
                               ControllerRequest creq,
                               String dbName,
                               String userName,
                               Throwable theException)
                        throws ServletException

Handle an exception error that is not otherwise caught or handled by the Controller instance itself. Typically, these will be reserved for "system failure" type of situations, as anything that the user can reasonable be expected to correct should be reported in the ErrorCollection instead.

Parameters:

req - The HTTPServletRequest

creq - The ControllerRequest Object

dbName - The current data context

userName - The currently logged in Username

theException - The java.lang.Throwable object that was caught

Throws:

ServletException - upon fatal error for handling the exception

addRequestedURLtoSession

protected void addRequestedURLtoSession(HttpServletRequest req,
                                        ControllerRequest creq)
                                 throws ControllerException

Throws:

ControllerException

getRequestURL

protected String getRequestURL(HttpServletRequest req)

recreate requested URL; never null, though could be empty string

addRegDomainParamtoSession

protected void addRegDomainParamtoSession(HttpServletRequest req,
                                          ControllerRequest creq,
                                          String regDomain)
                                   throws ControllerException

???????????????????????

Parameters:

req - ?

creq - ?

regDomain - ?

Throws:

ControllerException

instantiate

public static Controller instantiate(String className)
                              throws ControllerException

Factory method to create an Controller from it's name Do not call this function directly! Use ConfigManager.getControllerFactory() .getInstance(java.lang.String) instead.

Parameters:

className - The classname of the controller to instantiated

Returns:

a fully instantiated Controller Object

Throws:

ControllerException - upon construction failure

isFinalState

protected boolean isFinalState(String newState)

Return True if the passed in state was added to this controller as a final state.

Parameters:

newState - the state name to use as the final state.

Returns:

true if this is the final state.

isHandleState

protected boolean isHandleState(State nextState)

Return True if the passed in state was added to this controller as a handle state.

Parameters:

nextState - the state name to check against

Returns:

true if it is supposed to handle the state.

isPromptState

protected boolean isPromptState(State nextState)

Return True if the passed in state was added to this controller as a prompt state.

Parameters:

nextState - the state name to check against

Returns:

true if it is the prompt state.

loadStateForm

protected StateForm loadStateForm(State nextState,
                                  org.apache.struts.action.ActionForm controllerForm)
                           throws ControllerException

Return the state's form with data from the controller's form. The controller's form is specified in the struts config file. The state form is specified in the state's stateFormClass attribute.

Parameters:

nextState - The next state to use

controllerForm - the ControllerForm as specified in the struts config file.

Returns:

a fully instantiated StateForm

Throws:

ControllerException - if there is an error instantiating the State Form

newState

public ControllerResponse newState(String newState,
                                   ControllerRequest myRequest)
                            throws ControllerException,
                                   NonHandleableException

This is the method where all of the real work of the controller is done. The client calls this to indicate what state the controller is transitioning into.

This is normally what is called from the command line when driving a Controller object. If running in a struts environment, this function call is wrapped by execute() method which does the actual running, plus then performs tasks such as finding the next forward etc.

Parameters:

newState - The new state to transition to

myRequest - The calling controllerRequest object.

Returns:

a newly instantiated ControllerResponse for this state.

Throws:

ControllerException - on Error

NonHandleableException - if the error should not be handled by an error controller

prePerform

protected void prePerform(State nextState,
                          ControllerRequest request,
                          ControllerResponse response)
                   throws ControllerException

Template Method, allowing a subclass to do an action after any state in this controller is performed. For example, a common header for the web pages could be created here, so long as the web pages in question, with the common header, were all in the same controller which overrides this method.

Parameters:

nextState - the state to be performed

request - the request object

response - the response object

Throws:

ControllerException

postPerform

protected void postPerform(State nextState,
                           ControllerRequest request,
                           ControllerResponse response)
                    throws ControllerException

Template Method, allowing a subclass to into actions after the invocation of any state in this controller. For example, a common footer for web pages could be created here, so long as the web pages in question, with the common footer, were all in the same controller which overrides this method. (Multiple controllers which need common pre/post actions could share a common superclass.)

Parameters:

nextState - the state to be performed

request - the request object

response - the response object

Throws:

ControllerException

nextHandleState

protected String nextHandleState(State nextState)

Return the name of the handle state that is associated with the passed in prompt state. Null will be returned if the passed in state is not a prompt state.

Parameters:

nextState - the next state to check against

Returns:

the name of the 'handle' state paired with the nextState parameter

nextPromptState

protected String nextPromptState(State nextState)

Return the name of the prompt state that is 'next' to the passed in prompt state in the sequence for this controller. If the passed in state is the last prompt state in this controller then null will be returned.

Parameters:

nextState - the next state to check against

Returns:

the name of the 'prompt' state paired with the nextState parameter

endTimer

protected void endTimer(long beginTimer,
                        HttpServletRequest request)

Used for logging time of requests.

Parameters:

beginTimer - The start execution time

request - The HTTPServletRequest to instrument

execute

public org.apache.struts.action.ActionForward execute(org.apache.struts.action.ActionMapping mapping,
                                                      org.apache.struts.action.ActionForm form,
                                                      HttpServletRequest request,
                                                      HttpServletResponse response)
                                               throws IOException,
                                                      ServletException

Process the specified HTTP request, and create the corresponding HTTP response (or forward to another web component that will create it). Return an ActionForward instance describing where and how control should be forwarded, or null if the response has already been completed. Note, that if you wish to run a controller within something other than a HTTP session, then call newState directly.

Parameters:

mapping - The ActionMapping used to select this instance

form - The optional ActionForm bean for this request (if any)

request - The HTTP request we are processing

response - The HTTP response we are creating

Returns:

The ActionForward or null

Throws:

IOException - if an input/output error occurs

ServletException - if a servlet exception occurs

getActionForward

protected org.apache.struts.action.ActionForward getActionForward(ServletControllerRequest req,
                                                                  org.apache.struts.config.ActionConfig mapping,
                                                                  ControllerResponse res)
                                                           throws NonHandleableException,
                                                                  ControllerException

Determine the forward appropriate for this controller/state, either from parameters or from configuration files, or from remapping based on past extensions like .xsl

Parameters:

req - the ServletControllerRequest object

mapping - the ActionConfig that defines the mapping

res - the ControllerResponse object that has been handed back to us by Controller.newState()

Returns:

an ActionForward instance.

Throws:

NonHandleableException - upon fatal error

ControllerException - upon error

remapFromExtension

protected org.apache.struts.config.ForwardConfig remapFromExtension(org.apache.struts.config.ForwardConfig fwd,
                                                                    org.apache.struts.config.ActionConfig mapping,
                                                                    ServletControllerRequest req)
                                                             throws ControllerException

if the extension in the current forward is ".xsl" or ".xslt", remap the forward to "xml", and set a parameter for the xsl style sheet. author: Larry Hamel, CodeGuild, Inc.

Parameters:

fwd - The ForwardConfig object

mapping - the ActionConfig for the particular controller instance

req - the ServletControllerRequest for the request.

Returns:

ForwardConfig instance.

Throws:

ControllerException - upon error

redirectRequest

protected void redirectRequest(HttpServletResponse response,
                               String redirectURL)
                        throws IOException

redirect response so that URL changes in client browser

Parameters:

response - The Servlet Response

redirectURL - The URL to redirect the browser to.

Throws:

IOException - upon browser error.

populateStateForm

protected void populateStateForm(StateForm stateForm,
                                 ControllerRequest request)
                          throws ControllerException

Populate the state form with any matching request parameters.

Parameters:

stateForm - The name of the state form to populate

request - The source of the variables for the state form.

Throws:

ControllerException - upon BeanUtils.populate() error

previousPromptState

protected String previousPromptState(State nextState)

Return the name of the prompt state that is 'previous' to the passed in prompt state in the sequence for this controller. If the passed in state is the first prompt state in this controller then null will be returned.

Parameters:

nextState - The state to check against

Returns:

the previous prompt state

processRequestTransitions

protected void processRequestTransitions(State nextState,
                                         ControllerRequest request)
                                  throws ControllerException

This method picks up the following routing parameters from the current request and builds transition objects from them before the state is invoked.

1. "Controller Success" These parameters identify the state that should be run once this controller completes successfully (ie the'final' state has completed without errors). Any controller success parameters will cause this method to put a serialized transition object specific to this controller in session scope.

2. "State Success" These parameters identify the state that should be run if this state completes without errors. Any state success parameters will cause this method to assign a transition object to this currently running state.

3. "State Error" These parameters identify the state that should be run if this state completes with errors. Any state error parameters will cause this method to assign a transition object to this currently running state.

Note, the transition specified at this time can be overridden by the state when it executes.

Parameters:

nextState - the next state to check process

request - The controllerRequest object

Throws:

ControllerException - upon error.

processTransitions

protected Transition processTransitions(ControllerRequest request,
                                        ControllerResponse response,
                                        State nextState)
                                 throws ControllerException,
                                        NonHandleableException

This method is the traffic cop that determines which transition to execute after a state completes.

1. "State Error" The state returned with errors in the error collection. The 'error transition' associated with the state is executed. This transition could have been set either in processRequestTransitions() prior to state execution or in the state itself during execution.

2. "State Success" The state returned without errors in the error collection. The following priority is followed: - If the 'success transition' is not null for this state then it is executed. - If the state that just completed is a final state then: - If the 'chaining transition' is not null for this controller then it is executed. - If the 'controller success transition' is not null for this controller then it is executed.

Parameters:

request - The ControllerRequest Object

response - The ControllerResponse Object

nextState - the state to transition to.

Returns:

An instantiated Transition Object

Throws:

NonHandleableException - upon a fatal error.

ControllerException

setControllerChainingTransition

protected void setControllerChainingTransition(Transition newControllerChainingTransition)
                                        throws NonHandleableException

Set the transition that will be executed when this controller completes successfully. This will not likely be used as often as the runtime 'controller success' routing parameters. However when used, it will relay any 'controller success' parameters onto the next controller so that the return path is not lost.

Parameters:

newControllerChainingTransition - The new transition for when the controller completes successfully.

Throws:

NonHandleableException - upon incorrect parameters.

setControllerSecurityTransition

protected void setControllerSecurityTransition(Transition newControllerSecurityTransition)

Set the transition that will be executed when a user attempts to run a state he doesn't have authorization on. As always, this transition can have return-to-sender enabled. This could allow a login screen to be called and then control would automatically return to the state whose authorization failed.

Parameters:

newControllerSecurityTransition - To execute.

setCurrentState

public ControllerResponse setCurrentState(String newState,
                                          ControllerRequest params)
                                   throws ControllerException,
                                          NonHandleableException

Convenience method to be able to access the state as a property from a JSP.

Parameters:

newState - The newState to set to.

params - The ControllerRequest object

Returns:

a newly instantiated ControllerResponse

Throws:

ControllerException - upon error

NonHandleableException - upon fatal error

setInitialState

public void setInitialState(String newInitialState)

Set what state to invoke if no state parameter is set.

Parameters:

newInitialState - The state to use as the initial state.

setSchema

protected void setSchema(String schemaClass)

Tell this Controller object what Schema it belongs to. This is used when the Controller tries to use it's "getString(String, Object[])" method to prepare internationalized messages - it passes the call along to the appropriate schema which knows how to locate the proper message file.

Parameters:

schemaClass - The classname of the Schema to associate with.

setSchema

protected void setSchema(Class schemaClass)

Identical to setSchema(String) but provides a typesafe way of passing parameters. Example:
setSchema(com.jcorporate.expresso.core.ExpressoSchema .class);

Parameters:

schemaClass - The Class of the schema to set

setupDefaultValues

public void setupDefaultValues(String dbName)
                        throws DBException

Allows for DBCreate to set up proper default values for views, etc.

Parameters:

dbName - the name of the db to add these values to.

Throws:

DBException - upon error

setupReturnToSender

protected void setupReturnToSender(State nextState,
                                   ControllerRequest request)
                            throws ControllerException

This method is called before a state executes. It will assign a return-to-sender transition to the state. This transition will include the parameters that this state is being called with.

If this state causes a transition (with return-to-sender enabled) to be executed, then this state's return-to-sender transition will be serialized and passed to the next controller. This controller will then use this transition (once the controller completes successfull) to return to this state with the same parameters that this state was initally called with.

This method will also check for a request parameter that overrides the return-to-sender transition that would normally be associated with this state. This is useful when the final state reruns all of the controller's handle states. In that case, any transitions should return to the final state and not the handle state that caused the transition.

Parameters:

nextState - = The state that is about to be executed

request - The parsed ControllerRequest object

Throws:

ControllerException - upon error.

stateAllowed

public boolean stateAllowed(String newState,
                            ControllerRequest params)
                     throws ControllerException

Is this state allowed for the current user? The generic controller object can't determine this, but the DBController child of this object checks the database to determine which users can access which states.

Parameters:

newState - The name of the state being checked

params - The ControllerRequestObject

Returns:

True if the state is allowed, else false if it is not

Throws:

ControllerException - upon error

transition

protected void transition(String newState,
                          ControllerRequest req,
                          ControllerResponse res)
                   throws ControllerException,
                          NonHandleableException

Throws:

ControllerException

NonHandleableException

transition

protected void transition(String newState,
                          Class externalController,
                          ControllerRequest req,
                          ControllerResponse res)
                   throws ControllerException,
                          NonHandleableException

convenience method for transition to other controller

Parameters:

newState - the new state to transition to

externalController - the class of the external controller

req - the ControllerRequest parameter that the state handler has

res - the ControllerResponse object that was passed to your state method

Throws:

ControllerException - upon error

NonHandleableException - upon fatal error

transition

protected void transition(String newState,
                          ControllerRequest req,
                          ControllerResponse res,
                          boolean clear)
                   throws ControllerException,
                          NonHandleableException

Transition to an internal state. By internal state we mean that this method is used for transitioning to another 'state' inside the same controller class [inherited states not withstanding]. You cannot, however use this method to transfer control between controllers

Parameters:

newState - the state to transition to

req - The ControllerRequest object that has been given your state handler

res - The ControllerResponse object that has been given to your state handler

clear - Should existing ControllerElements (Input/Output/Block/Transition) be removed from the resulting ControllerResponse (set to true if that is the desired behavior)

Throws:

ControllerException - upon error

NonHandleableException - upon fatal error

unloadStateForm

protected void unloadStateForm(StateForm stateForm,
                               org.apache.struts.action.ActionForm controllerForm)
                        throws ControllerException

Move the state's form data back into the controller's form. The controller's form is specified in the struts config file. The state's form is specified in the state's stateFormClass attribute.

Parameters:

stateForm - The stateForm to unload

controllerForm - The associated controllerForm

Throws:

ControllerException - upon error transferring the data between the forms.

redirectRequest

public void redirectRequest(ControllerRequest request,
                            ControllerResponse response,
                            String redirectURL)
                     throws IOException

redirect response so that URL changes in client browser

Parameters:

request - The ControllerRquest object.

response - The ControllerResponse object

redirectURL - The URL to redirect the browser to.

Throws:

IOException - upon redirect error.

getLogger

public org.apache.log4j.Logger getLogger()

Call from subclass to log into Category with subclass name will create logger with subclass name as necessary.

Returns:

org.apache.logj.Logger

setupSubclassLog

protected void setupSubclassLog()

setup a subclass logger separately from the base controller logger. Is this right? *PP*

generateToken

protected String generateToken(ControllerRequest request)

Generate a new transaction token, to be used for enforcing a single request for a particular transaction.

Thanks to "Raul DAVIDOVICH" (R.DAVIDOVICH@caconcology.com)

Parameters:

request - The request we are processing

Returns:

transaction token usually cryptographically created

isTokenValid

protected boolean isTokenValid(ControllerRequest request)

Return true if there is a transaction token stored in the user's current session, and the value submitted as a request parameter with this action matches it. Returns false under any of the following circumstances:

• No session associated with this request
• No transaction token saved in the session
• No transaction token included as a request parameter
• The included transaction token value does not match the transaction token in the user's session

Parameters:

request - The servlet request we are processing

Returns:

boolean value if the request transaction token matched the stored transaction token.

See Also:

generateToken(com.jcorporate.expresso.core.controller.ControllerRequest), resetToken(com.jcorporate.expresso.core.controller.ControllerRequest), saveToken(com.jcorporate.expresso.core.controller.ControllerRequest)

resetToken

protected void resetToken(ControllerRequest request)

Reset the saved transaction token in the user's session. This indicates that transactional token checking will not be needed on the next request that is submitted.

Parameters:

request - The servlet request we are processing

See Also:

saveToken(com.jcorporate.expresso.core.controller.ControllerRequest), isTokenValid(com.jcorporate.expresso.core.controller.ControllerRequest)

saveToken

protected void saveToken(ControllerRequest request)

Save a new transaction token in the user's current session, creating a new session if necessary.

Parameters:

request - The servlet request we are processing

See Also:

resetToken(com.jcorporate.expresso.core.controller.ControllerRequest), isTokenValid(com.jcorporate.expresso.core.controller.ControllerRequest)

getParamValues

public static String[] getParamValues(ServletControllerRequest request,
                                      String paramName)

Fetches array of parameter values from underlying HTTP request; use this in a web app to access the underlying parameters in the HTTP request which have the same name; parameters with the same name are not reflected in the hashtable maintained by ControllerRequest;

Parameters:

request - cast ControllerRequest to get required type

paramName - key to look for among all parameters

Returns:

an array of String objects containing all of the values the given request parameter has, or null if the parameter does not exist.