org.scopemvc.controller.servlet
Class ScopeServlet

java.lang.Object
  |
  +--javax.servlet.GenericServlet
        |
        +--javax.servlet.http.HttpServlet
              |
              +--org.scopemvc.controller.servlet.ScopeServlet

All Implemented Interfaces:

java.io.Serializable, javax.servlet.Servlet, javax.servlet.ServletConfig

Direct Known Subclasses:

JSPScopeServlet, XSLScopeServlet

public abstract class ScopeServlet

extends javax.servlet.http.HttpServlet

Base class for a web app's servlet dispatcher: subclass this to implement application startup and initialisation (use a static initializer). This class accepts incoming requests, collects the parameters into a mutable HashMap, parses them to create a Control and to find a ViewID to identify the View the user interacted with. The request parameters are then passed to the View to populate its Model, before the View issues the Control for the owning Controller to handle.

A configurable number of Application Controllers (and sub-Controllers and their Views and Models) are created on the first request. These are put into a pool to be shared between all future requests. For this reason, Controllers that are shared must be aware of the possible need to reset their model's state before handling a Control.

A form request is handled as follows:

Most steps in this sequence are implemented by Template Methods that can be overridden to change the default behaviour.

The issue of session state management and model scope is not resolved here.

See the various XML/XSLT and JSP servlet samples for examples of use.

Version:

$Revision: 1.16 $ $Date: 2002/09/06 16:11:48 $

Author:

Steve Meyfroidt

See Also:

ServletContext, XSLScopeServlet, JSPScopeServlet, Serialized Form

Nested Class Summary

protected class

ScopeServlet.SharedControllerFactory

Field Summary

static java.lang.String	CONTROL_PARAM The key used to identify the Control ID in the request parameters for this implementation.
protected ObjectPool	sharedControllerPool Pool of shared application Controllers for this servlet instance.
static java.lang.String	VALIDATION_FAILURES The default validation error handler in handleValidationFailures(org.scopemvc.view.servlet.Page, java.util.List) puts the list of ValidationFailures in the properties of the ViewContext under this key for later retrieval by a Controller.
static java.lang.String	VIEW_ID_PARAM The request's key that identifies the View ID used to find the active View that a Control was sent from.

Constructor Summary

ScopeServlet()
Constructor for the ScopeServlet object

Method Summary

protected abstract Controller	createApplicationController() Override this to create the root application Controller.
protected Control	createControl(java.util.HashMap ioFormParameters) Return a Control instance from request form parameters getting the Control ID from the CONTROL_PARAM form value, and setting the formParameters HashMap as the Control's parameter.
protected abstract ServletContext	createServletContext(javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse resp, java.util.HashMap inFormParameters) Create a ViewContext that will be used for a request: default impl here returns a new ServletContext.
protected void	doGet(javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse resp) This implementation maps GET requests onto POST requests.
protected void	doPost(javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse resp) Default implementation uses shared application instances.
protected Page	findDefaultPage(Controller inRootController) If the request ViewID doesn't match any Page then this provides a default Page: could be the start page of the application that the user gets to by invoking the servlet with no parameters.
protected Page	findPageByID(Controller inRootController, java.lang.String inViewID) Search through application's Controller hierarchy to find a Page matching the ViewID.
protected java.lang.String	findViewID(java.util.HashMap inParameters) Could be overidden to provide a default ViewID if none in the parameters, but also see getFormParameters(javax.servlet.http.HttpServletRequest).
protected java.util.HashMap	getFormParameters(javax.servlet.http.HttpServletRequest inRequest) Copy references to all form parameters into a mutable Map.
protected void	handleRequest(java.util.HashMap formParameters)
protected boolean	handleValidationFailures(Page inPage, java.util.List inFailures) Called if an exception is thrown by Page.populateModel.
protected void	initSharedControllerPool()
static void	redirect(java.util.HashMap inFormParameters) Call from a Controller instead of showing a View to force an internal redirect.

Methods inherited from class javax.servlet.http.HttpServlet

doDelete, doOptions, doPut, doTrace, getLastModified, service, service

Methods inherited from class javax.servlet.GenericServlet

destroy, getInitParameter, getInitParameterNames, getServletConfig, getServletContext, getServletInfo, getServletName, init, init, log, log

Methods inherited from class java.lang.Object

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

Field Detail

VALIDATION_FAILURES

public static final java.lang.String VALIDATION_FAILURES

The default validation error handler in handleValidationFailures(org.scopemvc.view.servlet.Page, java.util.List) puts the list of ValidationFailures in the properties of the ViewContext under this key for later retrieval by a Controller.

See Also:

Constant Field Values

CONTROL_PARAM

public static java.lang.String CONTROL_PARAM

The key used to identify the Control ID in the request parameters for this implementation. Initialised from the "org.scopemvc.controller.servlet.ScopeServlet.ControlParam" value from ScopeConfig.

See Also:

createControl(java.util.HashMap)

VIEW_ID_PARAM

public static java.lang.String VIEW_ID_PARAM

The request's key that identifies the View ID used to find the active View that a Control was sent from. Initialised from the "org.scopemvc.controller.servlet.ScopeServlet.ViewIDParam" value of ScopeConfig.

See Also:

findPageByID(org.scopemvc.core.Controller, java.lang.String)

sharedControllerPool

protected ObjectPool sharedControllerPool

Pool of shared application Controllers for this servlet instance.

Constructor Detail

ScopeServlet

public ScopeServlet()

Constructor for the ScopeServlet object

Method Detail

redirect

public static void redirect(java.util.HashMap inFormParameters)

Call from a Controller instead of showing a View to force an internal redirect. Pass a HashMap of form parameters for the new request.

Parameters:

inFormParameters - TODO: Describe the Parameter

getFormParameters

protected java.util.HashMap getFormParameters(javax.servlet.http.HttpServletRequest inRequest)

Copy references to all form parameters into a mutable Map. If a parameter has multiple values then the parameter value will be a String[] else a String.

This is a useful place to insert default values for missing parameters, for example to map .../servlet/MyServlet onto some default "action" and "view" by inserting those default parameters into the returned HashMap if missing in incoming request.

Parameters:

inRequest - find parameters in this request

Returns:

Map containing references to all form parameters, either String or String[] if multiple values.

doGet

protected void doGet(javax.servlet.http.HttpServletRequest req,
                     javax.servlet.http.HttpServletResponse resp)
              throws javax.servlet.ServletException,
                     java.io.IOException

This implementation maps GET requests onto POST requests.

Overrides:

doGet in class javax.servlet.http.HttpServlet

Parameters:

req - TODO: Describe the Parameter

resp - TODO: Describe the Parameter

Throws:

javax.servlet.ServletException - TODO: Describe the Exception

java.io.IOException - TODO: Describe the Exception

doPost

protected void doPost(javax.servlet.http.HttpServletRequest req,
                      javax.servlet.http.HttpServletResponse resp)
               throws javax.servlet.ServletException,
                      java.io.IOException

Default implementation uses shared application instances.

Overrides:

doPost in class javax.servlet.http.HttpServlet

Parameters:

req - TODO: Describe the Parameter

resp - TODO: Describe the Parameter

Throws:

javax.servlet.ServletException - TODO: Describe the Exception

java.io.IOException - TODO: Describe the Exception

handleRequest

protected void handleRequest(java.util.HashMap formParameters)

Parameters:

formParameters - TODO: Describe the Parameter

createServletContext

protected abstract ServletContext createServletContext(javax.servlet.http.HttpServletRequest req,
                                                       javax.servlet.http.HttpServletResponse resp,
                                                       java.util.HashMap inFormParameters)

Create a ViewContext that will be used for a request: default impl here returns a new ServletContext. For example to implement your own error handling, extend the default ServletContext to override showError, and then override this method in your servlet subclass to create an instance of your own ServletContext.

Parameters:

req - TODO: Describe the Parameter

resp - TODO: Describe the Parameter

inFormParameters - TODO: Describe the Parameter

Returns:

TODO: Describe the Return Value

createControl

protected Control createControl(java.util.HashMap ioFormParameters)

Return a Control instance from request form parameters getting the Control ID from the CONTROL_PARAM form value, and setting the formParameters HashMap as the Control's parameter. Also handles imagemap requests of the form imagename.x=ControlId.

Override this for an application to create a default Control when none is supplied in the request, eg for a simple home request:

http://localhost:8080/myapp/MyServlet

with no parameters to display the application's home page. But also see getFormParameters(javax.servlet.http.HttpServletRequest).

Parameters:

ioFormParameters - request's form parameters.

Returns:

Control instance created from the form parameters

findViewID

protected java.lang.String findViewID(java.util.HashMap inParameters)

Could be overidden to provide a default ViewID if none in the parameters, but also see getFormParameters(javax.servlet.http.HttpServletRequest).

Parameters:

inParameters - TODO: Describe the Parameter

Returns:

TODO: Describe the Return Value

findPageByID

protected Page findPageByID(Controller inRootController,
                            java.lang.String inViewID)

Search through application's Controller hierarchy to find a Page matching the ViewID. Return null if not found.

Parameters:

inRootController - TODO: Describe the Parameter

inViewID - TODO: Describe the Parameter

Returns:

TODO: Describe the Return Value

findDefaultPage

protected Page findDefaultPage(Controller inRootController)

If the request ViewID doesn't match any Page then this provides a default Page: could be the start page of the application that the user gets to by invoking the servlet with no parameters. Here returns the first Page found by a depth-first traversal of the application hierarchy.

If you manage the getFormParameters(javax.servlet.http.HttpServletRequest) method to validate form parameters then this method might never be used. But if there's a single page that you want to use when an invalid ViewID is passed (eg an error page) then this is the place to do it.

Don't like this. Should be allowed to redirect to an error handler on invalid ViewID? *****

Parameters:

inRootController - TODO: Describe the Parameter

Returns:

TODO: Describe the Return Value

handleValidationFailures

protected boolean handleValidationFailures(Page inPage,
                                           java.util.List inFailures)

Called if an exception is thrown by Page.populateModel.

Default implementation here puts the List of ValidationFailures into the ViewContext under the VALIDATION_FAILURES key for retrieval (ViewContext.getProperty(java.lang.String) and handling by Controllers, ie:

 protected void doSomeHandler() throws ControlException {
   List validationFailures = (List)ViewContext.getViewContext().getProperty(ScopeServlet.VALIDATION_FAILURES);
   if (validationFailures != null) {
     // TODO: Handle the validation failures
   } else {
     // TODO: No validation failures so handle the control
   }
 }
 

Parameters:

inPage - TODO: Describe the Parameter

inFailures - TODO: Describe the Parameter

Returns:

true if this handler has finished the request, ie the normal request handler can stop immediately.

createApplicationController

protected abstract Controller createApplicationController()
                                                   throws java.lang.Exception

Override this to create the root application Controller. The application Controller should setup any child Controllers that it needs to handle parts of the application for it.

Returns:

new application Controller

Throws:

java.lang.Exception - on any failure

initSharedControllerPool

protected void initSharedControllerPool()
                                 throws java.lang.Exception

Throws:

java.lang.Exception - TODO: Describe the Exception