TypeConverter


1   /*
2    * Copyright (c) 2003, Inversoft
3    *
4    * This software is distribuable under the GNU Lesser General Public License.
5    * For more information visit gnu.org.
6    */
7   package com.inversoft.util.typeconverter;
8   
9   
10  /**
11   * TypeConverters are used to convert objects from one type 
12   * to another, convert strings to objects and to convert from 
13   * objects and strings to arrays of objects. The way that 
14   * this is setup is that a TypeConverter implementation is
15   * registered with the TypeConverterRegistry. The manager can 
16   * then be queried for a particular TypeConveter (see {@link 
17   * TypeConverterRegistry TypeConveterManager} for more information 
18   * about retrieval). Next, the TypeConverter can be used 
19   * for conversions using one of four methods described
20   * below. Any given TypeConverter may be used to convert to 
21   * many different types because of the way that the 
22   * TypeConverterRegistry searches for TypeConverters. Because 
23   * of this flexibility when converting, the TypeConverter 
24   * must be told what type to convert to. This is the reason 
25   * for the second convertTo parameter on all of the convert 
26   * methods.
27   * 
28   * @author  Brian Pontarelli
29   */
30  public interface TypeConverter {
31  
32      /**
33       * <p>
34       * Converts the given object to the given type. The type can be any type
35       * that is support by the TypeConverter, but generally is a type that is the
36       * type or a sub-type of the type the converter is registered for. For example,
37       * let's say the converter is registered to java.lang.Number, then the
38       * converter should be able to convert Integer, Long, Double, etc; unless
39       * a converter is registered for each one of these. So, we could call the
40       * converter with ("0.5", Double.class) in order to convert the string to
41       * a Double object.
42       * </p>
43       * 
44       * <p>
45       * It is common practice to call the convertString method from this method
46       * passing it value.toString and convertTo. Ofcourse this is not required and
47       * is up to the implementing class to determine how best to convert the value
48       * to the given type.
49       * </p>
50       * 
51       * <p>
52       * It is also common practice to handle array types in this method by checking
53       * if the convertTo type is an array and then calling convertToArray correctly. 
54       * This reduces the amount of work necessary for clients to convert values.
55       * See the java.lang.Class#isArray() method for more information
56       * </p>
57       * 
58       * <p>
59       * Lastly, it is common practice in this method to handle the case where
60       * the convertTo is not an array and the value is an array. In this case it is
61       * common to call the convertArray method in order to handle converting the
62       * value array to an object.
63       * </p>
64       * 
65       * @param   value The value to convert
66       * @param   convertTo The type to convert the value to
67       * @return  The converted value
68       * @throws  TypeConversionException If there was a problem converting the
69       *          given value to the given type
70       */
71      Object   convert(Object   value, Class   convertTo) throws TypeConversionException;
72      
73      /**
74       * <p>
75       * Converts the given String to the given type. The type can be any type
76       * that is support by the TypeConverter, but generally is a type that is the
77       * type or a sub-type of the type the converter is registered for. For example,
78       * let's say the converter is registered to java.lang.Number, then this
79       * converter should be able to convert Integer, Long, Double, etc. unless
80       * a converter is registered for each one of these. So, we could call the
81       * converter with ("0.5", Double.class) in order to convert the string to
82       * a Double object.
83       * </p>
84       * 
85       * <p>
86       * It is also common practice to handle array types in this method by checking
87       * if the convertTo type is an array and then calling convertStringToArray
88       * correctly. This reduces the amount of work necessary for clients to convert
89       * values. See the java.lang.Class#isArray() method for more information
90       * </p>
91       * 
92       * @param   value The String value to convert
93       * @param   convertTo The type to convert the value to
94       * @return  The converted value
95       * @throws  TypeConversionException If there was a problem converting the
96       *          given value to the given type
97       */
98      Object   convertString(String   value, Class   convertTo) throws TypeConversionException;
99  
100     /**
101      * <p>
102      * Converts the given array to an object. This method is mostly used to 
103      * take an array of length 1 and convert the 0th indices object to the given
104      * type. The type can be any type, but normally is the type or a sub-type of
105      * the type the converter is registered for.
106      * </p>
107      * 
108      * <p>
109      * It is also common practice to handle array types in this method by checking
110      * if the convertTo type is an array and then calling the convertArrayToArray
111      * method.
112      * </p>
113      * 
114      * @param   values The array to convert to an object
115      * @param   convertTo The type to convert the values to
116      * @return  The converted value
117      * @throws  TypeConversionException If there was a problem converting the given
118      *          array to an Obejct
119      */
120     Object   convertArray(Object   [] values, Class   convertTo) 
121     throws TypeConversionException;
122 
123     /**
124      * Converts the array to an array of the given type. The given type can be either
125      * an array or object, for this method to succeed. If the given type is an array
126      * this method should retrieve the component type of the array and construct a
127      * new array of the component type. It could then convert each array position in
128      * the value array to the given type (or the component type if convertTo is an array).
129      * 
130      * @param   values The array to convert to an array
131      * @param   convertTo Either the array type of the component type for the array
132      *          being converted to
133      * @return  The converted array
134      * @throws  TypeConversionException If there was a problem converting the given
135      *          array to an array
136      */
137     Object   [] convertArrayToArray(Object   [] values, Class   convertTo)
138     throws TypeConversionException;
139 
140     /**
141      * Converts the given object to an array of objects of the given type. This 
142      * method should also take care to check if the convertTo type is an array. 
143      * If it is, it is should retrieve the component type and use that when 
144      * constructing the return array and also when converting the value. Of course 
145      * it is up to the implementing method to determine how best to convert the 
146      * value to an array. This class should be able to handle convertTo types 
147      * that are both objects and arrays. So, if the converter is registered for 
148      * the java.lang.Double class, this method could be called with either 
149      * Double.class or Double[].class for the convertTo type and should return
150      * an instance of Double[].
151      * 
152      * @param   value The value to convert to an array
153      * @param   convertTo The componenet type of the array being converted to
154      * @return  The converted array
155      * @throws  TypeConversionException If there was a problem converting the
156      *          given value to the given type
157      */
158     Object   [] convertToArray(Object   value, Class   convertTo)
159     throws TypeConversionException;
160 
161     /**
162      * Converts the String to an array of objects of the given type (normally
163      * by using a StringTokenizer and converting each token to the correct type). 
164      * This method should also take care to check if the convertTo type is an 
165      * array. If it is, it is should retrieve the component type and use that 
166      * when constructing the return array and also when converting the value. 
167      * Of course it is up to the implementing method to determine how best to 
168      * convert the value to an array. This class should be able to handle 
169      * convertTo types that are both objects and arrays. So, if the converter 
170      * is registered for the java.lang.Double class, this method could be called
171      * with either Double.class or Double[].class for the convertTo type and 
172      * should return an instance of Double[].
173      * 
174      * @param   value The String value to convert to an array
175      * @param   convertTo The componenet type of the array being converted to
176      * @return  The converted array
177      * @throws  TypeConversionException If there was a problem converting the
178      *          given value to the given type
179      */
180     Object   [] convertStringToArray(String   value, String   delimiter, Class   convertTo)
181     throws TypeConversionException;
182 }
183 
184
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags