001/*
002 * Copyright 2002-2020 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.core.env;
018
019import org.springframework.lang.Nullable;
020
021/**
022 * Interface for resolving properties against any underlying source.
023 *
024 * @author Chris Beams
025 * @author Juergen Hoeller
026 * @since 3.1
027 * @see Environment
028 * @see PropertySourcesPropertyResolver
029 */
030public interface PropertyResolver {
031
032        /**
033         * Return whether the given property key is available for resolution,
034         * i.e. if the value for the given key is not {@code null}.
035         */
036        boolean containsProperty(String key);
037
038        /**
039         * Return the property value associated with the given key,
040         * or {@code null} if the key cannot be resolved.
041         * @param key the property name to resolve
042         * @see #getProperty(String, String)
043         * @see #getProperty(String, Class)
044         * @see #getRequiredProperty(String)
045         */
046        @Nullable
047        String getProperty(String key);
048
049        /**
050         * Return the property value associated with the given key, or
051         * {@code defaultValue} if the key cannot be resolved.
052         * @param key the property name to resolve
053         * @param defaultValue the default value to return if no value is found
054         * @see #getRequiredProperty(String)
055         * @see #getProperty(String, Class)
056         */
057        String getProperty(String key, String defaultValue);
058
059        /**
060         * Return the property value associated with the given key,
061         * or {@code null} if the key cannot be resolved.
062         * @param key the property name to resolve
063         * @param targetType the expected type of the property value
064         * @see #getRequiredProperty(String, Class)
065         */
066        @Nullable
067        <T> T getProperty(String key, Class<T> targetType);
068
069        /**
070         * Return the property value associated with the given key,
071         * or {@code defaultValue} if the key cannot be resolved.
072         * @param key the property name to resolve
073         * @param targetType the expected type of the property value
074         * @param defaultValue the default value to return if no value is found
075         * @see #getRequiredProperty(String, Class)
076         */
077        <T> T getProperty(String key, Class<T> targetType, T defaultValue);
078
079        /**
080         * Return the property value associated with the given key (never {@code null}).
081         * @throws IllegalStateException if the key cannot be resolved
082         * @see #getRequiredProperty(String, Class)
083         */
084        String getRequiredProperty(String key) throws IllegalStateException;
085
086        /**
087         * Return the property value associated with the given key, converted to the given
088         * targetType (never {@code null}).
089         * @throws IllegalStateException if the given key cannot be resolved
090         */
091        <T> T getRequiredProperty(String key, Class<T> targetType) throws IllegalStateException;
092
093        /**
094         * Resolve ${...} placeholders in the given text, replacing them with corresponding
095         * property values as resolved by {@link #getProperty}. Unresolvable placeholders with
096         * no default value are ignored and passed through unchanged.
097         * @param text the String to resolve
098         * @return the resolved String (never {@code null})
099         * @throws IllegalArgumentException if given text is {@code null}
100         * @see #resolveRequiredPlaceholders
101         */
102        String resolvePlaceholders(String text);
103
104        /**
105         * Resolve ${...} placeholders in the given text, replacing them with corresponding
106         * property values as resolved by {@link #getProperty}. Unresolvable placeholders with
107         * no default value will cause an IllegalArgumentException to be thrown.
108         * @return the resolved String (never {@code null})
109         * @throws IllegalArgumentException if given text is {@code null}
110         * or if any placeholders are unresolvable
111         */
112        String resolveRequiredPlaceholders(String text) throws IllegalArgumentException;
113
114}