org.scopemvc.controller.basic
Class BasicController

java.lang.Object
  |
  +--org.scopemvc.controller.basic.BasicController

All Implemented Interfaces:

Controller

public abstract class BasicController

extends java.lang.Object

implements Controller

Full implementation of Controller that adds:

• support for a View to notify its parent Controller when its bound model object is replaced with another (implemented completely in SwingView) via the CHANGE_MODEL_CONTROL_ID ControlID. Note that the PropertyView that a top-level Controller owns must not have a Selector set: this is only allowed for child Controllers that are delegated by a parent to handle a subview and associated submodel that is part of the parent model: the binding will be handled by the parent in this case.
• ControlException handling by using ViewContext.showError(java.lang.String, java.lang.String).

To implement a subclass of BasicController:

• implement a constructor to set up the Controller's initial model and View, and to create any child Controllers it may need. setModelAndView(java.lang.Object, org.scopemvc.core.View) may be useful here.
• implement doHandleControl(org.scopemvc.core.Control) to recognise the ID of incoming Controls and respond to them appropriately. For example:

   protected void doHandleControl(Control inControl) throws ControlException {
       if (inControl.matchesID(FOO_CONTROL_ID)) {
           doFoo(inControl.getParameter());
       } else if (inControl.matchesID(BAR_CONTROL_ID)) {
           doBar(inControl.getParameter());
       }
   }
   

• if necessary, implement a startup() method for the Controller to take its initial action (if your application calls startup() on this Controller).
• Internal: if using a View that can dynamically change its bound model, ensure the View sends the appropriate CHANGE_MODEL_CONTROL_ID Control to inform the parent Controller of the change. This is fully implemented in SwingView and is not needed for ServletView with the default implementation in XSLPage.

Version:

$Revision: 1.16 $ $Date: 2002/09/11 19:15:55 $

Author:

Steve Meyfroidt

Field Summary

static java.lang.String	CHANGE_MODEL_CONTROL_ID An internal Control calls changeModel().
static java.lang.String	EXIT_CONTROL_ID A convenience Control that can be used when a Controller wants to exit.
static java.lang.String	HANDLE_CONTROL_RUNTIME_ERROR_MSG_ID ID of error message for RuntimeExceptions caught by BasicController.
static java.lang.String	HIDE_VIEW_CONTROL_ID ID of common Control that is handled by BasicController to hide the current view.

Constructor Summary

BasicController()
Construct subclasses by either using a passed model object and View, or creating new ones.

Method Summary

void	addChild(BasicController inChild) Add a child Controller.
protected void	bindModelToView(View inView, java.lang.Object inModel) Bind a model object to a View if that is possible (model and view must be not null, the view must not have a selector marking it as being handled by a parent view)
protected void	doHandleControl(Control inControl) Custom implementation of some presentation logic.
java.util.List	getChildren() Returns the list of child Controllers.
java.lang.Object	getModel() Return the model bound to this Controller
Controller	getParent() Get the parent of this Controller
Controller	getTopParent() Convenience method.
View	getView() Return the View bound to this Controller.
void	handleControl(Control inControl) Application writers see doHandleControl(org.scopemvc.core.Control).
protected void	handleControlException(ControlException inException) Called by handleControl(org.scopemvc.core.Control) when a Control throws a ControlException.
protected void	hideView() Hide the View bound to this Controller.
protected void	hideView(View inView) Hide the given View
protected void	passControlToParent(Control inControl) Feed a Control to the parent Controller up the chain of command.
void	removeChild(BasicController inChild) Remove a child Controller from this Controller.
void	setModel(java.lang.Object inModel) Sets the model object that this Controller links to its View.
void	setModelAndView(java.lang.Object inModel, View inView) Change to both a new model object and new View, binding the two together properly.
protected void	setParent(BasicController inParent) Hook this Controller into the chain of responsiblity as a child of the passed Controller.
void	setView(View inView) Sets the View that this Controller links to its model object.
protected void	showError(java.lang.String inErrorTitle, java.lang.String inErrorMessage) Convenience to show an error using the current ViewContext.
protected void	showView() Show the view bound to this Controller.
protected void	showView(View inView) Show the given view.
void	shutdown() Shutdown the Controller and its bound View and Model.
void	startup() Starts the Controller and its bound View and Model.

Methods inherited from class java.lang.Object

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

Field Detail

HANDLE_CONTROL_RUNTIME_ERROR_MSG_ID

public static final java.lang.String HANDLE_CONTROL_RUNTIME_ERROR_MSG_ID

ID of error message for RuntimeExceptions caught by BasicController.

See Also:

Constant Field Values

HIDE_VIEW_CONTROL_ID

public static final java.lang.String HIDE_VIEW_CONTROL_ID

ID of common Control that is handled by BasicController to hide the current view.

See Also:

Constant Field Values

CHANGE_MODEL_CONTROL_ID

public static final java.lang.String CHANGE_MODEL_CONTROL_ID

An internal Control calls changeModel(). This is an internal Control to keep Controller's model in sync with the currently shown model in its View. This occurs when a parent controller modifies its model when that contains the submodel managed by a child controller. This is fully implemented by the concrete impl of SwingView. ServletView doesn't need it.

See Also:

Constant Field Values

EXIT_CONTROL_ID

public static final java.lang.String EXIT_CONTROL_ID

A convenience Control that can be used when a Controller wants to exit. For an application Controller this means exitting the application, but for a sub-controller it probably means just an exit from that local area of functionality. This impl causes this Control to propagate up the chain of responsibility so that if unhandled the application will exit.

The parameter of this Control is the Controller that issued it (ie the one that's shutting down), or null if just issued by this. The default impl here propagates the Control up, changing the shutdown Controller as it goes up, until it meets the top of the Controller tree at which point ViewContext.exit() is called: for Swing this does System.exit and for Servlets it is ignored. If you use this Control, recognise it at some parent of the Controller that can issue it, and take appropriate action.

See Also:

Constant Field Values

Constructor Detail

BasicController

public BasicController()

Construct subclasses by either using a passed model object and View, or creating new ones. Use setModel(java.lang.Object) and setView(org.scopemvc.core.View) or setModelAndView(java.lang.Object, org.scopemvc.core.View). Never show a View on construction: initialisation should set the application up without actually starting it by showing a View. An initial startup action implemented in startup() can show a View when called after construction.

Throw a ControlException from subclasses if something goes wrong.

Method Detail

getChildren

public final java.util.List getChildren()

Returns the list of child Controllers.
Used by ScopeServlet.

Returns:

List of child Controllers.

getParent

public final Controller getParent()

Get the parent of this Controller

Specified by:

getParent in interface Controller

Returns:

the parent Controller of this Controller in the chain of command

getModel

public final java.lang.Object getModel()

Return the model bound to this Controller

Specified by:

getModel in interface Controller

Returns:

the model object bound to the View that this Controller maintains

getView

public final View getView()

Return the View bound to this Controller.

Specified by:

getView in interface Controller

Returns:

the View that this Controller maintains

getTopParent

public final Controller getTopParent()

Convenience method.
Get the topmost parent Controller.

Specified by:

getTopParent in interface Controller

Returns:

the topmost parent Controller in the chain of responsibility.

setModel

public final void setModel(java.lang.Object inModel)

Sets the model object that this Controller links to its View. If you need to set both the View and model then use setModelAndView(java.lang.Object, org.scopemvc.core.View) rather than calling setModel and setView separately.

Specified by:

setModel in interface Controller

Parameters:

inModel - The new model value

setView

public final void setView(View inView)

Sets the View that this Controller links to its model object. Unlinks the old View from the current model object and also hides it, however, doesn't show the new view. If you need to set both the View and model object then slightly more efficient in establishing the binding to use setModelAndView(java.lang.Object, org.scopemvc.core.View) rather than calling setModel() and setView() separately.

Specified by:

setView in interface Controller

Parameters:

inView - The new view value

setModelAndView

public final void setModelAndView(java.lang.Object inModel,
                                  View inView)

Change to both a new model object and new View, binding the two together properly. Also disconnect and discard/hide the previous model/View pair.
Slightly more efficient in changing to a new model/view binding than calling setModel and setView separately.

Parameters:

inModel - new model object, can be null

inView - new View, cannot be null

addChild

public final void addChild(BasicController inChild)

Add a child Controller.
The child Controller will use this Controller as its parent.

Parameters:

inChild - The child Controller to add.

removeChild

public final void removeChild(BasicController inChild)

Remove a child Controller from this Controller.
The child Controller will have no more parent.

Parameters:

inChild - The child Controller to remove.

handleControl

public final void handleControl(Control inControl)

Application writers see doHandleControl(org.scopemvc.core.Control). This base implementation handles

• HIDE_VIEW_CONTROL_ID
• the internal CHANGE_MODEL_CONTROL_ID
• EXIT_CONTROL_ID after allowing application code to intercept in doHandleControl. If this Controller has a parent, then hideView and pass it up, else call the ViewContext to do the exit according to context.

Specified by:

handleControl in interface Controller

Parameters:

inControl - The Control to handle

See Also:

handleControl(org.scopemvc.core.Control)

startup

public void startup()

Starts the Controller and its bound View and Model.

Call this method after creating the Controller to make it perform its initial action. This method is not called automatically by Scope, so you have to call it yourself.
Default implementation here just calls showView() if a View is set.

shutdown

public void shutdown()

Shutdown the Controller and its bound View and Model.

Can be called by a parent Controller to shutdown and remove this from the chain of responsibility.
Default implementation does this:

• call shutdown() on every child controller
• call hideView()
• setParent(null)

setParent

protected final void setParent(BasicController inParent)

Hook this Controller into the chain of responsiblity as a child of the passed Controller. See addChild(org.scopemvc.controller.basic.BasicController)

Parameters:

inParent - The new parent value

passControlToParent

protected final void passControlToParent(Control inControl)

Feed a Control to the parent Controller up the chain of command.

Parameters:

inControl - The Control to delegate to the parent Controller

showView

protected final void showView()

Show the view bound to this Controller.

showView

protected final void showView(View inView)

Show the given view.

Parameters:

inView - The View to show

hideView

protected final void hideView()

Hide the View bound to this Controller.

hideView

protected final void hideView(View inView)

Hide the given View

Parameters:

inView - The View to hide

showError

protected final void showError(java.lang.String inErrorTitle,
                               java.lang.String inErrorMessage)

Convenience to show an error using the current ViewContext.

Parameters:

inErrorTitle - The title for the error message window

inErrorMessage - The content of the error message

bindModelToView

protected void bindModelToView(View inView,
                               java.lang.Object inModel)

Bind a model object to a View if that is possible (model and view must be not null, the view must not have a selector marking it as being handled by a parent view)

Parameters:

inView - the View to bind

inModel - the model object to bind to the View

doHandleControl

protected void doHandleControl(Control inControl)
                        throws ControlException

Custom implementation of some presentation logic.

Override this to recognise Controls that this Controller can handle. Any unhandled Controls are passed up the chain of responsibility to parent Controllers.

 protected void doHandleControl(Control inControl) throws ControlException {
     if (inControl.matchesID(FOO_CONTROL_ID)) {
         doFoo(inControl.getParameter());
     } else if (inControl.matchesID(BAR_CONTROL_ID)) {
         doBar(inControl.getParameter());
     }
 }
 

If something goes wrong when running some presentation logic, throw a ControlException which results in a call to handleControlException(org.scopemvc.core.ControlException)).

Parameters:

inControl - The Control to handle

Throws:

ControlException - If something goes wrong when running some presentation logic

handleControlException

protected void handleControlException(ControlException inException)

Called by handleControl(org.scopemvc.core.Control) when a Control throws a ControlException.
This implementation uses the showError(java.lang.String, java.lang.String) method.
A ContolException with a HANDLE_CONTROL_RUNTIME_ERROR_MSG_ID message can be generated when the Controller runs code that throws some unchecked exception.

Parameters:

inException - An exception thrown when something goes wrong with the presentation logic.