com.jcorporate.expresso.core.controller
Class Transition

java.lang.Object
  com.jcorporate.expresso.core.controller.ControllerElement
      com.jcorporate.expresso.core.controller.Transition

All Implemented Interfaces:

Cloneable, Serializable

public class Transition

extends ControllerElement

implements Cloneable, Serializable

An Transition is a choice that the user can make that initiates either another sequence in this same controller or some new controller. A transition is one of the three types of objects that a controller produces when it enters a new state, the others being Input objects and Output objects.

Another use of a Transition object is for internal transitioning between various controllers and their states. Typical example is as follows:

 Transition t = new Transition();
 t.setControllerObject(com.myapp.MyController.class);
 t.setState("State2");
 t.addParameter("SampleParam","This is a parameter value");
 return t.transition();
 

Recognized Attributes:

The following types are recognized by the expresso framework and automatically rendered: You may add your own types or ignore them if you are doing your own page rendering.

header: Renders the transition in the jc-header class style

image: Renders the transition as a clickable 'picture' Must use setImageURL to be set properly. If what's specified is simply the name, then the default renderers will look in the images directory for the appropriate icon.

button: Renders the transition as a button.

default behavior: Renders as a clickable button

Copyright 1999-2002 Jcorporate Ltd.

See Also:

Serialized Form

Constructor Summary

Transition()
Default Constructor.

Transition(String label, Class controllerClass, String controllerState)
Convenience method to allow for one line of code to construct a transition.

Transition(String newState, Controller myController)
Convenience method to transition to another state in this same controller.

Transition(String newLabel, String newObject)
Convenience constructor to create an action with a label and a controller already set.

Transition(String name, String label, Class controllerClass, String controllerState)
Convenience method to allow for one line of code to construct a transition.

Transition(String newName, String newLabel, String newObject)
Convenience constructor to create an action with a label and a controller already set.

Method Summary

void	addParam(String paramCode, String paramValue) Adds a parameter to a transition.
Object	clone() Returns a copy of itself
void	enableReturnToSender(ControllerResponse response) Call this method when the state/controller being transitioned to should return control back to the calling state once it has 'completed' successfully.
static ControllerElement	fromXML(org.w3c.dom.Node n) Return a controller element based upon the xml fragment
static Transition	fromXML(String newTransition) Return a Transition based upon the String based xml fragment
String	getControllerObject() Return the name of the controller object that this Transition referred to.
String	getFullUrl() Similar to getURL but also includes the context path.
String	getHTMLParamString() Returns a hidden form field string that is safe in either the GET or POST case.
String	getMapping() This function returns the mapping of the Struts action (including the .do part) but without a context prepended to the mapping.
String	getOwnerController() Sets the controller that created this transition.
String	getParam(String paramCode) Return the value for a specific parameter for this transition object.
Hashtable	getParams() Return the hashtable of parameters for this transition object.
String	getParamString() Return a string of the current params This is NOT URL encoded string.
String	getParamString(boolean includeControllerParameter)
HttpServletResponse	getServletResponse() Gets an underlying ServletResponse if it has been set either through setting the controller response or manually
String	getState() Retrieve the currently set state
String	getTheUrl(boolean resolveControllerReference) Internal use for retrieving the URL that this transition points to.
String	getUrl() Returns a URL reference for this transition.
boolean	isExternalTransition(String runningController) Returns True if the destination for this transition is a different controller from the one currently active.
boolean	isRecursiveTransition(String runningState, String runningController) Returns True if the destination for this transition is the same as the currently active state.
boolean	isReturnToSenderEnabled() Return the return-to-sender flag.
protected ControllerResponse	newStateDispatch(ControllerRequest request) This method invokes a new controller by dispatching to it rather than calling it directly.
void	redirectTransition(ControllerRequest request, ControllerResponse response) Transition to a new controller and state by issuing a Redirect request to the browser.
void	setControllerObject(Class c) Mor Typesafe way of setting the controller object.
void	setControllerObject(String newObject) Set the Controller that this action referrs to
void	setControllerResponse(ControllerResponse newResponse) Override of the normal setControllerResponse so that the HttpServletResponse is also set for this particular transition.
void	setOwnerController(String newController) Sets the controller that created this transition.
void	setParams(Hashtable newParams) Set this transition's parameters to the passed in collection.
void	setReturnToSenderParms(ControllerRequest newReturnToSenderRequest) This method will take the request parameters that were passed to this state and will copy them into this transition's parameters.
void	setServletResponse(HttpServletResponse servletResponse) Low level, sets the servlet response.
void	setState(String newState) Sets the target state to transition to.
FastStringBuffer	toXML(FastStringBuffer stream) Convert the object to an xml fragment.
ControllerResponse	transition(ControllerRequest req, ControllerResponse res) Run this transition - e.g. transition to the new state of the specified controller object immediately, setting the specified response to the response of this new controller/state, discarding any previous response
ControllerResponse	transition(ControllerRequest req, ControllerResponse res, boolean clear) Run this transition - e.g. transition to the new state of the specified controller object immediately, setting the specified response to the response of this new controller/state, discarding any previous response (if "clear" is specified) NB: all parameters in the original request are discarded, except those that are explicit params added to this Transition.

Methods inherited from class com.jcorporate.expresso.core.controller.ControllerElement

addNested, allNested, fromXML, getAttribute, getAttributes, getAttributesOrNull, getContent, getContents, getControllerResponse, getDescription, getDisplayLength, getLabel, getLines, getName, getNested, getNested, getNestedCount, getNestedIterator, getNestedMap, getNestedOrNull, getParent, getTitle, getType, remove, removeNested, setAttribute, setDescription, setDisplayLength, setLabel, setLines, setName, setParent, setType

Methods inherited from class java.lang.Object

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

Constructor Detail

Transition

public Transition()

Default Constructor. Normally you don't use this.

Transition

public Transition(String newState,
                  Controller myController)

Convenience method to transition to another state in this same controller.

Parameters:

newState - the new name of the state.

myController - An instantiated Controller object. Use a ControllerFactory to instantiate the controller if you must use this constructor.

Transition

public Transition(String newLabel,
                  String newObject)

Convenience constructor to create an action with a label and a controller already set.

Parameters:

newLabel - Label for the new action

newObject - The name of the object this action referred to

Transition

public Transition(String newName,
                  String newLabel,
                  String newObject)

Convenience constructor to create an action with a label and a controller already set.

Parameters:

newName - Name of this Transition object

newLabel - Label for the new action

newObject - The name of the Controller object this action referred to

Transition

public Transition(String name,
                  String label,
                  Class controllerClass,
                  String controllerState)

Convenience method to allow for one line of code to construct a transition.

Parameters:

name - The name of the transition

label - The label to use for the transition

controllerClass - The Class of the controller to use

controllerState - The name of the controller's state.

Transition

public Transition(String label,
                  Class controllerClass,
                  String controllerState)

Convenience method to allow for one line of code to construct a transition. The (internal) name of the transition will be the state name.

Parameters:

label - The label to use for the transition

controllerClass - The Class of the controller to use

controllerState - The name of the controller's state.

Method Detail

addParam

public void addParam(String paramCode,
                     String paramValue)

Adds a parameter to a transition. These parameters are meant to be eventually consumed by the target controller via the request.getParameter() method.

Parameters:

paramCode - The code name of the parameter

paramValue - The value for the paramter

setState

public void setState(String newState)

Sets the target state to transition to.

Parameters:

newState - java.lang.String

getState

public String getState()

Retrieve the currently set state

Returns:

java.lang.String

clone

public Object clone()
             throws CloneNotSupportedException

Returns a copy of itself

Overrides:

clone in class ControllerElement

Returns:

a cloned and instantiated Transition object.

Throws:

CloneNotSupportedException - as required by the method signature.

enableReturnToSender

public void enableReturnToSender(ControllerResponse response)
                          throws ControllerException

Call this method when the state/controller being transitioned to should return control back to the calling state once it has 'completed' successfully. Th 'completion' point depends on whether the transition is to an external (new controller) or internal state. For external transitions, the completion point is once the Final state has run successfully. For internal transitions, the completion point is once the called state has run successfully. When this method is called with a non-null response parameter, this indicates the currently running state should be the return address. If this method is called with a null response parameter then this indicates that the return address should be determined at transition execution time. This is useful/necessary when a transition is instantiated outside the scope of a state execution. For example, when the controllerSecurityTransition value is set in the controller constructor, the return state is not known/active.

Parameters:

response - the ControllerResponse object

Throws:

ControllerException - upon error

isExternalTransition

public boolean isExternalTransition(String runningController)

Returns True if the destination for this transition is a different controller from the one currently active.

Parameters:

runningController - the name of the controller we're currently in. Usually you would use this.getClass().getName() within your own controller as a parameter.

Returns:

true if this is a transition to a another controller.

getControllerObject

public String getControllerObject()

Return the name of the controller object that this Transition referred to. If this is null, then it refers to the same controller object (e.g. intra-controller transition)

Returns:

The class name of the controller object this action referrs to.

getOwnerController

public String getOwnerController()

Sets the controller that created this transition. If controllerObject equals owner controller, then no controller= parameter is generated.

Returns:

the owner controller

getParam

public String getParam(String paramCode)

Return the value for a specific parameter for this transition object.

Parameters:

paramCode - The code (name) of the parameter

Returns:

The value of the parameter as a string

getParams

public Hashtable getParams()

Return the hashtable of parameters for this transition object. These parameters are to be handed to the new controller when the action is called.

Returns:

A hashtable of name/value pairs for the parameters

getParamString

public String getParamString(boolean includeControllerParameter)

getParamString

public String getParamString()

Return a string of the current params This is NOT URL encoded string. Use either getUrl() OR java.net.URLEncoder() to do this job.

Returns:

java.lang.String

newStateDispatch

protected ControllerResponse newStateDispatch(ControllerRequest request)
                                       throws ControllerException,
                                              NonHandleableException

This method invokes a new controller by dispatching to it rather than calling it directly. This is required when transitioning to external states so that Struts can setup the controller form. The currently active controller request is passed to the new state to simulate a direct call to the state. The request is then picked up by the controller's perform method. Any exceptions raised by the target state will filter back here to be passed on. This approach was needed in order to simulate a direct call the the state while at the same time allowing Struts to setup the controller form.

Parameters:

request - the ControllerRequest Object

Returns:

an instantiated ControllerResponse object

Throws:

ControllerException

NonHandleableException

isRecursiveTransition

public boolean isRecursiveTransition(String runningState,
                                     String runningController)

Returns True if the destination for this transition is the same as the currently active state. Avoid infinite loop.

Parameters:

runningState - the current state

runningController - the current controller

Returns:

true if we're recusing to the same state and controller as we're already in.

isReturnToSenderEnabled

public boolean isReturnToSenderEnabled()

Return the return-to-sender flag.

Returns:

boolean

getHTMLParamString

public String getHTMLParamString()

Returns a hidden form field string that is safe in either the GET or POST case. Creation date: (1/10/01 11:24:00 AM) author: Adam Rossi, PlatinumSolutions

Returns:

java.lang.String

setControllerObject

public void setControllerObject(String newObject)

Set the Controller that this action referrs to

Parameters:

newObject - Name of the Controller object that this Transition refers to

setControllerObject

public void setControllerObject(Class c)

Mor Typesafe way of setting the controller object. Any typos will be caught at compile time. Example usage:

 Transition t = new Transition();
 t.setControllerObject(com.jcorporate.expresso.services.Status.class);
 

Parameters:

c - the class of the controller object to add.

setOwnerController

public void setOwnerController(String newController)

Sets the controller that created this transition. If controllerObject equals owner controller, then no controller= parameter is generated.

Parameters:

newController - the classname of the new controller

setParams

public void setParams(Hashtable newParams)

Set this transition's parameters to the passed in collection.

Parameters:

newParams - the new parameters in bulk

setReturnToSenderParms

public void setReturnToSenderParms(ControllerRequest newReturnToSenderRequest)

This method will take the request parameters that were passed to this state and will copy them into this transition's parameters. These parameters will then be used when this state is reinvoked (return-to-sender) in order to re-establish the parameter context.

Parameters:

newReturnToSenderRequest - The ControllerRequest object

toXML

public FastStringBuffer toXML(FastStringBuffer stream)

Convert the object to an xml fragment.

Overrides:

toXML in class ControllerElement

Parameters:

stream - an instantiated FastStringBuffer to which we append to.

Returns:

a FastStringBuffer object

fromXML

public static Transition fromXML(String newTransition)
                          throws ControllerException

Return a Transition based upon the String based xml fragment

Parameters:

newTransition - an xml fragment

Returns:

an instantiated Transition object

Throws:

ControllerException - upon error

fromXML

public static ControllerElement fromXML(org.w3c.dom.Node n)
                                 throws ControllerException

Return a controller element based upon the xml fragment

Parameters:

n - a DOM Node object

Returns:

an instantiated ControllerElement

Throws:

ControllerException - upon error

getTheUrl

public String getTheUrl(boolean resolveControllerReference)
                 throws ControllerException

Internal use for retrieving the URL that this transition points to.

Parameters:

resolveControllerReference - should the controller be resolved to a mapping or should it just be the request path with a controler equals parameter. True if you want the URL mapped to a .do mapping.

Returns:

java.lang.String

Throws:

ControllerException - if there is an error or there is no controller response object available to help resoolve the reference.

getUrl

public String getUrl()
              throws ControllerException

Returns a URL reference for this transition. The URL does NOT include the context path.

Returns:

java.lang.String

Throws:

ControllerException - upon error

getFullUrl

public String getFullUrl()
                  throws ControllerException

Similar to getURL but also includes the context path. Useful for working with JSTL cout expressions inside an <a> link.

If the ControllerResponse has been set and running in a servlet environment, then this function also encodes the resulting URL with suitable session id's if necessary too

This URL is optimized, so it includes a "controller" param only if the destination controller is different than the controller of the ControllerResponse (if the response is known). For a guaranteed controller param,

Returns:

java.lang.String

Throws:

ControllerException - upon error.

See Also:

getTheUrl(boolean)

getMapping

public String getMapping()
                  throws ControllerException

This function returns the mapping of the Struts action (including the .do part) but without a context prepended to the mapping.

Returns:

java.lang.String

Throws:

ControllerException

transition

public ControllerResponse transition(ControllerRequest req,
                                     ControllerResponse res)
                              throws ControllerException,
                                     NonHandleableException

Run this transition - e.g. transition to the new state of the specified controller object immediately, setting the specified response to the response of this new controller/state, discarding any previous response

Parameters:

req - The ControllerRequest object handed to you by the framework

res - the ControllerResponse object handed to you by the framework

Returns:

the ControllerResponse Object from the called controller

Throws:

ControllerException - upon error

NonHandleableException - upon fatal error

redirectTransition

public void redirectTransition(ControllerRequest request,
                               ControllerResponse response)
                        throws ControllerException

Transition to a new controller and state by issuing a Redirect request to the browser. This can only be used in a Servlet environment, and is mainly useful when you want the URL for the browser to change after a request, so for example, after making an online purchase, you display the invoice, but if the user hit's refresh, you don't want the processing to occur again.

Parameters:

request - The ControllerRequest object handed to you by the framework

response - the ControllerResponse object handed to you by the framework

Throws:

ControllerException

transition

public ControllerResponse transition(ControllerRequest req,
                                     ControllerResponse res,
                                     boolean clear)
                              throws ControllerException,
                                     NonHandleableException

Run this transition - e.g. transition to the new state of the specified controller object immediately, setting the specified response to the response of this new controller/state, discarding any previous response (if "clear" is specified) NB: all parameters in the original request are discarded, except those that are explicit params added to this Transition. Therefore, if you have a param X in the original state, and you need it in the upcoming state, use addParam() to preserve it, OR use the ControllerResponse.setFormCache() to save them before the transition(),

Parameters:

req - The ControllerRequest object handed to you by the framework

res - the ControllerResponse object handed to you by the framework

clear - True clears the response object before adding the outputs from the called controller?

Returns:

the ControllerResponse Object from the called controller

Throws:

ControllerException - upon error

NonHandleableException - upon fatal error

See Also:

and response.getFormCache(paramName) to retrieve them, ControllerResponse.getFormCache(String)

getServletResponse

public HttpServletResponse getServletResponse()

Gets an underlying ServletResponse if it has been set either through setting the controller response or manually

Returns:

HttpServletResponse or NULL if not being used.

setServletResponse

public void setServletResponse(HttpServletResponse servletResponse)

Low level, sets the servlet response. Normally you won't use this function except under specialty situations where you are using a Transition more as a URL generator

Parameters:

servletResponse - a servlet response object for encoding URLs

setControllerResponse

public void setControllerResponse(ControllerResponse newResponse)

Override of the normal setControllerResponse so that the HttpServletResponse is also set for this particular transition.

Overrides:

setControllerResponse in class ControllerElement

Parameters:

newResponse - the controllerResponse to set.