001/*
002 * Copyright 2002-2012 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.servlet.mvc.support;
018
019import java.util.Collection;
020import java.util.Map;
021
022import org.springframework.lang.Nullable;
023import org.springframework.ui.Model;
024import org.springframework.web.servlet.FlashMap;
025
026/**
027 * A specialization of the {@link Model} interface that controllers can use to
028 * select attributes for a redirect scenario. Since the intent of adding
029 * redirect attributes is very explicit --  i.e. to be used for a redirect URL,
030 * attribute values may be formatted as Strings and stored that way to make
031 * them eligible to be appended to the query string or expanded as URI
032 * variables in {@code org.springframework.web.servlet.view.RedirectView}.
033 *
034 * <p>This interface also provides a way to add flash attributes. For a
035 * general overview of flash attributes see {@link FlashMap}. You can use
036 * {@link RedirectAttributes} to store flash attributes and they will be
037 * automatically propagated to the "output" FlashMap of the current request.
038 *
039 * <p>Example usage in an {@code @Controller}:
040 * <pre class="code">
041 * &#064;RequestMapping(value = "/accounts", method = RequestMethod.POST)
042 * public String handle(Account account, BindingResult result, RedirectAttributes redirectAttrs) {
043 *   if (result.hasErrors()) {
044 *     return "accounts/new";
045 *   }
046 *   // Save account ...
047 *   redirectAttrs.addAttribute("id", account.getId()).addFlashAttribute("message", "Account created!");
048 *   return "redirect:/accounts/{id}";
049 * }
050 * </pre>
051 *
052 * <p>A RedirectAttributes model is empty when the method is called and is never
053 * used unless the method returns a redirect view name or a RedirectView.
054 *
055 * <p>After the redirect, flash attributes are automatically added to the model
056 * of the controller that serves the target URL.
057 *
058 * @author Rossen Stoyanchev
059 * @since 3.1
060 */
061public interface RedirectAttributes extends Model {
062
063        @Override
064        RedirectAttributes addAttribute(String attributeName, @Nullable Object attributeValue);
065
066        @Override
067        RedirectAttributes addAttribute(Object attributeValue);
068
069        @Override
070        RedirectAttributes addAllAttributes(Collection<?> attributeValues);
071
072        @Override
073        RedirectAttributes mergeAttributes(Map<String, ?> attributes);
074
075        /**
076         * Add the given flash attribute.
077         * @param attributeName the attribute name; never {@code null}
078         * @param attributeValue the attribute value; may be {@code null}
079         */
080        RedirectAttributes addFlashAttribute(String attributeName, @Nullable Object attributeValue);
081
082        /**
083         * Add the given flash storage using a
084         * {@link org.springframework.core.Conventions#getVariableName generated name}.
085         * @param attributeValue the flash attribute value; never {@code null}
086         */
087        RedirectAttributes addFlashAttribute(Object attributeValue);
088
089        /**
090         * Return the attributes candidate for flash storage or an empty Map.
091         */
092        Map<String, ?> getFlashAttributes();
093}