Many teams will try to leverage their investments in terms of know-how and tools, both for existing projects and for new ones. Concretely, there are not only a large number of books and tools for Struts but also a lot of developers that have experience with it. Thus, if you can live with Struts's architectural flaws, it can still be a viable choice for the web layer. The same applies to WebWork and other web frameworks.

If you don't want to use Spring's web MVC but intend to leverage other solutions that Spring offers, you can integrate the web framework of your choice with Spring easily. Simply start up a Spring root application context via its ContextLoaderListener, and access it via its ServletContext attribute (or Spring's respective helper method) from within a Struts or WebWork action. Note that there aren't any "plugins" involved, therefore no dedicated integration: From the view of the web layer, you'll simply use Spring as a library, with the root application context instance as entry point.

All your registered beans and all of Spring's services can be at your fingertips even without Spring's web MVC. Spring doesn't compete with Struts or WebWork in this usage, it just addresses the many areas that the pure web frameworks don't, from bean configuration to data access and transaction handling. So you are able to enrich your application with a Spring middle tier and/or data access tier, even if you just want to use e.g. the transaction abstraction with JDBC or Hibernate.

If just focusing on the web support, some of the Spring's unique features are:

Of course, just a controller interface isn't enough. To provide a basic infrastructure, all of Spring's Controllers inherit from AbstractController, a class offering caching support and for instance the setting of the mimetype.

the last two properties are actually part of the WebContentGenerator which is the superclass of AbstractController but to keeps things clear...

When using the AbstractController as a baseclass for your controllers (which is not recommended since there are a lot of other controller that might already do the job for your) you only have to override the handleRequestInternal(HttpServletRequest, HttpServletResponse)-method and implement your logic code and return a ModelAndView object there. A short example consisting of a class and a declaration in the web application context.

package samples;

public class SampleController extends AbstractController {

    public ModelAndView handleRequestInternal(
        HttpServletRequest request,
        HttpServletResponse response)
    throws Exception {
        ModelAndView mav = new ModelAndView("foo", new HashMap());
    }
}

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

The class above and the declaration in the web application context is all you need to do besides setting up a handler mapping (see Section 12.4, “Handler mappings”) to get this very simple controller working. This controller will generates caching directives telling the client to cache things for 2 minutes before rechecking. This controller furthermore returns an hard-coded view (hmm, not so nice), named index (see Section 12.5, “Views and resolving them” for more information about views).

Besides the AbstractController - which you could of course extend, although a more concrete controller might offer you more functionality - there are a couple of other simple controllers that might ease the pain of developing simple MVC applications. The ParameterizableViewController basically is the same as the one in the example above, except for the fact that you can specify its view name that it'll be returning in the web application context (ahhh, no need to hard-code the viewname).

The FileNameViewController inspects the URL and retrieves the filename of the file request (the filename of http://www.springframework.org/index.html is index) and uses that as a viewname. Nothing more to it.

Spring offers a multi-action controller with which you aggregate multiple actions into one controller, grouping functionality together. The multi-action controller lives in a separate package - org.springframework.web.mvc.multiaction - and is capable of mapping requests to method names and then invoking the right method name. Using the multi-action controller is especially handy when you're having a lot of commons functionality in one controller, but want to have multiple entry points to the controller to tweak behavior for instance.

Methods defined for a multi-action controller will need to conform to the following signature:

// actionName can be replaced by any methodname
ModelAndView actionName(HttpServletRequest, HttpServletResponse);

Method overloading is not allowed since it'll confuse the MultiActionController. Furthermore, you can define exception handlers capable of handling exception that will be thrown form a method you specify. Exception handler methods need to return a ModelAndView object, just as any other action method and will need to conform to the following signature:

// anyMeaningfulName can be replaced by any methodname
ModelAndView anyMeaningfulName(HttpServletRequest, HttpServletResponse, ExceptionClass);

The ExceptionClass can be any exception, as long as it's a subclass of java.lang.Exception or java.lang.RuntimeException.

The MethodNameResolver is supposed to resolve method names based on the request coming in. There are three resolver to your disposal, but of course you can implement more of them yourself if you want.

A couple of examples. First of all one showing the ParameterMethodNameResolver and the delegate property, which will accept requests to urls with the parameter method included and set to retrieveIndex:

<bean id="paramResolver" class="org....mvc.multiaction.ParameterMethodNameResolver">
    <property name="paramName"><value>method</value></property>
</bean>

<bean id="paramMultiController" class="org....mvc.multiaction.MultiActionController">
    <property name="methodNameResolver"><ref bean="paramResolver"/></property>
    <property name="delegate"><ref bean="sampleDelegate"/>
</bean>

<bean id="sampleDelegate" class="samples.SampleDelegate"/>

## together with

public class SampleDelegate {

    public ModelAndView retrieveIndex(
        HttpServletRequest req, 
        HttpServletResponse resp) {

        return new ModelAndView("index", "date", new Long(System.currentTimeMillis()));
    }
}

When using the delegates shown above, we could also use the PropertiesMethodNameResolver to match a couple of URLs to the method we defined:

<bean id="propsResolver" class="org....mvc.multiaction.PropertiesMethodNameResolver">
    <property name="mappings">
        <props>
            <prop key="/index/welcome.html">retrieveIndex</prop>
            <prop key="/**/notwelcome.html">retrieveIndex</prop>
            <prop key="/*/user?.html">retrieveIndex</prop>
        </props>
    </property>
</bean>

<bean id="paramMultiController" class="org....mvc.multiaction.MultiActionController">
    <property name="methodNameResolver"><ref bean="propsResolver"/></property>
    <property name="delegate"><ref bean="sampleDelegate"/>
</bean>

Spring's CommandControllers are a fundamental part of the Spring MVC package. Command controllers provide a way to interact with data objects and dynamically bind parameters from the HttpServletRequest to the data object you're specifying. This compares to Struts's actionforms, where in Spring, you don't have to implement any interface of superclasses to do data binding. First, let's examine what command controllers available, just to get clear picture of what you can do with them:

A very simple, but very powerful handler mapping is the BeanNameUrlHandlerMapping, which maps incoming HTTP requests to names of beans, defined in the web application context. Let's say we want to enable a user to insert an account and we've already provided an appropriate FormController (see Section 12.3.4, “CommandControllers” for more information on Command- and FormControllers) and a JSP view (or Velocity template) that renders the form. When using the BeanNameUrlHandlerMapping, we could map the HTTP request with URL http://samples.com/editaccount.form to the appropriate FormController as follows:

<beans>
    <bean id="handlerMapping" 
          class="org.springframework.web.servlet.handler.BeanNameUrlHandlerMapping"/>
        
    <bean name="/editaccount.form"
          class="org.springframework.web.servlet.mvc.SimpleFormController">
        <property name="formView"><value>account</value></property>
        <property name="successView"><value>account-created</value></property>
        <property name="commandName"><value>Account</value></property>
        <property name="commandClass"><value>samples.Account</value></property>
    </bean>
<beans>    

All incoming requests for the URL /editaccount.form will now be handled by the FormController in the source listing above. Of course we have to define a servlet-mapping in web.xml as well, to let through all the requests ending with .form.

<web-app>
    ...
    <servlet>
        <servlet-name>sample</servlet-name>
        <servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class>
        <load-on-startup>1</load-on-startup>
    </servlet>

   <!-- Maps the sample dispatcher to /*.form -->
    <servlet-mapping>
        <servlet-name>sample</servlet-name>
        <url-pattern>*.form</url-pattern>
    </servlet-mapping>
    ...
</web-app>

NOTE: if you want to use the BeanNameUrlHandlerMapping, you don't necessarily have to define it in the web application context (as indicated above). By default, if no handler mapping can be found in the context, the DispatcherServlet creates a BeanNameUrlHandlerMapping for you!

A further - and much more powerful handler mapping - is the SimpleUrlHandlerMapping. This mapping is configurable in the application context and has Ant-style path matching capabilities (see ???). A couple of example will probably makes thing clear enough:

<web-app>
    ...
    <servlet>
        <servlet-name>sample</servlet-name>
        <servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class>
        <load-on-startup>1</load-on-startup>
    </servlet>

    <!-- Maps the sample dispatcher to /*.form -->
    <servlet-mapping>
        <servlet-name>sample</servlet-name>
        <url-pattern>*.form</url-pattern>
    </servlet-mapping>
    <servlet-mapping>
        <servlet-name>sample</servlet-name>
        <url-pattern>*.html</url-pattern>
    </servlet-mapping>
    ...
</web-app>

Allows all requests ending with .html and .form to be handled by the sample dispatcher servlet.

<beans>
    <bean id="handlerMapping" 
          class="org.springframework.web.servlet.handler.SimpleUrlHandlerMapping">            
        <property name="mappings">
            <props>
                <prop key="/*/account.form">editAccountFormController</prop>
                <prop key="/*/editaccount.form">editAccountFormController</prop>
                <prop key="/ex/view*.html">someViewController</prop>
                <prop key="/**/help.html">helpController</prop>
            </props>
        </property>
    </bean>
    
    <bean id="someViewController"
          class="org.springframework.web.servlet.mvc.UrlFilenameViewController"/>
    
    <bean id="editAccountFormController"
          class="org.springframework.web.servlet.mvc.SimpleFormController">
        <property name="formView"><value>account</value></property>
        <property name="successView"><value>account-created</value></property>
        <property name="commandName"><value>Account</value></property>
        <property name="commandClass"><value>samples.Account</value></property>
    </bean>
<beans>

This handler mapping first of all reroutes all requests in all directories for a file named help.html to the someViewController, which is a UrlFilenameViewController (more about that can be found in Section 12.3, “Controllers”). Also, all requests for a resource beginning with view, ending with .html, in the directory ex, will be rerouted to that specific controller. Furthermore, two mappings have been defined that will match with the editAccountFormController.

The handler mapping also has a notion of handler interceptors, that can be extremely useful when you want to apply specific functionality to all requests, for example the checking for a principal or something alike.

Interceptors located in the handler mapping must implement HandlerInterceptor from the org.springframework.web.servlet-package. This interface defines three methods, one that will be called before the actual handler will be executed, one that will be called after the handler is executed, and one that is called after the complete request has finished. Those three methods should provide you with enough flexibility to do all kinds of pre- and post-processing.

The preHandle method has a boolean return value. Using this value, you can tweak the behavior of the execution chain. When returning true, the handler execution chain will continue, when returning false, the DispatcherServlet assumes the interceptor itself has taken care of requests (and for instance rendered an appropriate view) and does not continue with executing the other interceptors and the actual handler in the execution chain.

The following example provides an interceptor that intercepts all requests and reroutes the user to a specific page if the time is not between 9 a.m. and 6 p.m.

<beans>
    <bean id="handlerMapping" 
          class="org.springframework.web.servlet.handler.SimpleUrlHandlerMapping">            
        <property name="interceptors">
            <list>
                <ref bean="officeHoursInterceptor"/>
            </list>
        </property>
        <property name="mappings">
            <props>
                <prop key="/*.form">editAccountFormController</prop>
                <prop key="/*.view">editAccountFormController</prop>
            </props>
        </property>
    </bean>
    
    <bean id="officeHoursInterceptor" 
          class="samples.TimeBasedAccessInterceptor">
        <property name="openingTime"><value>9</value></property>
        <property name="closingTime"><value>18</value></property>
    </bean>    
<beans>

package samples;

public class TimeBasedAccessInterceptor extends HandlerInterceptorAdapter {

    private int openingTime;    
    private int closingTime;    
    public void setOpeningTime(int openingTime) {
        this.openingTime = openingTime;
    }    
    public void setClosingTime(int closingTime) {
        this.closingTime = closingTime;
    }    
    public boolean preHandle(
            HttpServletRequest request,
            HttpServletResponse response,
            Object handler)
    throws Exception {
        Calendar cal = Calendar.getInstance();
        int hour = cal.get(HOUR_OF_DAY);
        if (openingTime <= hour < closingTime) {
            return true;
        } else {
            response.sendRedirect("http://host.com/outsideOfficeHours.html");
            return false;
        }
    }    
}

Any request coming in, will be intercepted by the TimeBasedAccessInterceptor, and if the current time is outside office hours, the user will be redirect to a static html file, saying for instance he can only access the website during office hours.

As you can see, Spring has an adapter to make it easy for you to extend the HandlerInterceptor.

As discussed before, all controllers in the Spring web framework, return a ModelAndView instance. Views in Spring are addressed by a view name and are resolved by a viewresolver. Spring comes with quite a few view resolvers. We'll list most of them and then provide a couple of examples.

As an example, when using JSP for a view technology you can use the the UrlBasedViewResolver. This view resolver translates view names to a URL and hands the request over the RequestDispatcher to render the view.

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

When returning test as a viewname, this view resolver will hand the request over to the RequestDispatcher that'll send the request to /WEB-INF/jsp/test.jsp.

When mixing different view technologies in a web application, you can use the ResourceBundleViewResolver:

<bean id="viewResolver"
      class="org.springframework.web.servlet.view.ResourceBundleViewResolver">
    <property name="basename"><value>views</value></property>
    <property name="defaultParentView"><value>parentView</value></property>
</bean>

The ResourceBundleViewResolver inspects the ResourceBundle identified by the basename and for each view it is supposed to resolve, it uses the value of the property [viewname].class as the view class and the value of the property [viewname].url as the view url. As you can see, you can identify a parent view, from which all view in the properties file sort of extend. This way you can specify a default view class for instance.

A note on caching: subclasses of AbstractCachingViewResolver cache view instances they've resolved. This greatly improves performance when using certain view technology. It's possible to turn off the cache, by setting the cache property to false. Furthermore, if you have the requirement to be able to refresh a certain view at runtime (for example when a Velocity template has been modified), you can use the removeFromCache(String viewName, Locale loc) method.

Spring supports more than just one view resolver. This allows you to chain resolvers and for example override specific views in certain circumstances. Chaining is view resolvers is pretty straightforward: just add more than one resolver to your application context and if necessary, set the order property to specify an order. Remember: the higher the order property, the later the view resolver will be positioned in the chain.

A chain of view resolvers for example could consist of two, one InternalResourceViewResolver (positioned as the last resolver) and an XmlViewResolver specifying Excel views (those are not supported by the InternalResourceViewResolver):

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

<bean id="excelViewResolver">
		class="org.springframework.web.servlet.view.XmlViewResolver">
	<property name="order"><value>1</value></property>
	<property name="location"><value>/WEB-INF/views.xml</value></property>
</bean>

### views.xml

<beans>
	<bean name="report" class="org.springframework.example.ReportExcelView"/>
</beans>

If a specific view resolver does not result in a view, Spring will inspect the context to see if other view resolvers are configured. If not, it'll throw an Exception. If there are additional view resolvers, it'll continue to inspect those.

You have to keep something else in mind: the contract of a view resolver mentions that a view resolver can return null to indicate the view could not be found. Not all view resolvers do this however! This is because the InternalResourceViewResolver for example simply cannot detect whether or not the view exists (it uses the RequestDispatcher internally, and dispatching is the only way to figure out if for example a JSP exists--this can only be done once). The same holds for the VelocityViewResolver and some others. Check the JavaDoc for the view resolver to see if you're dealing with a view resolver that does not report non-existing views. As a result of this, putting an InternalResourceViewResolver in the chain on a place other than the last, will result in the chain not being fully inspected, since the InternalResourceViewResolver will always return a view!

This locale resolver inspects the accept-language header in the request that was sent by the browser of the client. Usually this header field contains the locale of the client's operating system.

This locale resolver inspects a Cookie that might exist on the client, to see if there's a locale specified. If so, it uses that specific locale. Using the properties of this locale resolver, you can specify the name of the cookie, as well as the maximum age.

<bean id="localeResolver">
    <property name="cookieName"><value>clientlanguage</value></property>
    <!-- in seconds. If set to -1, the cookie is not persisted (deleted when browser shuts down) -->
    <property name="cookieMaxAge"><value>100000</value></property>
</bean>

This is an example of defining a CookieLocaleResolver.

The SessionLocaleResolver allows you to retrieve locales from the session that might be associated to the user's request.

You can build in changing of locales using the LocaleChangeInterceptor. This interceptor needs to be added to one of the handler mappings (see Section 12.4, “Handler mappings”) and it will detect a parameter in the request and change the locale (it calls setLocale() on the LocaleResolver that also exists in the context).

<bean id="localeChangeInterceptor" 
      class="org.springframework.web.servlet.i18n.LocaleChangeInterceptor">
    <property name="paramName"><value>siteLanguage</value></property>
</bean>
        
<bean id="localeResolver"
      class="org.springframework.web.servlet.i18n.CookieLocaleResolver"/>
         
<bean id="urlMapping" 
      class="org.springframework.web.servlet.handler.SimpleUrlHandlerMapping"> 
    <property name="interceptors">
        <list>
            <ref local="localeChangeInterceptor"/>
        </list>
    </property>
    <property name="mappings">
        <props>
            <prop key="/**/*.view">someController</prop>
        </props>
    </property>
</bean>

All calls to all *.view resources containing a parameter named siteLanguage will now change the locale. So a call to http://www.sf.net/home.view?siteLanguage=nl will change the site language to Dutch.

Spring has built-in multipart support to handle fileuploads in web applications. The design for the multipart support is done with pluggable MultipartResovler objects, defined in the org.springframework.web.multipart package. Out of the box, Spring provides MultipartResolver for use with Commons FileUpload (http://jakarta.apache.org/commons/fileupload) and COS FileUpload (http://www.servlets.com/cos). How uploading files is supported will be described in the rest of this chapter.

By default, no multipart handling will be done by Spring, as some developers will want to handle multiparts themselves. You'll have to enable it yourself by adding a multipart resolver to the web application's context. After you've done that, each request will be inspected for a multipart that it might contain. If no such multipart is found, the request will continue as expected. However, if a multipart is found in the request, the MultipartResolver that has been declared in your context will resolve. After that, the multipart attribute in your request will be treated as any other attributes.

The following example shows how to use the CommonsMultipartResolver:

<bean id="multipartResolver" 
    class="org.springframework.web.multipart.commons.CommonsMultipartResolver">

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

This is an example using the CosMultipartResolver:

<bean id="multipartResolver" 
    class="org.springframework.web.multipart.cos.CosMultipartResolver">

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

Of course you need to stick 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, while in the case of the CosMultipartResolver, use cos.jar.

Now that you have seen how to set Spring up to handle multipart requests, let's talk about how to actually use it. When the Spring DispatcherServlet detects a Multipart request, it activates the resolver that has been declared in your context and hands over the request. What it basically does is wrap the current HttpServletRequest into a MultipartHttpServletRequest that has support for multiparts. Using the MultipartHttpServletRequest you can get information about the multiparts contained by this request and actually get the multiparts themselves in your controllers.

After the MultipartResolver has finished doing its job, the request will be processed like any other. To use it, you create a form with an upload field, then let Spring bind the file on your form. 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 beans you have to register a custom editor with the ServletRequestDatabinder. There are a couple of editors available for handling files and setting the results on a bean. There's a StringMultipartEditor capable of converting files to Strings (using a user-defined character set) and there's a ByteArrayMultipartEditor which converts files to byte arrays. They function just as the CustomDateEditor does.

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

<beans>

    ...

    <bean id="multipartResolver"
        class="org.springframework.web.multipart.commons.CommonsMultipartResolver"/>

    <bean id="urlMapping" class="org.springframework.web.servlet.handler.SimpleUrlHandlerMapping">
        <property name="mappings">
            <props>
                <prop key="/upload.form">fileUploadController</prop>
            </props>
        </property>
    </bean>

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

</beans>

After that, create the controller and the actual bean holding the file property

// snippet from FileUploadController
public class FileUploadController extends SimpleFormController {

    protected ModelAndView onSubmit(
        HttpServletRequest request,
        HttpServletResponse response,
        Object command,
        BindException errors)
        throws ServletException, IOException {
        
        // 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
        }

        // well, let's do nothing with the bean for now and return:        
        return super.onSubmit(request, response, command, errors);
    }
    
    protected void initBinder(
        HttpServletRequest request,
        ServletRequestDataBinder binder)
        throws ServletException {
        // to actually be able to convert Multipart instance to byte[]
        // we have to register a custom editor (in this case the
        // ByteArrayMultipartEditor
        binder.registerCustomEditor(byte[].class, new ByteArrayMultipartFileEditor());
        // now Spring knows how to handle multipart object and convert them
    }
        
}

// snippet from FileUploadBean
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 these examples, 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, etcetera).

But we're still not finished. To actually let the user upload something, we have to create a form:

<html>
    <head>
        <title>Upload a file please</title>
    </head>
    <body>
        <h1>Please upload a file</h1>
        <form method="post" action="upload.form" enctype="multipart/form-data">
            <input type="file" name="file"/>
            <input type="submit"/>
        </form>
    </body>
</html>

As you can see, we've created a field named after the property of the bean that holds the byte[]. Furthermore we've added the encoding attribute which is necessary to let the browser know how to encode the multipart fields (do not forget this!). Right now everything should work.