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.source;
018
019import java.util.function.Predicate;
020
021import org.springframework.boot.origin.OriginTrackedValue;
022
023/**
024 * A source of {@link ConfigurationProperty ConfigurationProperties}.
025 *
026 * @author Phillip Webb
027 * @author Madhura Bhave
028 * @since 2.0.0
029 * @see ConfigurationPropertyName
030 * @see OriginTrackedValue
031 * @see #getConfigurationProperty(ConfigurationPropertyName)
032 */
033@FunctionalInterface
034public interface ConfigurationPropertySource {
035
036        /**
037         * Return a single {@link ConfigurationProperty} from the source or {@code null} if no
038         * property can be found.
039         * @param name the name of the property (must not be {@code null})
040         * @return the associated object or {@code null}.
041         */
042        ConfigurationProperty getConfigurationProperty(ConfigurationPropertyName name);
043
044        /**
045         * Returns if the source contains any descendants of the specified name. May return
046         * {@link ConfigurationPropertyState#PRESENT} or
047         * {@link ConfigurationPropertyState#ABSENT} if an answer can be determined or
048         * {@link ConfigurationPropertyState#UNKNOWN} if it's not possible to determine a
049         * definitive answer.
050         * @param name the name to check
051         * @return if the source contains any descendants
052         */
053        default ConfigurationPropertyState containsDescendantOf(
054                        ConfigurationPropertyName name) {
055                return ConfigurationPropertyState.UNKNOWN;
056        }
057
058        /**
059         * Return a filtered variant of this source, containing only names that match the
060         * given {@link Predicate}.
061         * @param filter the filter to match
062         * @return a filtered {@link ConfigurationPropertySource} instance
063         */
064        default ConfigurationPropertySource filter(
065                        Predicate<ConfigurationPropertyName> filter) {
066                return new FilteredConfigurationPropertiesSource(this, filter);
067        }
068
069        /**
070         * Return a variant of this source that supports name aliases.
071         * @param aliases a function that returns a stream of aliases for any given name
072         * @return a {@link ConfigurationPropertySource} instance supporting name aliases
073         */
074        default ConfigurationPropertySource withAliases(
075                        ConfigurationPropertyNameAliases aliases) {
076                return new AliasedConfigurationPropertySource(this, aliases);
077        }
078
079        /**
080         * Return the underlying source that is actually providing the properties.
081         * @return the underlying property source or {@code null}.
082         */
083        default Object getUnderlyingSource() {
084                return null;
085        }
086
087}