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.camel.spi;
018
019import java.util.List;
020
021import org.apache.camel.StaticService;
022import org.apache.camel.TypeConverter;
023
024/**
025 * Registry for type converters.
026 * <p/>
027 * The utilization {@link Statistics} is by default disabled, as it has a slight performance impact under very high
028 * concurrent load. The statistics can be enabled using {@link Statistics#setStatisticsEnabled(boolean)} method.
029 *
030 * @version 
031 */
032public interface TypeConverterRegistry extends StaticService {
033
034    /**
035     * Utilization statistics of the this registry.
036     */
037    interface Statistics {
038
039        /**
040         * Number of noop attempts (no type conversion was needed)
041         */
042        long getNoopCounter();
043
044        /**
045         * Number of type conversion attempts
046         */
047        long getAttemptCounter();
048
049        /**
050         * Number of successful conversions
051         */
052        long getHitCounter();
053
054        /**
055         * Number of attempts which cannot be converted as no suitable type converter exists
056         */
057        long getMissCounter();
058
059        /**
060         * Number of failed attempts during type conversion
061         */
062        long getFailedCounter();
063
064        /**
065         * Reset the counters
066         */
067        void reset();
068
069        /**
070         * Whether statistics is enabled.
071         */
072        boolean isStatisticsEnabled();
073
074        /**
075         * Sets whether statistics is enabled.
076         *
077         * @param statisticsEnabled <tt>true</tt> to enable
078         */
079        void setStatisticsEnabled(boolean statisticsEnabled);
080    }
081
082    /**
083     * Registers a new type converter
084     *
085     * @param toType        the type to convert to
086     * @param fromType      the type to convert from
087     * @param typeConverter the type converter to use
088     */
089    void addTypeConverter(Class<?> toType, Class<?> fromType, TypeConverter typeConverter);
090
091    /**
092     * Removes the type converter
093     *
094     * @param toType        the type to convert to
095     * @param fromType      the type to convert from
096     * @return <tt>true</tt> if removed, <tt>false</tt> if the type converter didn't exist
097     */
098    boolean removeTypeConverter(Class<?> toType, Class<?> fromType);
099
100    /**
101     * Registers a new fallback type converter
102     *
103     * @param typeConverter the type converter to use
104     * @param canPromote  whether or not the fallback type converter can be promoted to a first class type converter
105     */
106    void addFallbackTypeConverter(TypeConverter typeConverter, boolean canPromote);
107
108    /**
109     * Performs a lookup for a given type converter.
110     *
111     * @param toType        the type to convert to
112     * @param fromType      the type to convert from
113     * @return the type converter or <tt>null</tt> if not found.
114     */
115    TypeConverter lookup(Class<?> toType, Class<?> fromType);
116
117    /**
118     * Gets a read-only list of the type converter from / to classes
119     *
120     * @return a list containing fromType/toType class names
121     */
122    List<Class<?>[]> listAllTypeConvertersFromTo();
123
124    /**
125     * Sets the injector to be used for creating new instances during type conversions.
126     *
127     * @param injector the injector
128     */
129    void setInjector(Injector injector);
130
131    /**
132     * Gets the injector
133     *
134     * @return the injector
135     */
136    Injector getInjector();
137
138    /**
139     * Gets the utilization statistics of this type converter registry
140     *
141     * @return the utilization statistics
142     */
143    Statistics getStatistics();
144
145    /**
146     * Number of type converters in the registry.
147     *
148     * @return number of type converters in the registry.
149     */
150    int size();
151
152}