001/*
002 * Copyright 2002-2015 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.lang.annotation.Documented;
020import java.lang.annotation.ElementType;
021import java.lang.annotation.Retention;
022import java.lang.annotation.RetentionPolicy;
023import java.lang.annotation.Target;
024
025import org.springframework.core.annotation.AliasFor;
026
027/**
028 * Annotation which indicates that a method parameter should be bound to a
029 * name-value pair within a path segment. Supported for {@link RequestMapping}
030 * annotated handler methods in Servlet environments.
031 *
032 * <p>If the method parameter type is {@link java.util.Map} and a matrix variable
033 * name is specified, then the matrix variable value is converted to a
034 * {@link java.util.Map} assuming an appropriate conversion strategy is available.
035 *
036 * <p>If the method parameter is {@link java.util.Map Map&lt;String, String&gt;} or
037 * {@link org.springframework.util.MultiValueMap MultiValueMap&lt;String, String&gt;}
038 * and a variable name is not specified, then the map is populated with all
039 * matrix variable names and values.
040 *
041 * @author Rossen Stoyanchev
042 * @author Sam Brannen
043 * @since 3.2
044 */
045@Target(ElementType.PARAMETER)
046@Retention(RetentionPolicy.RUNTIME)
047@Documented
048public @interface MatrixVariable {
049
050        /**
051         * Alias for {@link #name}.
052         */
053        @AliasFor("name")
054        String value() default "";
055
056        /**
057         * The name of the matrix variable.
058         * @since 4.2
059         * @see #value
060         */
061        @AliasFor("value")
062        String name() default "";
063
064        /**
065         * The name of the URI path variable where the matrix variable is located,
066         * if necessary for disambiguation (e.g. a matrix variable with the same
067         * name present in more than one path segment).
068         */
069        String pathVar() default ValueConstants.DEFAULT_NONE;
070
071        /**
072         * Whether the matrix variable is required.
073         * <p>Default is {@code true}, leading to an exception being thrown in
074         * case the variable is missing in the request. Switch this to {@code false}
075         * if you prefer a {@code null} if the variable is missing.
076         * <p>Alternatively, provide a {@link #defaultValue}, which implicitly sets
077         * this flag to {@code false}.
078         */
079        boolean required() default true;
080
081        /**
082         * The default value to use as a fallback.
083         * <p>Supplying a default value implicitly sets {@link #required} to
084         * {@code false}.
085         */
086        String defaultValue() default ValueConstants.DEFAULT_NONE;
087
088}