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.validation;
018
019import java.beans.PropertyEditor;
020import java.util.Map;
021
022import org.springframework.beans.PropertyEditorRegistry;
023import org.springframework.lang.Nullable;
024
025/**
026 * General interface that represents binding results. Extends the
027 * {@link Errors interface} for error registration capabilities,
028 * allowing for a {@link Validator} to be applied, and adds
029 * binding-specific analysis and model building.
030 *
031 * <p>Serves as result holder for a {@link DataBinder}, obtained via
032 * the {@link DataBinder#getBindingResult()} method. BindingResult
033 * implementations can also be used directly, for example to invoke
034 * a {@link Validator} on it (e.g. as part of a unit test).
035 *
036 * @author Juergen Hoeller
037 * @since 2.0
038 * @see DataBinder
039 * @see Errors
040 * @see Validator
041 * @see BeanPropertyBindingResult
042 * @see DirectFieldBindingResult
043 * @see MapBindingResult
044 */
045public interface BindingResult extends Errors {
046
047        /**
048         * Prefix for the name of the BindingResult instance in a model,
049         * followed by the object name.
050         */
051        String MODEL_KEY_PREFIX = BindingResult.class.getName() + ".";
052
053
054        /**
055         * Return the wrapped target object, which may be a bean, an object with
056         * public fields, a Map - depending on the concrete binding strategy.
057         */
058        @Nullable
059        Object getTarget();
060
061        /**
062         * Return a model Map for the obtained state, exposing a BindingResult
063         * instance as '{@link #MODEL_KEY_PREFIX MODEL_KEY_PREFIX} + objectName'
064         * and the object itself as 'objectName'.
065         * <p>Note that the Map is constructed every time you're calling this method.
066         * Adding things to the map and then re-calling this method will not work.
067         * <p>The attributes in the model Map returned by this method are usually
068         * included in the {@link org.springframework.web.servlet.ModelAndView}
069         * for a form view that uses Spring's {@code bind} tag in a JSP,
070         * which needs access to the BindingResult instance. Spring's pre-built
071         * form controllers will do this for you when rendering a form view.
072         * When building the ModelAndView instance yourself, you need to include
073         * the attributes from the model Map returned by this method.
074         * @see #getObjectName()
075         * @see #MODEL_KEY_PREFIX
076         * @see org.springframework.web.servlet.ModelAndView
077         * @see org.springframework.web.servlet.tags.BindTag
078         */
079        Map<String, Object> getModel();
080
081        /**
082         * Extract the raw field value for the given field.
083         * Typically used for comparison purposes.
084         * @param field the field to check
085         * @return the current value of the field in its raw form, or {@code null} if not known
086         */
087        @Nullable
088        Object getRawFieldValue(String field);
089
090        /**
091         * Find a custom property editor for the given type and property.
092         * @param field the path of the property (name or nested path), or
093         * {@code null} if looking for an editor for all properties of the given type
094         * @param valueType the type of the property (can be {@code null} if a property
095         * is given but should be specified in any case for consistency checking)
096         * @return the registered editor, or {@code null} if none
097         */
098        @Nullable
099        PropertyEditor findEditor(@Nullable String field, @Nullable Class<?> valueType);
100
101        /**
102         * Return the underlying PropertyEditorRegistry.
103         * @return the PropertyEditorRegistry, or {@code null} if none
104         * available for this BindingResult
105         */
106        @Nullable
107        PropertyEditorRegistry getPropertyEditorRegistry();
108
109        /**
110         * Resolve the given error code into message codes.
111         * <p>Calls the configured {@link MessageCodesResolver} with appropriate parameters.
112         * @param errorCode the error code to resolve into message codes
113         * @return the resolved message codes
114         */
115        String[] resolveMessageCodes(String errorCode);
116
117        /**
118         * Resolve the given error code into message codes for the given field.
119         * <p>Calls the configured {@link MessageCodesResolver} with appropriate parameters.
120         * @param errorCode the error code to resolve into message codes
121         * @param field the field to resolve message codes for
122         * @return the resolved message codes
123         */
124        String[] resolveMessageCodes(String errorCode, String field);
125
126        /**
127         * Add a custom {@link ObjectError} or {@link FieldError} to the errors list.
128         * <p>Intended to be used by cooperating strategies such as {@link BindingErrorProcessor}.
129         * @see ObjectError
130         * @see FieldError
131         * @see BindingErrorProcessor
132         */
133        void addError(ObjectError error);
134
135        /**
136         * Record the given value for the specified field.
137         * <p>To be used when a target object cannot be constructed, making
138         * the original field values available through {@link #getFieldValue}.
139         * In case of a registered error, the rejected value will be exposed
140         * for each affected field.
141         * @param field the field to record the value for
142         * @param type the type of the field
143         * @param value the original value
144         * @since 5.0.4
145         */
146        default void recordFieldValue(String field, Class<?> type, @Nullable Object value) {
147        }
148
149        /**
150         * Mark the specified disallowed field as suppressed.
151         * <p>The data binder invokes this for each field value that was
152         * detected to target a disallowed field.
153         * @see DataBinder#setAllowedFields
154         */
155        default void recordSuppressedField(String field) {
156        }
157
158        /**
159         * Return the list of fields that were suppressed during the bind process.
160         * <p>Can be used to determine whether any field values were targeting
161         * disallowed fields.
162         * @see DataBinder#setAllowedFields
163         */
164        default String[] getSuppressedFields() {
165                return new String[0];
166        }
167
168}