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.beans;
018
019import java.beans.PropertyEditor;
020
021import org.springframework.lang.Nullable;
022
023/**
024 * Encapsulates methods for registering JavaBeans {@link PropertyEditor PropertyEditors}.
025 * This is the central interface that a {@link PropertyEditorRegistrar} operates on.
026 *
027 * <p>Extended by {@link BeanWrapper}; implemented by {@link BeanWrapperImpl}
028 * and {@link org.springframework.validation.DataBinder}.
029 *
030 * @author Juergen Hoeller
031 * @since 1.2.6
032 * @see java.beans.PropertyEditor
033 * @see PropertyEditorRegistrar
034 * @see BeanWrapper
035 * @see org.springframework.validation.DataBinder
036 */
037public interface PropertyEditorRegistry {
038
039        /**
040         * Register the given custom property editor for all properties of the given type.
041         * @param requiredType the type of the property
042         * @param propertyEditor the editor to register
043         */
044        void registerCustomEditor(Class<?> requiredType, PropertyEditor propertyEditor);
045
046        /**
047         * Register the given custom property editor for the given type and
048         * property, or for all properties of the given type.
049         * <p>If the property path denotes an array or Collection property,
050         * the editor will get applied either to the array/Collection itself
051         * (the {@link PropertyEditor} has to create an array or Collection value) or
052         * to each element (the {@code PropertyEditor} has to create the element type),
053         * depending on the specified required type.
054         * <p>Note: Only one single registered custom editor per property path
055         * is supported. In the case of a Collection/array, do not register an editor
056         * for both the Collection/array and each element on the same property.
057         * <p>For example, if you wanted to register an editor for "items[n].quantity"
058         * (for all values n), you would use "items.quantity" as the value of the
059         * 'propertyPath' argument to this method.
060         * @param requiredType the type of the property. This may be {@code null}
061         * if a property is given but should be specified in any case, in particular in
062         * case of a Collection - making clear whether the editor is supposed to apply
063         * to the entire Collection itself or to each of its entries. So as a general rule:
064         * <b>Do not specify {@code null} here in case of a Collection/array!</b>
065         * @param propertyPath the path of the property (name or nested path), or
066         * {@code null} if registering an editor for all properties of the given type
067         * @param propertyEditor editor to register
068         */
069        void registerCustomEditor(@Nullable Class<?> requiredType, @Nullable String propertyPath, PropertyEditor propertyEditor);
070
071        /**
072         * Find a custom property editor for the given type and property.
073         * @param requiredType the type of the property (can be {@code null} if a property
074         * is given but should be specified in any case for consistency checking)
075         * @param propertyPath the path of the property (name or nested path), or
076         * {@code null} if looking for an editor for all properties of the given type
077         * @return the registered editor, or {@code null} if none
078         */
079        @Nullable
080        PropertyEditor findCustomEditor(@Nullable Class<?> requiredType, @Nullable String propertyPath);
081
082}