001/* 002 * Copyright 2002-2016 the original author or authors. 003 * 004 * Licensed under the Apache License, Version 2.0 (the "License"); 005 * you may not use this file except in compliance with the License. 006 * You may obtain a copy of the License at 007 * 008 * https://www.apache.org/licenses/LICENSE-2.0 009 * 010 * Unless required by applicable law or agreed to in writing, software 011 * distributed under the License is distributed on an "AS IS" BASIS, 012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 013 * See the License for the specific language governing permissions and 014 * limitations under the License. 015 */ 016 017package org.springframework.web.servlet.mvc; 018 019import javax.servlet.http.HttpServletRequest; 020import javax.servlet.http.HttpServletResponse; 021 022import org.springframework.lang.Nullable; 023import org.springframework.web.servlet.ModelAndView; 024 025/** 026 * Base Controller interface, representing a component that receives 027 * {@code HttpServletRequest} and {@code HttpServletResponse} 028 * instances just like a {@code HttpServlet} but is able to 029 * participate in an MVC workflow. Controllers are comparable to the 030 * notion of a Struts {@code Action}. 031 * 032 * <p>Any implementation of the Controller interface should be a 033 * <i>reusable, thread-safe</i> class, capable of handling multiple 034 * HTTP requests throughout the lifecycle of an application. To be able to 035 * configure a Controller easily, Controller implementations are encouraged 036 * to be (and usually are) JavaBeans. 037 * 038 * <h3><a name="workflow">Workflow</a></h3> 039 * 040 * <p>After a {@code DispatcherServlet} has received a request and has 041 * done its work to resolve locales, themes, and suchlike, it then tries 042 * to resolve a Controller, using a 043 * {@link org.springframework.web.servlet.HandlerMapping HandlerMapping}. 044 * When a Controller has been found to handle the request, the 045 * {@link #handleRequest(HttpServletRequest, HttpServletResponse) handleRequest} 046 * method of the located Controller will be invoked; the located Controller 047 * is then responsible for handling the actual request and — if applicable 048 * — returning an appropriate 049 * {@link org.springframework.web.servlet.ModelAndView ModelAndView}. 050 * So actually, this method is the main entry point for the 051 * {@link org.springframework.web.servlet.DispatcherServlet DispatcherServlet} 052 * which delegates requests to controllers. 053 * 054 * <p>So basically any <i>direct</i> implementation of the {@code Controller} interface 055 * just handles HttpServletRequests and should return a ModelAndView, to be further 056 * interpreted by the DispatcherServlet. Any additional functionality such as 057 * optional validation, form handling, etc. should be obtained through extending 058 * {@link org.springframework.web.servlet.mvc.AbstractController AbstractController} 059 * or one of its subclasses. 060 * 061 * <h3>Notes on design and testing</h3> 062 * 063 * <p>The Controller interface is explicitly designed to operate on HttpServletRequest 064 * and HttpServletResponse objects, just like an HttpServlet. It does not aim to 065 * decouple itself from the Servlet API, in contrast to, for example, WebWork, JSF or Tapestry. 066 * Instead, the full power of the Servlet API is available, allowing Controllers to be 067 * general-purpose: a Controller is able to not only handle web user interface 068 * requests but also to process remoting protocols or to generate reports on demand. 069 * 070 * <p>Controllers can easily be tested by passing in mock objects for the 071 * HttpServletRequest and HttpServletResponse objects as parameters to the 072 * {@link #handleRequest(HttpServletRequest, HttpServletResponse) handleRequest} 073 * method. As a convenience, Spring ships with a set of Servlet API mocks 074 * that are suitable for testing any kind of web components, but are particularly 075 * suitable for testing Spring web controllers. In contrast to a Struts Action, 076 * there is no need to mock the ActionServlet or any other infrastructure; 077 * mocking HttpServletRequest and HttpServletResponse is sufficient. 078 * 079 * <p>If Controllers need to be aware of specific environment references, they can 080 * choose to implement specific awareness interfaces, just like any other bean in a 081 * Spring (web) application context can do, for example: 082 * <ul> 083 * <li>{@code org.springframework.context.ApplicationContextAware}</li> 084 * <li>{@code org.springframework.context.ResourceLoaderAware}</li> 085 * <li>{@code org.springframework.web.context.ServletContextAware}</li> 086 * </ul> 087 * 088 * <p>Such environment references can easily be passed in testing environments, 089 * through the corresponding setters defined in the respective awareness interfaces. 090 * In general, it is recommended to keep the dependencies as minimal as possible: 091 * for example, if all you need is resource loading, implement ResourceLoaderAware only. 092 * Alternatively, derive from the WebApplicationObjectSupport base class, which gives 093 * you all those references through convenient accessors but requires an 094 * ApplicationContext reference on initialization. 095 * 096 * <p>Controllers can optionally implement the {@link LastModified} interface. 097 * 098 * @author Rod Johnson 099 * @author Juergen Hoeller 100 * @see LastModified 101 * @see SimpleControllerHandlerAdapter 102 * @see AbstractController 103 * @see org.springframework.mock.web.MockHttpServletRequest 104 * @see org.springframework.mock.web.MockHttpServletResponse 105 * @see org.springframework.context.ApplicationContextAware 106 * @see org.springframework.context.ResourceLoaderAware 107 * @see org.springframework.web.context.ServletContextAware 108 * @see org.springframework.web.context.support.WebApplicationObjectSupport 109 */ 110@FunctionalInterface 111public interface Controller { 112 113 /** 114 * Process the request and return a ModelAndView object which the DispatcherServlet 115 * will render. A {@code null} return value is not an error: it indicates that 116 * this object completed request processing itself and that there is therefore no 117 * ModelAndView to render. 118 * @param request current HTTP request 119 * @param response current HTTP response 120 * @return a ModelAndView to render, or {@code null} if handled directly 121 * @throws Exception in case of errors 122 */ 123 @Nullable 124 ModelAndView handleRequest(HttpServletRequest request, HttpServletResponse response) throws Exception; 125 126}