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.LoggingLevel;
022import org.apache.camel.StaticService;
023import org.apache.camel.TypeConverter;
024import org.apache.camel.TypeConverterExists;
025import org.apache.camel.TypeConverters;
026
027/**
028 * Registry for type converters.
029 * <p/>
030 * The utilization {@link Statistics} is by default disabled, as it has a slight performance impact under very high
031 * concurrent load. The statistics can be enabled using {@link Statistics#setStatisticsEnabled(boolean)} method.
032 *
033 * @version 
034 */
035public interface TypeConverterRegistry extends StaticService {
036
037    /**
038     * Utilization statistics of the this registry.
039     */
040    interface Statistics {
041
042        /**
043         * Number of noop attempts (no type conversion was needed)
044         */
045        long getNoopCounter();
046
047        /**
048         * Number of type conversion attempts
049         */
050        long getAttemptCounter();
051
052        /**
053         * Number of successful conversions
054         */
055        long getHitCounter();
056
057        /**
058         * Number of attempts which cannot be converted as no suitable type converter exists
059         */
060        long getMissCounter();
061
062        /**
063         * Number of failed attempts during type conversion
064         */
065        long getFailedCounter();
066
067        /**
068         * Reset the counters
069         */
070        void reset();
071
072        /**
073         * Whether statistics is enabled.
074         */
075        boolean isStatisticsEnabled();
076
077        /**
078         * Sets whether statistics is enabled.
079         *
080         * @param statisticsEnabled <tt>true</tt> to enable
081         */
082        void setStatisticsEnabled(boolean statisticsEnabled);
083    }
084
085    /**
086     * Registers a new type converter.
087     * <p/>
088     * This method may throw {@link org.apache.camel.TypeConverterExistsException} if configured to fail if an existing
089     * type converter already exists
090     *
091     * @param toType        the type to convert to
092     * @param fromType      the type to convert from
093     * @param typeConverter the type converter to use
094     */
095    void addTypeConverter(Class<?> toType, Class<?> fromType, TypeConverter typeConverter);
096
097    /**
098     * Removes the type converter
099     *
100     * @param toType        the type to convert to
101     * @param fromType      the type to convert from
102     * @return <tt>true</tt> if removed, <tt>false</tt> if the type converter didn't exist
103     */
104    boolean removeTypeConverter(Class<?> toType, Class<?> fromType);
105
106    /**
107     * Registers all the type converters from the class, each converter must be implemented as a method and annotated with {@link org.apache.camel.Converter}.
108     *
109     * @param typeConverters class which implements the type converters
110     */
111    void addTypeConverters(TypeConverters typeConverters);
112
113    /**
114     * Registers a new fallback type converter
115     *
116     * @param typeConverter the type converter to use
117     * @param canPromote  whether or not the fallback type converter can be promoted to a first class type converter
118     */
119    void addFallbackTypeConverter(TypeConverter typeConverter, boolean canPromote);
120
121    /**
122     * Performs a lookup for a given type converter.
123     *
124     * @param toType        the type to convert to
125     * @param fromType      the type to convert from
126     * @return the type converter or <tt>null</tt> if not found.
127     */
128    TypeConverter lookup(Class<?> toType, Class<?> fromType);
129
130    /**
131     * Gets a read-only list of the type converter from / to classes
132     *
133     * @return a list containing fromType/toType class names
134     */
135    List<Class<?>[]> listAllTypeConvertersFromTo();
136
137    /**
138     * Sets the injector to be used for creating new instances during type conversions.
139     *
140     * @param injector the injector
141     */
142    void setInjector(Injector injector);
143
144    /**
145     * Gets the injector
146     *
147     * @return the injector
148     */
149    Injector getInjector();
150
151    /**
152     * Gets the utilization statistics of this type converter registry
153     *
154     * @return the utilization statistics
155     */
156    Statistics getStatistics();
157
158    /**
159     * Number of type converters in the registry.
160     *
161     * @return number of type converters in the registry.
162     */
163    int size();
164
165    /**
166     * The logging level to use when logging that a type converter already exists when attempting to add a duplicate type converter.
167     * <p/>
168     * The default logging level is <tt>WARN</tt>
169     */
170    LoggingLevel getTypeConverterExistsLoggingLevel();
171
172    /**
173     * The logging level to use when logging that a type converter already exists when attempting to add a duplicate type converter.
174     * <p/>
175     * The default logging level is <tt>WARN</tt>
176     */
177    void setTypeConverterExistsLoggingLevel(LoggingLevel typeConverterExistsLoggingLevel);
178
179    /**
180     * What should happen when attempting to add a duplicate type converter.
181     * <p/>
182     * The default behavior is to override the existing.
183     */
184    TypeConverterExists getTypeConverterExists();
185
186    /**
187     * What should happen when attempting to add a duplicate type converter.
188     * <p/>
189     * The default behavior is to override the existing.
190     */
191    void setTypeConverterExists(TypeConverterExists typeConverterExists);
192
193}