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     */
017    package org.apache.camel;
018    
019    
020    /**
021     * A pluggable strategy to be able to convert objects <a
022     * href="http://camel.apache.org/type-converter.html">to different
023     * types</a> such as to and from String, InputStream/OutputStream,
024     * Reader/Writer, Document, byte[], ByteBuffer etc
025     * 
026     * @version 
027     */
028    public interface TypeConverter {
029    
030        /**
031         * Whether the type converter allows returning null as a valid response.
032         * <p/>
033         * By default <tt>null</tt> is not a valid response, returning <tt>false</tt> from this method.
034         */
035        boolean allowNull();
036    
037        /**
038         * Converts the value to the specified type
039         *
040         * @param type the requested type
041         * @param value the value to be converted
042         * @return the converted value, or <tt>null</tt> if not possible to convert
043         * @throws TypeConversionException is thrown if error during type conversion
044         */
045        <T> T convertTo(Class<T> type, Object value) throws TypeConversionException;
046    
047        /**
048         * Converts the value to the specified type in the context of an exchange
049         * <p/>
050         * Used when conversion requires extra information from the current
051         * exchange (such as encoding).
052         *
053         * @param type the requested type
054         * @param exchange the current exchange
055         * @param value the value to be converted
056         * @return the converted value, or <tt>null</tt> if not possible to convert
057         * @throws TypeConversionException is thrown if error during type conversion
058         */
059        <T> T convertTo(Class<T> type, Exchange exchange, Object value) throws TypeConversionException;
060    
061        /**
062         * Converts the value to the specified type
063         *
064         * @param type the requested type
065         * @param value the value to be converted
066         * @return the converted value, is never <tt>null</tt>
067         * @throws TypeConversionException is thrown if error during type conversion
068         * @throws NoTypeConversionAvailableException if no type converters exists to convert to the given type
069         */
070        <T> T mandatoryConvertTo(Class<T> type, Object value) throws TypeConversionException, NoTypeConversionAvailableException;
071    
072        /**
073         * Converts the value to the specified type in the context of an exchange
074         * <p/>
075         * Used when conversion requires extra information from the current
076         * exchange (such as encoding).
077         *
078         * @param type the requested type
079         * @param exchange the current exchange
080         * @param value the value to be converted
081         * @return the converted value, is never <tt>null</tt>
082         * @throws TypeConversionException is thrown if error during type conversion
083         * @throws NoTypeConversionAvailableException if no type converters exists to convert to the given type
084         */
085        <T> T mandatoryConvertTo(Class<T> type, Exchange exchange, Object value) throws TypeConversionException, NoTypeConversionAvailableException;
086    
087        /**
088         * Tries to convert the value to the specified type,
089         * returning <tt>null</tt> if not possible to convert.
090         * <p/>
091         * This method will <b>not</b> throw an exception if an exception occurred during conversion.
092         *
093         * @param type the requested type
094         * @param value the value to be converted
095         * @return the converted value, or <tt>null</tt> if not possible to convert
096         */
097        <T> T tryConvertTo(Class<T> type, Object value);
098    
099        /**
100         * Tries to convert the value to the specified type in the context of an exchange,
101         * returning <tt>null</tt> if not possible to convert.
102         * <p/>
103         * This method will <b>not</b> throw an exception if an exception occurred during conversion.
104         * Converts the value to the specified type in the context of an exchange
105         * <p/>
106         * Used when conversion requires extra information from the current
107         * exchange (such as encoding).
108         *
109         * @param type the requested type
110         * @param exchange the current exchange
111         * @param value the value to be converted
112         * @return the converted value, or <tt>null</tt> if not possible to convert
113         */
114        <T> T tryConvertTo(Class<T> type, Exchange exchange, Object value);
115    
116    }