KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > springframework > web > servlet > mvc > Controller


1 /*
2  * Copyright 2002-2006 the original author or authors.
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16
17 package org.springframework.web.servlet.mvc;
18
19 import javax.servlet.http.HttpServletRequest JavaDoc;
20 import javax.servlet.http.HttpServletResponse JavaDoc;
21
22 import org.springframework.web.servlet.ModelAndView;
23
24 /**
25  * Base Controller interface, representing a component that receives
26  * <code>HttpServletRequest</code> and <code>HttpServletResponse</code>
27  * instances just like a <code>HttpServlet</code> but is able to
28  * participate in an MVC workflow. Controllers are comparable to the
29  * notion of a Struts <code>Action</code>.
30  *
31  * <p>Any implementation of the Controller interface should be a
32  * <i>reusable, thread-safe</i> class, capable of handling multiple
33  * HTTP requests throughout the lifecycle of an application. To be able to
34  * configure a Controller easily, Controller implementations are encouraged
35  * to be (and usually are) JavaBeans.
36  * </p>
37  *
38  * <p><b><a name="workflow">Workflow</a></b></p>
39  *
40  * <p>
41  * After a <cde>DispatcherServlet</code> has received a request and has
42  * done its work to resolve locales, themes and suchlike, it then tries
43  * to resolve a Controller, using a
44  * {@link org.springframework.web.servlet.HandlerMapping HandlerMapping}.
45  * When a Controller has been found to handle the request, the
46  * {@link #handleRequest(HttpServletRequest, HttpServletResponse) handleRequest}
47  * method of the located Controller will be invoked; the located Controller
48  * is then responsible for handling the actual request and - if applicable -
49  * returning an appropriate
50  * {@link org.springframework.web.servlet.ModelAndView ModelAndView}.
51  * So actually, this method is the main entrypoint for the
52  * {@link org.springframework.web.servlet.DispatcherServlet DispatcherServlet}
53  * which delegates requests to controllers. This method - and also this interface -
54  * should preferrably not be implemented by custom controllers <i>directly</i>, since
55  * abstract controller also provided by this package already provide a lot of
56  * functionality for typical use cases in web applications. A few examples of
57  * those controllers:
58  * {@link AbstractController AbstractController},
59  * {@link AbstractCommandController AbstractCommandController},
60  * {@link SimpleFormController SimpleFormController}.</p>
61  *
62  * <p>So basically any <i>direct</i> implementation of the Controller interface
63  * just handles HttpServletRequests and should return a ModelAndView, to be further
64  * interpreted by the DispatcherServlet. Any additional functionality such as
65  * optional validation, form handling, etc should be obtained through extending
66  * one of the abstract controller classes mentioned above.</p>
67  *
68  * <p><b>Notes on design and testing</b></p>
69  *
70  * <p>The Controller interface is explicitly designed to operate on HttpServletRequest
71  * and HttpServletResponse objects, just like an HttpServlet. It does not aim to
72  * decouple itself from the Servlet API, in contrast to, for example, WebWork, JSF or Tapestry.
73  * Instead, the full power of the Servlet API is available, allowing Controllers to be
74  * general-purpose: a Controller is able to not only handle web user interface
75  * requests but also to process remoting protocols or to generate reports on demand.</p>
76  *
77  * <p>Controllers can easily be tested by passing in mock objects for the
78  * HttpServletRequest and HttpServletResponse objects as parameters to the
79  * {@link #handleRequest(HttpServletRequest, HttpServletResponse) handleRequest}
80  * method. As a convenience, Spring ships with a set of Servlet API mocks
81  * that are suitable for testing any kind of web components, but are particularly
82  * suitable for testing Spring web controllers. In contrast to a Struts Action,
83  * there is no need to mock the ActionServlet or any other infrastructure;
84  * HttpServletRequest and HttpServletResponse are sufficient.</p>
85  *
86  * <p>If Controllers need to be aware of specific environment references, they can
87  * choose to implement specific awareness interfaces, just like any other bean in a
88  * Spring (web) application context can do, for example:</p>
89  * <ul>
90  * <li><code>org.springframework.context.ApplicationContextAware</code></li>
91  * <li><code>org.springframework.context.ResourceLoaderAware</code></li>
92  * <li><code>org.springframework.web.context.ServletContextAware</code></li>
93  * </ul>
94  *
95  * <p>Such environment references can easily be passed in testing environments,
96  * through the corresponding setters defined in the respective awareness interfaces.
97  * In general, it is recommended to keep the dependencies as minimal as possible:
98  * for example, if all you need is resource loading, implement ResourceLoaderAware only.
99  * Alternatively, derive from the WebApplicationObjectSupport base class, which gives
100  * you all those references through convenient accessors - but requires an
101  * ApplicationContext reference on initialization.
102  *
103  * <p>Controllers can optionally implement the LastModified interface.
104  *
105  * @author Rod Johnson
106  * @author Juergen Hoeller
107  * @see LastModified
108  * @see SimpleControllerHandlerAdapter
109  * @see AbstractController
110  * @see AbstractCommandController
111  * @see SimpleFormController
112  * @see org.springframework.mock.web.MockHttpServletRequest
113  * @see org.springframework.mock.web.MockHttpServletResponse
114  * @see org.springframework.context.ApplicationContextAware
115  * @see org.springframework.context.ResourceLoaderAware
116  * @see org.springframework.web.context.ServletContextAware
117  * @see org.springframework.web.context.support.WebApplicationObjectSupport
118  */
119 public interface Controller {
120
121     /**
122      * Process the request and return a ModelAndView object which the DispatcherServlet
123      * will render. A <code>null</code> return value is not an error: It indicates that
124      * this object completed request processing itself, thus there is no ModelAndView
125      * to render.
126      * @param request current HTTP request
127      * @param response current HTTP response
128      * @return a ModelAndView to render, or <code>null</code> if handled directly
129      * @throws Exception in case of errors
130      */
131     ModelAndView handleRequest(HttpServletRequest JavaDoc request, HttpServletResponse JavaDoc response) throws Exception JavaDoc;
132
133 }
134
Popular Tags