001/*
002 * Copyright 2002-2019 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.ui;
018
019import java.util.Collection;
020import java.util.LinkedHashMap;
021import java.util.Map;
022
023import org.springframework.core.Conventions;
024import org.springframework.lang.Nullable;
025import org.springframework.util.Assert;
026
027/**
028 * Implementation of {@link java.util.Map} for use when building model data for use
029 * with UI tools. Supports chained calls and generation of model attribute names.
030 *
031 * <p>This class serves as generic model holder for Servlet MVC but is not tied to it.
032 * Check out the {@link Model} interface for an interface variant.
033 *
034 * @author Rob Harrop
035 * @author Juergen Hoeller
036 * @since 2.0
037 * @see Conventions#getVariableName
038 * @see org.springframework.web.servlet.ModelAndView
039 */
040@SuppressWarnings("serial")
041public class ModelMap extends LinkedHashMap<String, Object> {
042
043        /**
044         * Construct a new, empty {@code ModelMap}.
045         */
046        public ModelMap() {
047        }
048
049        /**
050         * Construct a new {@code ModelMap} containing the supplied attribute
051         * under the supplied name.
052         * @see #addAttribute(String, Object)
053         */
054        public ModelMap(String attributeName, @Nullable Object attributeValue) {
055                addAttribute(attributeName, attributeValue);
056        }
057
058        /**
059         * Construct a new {@code ModelMap} containing the supplied attribute.
060         * Uses attribute name generation to generate the key for the supplied model
061         * object.
062         * @see #addAttribute(Object)
063         */
064        public ModelMap(Object attributeValue) {
065                addAttribute(attributeValue);
066        }
067
068
069        /**
070         * Add the supplied attribute under the supplied name.
071         * @param attributeName the name of the model attribute (never {@code null})
072         * @param attributeValue the model attribute value (can be {@code null})
073         */
074        public ModelMap addAttribute(String attributeName, @Nullable Object attributeValue) {
075                Assert.notNull(attributeName, "Model attribute name must not be null");
076                put(attributeName, attributeValue);
077                return this;
078        }
079
080        /**
081         * Add the supplied attribute to this {@code Map} using a
082         * {@link org.springframework.core.Conventions#getVariableName generated name}.
083         * <p><i>Note: Empty {@link Collection Collections} are not added to
084         * the model when using this method because we cannot correctly determine
085         * the true convention name. View code should check for {@code null} rather
086         * than for empty collections as is already done by JSTL tags.</i>
087         * @param attributeValue the model attribute value (never {@code null})
088         */
089        public ModelMap addAttribute(Object attributeValue) {
090                Assert.notNull(attributeValue, "Model object must not be null");
091                if (attributeValue instanceof Collection && ((Collection<?>) attributeValue).isEmpty()) {
092                        return this;
093                }
094                return addAttribute(Conventions.getVariableName(attributeValue), attributeValue);
095        }
096
097        /**
098         * Copy all attributes in the supplied {@code Collection} into this
099         * {@code Map}, using attribute name generation for each element.
100         * @see #addAttribute(Object)
101         */
102        public ModelMap addAllAttributes(@Nullable Collection<?> attributeValues) {
103                if (attributeValues != null) {
104                        for (Object attributeValue : attributeValues) {
105                                addAttribute(attributeValue);
106                        }
107                }
108                return this;
109        }
110
111        /**
112         * Copy all attributes in the supplied {@code Map} into this {@code Map}.
113         * @see #addAttribute(String, Object)
114         */
115        public ModelMap addAllAttributes(@Nullable Map<String, ?> attributes) {
116                if (attributes != null) {
117                        putAll(attributes);
118                }
119                return this;
120        }
121
122        /**
123         * Copy all attributes in the supplied {@code Map} into this {@code Map},
124         * with existing objects of the same name taking precedence (i.e. not getting
125         * replaced).
126         */
127        public ModelMap mergeAttributes(@Nullable Map<String, ?> attributes) {
128                if (attributes != null) {
129                        attributes.forEach((key, value) -> {
130                                if (!containsKey(key)) {
131                                        put(key, value);
132                                }
133                        });
134                }
135                return this;
136        }
137
138        /**
139         * Does this model contain an attribute of the given name?
140         * @param attributeName the name of the model attribute (never {@code null})
141         * @return whether this model contains a corresponding attribute
142         */
143        public boolean containsAttribute(String attributeName) {
144                return containsKey(attributeName);
145        }
146
147        /**
148         * Return the attribute value for the given name, if any.
149         * @param attributeName the name of the model attribute (never {@code null})
150         * @return the corresponding attribute value, or {@code null} if none
151         * @since 5.2
152         */
153        @Nullable
154        public Object getAttribute(String attributeName) {
155                return get(attributeName);
156        }
157
158}