001    /*
002     *  Copyright 2004 The Apache Software Foundation
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     *      http://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    package org.apache.commons.convert;
017    
018    /**
019     * Defines a factory for Conversion objects that will create a conversion on demand
020     * or return a singleton.
021     *
022     * @author Stephen Colebourne
023     * @version $Id: ConversionFactory.java 155441 2005-02-26 13:19:22Z dirkv $
024     * @since 1.0
025     */
026    public interface ConversionFactory {
027    
028        /**
029         * Checks if this factory supports the required conversion returning a
030         * percentage match.
031         * <p>
032         * The returned <code>int</code> represents the percentage by which this
033         * factory matches the required conversion. The percentage (ie 0-100) is used
034         * to determine which conversion factory to use when a conflict arises.
035         * 
036         * @param value  the value to be converted, read only, may be null
037         * @param fromType  the type to convert from, may be null
038         * @param toType  the type to convert to, may be null
039         * @return a value between 0 and 100 inclusive, 0 means no match, 100 perfact match
040         */
041        int getMatchPercent(Object value, Class fromType, Class toType);
042    
043        /**
044         * Create a conversion object for the conversion.
045         * <p>
046         * The returned conversion must not store the value. The conversion object
047         * will be used repeatedly for all future conversions between these two types
048         * without further reference to the factory.
049         *
050         * @param value  the value to be converted, read only, may be null
051         * @param fromType  the type to convert from, may be null
052         * @param toType  the type to convert to, may be null
053         * @return a Conversion object for repeatedly performing conversions
054         */
055        Conversion getInstance(Object value, Class fromType, Class toType);
056    
057    }