18154768944

Committed 01 Oct 2025 07:26AM UTC coverage: 81.882% (-0.005%) from 81.887%

Build # 18154768944

Build Type

push

github

Committed by

web-flow

Commit Message

Merge pull request #290 from TAKETODAY/dev/jspecify

jspecify

Coverage Stats

59788 of 78013 branches covered (76.64%)

Branch coverage included in aggregate %.

141239 of 167496 relevant lines covered (84.32%)

3.6 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

25.0

today-context/src/main/java/infra/validation/BindingResult.java

/*
 * Copyright 2017 - 2025 the original author or authors.
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program. If not, see [https://www.gnu.org/licenses/]
 */

package infra.validation;

import org.jspecify.annotations.Nullable;

import java.beans.PropertyEditor;
import java.util.Map;

import infra.beans.PropertyEditorRegistry;

/**
 * General interface that represents binding results. Extends the
 * {@link Errors interface} for error registration capabilities,
 * allowing for a {@link Validator} to be applied, and adds
 * binding-specific analysis and model building.
 *
 * <p>Serves as result holder for a {@link DataBinder}, obtained via
 * the {@link DataBinder#getBindingResult()} method. BindingResult
 * implementations can also be used directly, for example to invoke
 * a {@link Validator} on it (e.g. as part of a unit test).
 *
 * @author Juergen Hoeller
 * @author <a href="https://github.com/TAKETODAY">海子 Yang</a>
 * @see DataBinder
 * @see Errors
 * @see Validator
 * @see BeanPropertyBindingResult
 * @see DirectFieldBindingResult
 * @see MapBindingResult
 * @since 4.0
 */
public interface BindingResult extends Errors {

  /**
   * Prefix for the name of the BindingResult instance in a model,
   * followed by the object name.
   */
  String MODEL_KEY_PREFIX = BindingResult.class.getName() + ".";

  /**
   * Return the wrapped target object, which may be a bean, an object with
   * public fields, a Map - depending on the concrete binding strategy.
   */
  @Nullable
  Object getTarget();

  /**
   * Return a model Map for the obtained state, exposing a BindingResult
   * instance as '{@link #MODEL_KEY_PREFIX MODEL_KEY_PREFIX} + objectName'
   * and the object itself as 'objectName'.
   * <p>Note that the Map is constructed every time you're calling this method.
   * Adding things to the map and then re-calling this method will not work.
   * <p>The attributes in the model Map returned by this method are usually
   * included in the {@link infra.web.view.ModelAndView}
   * for a form view that uses Framework's {@code bind} tag in a JSP,
   * which needs access to the BindingResult instance. Framework's pre-built
   * form controllers will do this for you when rendering a form view.
   * When building the ModelAndView instance yourself, you need to include
   * the attributes from the model Map returned by this method.
   *
   * @see #getObjectName()
   * @see #MODEL_KEY_PREFIX
   * @see infra.web.view.ModelAndView
   */
  Map<String, Object> getModel();

  /**
   * Extract the raw field value for the given field.
   * Typically used for comparison purposes.
   *
   * @param field the field to check
   * @return the current value of the field in its raw form, or {@code null} if not known
   */
  @Nullable
  Object getRawFieldValue(String field);

  /**
   * Find a custom property editor for the given type and property.
   *
   * @param field the path of the property (name or nested path), or
   * {@code null} if looking for an editor for all properties of the given type
   * @param valueType the type of the property (can be {@code null} if a property
   * is given but should be specified in any case for consistency checking)
   * @return the registered editor, or {@code null} if none
   */
  @Nullable
  PropertyEditor findEditor(@Nullable String field, @Nullable Class<?> valueType);

  /**
   * Return the underlying PropertyEditorRegistry.
   *
   * @return the PropertyEditorRegistry, or {@code null} if none
   * available for this BindingResult
   */
  @Nullable
  PropertyEditorRegistry getPropertyEditorRegistry();

  /**
   * Resolve the given error code into message codes.
   * <p>Calls the configured {@link MessageCodesResolver} with appropriate parameters.
   *
   * @param errorCode the error code to resolve into message codes
   * @return the resolved message codes
   */
  String[] resolveMessageCodes(String errorCode);

  /**
   * Resolve the given error code into message codes for the given field.
   * <p>Calls the configured {@link MessageCodesResolver} with appropriate parameters.
   *
   * @param errorCode the error code to resolve into message codes
   * @param field the field to resolve message codes for
   * @return the resolved message codes
   */
  String[] resolveMessageCodes(String errorCode, String field);

  /**
   * Add a custom {@link ObjectError} or {@link FieldError} to the errors list.
   * <p>Intended to be used by cooperating strategies such as {@link BindingErrorProcessor}.
   *
   * @see ObjectError
   * @see FieldError
   * @see BindingErrorProcessor
   */
  void addError(ObjectError error);

  /**
   * Record the given value for the specified field.
   * <p>To be used when a target object cannot be constructed, making
   * the original field values available through {@link #getFieldValue}.
   * In case of a registered error, the rejected value will be exposed
   * for each affected field.
   *
   * @param field the field to record the value for
   * @param type the type of the field
   * @param value the original value
   * @since 4.0
   */
  default void recordFieldValue(String field, Class<?> type, @Nullable Object value) {
  }

  /**
   * Mark the specified disallowed field as suppressed.
   * <p>The data binder invokes this for each field value that was
   * detected to target a disallowed field.
   *
   * @see DataBinder#setAllowedFields
   */
  default void recordSuppressedField(String field) {
  }

  /**
   * Return the list of fields that were suppressed during the bind process.
   * <p>Can be used to determine whether any field values were targeting
   * disallowed fields.
   *
   * @see DataBinder#setAllowedFields
   */
  default String[] getSuppressedFields() {
    return new String[0];
  }

}

1	/*
2	* Copyright 2017 - 2025 the original author or authors.
3	*
4	* This program is free software: you can redistribute it and/or modify
5	* it under the terms of the GNU General Public License as published by
6	* the Free Software Foundation, either version 3 of the License, or
7	* (at your option) any later version.
8	*
9	* This program is distributed in the hope that it will be useful,
10	* but WITHOUT ANY WARRANTY; without even the implied warranty of
11	* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12	* GNU General Public License for more details.
13	*
14	* You should have received a copy of the GNU General Public License
15	* along with this program. If not, see [https://www.gnu.org/licenses/]
16	*/
17
18	package infra.validation;
19
20	import org.jspecify.annotations.Nullable;
21
22	import java.beans.PropertyEditor;
23	import java.util.Map;
24
25	import infra.beans.PropertyEditorRegistry;
26
27	/**
28	* General interface that represents binding results. Extends the
29	* {@link Errors interface} for error registration capabilities,
30	* allowing for a {@link Validator} to be applied, and adds
31	* binding-specific analysis and model building.
32	*
33	* <p>Serves as result holder for a {@link DataBinder}, obtained via
34	* the {@link DataBinder#getBindingResult()} method. BindingResult
35	* implementations can also be used directly, for example to invoke
36	* a {@link Validator} on it (e.g. as part of a unit test).
37	*
38	* @author Juergen Hoeller
39	* @author <a href="https://github.com/TAKETODAY">海子 Yang</a>
40	* @see DataBinder
41	* @see Errors
42	* @see Validator
43	* @see BeanPropertyBindingResult
44	* @see DirectFieldBindingResult
45	* @see MapBindingResult
46	* @since 4.0
47	*/
48	public interface BindingResult extends Errors {
49
50	/**
51	* Prefix for the name of the BindingResult instance in a model,
52	* followed by the object name.
53	*/
54	String MODEL_KEY_PREFIX = BindingResult.class.getName() + ".";	5✔
55
56	/**
57	* Return the wrapped target object, which may be a bean, an object with
58	* public fields, a Map - depending on the concrete binding strategy.
59	*/
60	@Nullable
61	Object getTarget();
62
63	/**
64	* Return a model Map for the obtained state, exposing a BindingResult
65	* instance as '{@link #MODEL_KEY_PREFIX MODEL_KEY_PREFIX} + objectName'
66	* and the object itself as 'objectName'.
67	* <p>Note that the Map is constructed every time you're calling this method.
68	* Adding things to the map and then re-calling this method will not work.
69	* <p>The attributes in the model Map returned by this method are usually
70	* included in the {@link infra.web.view.ModelAndView}
71	* for a form view that uses Framework's {@code bind} tag in a JSP,
72	* which needs access to the BindingResult instance. Framework's pre-built
73	* form controllers will do this for you when rendering a form view.
74	* When building the ModelAndView instance yourself, you need to include
75	* the attributes from the model Map returned by this method.
76	*
77	* @see #getObjectName()
78	* @see #MODEL_KEY_PREFIX
79	* @see infra.web.view.ModelAndView
80	*/
81	Map<String, Object> getModel();
82
83	/**
84	* Extract the raw field value for the given field.
85	* Typically used for comparison purposes.
86	*
87	* @param field the field to check
88	* @return the current value of the field in its raw form, or {@code null} if not known
89	*/
90	@Nullable
91	Object getRawFieldValue(String field);
92
93	/**
94	* Find a custom property editor for the given type and property.
95	*
96	* @param field the path of the property (name or nested path), or
97	* {@code null} if looking for an editor for all properties of the given type
98	* @param valueType the type of the property (can be {@code null} if a property
99	* is given but should be specified in any case for consistency checking)
100	* @return the registered editor, or {@code null} if none
101	*/
102	@Nullable
103	PropertyEditor findEditor(@Nullable String field, @Nullable Class<?> valueType);
104
105	/**
106	* Return the underlying PropertyEditorRegistry.
107	*
108	* @return the PropertyEditorRegistry, or {@code null} if none
109	* available for this BindingResult
110	*/
111	@Nullable
112	PropertyEditorRegistry getPropertyEditorRegistry();
113
114	/**
115	* Resolve the given error code into message codes.
116	* <p>Calls the configured {@link MessageCodesResolver} with appropriate parameters.
117	*
118	* @param errorCode the error code to resolve into message codes
119	* @return the resolved message codes
120	*/
121	String[] resolveMessageCodes(String errorCode);
122
123	/**
124	* Resolve the given error code into message codes for the given field.
125	* <p>Calls the configured {@link MessageCodesResolver} with appropriate parameters.
126	*
127	* @param errorCode the error code to resolve into message codes
128	* @param field the field to resolve message codes for
129	* @return the resolved message codes
130	*/
131	String[] resolveMessageCodes(String errorCode, String field);
132
133	/**
134	* Add a custom {@link ObjectError} or {@link FieldError} to the errors list.
135	* <p>Intended to be used by cooperating strategies such as {@link BindingErrorProcessor}.
136	*
137	* @see ObjectError
138	* @see FieldError
139	* @see BindingErrorProcessor
140	*/
141	void addError(ObjectError error);
142
143	/**
144	* Record the given value for the specified field.
145	* <p>To be used when a target object cannot be constructed, making
146	* the original field values available through {@link #getFieldValue}.
147	* In case of a registered error, the rejected value will be exposed
148	* for each affected field.
149	*
150	* @param field the field to record the value for
151	* @param type the type of the field
152	* @param value the original value
153	* @since 4.0
154	*/
155	default void recordFieldValue(String field, Class<?> type, @Nullable Object value) {
156	}	×
157
158	/**
159	* Mark the specified disallowed field as suppressed.
160	* <p>The data binder invokes this for each field value that was
161	* detected to target a disallowed field.
162	*
163	* @see DataBinder#setAllowedFields
164	*/
165	default void recordSuppressedField(String field) {
166	}	×
167
168	/**
169	* Return the list of fields that were suppressed during the bind process.
170	* <p>Can be used to determine whether any field values were targeting
171	* disallowed fields.
172	*
173	* @see DataBinder#setAllowedFields
174	*/
175	default String[] getSuppressedFields() {
176	return new String[0];	×
177	}
178
179	}

TAKETODAY / today-infrastructure / 18154768944

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous