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 &mdash; if applicable
048 * &mdash; 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}