001: /*
002: * Copyright 2002-2007 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: * http://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:
017: package org.springframework.web.bind.annotation;
018:
019: import java.lang.annotation.Documented;
020: import java.lang.annotation.ElementType;
021: import java.lang.annotation.Retention;
022: import java.lang.annotation.RetentionPolicy;
023: import java.lang.annotation.Target;
024:
025: /**
026: * Annotation for mapping web requests onto specific handler classes and/or
027: * handler methods. Provides consistent style between Servlet and Portlet
028: * environments, with the semantics adapting to the concrete environment.
029: *
030: * <p><b>NOTE:</b> Method-level mappings are only allowed to narrow the mapping
031: * expressed at the class level (if any). HTTP paths / portlet modes need to
032: * uniquely map onto specific handler beans, with any given path / mode only
033: * allowed to be mapped onto one specific handler bean (not spread across
034: * multiple handler beans). It is strongly recommended to co-locate related
035: * handler methods into the same bean.
036: *
037: * <p>Handler methods which are annotated with this annotation are allowed
038: * to have very flexible signatures. They may have arguments of the following
039: * types, in arbitrary order (except for validation results, which need to
040: * follow right after the corresponding command object, if desired):
041: * <ul>
042: * <li>request / response / session (Servlet API or Portlet API).
043: * <li>{@link org.springframework.web.context.request.WebRequest}.
044: * <li>{@link java.util.Locale} for the current request locale.
045: * <li>{@link java.io.InputStream} / {@link java.io.Reader} for access
046: * to the request's content.
047: * <li>{@link java.io.OutputStream} / {@link java.io.Writer} for generating
048: * the response's content.
049: * <li>{@link RequestParam @RequestParam} annotated parameters for access to
050: * specific request parameters.
051: * <li>{@link java.util.Map} / {@link org.springframework.ui.ModelMap} for
052: * enriching the implicit model that will be exposed to the web view.
053: * <li>Command/form objects to bind parameters to: as bean properties or fields,
054: * with customizable type conversion, depending on {@link InitBinder} methods
055: * and/or the HandlerAdapter configuration - see the "webBindingInitializer"
056: * property on AnnotationMethodHandlerAdapter.
057: * Such command objects along with their validation results will be exposed
058: * as model attributes, by default using the non-qualified command class name
059: * in property notation (e.g. "orderAddress" for type "mypackage.OrderAddress").
060: * Specify a parameter-level {@link ModelAttribute} annotation for declaring
061: * a specific model attribute name.
062: * <li>{@link org.springframework.validation.Errors} /
063: * {@link org.springframework.validation.BindingResult} validation results
064: * for a preceding command/form object (the immediate preceding argument).
065: * <li>{@link org.springframework.web.bind.support.SessionStatus} status handle
066: * for marking form processing as complete (triggering the cleanup of session
067: * attributes that have been indicated by the {@link SessionAttributes} annotation
068: * at the handler type level).
069: * </ul>
070: *
071: * <p>The following return types are supported for handler methods:
072: * <ul>
073: * <li>A <code>ModelAndView</code> object (Servlet MVC or Portlet MVC),
074: * with the model implicitly enriched with command objects and the results
075: * of {@link ModelAttribute} annotated reference data accessor methods.
076: * <li>A {@link java.util.Map} object for exposing a model,
077: * with the view name implicitly determined through a
078: * {@link org.springframework.web.servlet.RequestToViewNameTranslator}
079: * and the model implicitly enriched with command objects and the results
080: * of {@link ModelAttribute} annotated reference data accessor methods.
081: * <li>A {@link java.lang.String} value which is interpreted as view name,
082: * with the model implicitly determined through command objects and
083: * {@link ModelAttribute} annotated reference data accessor methods.
084: * The handler method may also programmatically enrich the model through
085: * declaring a {@link org.springframework.ui.ModelMap} attribute (see above).
086: * <li><code>void</code> if the method handles the response itself
087: * (e.g. through writing the response content directly).
088: * </ul>
089: *
090: * <p><b>NOTE: <code>@RequestMapping</code> will only be processed if a
091: * corresponding <code>HandlerMapping</code> (for type level annotations)
092: * and/or <code>HandlerAdapter</code> (for method level annotations) is
093: * present in the dispatcher.</b> This is the case by default in both
094: * <code>DispatcherServlet</code> and <code>DispatcherPortlet</code>.
095: * However, if you are defining custom <code>HandlerMappings</code> or
096: * <code>HandlerAdapters</code>, then you need to make sure that a
097: * corresponding custom <code>DefaultAnnotationHandlerMapping</code>
098: * and/or <code>AnnotationMethodHandlerAdapter</code> is defined as well
099: * - provided that you intend to use <code>@RequestMapping</code>.
100: *
101: * @author Juergen Hoeller
102: * @author Arjen Poutsma
103: * @since 2.5
104: * @see RequestParam
105: * @see ModelAttribute
106: * @see SessionAttributes
107: * @see InitBinder
108: * @see org.springframework.web.context.request.WebRequest
109: * @see org.springframework.web.servlet.mvc.annotation.DefaultAnnotationHandlerMapping
110: * @see org.springframework.web.servlet.mvc.annotation.AnnotationMethodHandlerAdapter
111: * @see org.springframework.web.portlet.mvc.annotation.DefaultAnnotationHandlerMapping
112: * @see org.springframework.web.portlet.mvc.annotation.AnnotationMethodHandlerAdapter
113: */
114: @Target({ElementType.METHOD,ElementType.TYPE})
115: @Retention(RetentionPolicy.RUNTIME)
116: @Documented
117: public @interface RequestMapping {
118:
119: /**
120: * The primary mapping expressed by this annotation.
121: * <p>In a Servlet environment: the path mapping URLs (e.g. "/myPath.do")
122: * <p>In a Portlet environment: the mapped portlet modes (e.g. "EDIT")
123: * <p><b>Supported at the type level as well as at the method level!</b>
124: * When used at the type level, all method level mappings inherit
125: * this primary mapping, narrowing it for a specific handler method.
126: */
127: String[] value() default {};
128:
129: /**
130: * The HTTP request methods to map to, narrowing the primary mapping:
131: * GET, POST, HEAD, OPTIONS, PUT, DELETE, TRACE.
132: * <p><b>Only supported at the handler method level in Servlet environments!</b>
133: */
134: RequestMethod[] method() default {};
135:
136: /**
137: * The parameters of the mapped request, narrowing the primary mapping.
138: * <p>Same format for any environment: a sequence of "myParam=myValue" style
139: * expressions, with a request only mapped if each such parameter is found
140: * to have the given value. "myParam" style expressions are also supported,
141: * with such parameters having to be present in the request (allowed to
142: * have any value).
143: * <p><b>Only supported at the handler method level!</b>
144: */
145: String[] params() default {};
146:
147: }
|