0
# Type Conversion and Handling
1

2
Core type conversion system for converting between Java types, with built-in support for collections, numbers, and extensible custom type handlers.
3

4
## Capabilities
5

6
### Type Handler Factory
7

8
Central factory for type conversion operations with pre-configured handlers for common conversions.
9

10
```java { .api }
11
/**
12
 * Factory for type conversion handlers with built-in handlers for collections and numbers
13
 */
14
public class TypeHandlerFactory {
15
    /**
16
     * Convert value between types using registered handlers
17
     * @param from - Source type class
18
     * @param to - Target type class  
19
     * @param value - Value to convert
20
     * @return Converted value of target type
21
     */
22
    public static <T> T convert(Class from, Class<? extends T> to, Object value);
23
    
24
    /**
25
     * Get available type handlers for source type
26
     * @param from - Source type class
27
     * @return Map of target types to their handlers
28
     */
29
    public static Map<Class, TypeHandler> getHandler(Class from);
30
    
31
    /**
32
     * Register custom type handler
33
     * @param from - Source type class
34
     * @param to - Target type class
35
     * @param handler - Handler implementation
36
     */
37
    public static void addHandler(Class from, Class to, TypeHandler handler);
38
}
39
```
40

41
**Usage Examples:**
42

43
```java
44
import org.jboss.errai.common.client.types.TypeHandlerFactory;
45

46
// Convert string to integer
47
Integer result = TypeHandlerFactory.convert(String.class, Integer.class, "123");
48

49
// Convert collection to array
50
List<String> list = Arrays.asList("a", "b", "c");
51
String[] array = TypeHandlerFactory.convert(Collection.class, String[].class, list);
52

53
// Convert number to date
54
Number timestamp = 1234567890000L;
55
Date date = TypeHandlerFactory.convert(Number.class, Date.class, timestamp);
56
```
57

58
### Type Handler Interface
59

60
Base interface for implementing custom type conversions.
61

62
```java { .api }
63
/**
64
 * Interface for converting between types
65
 * @param <V> - Source value type
66
 * @param <T> - Target type
67
 */
68
public interface TypeHandler<V, T> {
69
    /**
70
     * Convert input value to target type
71
     * @param in - Input value of source type
72
     * @return Converted value of target type
73
     */
74
    public T getConverted(V in);
75
}
76
```
77

78
**Usage Example:**
79

80
```java
81
import org.jboss.errai.common.client.types.TypeHandler;
82
import org.jboss.errai.common.client.types.TypeHandlerFactory;
83

84
// Custom handler for converting strings to custom objects
85
public class StringToCustomObject implements TypeHandler<String, CustomObject> {
86
    public CustomObject getConverted(String in) {
87
        return new CustomObject(in);
88
    }
89
}
90

91
// Register the handler
92
TypeHandlerFactory.addHandler(String.class, CustomObject.class, new StringToCustomObject());
93

94
// Use the handler
95
CustomObject obj = TypeHandlerFactory.convert(String.class, CustomObject.class, "input");
96
```
97

98
### JSON Type Helper
99

100
Utility for converting GWT JSONValue objects to typed Java objects using the type conversion system.
101

102
```java { .api }
103
/**
104
 * Utility for converting JSONValue objects to typed Java objects
105
 */
106
public class JSONTypeHelper {
107
    /**
108
     * Convert JSONValue to specified type using type handlers
109
     * @param value - JSONValue to convert
110
     * @param to - Target type class
111
     * @return Converted object of target type
112
     */
113
    public static <T> T convert(JSONValue value, Class<? extends T> to);
114
    
115
    /**
116
     * Helper method for encoding objects to JSON-compatible strings
117
     * @param v - Object to encode
118
     * @return JSON-compatible string representation
119
     */
120
    public static String encodeHelper(Object v);
121
}
122
```
123

124
**Usage Example:**
125

126
```java
127
import com.google.gwt.json.client.JSONParser;
128
import com.google.gwt.json.client.JSONValue;
129
import org.jboss.errai.common.client.types.JSONTypeHelper;
130

131
// Parse JSON and convert to typed object
132
JSONValue jsonValue = JSONParser.parseStrict("[1, 2, 3]");
133
List<Integer> list = JSONTypeHelper.convert(jsonValue, List.class);
134

135
// Encode helper
136
String encoded = JSONTypeHelper.encodeHelper("hello"); // Returns "\"hello\""
137
```
138

139
## Built-in Type Handlers
140

141
### Collection Conversion Handlers
142

143
Pre-configured handlers for converting collections to various array and collection types.
144

145
**Available Collection Handlers:**
146
- `Collection` → `boolean[]` (CollectionToBooleanArray)
147
- `Collection` → `byte[]` (CollectionToByteArray)
148
- `Collection` → `char[]` (CollectionToCharArray)
149
- `Collection` → `double[]` (CollectionToDoubleArray)
150
- `Collection` → `float[]` (CollectionToFloatArray)
151
- `Collection` → `int[]` (CollectionToIntArray)
152
- `Collection` → `long[]` (CollectionToLongArray)
153
- `Collection` → `String[]` (CollectionToStringArray)
154
- `Collection` → `Object[]` (CollectionToObjArray)
155
- `Collection` → `List` (CollectionToList)
156
- `Collection` → `Set` (CollectionToSet)
157

158
**Usage Example:**
159

160
```java
161
import java.util.*;
162
import org.jboss.errai.common.client.types.TypeHandlerFactory;
163

164
List<String> stringList = Arrays.asList("a", "b", "c");
165

166
// Convert to string array
167
String[] stringArray = TypeHandlerFactory.convert(Collection.class, String[].class, stringList);
168

169
// Convert to set
170
Set<String> stringSet = TypeHandlerFactory.convert(Collection.class, Set.class, stringList);
171
```
172

173
### Number Conversion Handlers
174

175
Pre-configured handlers for converting Number objects to specific numeric types and dates.
176

177
**Available Number Handlers:**
178
- `Number` → `Integer` (NumberToInt)
179
- `Number` → `Long` (NumberToLong)  
180
- `Number` → `Short` (NumberToShort)
181
- `Number` → `Float` (NumberToFloat)
182
- `Number` → `Double` (NumberToDouble)
183
- `Number` → `Byte` (NumberToByte)
184
- `Number` → `java.util.Date` (NumberToDate)
185
- `Number` → `java.sql.Date` (NumberToSQLDate)
186

187
**Usage Example:**
188

189
```java
190
import org.jboss.errai.common.client.types.TypeHandlerFactory;
191
import java.util.Date;
192

193
Double doubleValue = 1234567890000.0;
194

195
// Convert to integer
196
Integer intValue = TypeHandlerFactory.convert(Number.class, Integer.class, doubleValue);
197

198
// Convert to date (from timestamp)
199
Date date = TypeHandlerFactory.convert(Number.class, Date.class, doubleValue);
200
```
201

202
### Primitive Type Handlers
203

204
Limited set of handlers for primitive type conversions.
205

206
**Available Primitive Handlers:**
207
- `Integer` → `Byte` (IntToByte)
208

209
## Specific Type Handler Implementations
210

211
The type handler factory includes numerous built-in implementations that can be accessed directly if needed:
212

213
### Number Type Handler Classes
214

215
```java { .api }
216
// Available Number conversion handler classes (all public)
217
public class NumberToInt implements TypeHandler<Number, Integer> {
218
    public Integer getConverted(Number in);
219
}
220

221
public class NumberToLong implements TypeHandler<Number, Long> {
222
    public Long getConverted(Number in);
223
}
224

225
public class NumberToShort implements TypeHandler<Number, Short> {
226
    public Short getConverted(Number in);
227
}
228

229
public class NumberToFloat implements TypeHandler<Number, Float> {
230
    public Float getConverted(Number in);
231
}
232

233
public class NumberToDouble implements TypeHandler<Number, Double> {
234
    public Double getConverted(Number in);
235
}
236

237
public class NumberToByte implements TypeHandler<Number, Byte> {
238
    public Byte getConverted(Number in);
239
}
240

241
public class NumberToDate implements TypeHandler<Number, java.util.Date> {
242
    public java.util.Date getConverted(Number in);
243
}
244

245
public class NumberToSQLDate implements TypeHandler<Number, java.sql.Date> {
246
    public java.sql.Date getConverted(Number in);
247
}
248
```
249

250
### Collection Type Handler Classes
251

252
```java { .api }
253
// Available Collection conversion handler classes (all public)
254
public class CollectionToList implements TypeHandler<Collection, List> {
255
    public List getConverted(Collection in);
256
}
257

258
public class CollectionToSet implements TypeHandler<Collection, Set> {
259
    public Set getConverted(Collection in);
260
}
261

262
public class CollectionToObjArray implements TypeHandler<Collection, Object[]> {
263
    public Object[] getConverted(Collection in);
264
}
265

266
public class CollectionToStringArray implements TypeHandler<Collection, String[]> {
267
    public String[] getConverted(Collection in);
268
}
269

270
public class CollectionToIntArray implements TypeHandler<Collection, int[]> {
271
    public int[] getConverted(Collection in);
272
}
273

274
public class CollectionToLongArray implements TypeHandler<Collection, long[]> {
275
    public long[] getConverted(Collection in);
276
}
277

278
public class CollectionToBooleanArray implements TypeHandler<Collection, boolean[]> {
279
    public boolean[] getConverted(Collection in);
280
}
281

282
public class CollectionToDoubleArray implements TypeHandler<Collection, double[]> {
283
    public double[] getConverted(Collection in);
284
}
285

286
public class CollectionToFloatArray implements TypeHandler<Collection, float[]> {
287
    public float[] getConverted(Collection in);
288
}
289

290
public class CollectionToByteArray implements TypeHandler<Collection, byte[]> {
291
    public byte[] getConverted(Collection in);
292
}
293

294
public class CollectionToCharArray implements TypeHandler<Collection, char[]> {
295
    public char[] getConverted(Collection in);
296
}
297
```
298

299
### Primitive Type Handler Classes
300

301
```java { .api }
302
// Available primitive conversion handler classes
303
public class IntToByte implements TypeHandler<Integer, Byte> {
304
    public Byte getConverted(Integer in);
305
}
306
```
307

308
These handler classes are automatically registered with the `TypeHandlerFactory` and can be accessed through the factory methods or instantiated directly if needed.
309

310
## Inheritance Mapping
311

312
The type handler factory includes inheritance mapping for finding appropriate handlers:
313

314
**Number Inheritance:**
315
- `Integer`, `Long`, `Short`, `Float`, `Double` → `Number`
316

317
**Collection Inheritance:**
318
- `ArrayList`, `LinkedList`, `AbstractList`, `Stack` → `List`
319
- `HashSet`, `AbstractSet` → `Set`  
320
- `List`, `Set` → `Collection`
321

322
This allows handlers registered for parent types to work with subclasses automatically.