org.eclipse.microprofile.config.spi.Converter Maven / Gradle / Ivy

Go to download
/*
 ********************************************************************************
 * Copyright (c) 2011-2017 Contributors to the Eclipse Foundation
 *
 * See the NOTICE file(s) distributed with this work for additional
 * information regarding copyright ownership.
 *
 * 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
 *
 *     http://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.
 *
 * Contributors:
 *   2015-04-30 - Ron Smeral
 *      Initially authored in Apache DeltaSpike 25b2b8cc0c955a28743f
 *   2016-07-14 - Mark Struberg
 *      JavaDoc + priority
 *   2016-12-01 - Emily Jiang / IBM Corp
 *      Marking as FunctionalInterface + JavaDoc + additional types
 *
 *******************************************************************************/

package org.eclipse.microprofile.config.spi;

import java.io.Serializable;

/**
 * Interface for converting configured values from String to any Java type.
 **
 * 
Converters for the following types are provided by default:
 * 

 *     {@code boolean} and {@code Boolean}, values for {@code true}: (case insensitive)
 *     "true", "yes", "Y", "on", "1"
 *     {@code int} and {@code Integer}
 *     {@code long} and {@code Long}
 *     {@code float} and {@code Float}, a dot '.' is used to separate the fractional digits
 *     {@code double} and {@code Double}, a dot '.' is used to separate the fractional digits
 *     {@code java.lang.Class} based on the result of {@link java.lang.Class#forName}
 *
 * 
 *
 * Custom Converters will get picked up via the {@link java.util.ServiceLoader} mechanism and and can be registered by
 * providing a file

 * META-INF/services/org.eclipse.microprofile.config.spi.Converter

 * which contains the fully qualified {@code Converter} implementation class name as content.
 *
 * 
A Converter can specify a {@code javax.annotation.Priority}.
 * If no priority is explicitly assigned, the value of 100 is assumed.
 * If multiple Converters are registered for the same type, the one with the highest priority will be used. Highest number means highest priority.
 *
 * 
Custom Converters can also be registered programmatically via `ConfigBuilder#withConverters(Converter... converters)` or
 * `ConfigBuilder#withConverter(Class type, int priority, Converter converter)`.
 *
 * All Built In Converters have a {@code javax.annotation.Priority} of 1
 * A Converter should handle null values returning either null or a valid Object of the specified type.
 *
 * 
Array Converters
 *  The implementation must support the Array converter for each built-in converters and custom converters.
 *  The delimiter for the config value is ",". The escape character is "\".
 *  e.g. myPets=dog,cat,dog\,cat 
 * 
 *  For the property injection, List and Set should be supported as well.
 *
 *  

 *  Usage:
 *  

 *  
 *  String[] myPets = config.getValue("myPet", String[].class);
 *  
 *
 *  

 *  {@code @Inject @ConfigProperty(name="myPets") private String[] myPets;}
 *  

 *  {@code @Inject @ConfigProperty(name="myPets") private List myPets;}
 *
 *  

 *  {@code @Inject @ConfigProperty(name="myPets") private Set myPets;}
 *  

 *  myPets will be "dog", "cat", "dog,cat"
 * 
Implicit Converters
 *
 * If no explicit Converter and no built-in Converter could be found for a certain type,
 * the {@code Config} provides an Implicit Converter, if
 * 
 *     the target type {@code T} has a {@code public static T of(String)} method, or
 *     the target type {@code T} has a {@code public static T valueOf(String)} method, or
 *     the target type {@code T} has a {@code public static T parse(CharSequence)} method, or
 *     the target type {@code T} has a public Constructor with a String parameter.
 * 

 * @author Ron Smeral
 * @author Mark Struberg
 * @author Emily Jiang
 * @author John D. Ament
 */
public interface Converter extends Serializable {
    /**
     * Configure the string value to a specified type
     * @param value the string representation of a property value.
     * @return the converted value or null
     *
     * @throws IllegalArgumentException if the value cannot be converted to the specified type.
     */
    T convert(String value);
}