001/*
002 * Copyright 2012-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 *      http://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.boot.context.properties.bind;
018
019import org.springframework.boot.context.properties.source.ConfigurationPropertyName;
020
021/**
022 * Callback interface that can be used to handle additional logic during element
023 * {@link Binder binding}.
024 *
025 * @author Phillip Webb
026 * @author Madhura Bhave
027 * @since 2.0.0
028 */
029public interface BindHandler {
030
031        /**
032         * Default no-op bind handler.
033         */
034        BindHandler DEFAULT = new BindHandler() {
035
036        };
037
038        /**
039         * Called when binding of an element starts but before any result has been determined.
040         * @param <T> the bindable source type
041         * @param name the name of the element being bound
042         * @param target the item being bound
043         * @param context the bind context
044         * @return the actual item that should be used for binding (may be {@code null})
045         */
046        default <T> Bindable<T> onStart(ConfigurationPropertyName name, Bindable<T> target,
047                        BindContext context) {
048                return target;
049        }
050
051        /**
052         * Called when binding of an element ends with a successful result. Implementations
053         * may change the ultimately returned result or perform addition validation.
054         * @param name the name of the element being bound
055         * @param target the item being bound
056         * @param context the bind context
057         * @param result the bound result (never {@code null})
058         * @return the actual result that should be used (may be {@code null})
059         */
060        default Object onSuccess(ConfigurationPropertyName name, Bindable<?> target,
061                        BindContext context, Object result) {
062                return result;
063        }
064
065        /**
066         * Called when binding fails for any reason (including failures from
067         * {@link #onSuccess} calls). Implementations may choose to swallow exceptions and
068         * return an alternative result.
069         * @param name the name of the element being bound
070         * @param target the item being bound
071         * @param context the bind context
072         * @param error the cause of the error (if the exception stands it may be re-thrown)
073         * @return the actual result that should be used (may be {@code null}).
074         * @throws Exception if the binding isn't valid
075         */
076        default Object onFailure(ConfigurationPropertyName name, Bindable<?> target,
077                        BindContext context, Exception error) throws Exception {
078                throw error;
079        }
080
081        /**
082         * Called when binding finishes, regardless of whether the property was bound or not.
083         * @param name the name of the element being bound
084         * @param target the item being bound
085         * @param context the bind context
086         * @param result the bound result (may be {@code null})
087         * @throws Exception if the binding isn't valid
088         */
089        default void onFinish(ConfigurationPropertyName name, Bindable<?> target,
090                        BindContext context, Object result) throws Exception {
091        }
092
093}