org.springframework.web.portlet.mvc
Class AbstractController

java.lang.Object
  extended by org.springframework.context.support.ApplicationObjectSupport
      extended by org.springframework.web.portlet.context.PortletApplicationObjectSupport
          extended by org.springframework.web.portlet.handler.PortletContentGenerator
              extended by org.springframework.web.portlet.mvc.AbstractController
All Implemented Interfaces:
Aware, ApplicationContextAware, PortletContextAware, Controller
Direct Known Subclasses:
BaseCommandController, ParameterizableViewController, PortletWrappingController

public abstract class AbstractController
extends PortletContentGenerator
implements Controller

Convenient superclass for controller implementations, using the Template Method design pattern.

As stated in the Controller interface, a lot of functionality is already provided by certain abstract base controllers. The AbstractController is one of the most important abstract base controller providing basic features such controlling if a session is required and render caching.

Workflow (and that defined by interface):

  1. If this is an action request, handleActionRequest will be called by the DispatcherPortlet once to perform the action defined by this controller.
  2. If a session is required, try to get it (PortletException if not found).
  3. Call method handleActionRequestInternal, (optionally synchronizing around the call on the PortletSession), which should be overridden by extending classes to provide actual functionality to perform the desired action of the controller. This will be executed only once.
  4. For a straight render request, or the render phase of an action request (assuming the same controller is called for the render phase -- see tip below), handleRenderRequest will be called by the DispatcherPortlet repeatedly to render the display defined by this controller.
  5. If a session is required, try to get it (PortletException if none found).
  6. It will control caching as defined by the cacheSeconds property.
  7. Call method handleRenderRequestInternal, (optionally synchronizing around the call on the PortletSession), which should be overridden by extending classes to provide actual functionality to return ModelAndView objects. This will be executed repeatedly as the portal updates the current displayed page.

Exposed configuration properties (and those defined by interface):

name default description
requireSession false whether a session should be required for requests to be able to be handled by this controller. This ensures, derived controller can - without fear of Nullpointers - call request.getSession() to retrieve a session. If no session can be found while processing the request, a PortletException will be thrown
synchronizeOnSession false whether the calls to handleRenderRequestInternal and handleRenderRequestInternal should be synchronized around the PortletSession, to serialize invocations from the same client. No effect if there is no PortletSession.
cacheSeconds -1 indicates the amount of seconds to specify caching is allowed in the render response generatedby this request. 0 (zero) will indicate no caching is allowed at all, -1 (the default) will not override the portlet configuration and any positive number will cause the render response to declare the amount indicated as seconds to cache the content
renderWhenMinimized false whether should be rendered when the portlet is in a minimized state -- will return null for the ModelandView when the portlet is minimized and this is false

TIP: The controller mapping will be run twice by the PortletDispatcher for action requests -- once for the action phase and again for the render phase. You can reach the render phase of a different controller by simply changing the values for the criteria your mapping is using, such as portlet mode or a request parameter, during the action phase of your controller. This is very handy since redirects within the portlet are apparently impossible. Before doing this, it is usually wise to call clearAllRenderParameters and then explicitly set all the parameters that you want the new controller to see. This avoids unexpected parameters from being passed to the render phase of the second controller, such as the parameter indicating a form submit ocurred in an AbstractFormController.

Thanks to Rainer Schmitz and Nick Lothian for their suggestions!

Since:
2.0
Author:
John A. Lewis, Juergen Hoeller
See Also:
ResourceAwareController, EventAwareController

Field Summary
 
Fields inherited from class org.springframework.context.support.ApplicationObjectSupport
logger
 
Constructor Summary
AbstractController()
           
 
Method Summary
 void handleActionRequest(ActionRequest request, ActionResponse response)
          Process the action request.
protected  void handleActionRequestInternal(ActionRequest request, ActionResponse response)
          Subclasses are meant to override this method if the controller is expected to handle action requests.
 ModelAndView handleRenderRequest(RenderRequest request, RenderResponse response)
          Process the render request and return a ModelAndView object which the DispatcherPortlet will render.
protected  ModelAndView handleRenderRequestInternal(RenderRequest request, RenderResponse response)
          Subclasses are meant to override this method if the controller is expected to handle render requests.
 boolean isRenderWhenMinimized()
          Return whether controller will render when portlet is minimized.
 boolean isSynchronizeOnSession()
          Return whether controller execution should be synchronized on the session.
 void setRenderWhenMinimized(boolean renderWhenMinimized)
          Set if the controller should render an view when the portlet is in a minimized window.
 void setSynchronizeOnSession(boolean synchronizeOnSession)
          Set if controller execution should be synchronized on the session, to serialize parallel invocations from the same client.
 
Methods inherited from class org.springframework.web.portlet.handler.PortletContentGenerator
applyCacheSeconds, cacheForSeconds, check, checkAndPrepare, checkAndPrepare, getCacheSeconds, isRequireSession, preventCaching, setCacheSeconds, setRequireSession
 
Methods inherited from class org.springframework.web.portlet.context.PortletApplicationObjectSupport
getPortletContext, getTempDir, isContextRequired, setPortletContext
 
Methods inherited from class org.springframework.context.support.ApplicationObjectSupport
getApplicationContext, getMessageSourceAccessor, initApplicationContext, initApplicationContext, requiredContextClass, setApplicationContext
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

AbstractController

public AbstractController()
Method Detail

setSynchronizeOnSession

public final void setSynchronizeOnSession(boolean synchronizeOnSession)
Set if controller execution should be synchronized on the session, to serialize parallel invocations from the same client.

More specifically, the execution of the handleActionRequestInternal method will get synchronized if this flag is "true". The best available session mutex will be used for the synchronization; ideally, this will be a mutex exposed by HttpSessionMutexListener.

The session mutex is guaranteed to be the same object during the entire lifetime of the session, available under the key defined by the SESSION_MUTEX_ATTRIBUTE constant. It serves as a safe reference to synchronize on for locking on the current session.

In many cases, the PortletSession reference itself is a safe mutex as well, since it will always be the same object reference for the same active logical session. However, this is not guaranteed across different servlet containers; the only 100% safe way is a session mutex.

See Also:
handleActionRequestInternal(javax.portlet.ActionRequest, javax.portlet.ActionResponse), HttpSessionMutexListener, PortletUtils.getSessionMutex(javax.portlet.PortletSession)

isSynchronizeOnSession

public final boolean isSynchronizeOnSession()
Return whether controller execution should be synchronized on the session.


setRenderWhenMinimized

public final void setRenderWhenMinimized(boolean renderWhenMinimized)
Set if the controller should render an view when the portlet is in a minimized window. The default is false.

See Also:
PortletRequest.getWindowState(), WindowState.MINIMIZED

isRenderWhenMinimized

public final boolean isRenderWhenMinimized()
Return whether controller will render when portlet is minimized.


handleActionRequest

public void handleActionRequest(ActionRequest request,
                                ActionResponse response)
                         throws Exception
Description copied from interface: Controller
Process the action request. There is nothing to return.

Specified by:
handleActionRequest in interface Controller
Parameters:
request - current portlet action request
response - current portlet action response
Throws:
Exception - in case of errors

handleRenderRequest

public ModelAndView handleRenderRequest(RenderRequest request,
                                        RenderResponse response)
                                 throws Exception
Description copied from interface: Controller
Process the render request and return a ModelAndView object which the DispatcherPortlet will render. A null return value is not an error: It indicates that this object completed request processing itself, thus there is no ModelAndView to render.

Specified by:
handleRenderRequest in interface Controller
Parameters:
request - current portlet render request
response - current portlet render response
Returns:
a ModelAndView to render, or null if handled directly
Throws:
Exception - in case of errors

handleActionRequestInternal

protected void handleActionRequestInternal(ActionRequest request,
                                           ActionResponse response)
                                    throws Exception
Subclasses are meant to override this method if the controller is expected to handle action requests. The contract is the same as for handleActionRequest.

The default implementation throws a PortletException.

Throws:
Exception
See Also:
handleActionRequest(javax.portlet.ActionRequest, javax.portlet.ActionResponse), handleRenderRequestInternal(javax.portlet.RenderRequest, javax.portlet.RenderResponse)

handleRenderRequestInternal

protected ModelAndView handleRenderRequestInternal(RenderRequest request,
                                                   RenderResponse response)
                                            throws Exception
Subclasses are meant to override this method if the controller is expected to handle render requests. The contract is the same as for handleRenderRequest.

The default implementation throws a PortletException.

Throws:
Exception
See Also:
handleRenderRequest(javax.portlet.RenderRequest, javax.portlet.RenderResponse), handleActionRequestInternal(javax.portlet.ActionRequest, javax.portlet.ActionResponse)