001/*
002 * Copyright 2002-2018 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.bind.annotation;
018
019import java.beans.PropertyEditor;
020import java.lang.annotation.Documented;
021import java.lang.annotation.ElementType;
022import java.lang.annotation.Retention;
023import java.lang.annotation.RetentionPolicy;
024import java.lang.annotation.Target;
025
026import org.springframework.core.annotation.AliasFor;
027import org.springframework.core.convert.converter.Converter;
028import org.springframework.http.converter.HttpMessageConverter;
029import org.springframework.web.multipart.MultipartFile;
030import org.springframework.web.multipart.MultipartResolver;
031
032/**
033 * Annotation that can be used to associate the part of a "multipart/form-data" request
034 * with a method argument.
035 *
036 * <p>Supported method argument types include {@link MultipartFile} in conjunction with
037 * Spring's {@link MultipartResolver} abstraction, {@code javax.servlet.http.Part} in
038 * conjunction with Servlet 3.0 multipart requests, or otherwise for any other method
039 * argument, the content of the part is passed through an {@link HttpMessageConverter}
040 * taking into consideration the 'Content-Type' header of the request part. This is
041 * analogous to what @{@link RequestBody} does to resolve an argument based on the
042 * content of a non-multipart regular request.
043 *
044 * <p>Note that @{@link RequestParam} annotation can also be used to associate the part
045 * of a "multipart/form-data" request with a method argument supporting the same method
046 * argument types. The main difference is that when the method argument is not a String
047 * or raw {@code MultipartFile} / {@code Part}, {@code @RequestParam} relies on type
048 * conversion via a registered {@link Converter} or {@link PropertyEditor} while
049 * {@link RequestPart} relies on {@link HttpMessageConverter HttpMessageConverters}
050 * taking into consideration the 'Content-Type' header of the request part.
051 * {@link RequestParam} is likely to be used with name-value form fields while
052 * {@link RequestPart} is likely to be used with parts containing more complex content
053 * e.g. JSON, XML).
054 *
055 * @author Rossen Stoyanchev
056 * @author Arjen Poutsma
057 * @author Sam Brannen
058 * @since 3.1
059 * @see RequestParam
060 * @see org.springframework.web.servlet.mvc.method.annotation.RequestMappingHandlerAdapter
061 */
062@Target(ElementType.PARAMETER)
063@Retention(RetentionPolicy.RUNTIME)
064@Documented
065public @interface RequestPart {
066
067        /**
068         * Alias for {@link #name}.
069         */
070        @AliasFor("name")
071        String value() default "";
072
073        /**
074         * The name of the part in the {@code "multipart/form-data"} request to bind to.
075         * @since 4.2
076         */
077        @AliasFor("value")
078        String name() default "";
079
080        /**
081         * Whether the part is required.
082         * <p>Defaults to {@code true}, leading to an exception being thrown
083         * if the part is missing in the request. Switch this to
084         * {@code false} if you prefer a {@code null} value if the part is
085         * not present in the request.
086         */
087        boolean required() default true;
088
089}