KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > springframework > web > servlet > HandlerMapping


1 /*
2  * Copyright 2002-2007 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;
18
19 import javax.servlet.http.HttpServletRequest JavaDoc;
20
21 /**
22  * Interface to be implemented by objects that define a mapping between
23  * requests and handler objects.
24  *
25  * <p>This class can be implemented by application developers, although this is not
26  * necessary, as {@link org.springframework.web.servlet.handler.BeanNameUrlHandlerMapping}
27  * and {@link org.springframework.web.servlet.handler.SimpleUrlHandlerMapping}
28  * are included in the framework. The former is the default if no
29  * HandlerMapping bean is registered in the application context.
30  *
31  * <p>HandlerMapping implementations can support mapped interceptors but do not
32  * have to. A handler will always be wrapped in a {@link HandlerExecutionChain}
33  * instance, optionally accompanied by some {@link HandlerInterceptor} instances.
34  * The DispatcherServlet will first call each HandlerInterceptor's
35  * <code>preHandle</code> method in the given order, finally invoking the handler
36  * itself if all <code>preHandle</code> methods have returned <code>true</code>.
37  *
38  * <p>The ability to parameterize this mapping is a powerful and unusual
39  * capability of this MVC framework. For example, it is possible to write
40  * a custom mapping based on session state, cookie state or many other
41  * variables. No other MVC framework seems to be equally flexible.
42  *
43  * <p>Note: Implementations can implement the {@link org.springframework.core.Ordered}
44  * interface to be able to specify a sorting order and thus a priority for getting
45  * applied by DispatcherServlet. Non-Ordered instances get treated as lowest priority.
46  *
47  * @author Rod Johnson
48  * @author Juergen Hoeller
49  * @see org.springframework.core.Ordered
50  * @see org.springframework.web.servlet.handler.AbstractHandlerMapping
51  * @see org.springframework.web.servlet.handler.BeanNameUrlHandlerMapping
52  * @see org.springframework.web.servlet.handler.SimpleUrlHandlerMapping
53  */
54 public interface HandlerMapping {
55
56     /**
57      * Name of the {@link HttpServletRequest} attribute that contains the path
58      * within the handler mapping, in case of a pattern match, or the full
59      * relevant URI (typically within the DispatcherServlet's mapping) else.
60      * <p>Note: This attribute is not required to be supported by all
61      * HandlerMapping implementations. URL-based HandlerMappings will
62      * typically support it, but handlers should not necessarily expect
63      * this request attribute to be present in all scenarios.
64      */
65     String JavaDoc PATH_WITHIN_HANDLER_MAPPING_ATTRIBUTE = HandlerMapping.class.getName() + ".pathWithinHandlerMapping";
66
67
68     /**
69      * Return a handler and any interceptors for this request. The choice may be made
70      * on request URL, session state, or any factor the implementing class chooses.
71      * <p>The returned HandlerExecutionChain contains a handler Object, rather than
72      * even a tag interface, so that handlers are not constrained in any way.
73      * For example, a HandlerAdapter could be written to allow another framework's
74      * handler objects to be used.
75      * <p>Returns <code>null</code> if no match was found. This is not an error.
76      * The DispatcherServlet will query all registered HandlerMapping beans to find
77      * a match, and only decide there is an error if none can find a handler.
78      * @param request current HTTP request
79      * @return a HandlerExecutionChain instance containing handler object and
80      * any interceptors, or <code>null</code> if no mapping found
81      * @throws Exception if there is an internal error
82      */
83     HandlerExecutionChain getHandler(HttpServletRequest JavaDoc request) throws Exception JavaDoc;
84
85 }
86
Popular Tags