JavaGantt 2011.1 API

eu.beesoft.gaia.app
Class Controller

java.lang.Object
  extended by eu.beesoft.gaia.app.Controller
Direct Known Subclasses:
FileDownloadController, FormController

public abstract class Controller
extends java.lang.Object

Abstract superclass for all controllers. It supports the basic infrastructure for a controller lifecycle and communication.

Each controller is a singleton. The requested instance can ba accessed by the static method getController(String). Hence there is no space in the controller variables to store user data. For this purpose exists the Context. You can imagine it as a map of {name:value} entries for your free usage.

Each client has just one server Application at the time and just one current Context instance.

When the controller is requested from the client, the Application finds (or creates) its singleton instance via method getController(String). Then Application invokes its method process(ApplicationRequest, Context) to process the client request. Controller prepares the server response (for example data to display in some form) and returns it as the return value from this method.

With the next request (for example, user pressed some button on the form), the Application invokes method forward(ApplicationRequest, Context) on it. This is the standard, unchangeable behavior. The runnning controller should process data from the client before it processes requested action (they are delivered together in one ApplicationRequest instance). The request can be in forward() method forwarded to the other controller, or can be processed in a local method - it is a matter of the implementation or configuration.

If the incoming request is to be forwarded to the other controller, the forward() method first invokes createContextForForward(ApplicationRequest, Controller, Context) to create a new context. Override it to initialize the new context with data from the current context. Then is invoked process(ApplicationRequest, Context) method on the requested controller.

There are two ways to return control to the calling controller:

  1. invoke method returnSuccess(ApplicationResponse, Context) - this invokes method success(ApplicationResponse, Context) on the calling controller, which closes current context and prepares its parent context to be current and itself to be a running controller
  2. invoke method returnFailure(ApplicationResponse, Context) - this invokes method failure(ApplicationResponse, Context) on the calling controller with the same effects as described above

In this class is implementation of methods success() and failure() the same. But it will differ in subclasses. The first indicates that called controller does its work successfully and data are possibly changed. The calling controller should probably update its data. The second method should be used when something goes wrong (for example, an user pressed CANCEL button) and there is no change in data.


Constructor Summary
Controller()
          Default constructor.
 
Method Summary
 void addMapping(java.lang.String source, java.lang.String target)
          Adds new mapping entry to the controller action mapping.
protected  Context createContextForForward(ApplicationRequest request, Controller targetController, Context currentContext)
          Creates a new context with this controller as the starter and given targetController as the runner.
protected  ApplicationResponse failure(ApplicationResponse response, Context context)
          This method is invoked from the running controller, if it returns the control to this controller and action it performed finished with failure.
protected  ApplicationResponse forward(ApplicationRequest request, Context context)
          Forwards given client request with given context to the appropriate controller or local instance method.
static Controller getController(java.lang.String name)
          Returns an instance of the controller with given class name.
 java.util.Map<java.lang.String,java.lang.String> getMapping()
          Returns the map {action name : controller class name} used to forward the client requests.
protected abstract  ApplicationResponse process(ApplicationRequest request, Context context)
          Processes given client request for given context.
protected  ApplicationResponse returnFailure(ApplicationResponse response, Context context)
          Returns the control from this controller to the starter controller of the given context.
protected  ApplicationResponse returnSuccess(ApplicationResponse response, Context context)
          Returns the control from this controller to the starter controller of the given context.
 void setMapping(java.util.Map<java.lang.String,java.lang.String> mapping)
          Replaces the current action mapping with given argument.
protected  ApplicationResponse success(ApplicationResponse response, Context context)
          This method is invoked from the running controller, if it returns the control to this controller and action it performed finished successfully.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Controller

public Controller()
Default constructor.

Method Detail

getController

public static Controller getController(java.lang.String name)
Returns an instance of the controller with given class name. Once created controller is kept in internal map and repeatedly returned in the next calls. Use this method to ensure the controllers as singletons.

Parameters:
name - - qualified class name of the requested controller
Returns:
the controller instance of the given class
Throws:
java.lang.RuntimeException - if requested controller instance cannot be created

getMapping

public java.util.Map<java.lang.String,java.lang.String> getMapping()
Returns the map {action name : controller class name} used to forward the client requests.

Returns:
the action mapping

setMapping

public void setMapping(java.util.Map<java.lang.String,java.lang.String> mapping)
Replaces the current action mapping with given argument.

Parameters:
mapping - - the new mapping to set

addMapping

public void addMapping(java.lang.String source,
                       java.lang.String target)
Adds new mapping entry to the controller action mapping.

Parameters:
source - - the action name
target - - the other controller class or this controller method name

process

protected abstract ApplicationResponse process(ApplicationRequest request,
                                               Context context)
Processes given client request for given context.

Parameters:
request - - a client request
context - - a current application context
Returns:
an application response (never null)

forward

protected ApplicationResponse forward(ApplicationRequest request,
                                      Context context)
Forwards given client request with given context to the appropriate controller or local instance method. This method is invoked on the current controller (that is a runner controller in the current context) when the client requires some action.

It searches local action mapping to find entry that equals to the action name from a client request. If there is no mapping, it uses an action name from the given request.

If it is a controller class name, it creates a new context (see createContextForForward(ApplicationRequest, Controller, Context) and invokes process(ApplicationRequest, Context) method on that controller.

If it is an instance method name, it invokes that method with the given arguments.

Parameters:
request - - a client request
context - - a current application context
Returns:
an application response (never null)
Throws:
java.lang.RuntimeException - if cannot find a mapping for the requested action

createContextForForward

protected Context createContextForForward(ApplicationRequest request,
                                          Controller targetController,
                                          Context currentContext)
Creates a new context with this controller as the starter and given targetController as the runner. Override this method to move to the returned new context some entries from the current context.

Parameters:
request - - action request that requires this forward
targetController - - controller to process given request
currentContext - - the current context
Returns:
newly created context

returnSuccess

protected ApplicationResponse returnSuccess(ApplicationResponse response,
                                            Context context)
Returns the control from this controller to the starter controller of the given context. Invokes its success(ApplicationResponse, Context) method.

Parameters:
response - - response to return
context - - current context
Returns:
response returned by the starter controller

success

protected ApplicationResponse success(ApplicationResponse response,
                                      Context context)
This method is invoked from the running controller, if it returns the control to this controller and action it performed finished successfully. Closes given context.

Parameters:
response - - response to return
context - - current context. Note: this is a context of the calling controller, not this.
Returns:
given response

returnFailure

protected ApplicationResponse returnFailure(ApplicationResponse response,
                                            Context context)
Returns the control from this controller to the starter controller of the given context. Invokes its failure(ApplicationResponse, Context) method.

Parameters:
response - - response to return
context - - current context
Returns:
response returned by the starter controller

failure

protected ApplicationResponse failure(ApplicationResponse response,
                                      Context context)
This method is invoked from the running controller, if it returns the control to this controller and action it performed finished with failure. Closes given context.

Parameters:
response - - response to return
context - - current context. Note: this is a context of the calling controller, not this.
Returns:
given response

JavaGantt 2011.1 API