001/* -*- mode: Java; c-basic-offset: 2; indent-tabs-mode: nil; coding: utf-8-unix -*-
002 *
003 * Copyright © 2018–2019 microBean™.
004 *
005 * Licensed under the Apache License, Version 2.0 (the "License");
006 * you may not use this file except in compliance with the License.
007 * You may obtain a copy of the License at
008 *
009 *     http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
014 * implied.  See the License for the specific language governing
015 * permissions and limitations under the License.
016 */
017package org.microbean.microprofile.config;
018
019import java.lang.reflect.Type;
020
021/**
022 * An interface indicating that implementations might be able to
023 * convert {@link String} values to a variety of differently-typed
024 * objects.
025 *
026 * @author <a href="https://about.me/lairdnelson"
027 * target="_parent">Laird Nelson</a>
028 *
029 * @see #convert(String, Type)
030 */
031@FunctionalInterface
032public interface TypeConverter {
033
034  /**
035   * Converts the supplied {@link String} value to an object of the
036   * supplied {@link Type}, and returns it.
037   *
038   * <p>Implementations of this method are permitted to return {@code
039   * null}.</p>
040   *
041   * @param <T> the type of the return value, assumed to be assignable
042   * to references of the supplied type
043   *
044   * @param rawValue the {@link String} value to convert; may be
045   * {@code null}
046   *
047   * @param type the {@link Type} to which the value should be
048   * converted; must not be {@code null}; the type of the return value
049   * resulting from invocations of implementations of this method
050   * should be assignable to references of this type
051   *
052   * @return the converted object, which may be {@code null}
053   *
054   * @exception NullPointerException if {@code type} is {@code null}
055   *
056   * @exception IllegalArgumentException if conversion could not occur
057   * for any reason
058   */
059  public <T> T convert(final String rawValue, final Type type);
060  
061}