org.chwf.servlet
Class Controller

java.lang.Object
  |
  +--org.chwf.servlet.Controller

All Implemented Interfaces:

java.io.Serializable

public class Controller

extends java.lang.Object

implements java.io.Serializable

Superclass for controllers. Consult the documentation for more information about how to write controllers.

Author:

Paul Strack

See Also:

Serialized Form

Field Summary

static java.lang.Object	DEFAULT_NEW_OBJECT Constant indicating that a controller method parameter defaults to a new object, created using Class.newInstance().
static java.lang.Object	DEFAULT_NONE Constant indicating that a controller method parameter has no default.
static java.lang.String	REFERER_PAGE Constant for redirection to the referer page.

Constructor Summary

Controller()

Method Summary

void	addViewParameter(java.lang.String parameter, java.lang.Object value) Sets a parameter for the view redirection.
static Controller	getController(java.lang.Class controllerClass) Factory method to get controller singleton.
java.lang.Throwable	getError() Get the error associated with the controller's invocation, if any.
void	handleError(java.lang.String errorPage, java.lang.Throwable error) Specifies that the system redirect to the error page and pass it the specified error.
void	handleError(java.lang.Throwable error) Specifies that the system redirect to the default error page and pass it the specified error.
boolean	hasError() Return true if the controller invocation has an error.
InvocationContext	initContext() A system method that initializes the controller's invocation context.
void	release() Releases this controller from the user's session.
void	setView(java.lang.String url) Set the view for the controller.
void	setView(java.lang.String url, java.lang.String parameter, java.lang.Object value) Set the view and a single parameter value for the controller.
void	start() A lifecycle method called at the beginning of each controller invocation.
void	stop() A lifecycle method called at the end of each controller invocation.

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_NONE

public static final java.lang.Object DEFAULT_NONE

Constant indicating that a controller method parameter has no default. For single-valued parameters, this means that the parameter is required and its omission will throw a MissingParameterException. For multi-valued parameters, the default value will be an empty array. For boolean values, the default value will be false.

DEFAULT_NEW_OBJECT

public static final java.lang.Object DEFAULT_NEW_OBJECT

Constant indicating that a controller method parameter defaults to a new object, created using Class.newInstance().

REFERER_PAGE

public static final java.lang.String REFERER_PAGE

Constant for redirection to the referer page.

Constructor Detail

Controller

public Controller()

Method Detail

getController

public static Controller getController(java.lang.Class controllerClass)
                                throws RegistryException

Factory method to get controller singleton. This method only works if the user registry is initialized. This is always true for servlet and JSP invoked via Chrysalis.

Parameters:

controllerClass - The controller class.

Returns:

The controller.

Throws:

RegistryException - If the registry is not initialized.

start

public void start()
           throws java.lang.Exception

A lifecycle method called at the beginning of each controller invocation. It can be used to initialize controller resources, like JDBC connections or EJB references.

Throws:

java.lang.Exception - Any exception needed for logic.

stop

public void stop()
          throws java.lang.Exception

A lifecycle method called at the end of each controller invocation. It can be used to release controller resources and rollback transactions. This method is always called, even if there were exceptions during the controller invocation, as if this method were in a finally block.

If there were errors, the getError() method will return the error object. If there were no errors, the hasError() method returns false. This can be used as a test to determine whether to commit or rollback transactions.

 public void stop() throws Exception {
   if(hasError()) {
     transaction.rollback();
   } else {
     transaction.commit();
   }
 }

Throws:

java.lang.Exception - Any exception needed for logic.

setView

public void setView(java.lang.String url)

Set the view for the controller. When the invocation is complete, the system will redirect to this view. The view URL should be a "context-relative" URL. That is, if the URL begins with a "/", it should not include the application's context path. The URL will be resolved relative to the web application root directory. Controllers may call this method if they must manually control view redirection.

Parameters:

url - The URL to redirect to after processing is complete.

setView

public void setView(java.lang.String url,
                    java.lang.String parameter,
                    java.lang.Object value)

Set the view and a single parameter value for the controller. This simplifies the common situation when the controller needs to redirect to a JSP that requires a single parameter:

setView("/showItem.jsp", "itemId", item.getItemId());

This results in the redirection URL:

/{context-path}/showItem.jsp?itemId={itemId}

Parameters:

url - The URL to redirect to after processing is complete.

parameter - The parameter name.

value - The parameter value. This will be converted to a string.

addViewParameter

public void addViewParameter(java.lang.String parameter,
                             java.lang.Object value)

Sets a parameter for the view redirection. This parameter will be appended to the redirection URL. The parameter value will be converted to a String. The parameter name and value will be URL encoded before redirection. This method may be called multiple times to set multiple parameter values:

 addViewParameter("id", productId);
 addViewParameter("showSpecials", "true");

Parameters:

parameter - The parameter name.

value - The parameter value. This will be converted to a string.

handleError

public void handleError(java.lang.Throwable error)

Specifies that the system redirect to the default error page and pass it the specified error. Any specified view will be ignored. This method is an alternative to throwing the exception from the controller method.

Parameters:

error - The error.

handleError

public void handleError(java.lang.String errorPage,
                        java.lang.Throwable error)

Specifies that the system redirect to the error page and pass it the specified error. Any specified view will be ignored. This method lets the controller programmatically control error flow, allowing the controller to use different error pages for different kinds of errors.

Parameters:

errorPage - The error page.

error - The error.

getError

public java.lang.Throwable getError()

Get the error associated with the controller's invocation, if any.

Returns:

The error associated with the controller invocation, or null if there is none.

hasError

public boolean hasError()

Return true if the controller invocation has an error.

Returns:

True if the controller invocation has an error.

release

public void release()
             throws RegistryException

Releases this controller from the user's session. The next time that user invokes this controller class, a new controller object will be created with fresh data.

Throws:

RegistryException - If the registry is not initialized.

initContext

public InvocationContext initContext()

A system method that initializes the controller's invocation context. Developers should not use this method, except for testing purposes.

Returns:

The invocation context.