/*
 * Copyright 2002-2016 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      https://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.springframework.core.env;

import org.springframework.core.convert.support.ConfigurableConversionService;
import org.springframework.lang.Nullable;

Configuration interface to be implemented by most if not all PropertyResolver types. Provides facilities for accessing and customizing the ConversionService used when converting property values from one type to another. 
Author:
Chris Beams
Since:
3.1/**
 * Configuration interface to be implemented by most if not all {@link PropertyResolver}
 * types. Provides facilities for accessing and customizing the
 * {@link org.springframework.core.convert.ConversionService ConversionService}
 * used when converting property values from one type to another.
 *
 * @author Chris Beams
 * @since 3.1
 */
public interface ConfigurablePropertyResolver extends PropertyResolver {

	
Return the ConfigurableConversionService used when performing type conversions on properties. 
The configurable nature of the returned conversion service allows for the convenient addition and removal of individual Converter instances: 
ConfigurableConversionService cs = env.getConversionService();
cs.addConverter(new FooConverter());

See Also:
PropertyResolver.getProperty(String, Class<Object>)
ConverterRegistry.addConverter/**
	 * Return the {@link ConfigurableConversionService} used when performing type
	 * conversions on properties.
	 * <p>The configurable nature of the returned conversion service allows for
	 * the convenient addition and removal of individual {@code Converter} instances:
	 * <pre class="code">
	 * ConfigurableConversionService cs = env.getConversionService();
	 * cs.addConverter(new FooConverter());
	 * </pre>
	 * @see PropertyResolver#getProperty(String, Class)
	 * @see org.springframework.core.convert.converter.ConverterRegistry#addConverter
	 */
	ConfigurableConversionService getConversionService();

	
Set the ConfigurableConversionService to be used when performing type conversions on properties. 
Note: as an alternative to fully replacing the ConversionService, consider adding or removing individual Converter instances by drilling into getConversionService() and calling methods such as #addConverter. 
See Also:
PropertyResolver.getProperty(String, Class<Object>)
getConversionService()
ConverterRegistry.addConverter/**
	 * Set the {@link ConfigurableConversionService} to be used when performing type
	 * conversions on properties.
	 * <p><strong>Note:</strong> as an alternative to fully replacing the
	 * {@code ConversionService}, consider adding or removing individual
	 * {@code Converter} instances by drilling into {@link #getConversionService()}
	 * and calling methods such as {@code #addConverter}.
	 * @see PropertyResolver#getProperty(String, Class)
	 * @see #getConversionService()
	 * @see org.springframework.core.convert.converter.ConverterRegistry#addConverter
	 */
	void setConversionService(ConfigurableConversionService conversionService);

	
Set the prefix that placeholders replaced by this resolver must begin with.
/**
	 * Set the prefix that placeholders replaced by this resolver must begin with.
	 */
	void setPlaceholderPrefix(String placeholderPrefix);

	
Set the suffix that placeholders replaced by this resolver must end with.
/**
	 * Set the suffix that placeholders replaced by this resolver must end with.
	 */
	void setPlaceholderSuffix(String placeholderSuffix);

	
Specify the separating character between the placeholders replaced by this resolver and their associated default value, or null if no such special character should be processed as a value separator. /**
	 * Specify the separating character between the placeholders replaced by this
	 * resolver and their associated default value, or {@code null} if no such
	 * special character should be processed as a value separator.
	 */
	void setValueSeparator(@Nullable String valueSeparator);

	
Set whether to throw an exception when encountering an unresolvable placeholder nested within the value of a given property. A false value indicates strict resolution, i.e. that an exception will be thrown. A true value indicates that unresolvable nested placeholders should be passed through in their unresolved ${...} form. 
Implementations of PropertyResolver.getProperty(String) and its variants must inspect the value set here to determine correct behavior when property values contain unresolvable placeholders. 
Since:
3.2/**
	 * Set whether to throw an exception when encountering an unresolvable placeholder
	 * nested within the value of a given property. A {@code false} value indicates strict
	 * resolution, i.e. that an exception will be thrown. A {@code true} value indicates
	 * that unresolvable nested placeholders should be passed through in their unresolved
	 * ${...} form.
	 * <p>Implementations of {@link #getProperty(String)} and its variants must inspect
	 * the value set here to determine correct behavior when property values contain
	 * unresolvable placeholders.
	 * @since 3.2
	 */
	void setIgnoreUnresolvableNestedPlaceholders(boolean ignoreUnresolvableNestedPlaceholders);

	
Specify which properties must be present, to be verified by validateRequiredProperties(). /**
	 * Specify which properties must be present, to be verified by
	 * {@link #validateRequiredProperties()}.
	 */
	void setRequiredProperties(String... requiredProperties);

	
Validate that each of the properties specified by setRequiredProperties is present and resolves to a non-null value. 
Throws:
MissingRequiredPropertiesException – if any of the required
properties are not resolvable./**
	 * Validate that each of the properties specified by
	 * {@link #setRequiredProperties} is present and resolves to a
	 * non-{@code null} value.
	 * @throws MissingRequiredPropertiesException if any of the required
	 * properties are not resolvable.
	 */
	void validateRequiredProperties() throws MissingRequiredPropertiesException;

}