Developing a Portlet with Spring Portlet MVC and SimpleFormController

A previous article explained the basics of developing a Portlet. This article will introduce the Spring Portlet MVC Framework for developing Portlets. Specifically, this article will help you create a new Portlet using the SimpleFormController available in the Spring Portlet MVC Framework.

Before we get into the Spring Portlet MVC configuration let's review what is necessary to create the simplest Portlet application. First, you need a valid web.xml web application file. Second, you need to have a portlet.xml file that defines your Portlet. Finally, you need to have a compiled version of your Portlet as either a .class file or packages into a .jar archive. If your Portlet uses an view technology like JSPs, you may choose to include one or more JSP files.

The Spring Framework can be used to externally configure many components in your application. When you use the Spring Portlet MVC framework to build your Portlet application you will no longer write your own Portlet. Instead you configure your portlet.xml to use the Spring Portlet MVC Portlet. You must then configure a series of components using the Spring bean definition files. Let's take a look at how this is done.

File List

Here are all the files that are part of the sample Portlet this article is based on.

src/main/webapp/WEB-INF/jsp/guess.jsp
src/main/webapp/WEB-INF/jsp/answer.jsp
src/main/webapp/WEB-INF/context/GuessNumberPortlet-context.xml
src/main/webapp/WEB-INF/context/applicationContext.xml
src/main/webapp/WEB-INF/portlet.xml
src/main/webapp/WEB-INF/web.xml
src/main/webapp/images/guess.png
src/main/java/net/unicon/guessnumber/SimpleGuessNumberController.java
src/main/java/net/unicon/guessnumber/GuessNumberData.java
pom.xml

This article will not cover the maven pom.xml file, the simple data POJO that represents our model GuessNumberData.java, the graphic used in the portlet guess.png or either JSP file. All these files are provided in the attachment .zip file if you are interested in looking at the complete project. The attachment also includes the Eclipse project files.

portlet.xml

You must change your portlet.xml file to use the Spring Portlet MVC DispatcherPortlet class. It's also useful to define the location of the Spring bean definition file that will be used for this Portlet. This can be done with an init-parameter. If you do not specify the context location as an init parameter, then the default of portlet-name-portlet.xml file in the root of the WEB-INF directory will be used. Here is an snippet of the portlet.xml taken from the attached sample application.

<portlet-class>org.springframework.web.portlet.DispatcherPortlet</portlet-class>
<init-param>
    <name>contextConfigLocation</name>
    <value>/WEB-INF/context/GuessNumberPortlet-context.xml</value>
</init-param>

web.xml

In a Spring Portlet MVC application the web.xml file must contain a few standard entries to enable the framework. All Portlets are part of a bigger Portlet web application that may contain one or more Portlets. In order to share some components between Portlets a Spring application context must be configured in the web.xml file. To configure the application context specify a contextConfigLocation context parameter. If this context parameter is not included the default of applicationContext.xml at the root of the WEB-INF directory will be used. Three other parts must be specified in the web.xml file. Look at the following example for details of both the required elements and the optional contextConfigLocation.

<?xml version="1.0" encoding="UTF-8"?>

<web-app xmlns="http://java.sun.com/xml/ns/j2ee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         version="2.4"
         xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee web-app_2_4.xsd">

    <context-param>
        <param-name>contextConfigLocation</param-name>
        <param-value>/WEB-INF/context/applicationContext.xml</param-value>
    </context-param>

    <listener>
        <listener-class>org.springframework.web.context.ContextLoaderListener</listener-class>
    </listener>

    <servlet>
        <servlet-name>ViewRendererServlet</servlet-name>
        <servlet-class>org.springframework.web.servlet.ViewRendererServlet</servlet-class>
        <load-on-startup>1</load-on-startup>
    </servlet>

    <servlet-mapping>
        <servlet-name>ViewRendererServlet</servlet-name>
        <url-pattern>/WEB-INF/servlet/view</url-pattern>
    </servlet-mapping>
    
</web-app>

applicationContext.xml

Typically you place any component you want shared between more then one Portlet in the common application context for the web application. If you only have one Portlet in the web application, there is very little difference between what you define in the application context versus what you define in the Portlet context. For simplicity in this example everything has been placed in the Portlet context file. The following example shows the empty applicationContext.xml file.

<?xml version="1.0" encoding="UTF-8" ?>

<beans xmlns="http://www.springframework.org/schema/beans"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans-2.0.xsd">

</beans>

Portlet Application Context

In either the web application context or the Portlet context three things must be defined, a ViewResolver, a HandlerMapping and one or more Controllers. The ViewResolver tells the framework both how to translate simple names to full resource names and what kind of resource it is. In the example Portlet context below the ViewResolver is defined to look for JSP pages in the WEB-INF/jsp directory of the web application. The HandlerMapping tells the framework how to map incoming requests to the Portlet to different controllers. The Spring Portlet MVC Framework comes with a variety of interesting HandlerMapping implementations for mapping from Portlet Modes as well as arbitrary parameters. In the example, the HandlerMapping is straight forward and maps any request to the Portlet while in the View Portlet Mode to the guessNumberController. Although Spring Portlet MVC allows you to use other frameworks by defining special types of Handler implementations, we'll stick with the Spring Portlet MVC framework and define a Controller. In the example below we use a custom Controller class net.unicon.guessnumber.SimpleGuessNumberController.

<?xml version="1.0" encoding="UTF-8" ?>

<beans xmlns="http://www.springframework.org/schema/beans"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans-2.0.xsd">

	<bean id="viewResolver" class="org.springframework.web.servlet.view.InternalResourceViewResolver">
		<property name="cache" value="true"/>
		<property name="viewClass" value="org.springframework.web.servlet.view.JstlView"/>
		<property name="prefix" value="/WEB-INF/jsp/"/>
		<property name="suffix" value=".jsp"/>
	</bean>

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

	<bean id="guessNumberController" class="net.unicon.guessnumber.SimpleGuessNumberController">
		<property name="commandClass" value="net.unicon.guessnumber.GuessNumberData"/>
		<property name="commandName" value="model"/>
		<property name="formView" value="guess"/>
		<property name="successView" value="answer"/>
		<property name="bindOnNewForm" value="true"/>
		<property name="sessionForm" value="true"/>
	</bean>
</beans>

SimpleFormController

A framework is typically used because it does some amount of work for you. This is the case with SimpleFormController. The SimpleFormController is designed to handle those situations where you have one page that is a web form and another page that is displayed on successful completion of the form. If any errors occur during validation or processing of the form the form is displayed again, possibly retaining the users previously filled in values. A command object refers to the Java object used to hold all data submitted by the form. This command object is available to many of the SimpleFormController methods. In many cases the only thing a developer must implement is a method to handle a successfully form submission. In the sample application the onSubmitAction method has been left in to show where this handling can be done. The sample controller does two more things. It overrides the formBackingObject() method in order to change the behavior of how the command object is created. Normally the command object would simply be created by calling the no argument constructor on the class that was configured. In the sample formBackingObject() creates the command object and then sets some of the values, including pulling some the username from the Portlet user data and two Portlet preferences values. This data could be separately provided to the views by using the referenceData() method. The sample code does one more thing in the formBackingObject() method and causes the random number to be chosen by calling the startGame() method.

package net.unicon.guessnumber;

import java.util.Map;

import javax.portlet.PortletPreferences;
import javax.portlet.PortletRequest;
import javax.portlet.RenderRequest;

import org.springframework.web.portlet.mvc.SimpleFormController;

import net.unicon.guessnumber.GuessNumberData;

public class SimpleGuessNumberController extends SimpleFormController {

	@Override
	public void doSubmitAction(Object command) {
		// GuessNumberData data = (GuessNumberData)command;
		// Do something with the command object, e.g., save to database
	}

	@Override
	protected Object formBackingObject(PortletRequest request) throws Exception {
		GuessNumberData data = new GuessNumberData();

		Map<?,?> userInfo = (Map<?,?>)request.getAttribute(PortletRequest.USER_INFO);
		String username = "";
		if (userInfo != null) {
			username = (String)userInfo.get("username");
		}

		PortletPreferences prefs = request.getPreferences();
		String minimum = prefs.getValue("minimum","0");
		String maximum = prefs.getValue("maximum","10");

		data.startGame(username,minimum,maximum);
		
		return data;
	}
}

Summary

This article gives you a feel for developing with the Spring Portlet MVC framework. It is not intended to be a comprehensive study. Spring Portlet MVC can provide developers with the opportunity to externally configure and wire together their applications using the conventions provided by the Spring Framework. The convenience classes provided by the Spring Portlet MVC framework, such as the SimpleFormController can simplify Portlet development greatly. The combination of Spring's external application wiring combined with Spring Portlet MVC's conveneince classes leads to a powerful and compelling option for developing new Portlet applications.

---- Cris J H