The default handler is still a very simple Controller interface, offering just two methods:

The framework also includes most of the same controller implementation hierarchy, such as AbstractController, SimpleFormController, and so on. Data binding, command object usage, model handling, and view resolution are all the same as in the servlet framework.

All the view rendering capabilities of the servlet framework are used directly via a special bridge servlet named ViewRendererServlet. By using this servlet, the portlet request is converted into a servlet request and the view can be rendered using the entire normal servlet infrastructure. This means all the existing renderers, such as JSP, Velocity, etc., can still be used within the portlet.

Spring Portlet MVC supports beans whose lifecycle is scoped to the current HTTP request or HTTP Session (both normal and global). This is not a specific feature of Spring Portlet MVC itself, but rather of the WebApplicationContext container(s) that Spring Portlet MVC uses. These bean scopes are described in detail in the section entitled Section 3.4.3, “The other scopes”

Of course, just a Controller interface isn't enough. To provide a basic infrastructure, all of Spring Portlet MVC's Controllers inherit from AbstractController, a class offering access to Spring's ApplicationContext and control over caching.

The requireSession and cacheSeconds properties are declared on the PortletContentGenerator class, which is the superclass of AbstractController) but are included here for completeness.

When using the AbstractController as a baseclass for your controllers (which is not recommended since there are a lot of other controllers that might already do the job for you) you only have to override either the handleActionRequestInternal(ActionRequest, ActionResponse) method or the handleRenderRequestInternal(RenderRequest, RenderResponse) method (or both), implement your logic, and return a ModelAndView object (in the case of handleRenderRequestInternal).

The default implementations of both handleActionRequestInternal(..) and handleRenderRequestInternal(..) throw a PortletException. This is consistent with the behavior of GenericPortlet from the JSR- 168 Specification API. So you only need to override the method that your controller is intended to handle.

Here is short example consisting of a class and a declaration in the web application context.

package samples;

import javax.portlet.RenderRequest;
import javax.portlet.RenderResponse;

import org.springframework.web.portlet.mvc.AbstractController;
import org.springframework.web.portlet.ModelAndView;

public class SampleController extends AbstractController {

    public ModelAndView handleRenderRequestInternal(
        RenderRequest request,
        RenderResponse response) throws Exception {

        ModelAndView mav = new ModelAndView("foo");
        mav.addObject("message", "Hello World!");
        return mav;
    }
}

<bean id="sampleController" class="samples.SampleController">
    <property name="cacheSeconds" value="120"/>
</bean>

The class above and the declaration in the web application context is all you need besides setting up a handler mapping (see Section 16.5, “Handler mappings”) to get this very simple controller working.

Although you can extend AbstractController, Spring Portlet MVC provides a number of concrete implementations which offer functionality that is commonly used in simple MVC applications.

The ParameterizableViewController is basically the same as the example above, except for the fact that you can specify the view name that it will return in the web application context (no need to hard-code the view name).

The PortletModeNameViewController uses the current mode of the portlet as the view name. So, if your portlet is in View mode (i.e. PortletMode.VIEW) then it uses "view" as the view name.

Spring Portlet MVC has the exact same hierarchy of command controllers as Spring Web MVC. They provide a way to interact with data objects and dynamically bind parameters from the PortletRequest to the data object specified. Your data objects don't have to implement a framework-specific interface, so you can directly manipulate your persistent objects if you desire. Let's examine what command controllers are available, to get an overview of what you can do with them:

These command controllers are quite powerful, but they do require a detailed understanding of how they operate in order to use them efficiently. Carefully review the Javadocs for this entire hierarchy and then look at some sample implementations before you start using them.

Instead of developing new controllers, it is possible to use existing portlets and map requests to them from a DispatcherPortlet. Using the PortletWrappingController, you can instantiate an existing Portlet as a Controller as follows:

<bean id="wrappingController"
      class="org.springframework.web.portlet.mvc.PortletWrappingController">
    <property name="portletClass" value="sample.MyPortlet"/>
    <property name="portletName" value="my-portlet"/>
    <property name="initParameters">
        <value>
            config=/WEB-INF/my-portlet-config.xml
        </value>
    </property>
</bean>

This can be very valuable since you can then use interceptors to pre-process and post-process requests going to these portlets. Since JSR-168 does not support any kind of filter mechanism, this is quite handy. For example, this can be used to wrap the Hibernate OpenSessionInViewInterceptor around a MyFaces JSF Portlet.

This is a simple handler mapping that maps incoming requests based on the current mode of the portlet (e.g. ‘view’, ‘edit’, ‘help’). An example:

<bean id="portletModeHandlerMapping"
      class="org.springframework.web.portlet.handler.PortletModeHandlerMapping">
    <property name="portletModeMap">
        <map>
            <entry key="view" value-ref="viewHandler"/>
            <entry key="edit" value-ref="editHandler"/>
            <entry key="help" value-ref="helpHandler"/>
        </map>
    </property>
</bean>

If we need to navigate around to multiple controllers without changing portlet mode, the simplest way to do this is with a request parameter that is used as the key to control the mapping.

ParameterHandlerMapping uses the value of a specific request parameter to control the mapping. The default name of the parameter is 'action', but can be changed using the 'parameterName' property.

The bean configuration for this mapping will look something like this:

<bean id="parameterHandlerMapping"
      class="org.springframework.web.portlet.handler.ParameterHandlerMapping”>
    <property name="parameterMap">
        <map>
            <entry key="add" value-ref="addItemHandler"/>
            <entry key="edit" value-ref="editItemHandler"/>
            <entry key="delete" value-ref="deleteItemHandler"/>
        </map>
    </property>
</bean>

The most powerful built-in handler mapping, PortletModeParameterHandlerMapping combines the capabilities of the two previous ones to allow different navigation within each portlet mode.

Again the default name of the parameter is "action", but can be changed using the parameterName property.

By default, the same parameter value may not be used in two different portlet modes. This is so that if the portal itself changes the portlet mode, the request will no longer be valid in the mapping. This behavior can be changed by setting the allowDupParameters property to true. However, this is not recommended.

The bean configuration for this mapping will look something like this:

<bean id="portletModeParameterHandlerMapping"
      class="org.springframework.web.portlet.handler.PortletModeParameterHandlerMapping">
    <property name="portletModeParameterMap">
        <map>
            <entry key="view"> <!-- 'view' portlet mode -->
                <map>
                    <entry key="add" value-ref="addItemHandler"/>
                    <entry key="edit" value-ref="editItemHandler"/>
                    <entry key="delete" value-ref="deleteItemHandler"/>
                </map>
            </entry>
            <entry key="edit"> <!-- 'edit' portlet mode -->
                <map>
                    <entry key="prefs" value-ref="prefsHandler"/>
                    <entry key="resetPrefs" value-ref="resetPrefsHandler"/>
                </map>
            </entry>
        </map>
    </property>
</bean>

This mapping can be chained ahead of a PortletModeHandlerMapping, which can then provide defaults for each mode and an overall default as well.

Spring's handler mapping mechanism has a notion of handler interceptors, which can be extremely useful when you want to apply specific functionality to certain requests, for example, checking for a principal. Again Spring Portlet MVC implements these concepts in the same way as Web MVC.

Interceptors located in the handler mapping must implement HandlerInterceptor from the org.springframework.web.portlet package. Just like the servlet version, this interface defines three methods: one that will be called before the actual handler will be executed (preHandle), one that will be called after the handler is executed (postHandle), and one that is called after the complete request has finished (afterCompletion). These three methods should provide enough flexibility to do all kinds of pre- and post- processing.

The preHandle method returns a boolean value. You can use this method to break or continue the processing of the execution chain. When this method returns true, the handler execution chain will continue. When it returns false, the DispatcherPortlet assumes the interceptor itself has taken care of requests (and, for example, rendered an appropriate view) and does not continue executing the other interceptors and the actual handler in the execution chain.

The postHandle method is only called on a RenderRequest. The preHandle and afterCompletion methods are called on both an ActionRequest and a RenderRequest. If you need to execute logic in these methods for just one type of request, be sure to check what kind of request it is before processing it.

As with the servlet package, the portlet package has a concrete implementation of HandlerInterceptor called HandlerInterceptorAdapter. This class has empty versions of all the methods so that you can inherit from this class and implement just one or two methods when that is all you need.

The portlet package also has a concrete interceptor named ParameterMappingInterceptor that is meant to be used directly with ParameterHandlerMapping and PortletModeParameterHandlerMapping. This interceptor will cause the parameter that is being used to control the mapping to be forwarded from an ActionRequest to the subsequent RenderRequest. This will help ensure that the RenderRequest is mapped to the same Handler as the ActionRequest. This is done in the preHandle method of the interceptor, so you can still modify the parameter value in your handler to change where the RenderRequest will be mapped.

Be aware that this interceptor is calling setRenderParameter on the ActionResponse, which means that you cannot call sendRedirect in your handler when using this interceptor. If you need to do external redirects then you will either need to forward the mapping parameter manually or write a different interceptor to handle this for you.

The following example shows how to use the CommonsPortletMultipartResolver:

<bean id="portletMultipartResolver"
    class="org.springframework.web.portlet.multipart.CommonsPortletMultipartResolver">

    <!-- one of the properties available; the maximum file size in bytes -->
    <property name="maxUploadSize" value="100000"/>
</bean>

Of course you also need to put the appropriate jars in your classpath for the multipart resolver to work. In the case of the CommonsMultipartResolver, you need to use commons-fileupload.jar. Be sure to use at least version 1.1 of Commons FileUpload as previous versions do not support JSR-168 Portlet applications.

Now that you have seen how to set Portlet MVC up to handle multipart requests, let's talk about how to actually use it. When DispatcherPortlet detects a multipart request, it activates the resolver that has been declared in your context and hands over the request. What the resolver then does is wrap the current ActionRequest into a MultipartActionRequest that has support for multipart file uploads. Using the MultipartActionRequest you can get information about the multiparts contained by this request and actually get access to the multipart files themselves in your controllers.

Note that you can only receive multipart file uploads as part of an ActionRequest, not as part of a RenderRequest.

After the PortletMultipartResolver has finished doing its job, the request will be processed like any other. To use it, you create a form with an upload field (see immediately below), then let Spring bind the file onto your form (backing object). To actually let the user upload a file, we have to create a (JSP/HTML) form:

<h1>Please upload a file</h1>
<form method="post" action="<portlet:actionURL/>" enctype="multipart/form-data">
    <input type="file" name="file"/>
    <input type="submit"/>
</form>

As you can see, we've created a field named “file” after the property of the bean that holds the byte[]. Furthermore we've added the encoding attribute (enctype="multipart/form-data"), which is necessary to let the browser know how to encode the multipart fields (do not forget this!).

Just as with any other property that's not automagically convertible to a string or primitive type, to be able to put binary data in your objects you have to register a custom editor with the PortletRequestDataBinder. There are a couple of editors available for handling files and setting the results on an object. There's a StringMultipartFileEditor capable of converting files to Strings (using a user-defined character set) and there is a ByteArrayMultipartFileEditor which converts files to byte arrays. They function just as the CustomDateEditor does.

So, to be able to upload files using a form, declare the resolver, a mapping to a controller that will process the bean, and the controller itself.

<bean id="portletMultipartResolver"
      class="org.springframework.web.portlet.multipart.CommonsPortletMultipartResolver"/>

<bean id="portletModeHandlerMapping"
      class="org.springframework.web.portlet.handler.PortletModeHandlerMapping">
    <property name="portletModeMap">
        <map>
            <entry key="view" value-ref="fileUploadController"/>
        </map>
    </property>
</bean>

<bean id="fileUploadController" class="examples.FileUploadController">
    <property name="commandClass" value="examples.FileUploadBean"/>
    <property name="formView" value="fileuploadform"/>
    <property name="successView" value="confirmation"/>
</bean>

After that, create the controller and the actual class to hold the file property.

public class FileUploadController extends SimpleFormController {

    public void onSubmitAction(
        ActionRequest request,
        ActionResponse response,
        Object command,
        BindException errors)
        throws Exception {

        // cast the bean
        FileUploadBean bean = (FileUploadBean) command;

        // let's see if there's content there
        byte[] file = bean.getFile();
        if (file == null) {
            // hmm, that's strange, the user did not upload anything
        }

        // do something with the file here
    }

    protected void initBinder(
            PortletRequest request, PortletRequestDataBinder binder)
        throws Exception {
        // to actually be able to convert Multipart instance to byte[]
        // we have to register a custom editor
        binder.registerCustomEditor(byte[].class, new ByteArrayMultipartFileEditor());
        // now Spring knows how to handle multipart object and convert
    }
}

public class FileUploadBean {

    private byte[] file;

    public void setFile(byte[] file) {
        this.file = file;
    }

    public byte[] getFile() {
        return file;
    }
}

As you can see, the FileUploadBean has a property typed byte[] that holds the file. The controller registers a custom editor to let Spring know how to actually convert the multipart objects the resolver has found to properties specified by the bean. In this example, nothing is done with the byte[] property of the bean itself, but in practice you can do whatever you want (save it in a database, mail it to somebody, etc).

An equivalent example in which a file is bound straight to a String-typed property on a (form backing) object might look like this:

public class FileUploadController extends SimpleFormController {

    public void onSubmitAction(
        ActionRequest request,
        ActionResponse response,
        Object command,
        BindException errors) throws Exception {

        // cast the bean
        FileUploadBean bean = (FileUploadBean) command;

        // let's see if there's content there
        String file = bean.getFile();
        if (file == null) {
            // hmm, that's strange, the user did not upload anything
        }

        // do something with the file here
    }

    protected void initBinder(
        PortletRequest request, PortletRequestDataBinder binder) throws Exception {

        // to actually be able to convert Multipart instance to a String
        // we have to register a custom editor
        binder.registerCustomEditor(String.class,
            new StringMultipartFileEditor());
        // now Spring knows how to handle multipart objects and convert
    }
}

public class FileUploadBean {

    private String file;

    public void setFile(String file) {
        this.file = file;
    }

    public String getFile() {
        return file;
    }
}

Of course, this last example only makes (logical) sense in the context of uploading a plain text file (it wouldn't work so well in the case of uploading an image file).

The third (and final) option is where one binds directly to a MultipartFile property declared on the (form backing) object's class. In this case one does not need to register any custom property editor because there is no type conversion to be performed.

public class FileUploadController extends SimpleFormController {

    public void onSubmitAction(
        ActionRequest request,
        ActionResponse response,
        Object command,
        BindException errors) throws Exception {

        // cast the bean
        FileUploadBean bean = (FileUploadBean) command;

        // let's see if there's content there
        MultipartFile file = bean.getFile();
        if (file == null) {
            // hmm, that's strange, the user did not upload anything
        }

        // do something with the file here
    }
}

public class FileUploadBean {

    private MultipartFile file;

    public void setFile(MultipartFile file) {
        this.file = file;
    }

    public MultipartFile getFile() {
        return file;
    }
}