001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  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 implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.juneau.commons.conversion;
018
019/**
020 * A pluggable strategy for discovering {@link Conversion} functions between type pairs.
021 *
022 * <p>
023 * Implementations are passed to the {@link ConfigurableConverter} constructor and are consulted in order before
024 * the built-in {@link BasicConverter} reflection logic.
025 *
026 * <p>
027 * Return <jk>null</jk> from {@link #findConversion(Class, Class)} to indicate that this finder has no conversion for the
028 * given type pair; the next registered finder (or the built-in logic) will be tried instead.
029 *
030 * <h5 class='section'>Example:</h5>
031 * <p class='bjava'>
032 *    ConfigurableConverter <jv>converter</jv> = <jk>new</jk> ConfigurableConverter(
033 *       (<jv>inType</jv>, <jv>outType</jv>) -> {
034 *          <jk>if</jk> (<jv>inType</jv> == String.<jk>class</jk> &amp;&amp; <jv>outType</jv> == MyBean.<jk>class</jk>)
035 *             <jk>return</jk> (<jv>in</jv>, <jv>memberOf</jv>, <jv>session</jv>, <jv>args</jv>) -> MyBean.fromString((<jk>String</jk>) <jv>in</jv>);
036 *          <jk>return null</jk>;
037 *       }
038 *    );
039 * </p>
040 *
041 * <h5 class='section'>See Also:</h5><ul>
042 *    <li class='jc'>{@link ConfigurableConverter}
043 *    <li class='jc'>{@link Conversion}
044 * </ul>
045 */
046@FunctionalInterface
047public interface ConversionFinder {
048
049   /**
050    * Returns a {@link Conversion} for the specified input/output type pair, or <jk>null</jk> if this finder
051    * has no conversion for the pair.
052    *
053    * @param inType The input type class.
054    * @param outType The output type class.
055    * @return A {@link Conversion} function, or <jk>null</jk> if no conversion is available.
056    */
057   @SuppressWarnings({
058      "java:S1452" // Wildcards unavoidable; concrete I/O types are only known at runtime
059   })
060   Conversion<?,?> findConversion(Class<?> inType, Class<?> outType);
061}