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 attempts
041         */
042        long getAttemptCounter();
043
044        /**
045         * Number of successful conversions
046         */
047        long getHitCounter();
048
049        /**
050         * Number of attempts which cannot be converted as no suitable type converter exists
051         */
052        long getMissCounter();
053
054        /**
055         * Number of failed attempts during type conversion
056         */
057        long getFailedCounter();
058
059        /**
060         * Reset the counters
061         */
062        void reset();
063
064        /**
065         * Whether statistics is enabled.
066         */
067        boolean isStatisticsEnabled();
068
069        /**
070         * Sets whether statistics is enabled.
071         *
072         * @param statisticsEnabled <tt>true</tt> to enable
073         */
074        void setStatisticsEnabled(boolean statisticsEnabled);
075    }
076
077    /**
078     * Registers a new type converter
079     *
080     * @param toType        the type to convert to
081     * @param fromType      the type to convert from
082     * @param typeConverter the type converter to use
083     */
084    void addTypeConverter(Class<?> toType, Class<?> fromType, TypeConverter typeConverter);
085
086    /**
087     * Removes the type converter
088     *
089     * @param toType        the type to convert to
090     * @param fromType      the type to convert from
091     * @return <tt>true</tt> if removed, <tt>false</tt> if the type converter didn't exist
092     */
093    boolean removeTypeConverter(Class<?> toType, Class<?> fromType);
094
095    /**
096     * Registers a new fallback type converter
097     *
098     * @param typeConverter the type converter to use
099     * @param canPromote  whether or not the fallback type converter can be promoted to a first class type converter
100     */
101    void addFallbackTypeConverter(TypeConverter typeConverter, boolean canPromote);
102
103    /**
104     * Performs a lookup for a given type converter.
105     *
106     * @param toType        the type to convert to
107     * @param fromType      the type to convert from
108     * @return the type converter or <tt>null</tt> if not found.
109     */
110    TypeConverter lookup(Class<?> toType, Class<?> fromType);
111
112    /**
113     * Gets a read-only list of the type converter from / to classes
114     *
115     * @return a list containing fromType/toType class names
116     */
117    List<Class<?>[]> listAllTypeConvertersFromTo();
118
119    /**
120     * Sets the injector to be used for creating new instances during type conversions.
121     *
122     * @param injector the injector
123     */
124    void setInjector(Injector injector);
125
126    /**
127     * Gets the injector
128     *
129     * @return the injector
130     */
131    Injector getInjector();
132
133    /**
134     * Gets the utilization statistics of this type converter registry
135     *
136     * @return the utilization statistics
137     */
138    Statistics getStatistics();
139
140    /**
141     * Number of type converters in the registry.
142     *
143     * @return number of type converters in the registry.
144     */
145    int size();
146
147}