1 /*
2 * Copyright 2004 The Apache Software Foundation
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16 package org.apache.commons.convert;
17
18 /**
19 * Converter is the central class that holds a set of registered converters
20 * together and allows conversion to occur.
21 * <p>
22 * This class allows applications to add their own converters. This is achieved
23 * by creating a new instance and using that within the application. Generally,
24 * the instance is stored in a static variable in the application.
25 * <p>
26 * In this way, the application remains independent of other converters used
27 * by other applications or libraries.
28 *
29 * @author Stephen Colebourne
30 * @version $Id: Converter.java 155441 2005-02-26 13:19:22Z dirkv $
31 * @since 1.0
32 */
33 public class Converter {
34
35 /* The converter registry */
36 private final ConversionRegistry registry;
37
38 /**
39 * Constructs a new instance of the Converter useful to create a set
40 * of conversions separate from the default set.
41 * <p>
42 * The created converter has no conversions registered.
43 */
44 public Converter() {
45 this(false);
46 }
47
48 /**
49 * Constructs a new instance of the Converter useful to create a set
50 * of conversions separate from the default set.
51 *
52 * @param addDefaults whether to add the default conversions
53 */
54 public Converter(boolean addDefaults) {
55 super();
56 registry = createRegistry();
57 if (addDefaults) {
58 registry.addDefaultConversions();
59 }
60 }
61
62 /**
63 * Factory method for subclasses to change the registry implementation.
64 *
65 * @return a new, non-null, registry
66 */
67 protected ConversionRegistry createRegistry() {
68 return new ConversionRegistry();
69 }
70
71 //-----------------------------------------------------------------------
72 /**
73 * Convert the specified input object into an output object
74 * of the another type.
75 *
76 * @param value the input value to be converted
77 * @param fromClass the class to convert from, useful if null passed in
78 * @param toClass the class to convert to
79 * @return the converted value
80 * @throws ConversionException (runtime) if conversion fails
81 */
82 public Object convert(Object value, Class fromClass, Class toClass) {
83 return doConversion(value, fromClass, toClass);
84 }
85
86 /**
87 * Convert the specified input object into an output object
88 * of the another type.
89 *
90 * @param value the input value to be converted
91 * @param toClass the class to convert to
92 * @return the converted value
93 * @throws ConversionException (runtime) if conversion fails
94 */
95 public Object convert(Object value, Class toClass) {
96 return doConversion(value, null, toClass);
97 }
98
99 /**
100 * Convert the specified input object into a <code>String</code>.
101 *
102 * @param value the input value to be converted
103 * @param fromClass the class to convert from, useful if null passed in
104 * @return the converted value
105 * @throws ConversionException (runtime) if conversion fails
106 */
107 public String convertToString(Object value, Class fromClass) {
108 return (String) doConversion(value, fromClass, String.class);
109 }
110
111 /**
112 * Convert the specified input object into a <code>String</code>.
113 *
114 * @param value the input value to be converted
115 * @return the converted value
116 * @throws ConversionException (runtime) if conversion fails
117 */
118 public String convertToString(Object value) {
119 return (String) doConversion(value, null, String.class);
120 }
121
122 //-----------------------------------------------------------------------
123 /**
124 * Convert the specified input object into an output object of another type.
125 * <p>
126 * This implementation uses {{@link #doConversion(Conversion, Object)}.
127 *
128 * @param value the input value to be converted
129 * @param fromClass the class to convert from, useful if null passed in
130 * @param toClass the class to convert to
131 * @return the converted value
132 * @throws ConversionException (runtime) if conversion fails
133 */
134 protected Object doConversion(Object value, Class fromClass, Class toClass) {
135 Class valueClass = (value == null ? fromClass : value.getClass());
136 Conversion conv = getRegistry().getConversion(value, valueClass, toClass);
137 if (conv == null) {
138 throw new ConversionException("No Converter found to convert " + valueClass + " to " + toClass);
139 }
140 return doConversion(conv, value);
141 }
142
143 /**
144 * Convert the specified input object into an output object using the conversion.
145 * <p>
146 * This implementation catches exceptions and wraps them in a <code>ConversionException</code>.
147 *
148 * @param conversion the conversion to use
149 * @param value the value to convert
150 * @return the converted value
151 * @throws ConversionException (runtime) if conversion fails
152 */
153 protected Object doConversion(Conversion conversion, Object value) {
154 try {
155 return conversion.convert(value, this);
156
157 } catch (ConversionException ex) {
158 throw ex;
159 } catch (Exception ex) {
160 throw new ConversionException(conversion.toString(), ex);
161 }
162 }
163
164 //-----------------------------------------------------------------------
165 /**
166 * Gets the converter registry used for adding and removing converters.
167 *
168 * @return the converter registry, never null
169 */
170 public ConversionRegistry getRegistry() {
171 return registry;
172 }
173
174 //-----------------------------------------------------------------------
175 /**
176 * Returns a string describing this object.
177 *
178 * @return a string describing this object
179 */
180 public String toString() {
181 return "Converter";
182 }
183
184 }