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