0
# Marshalling Framework
1

2
Extensible marshalling system for converting objects to/from string representations and JSON objects, with registry classes for managing custom marshaller and demarshaller implementations.
3

4
## Capabilities
5

6
### Marshaller Interface
7

8
Interface for converting objects to string representations.
9

10
```java { .api }
11
/**
12
 * Interface for marshalling objects to string representation
13
 * @param <T> - Type of object to marshall
14
 */
15
public interface Marshaller<T> {
16
    /**
17
     * Marshall object to string representation
18
     * @param object - Object to marshall
19
     * @return String representation of the object
20
     */
21
    public String marshall(T object);
22
}
23
```
24

25
**Usage Example:**
26

27
```java
28
import org.jboss.errai.common.client.types.Marshaller;
29

30
// Custom marshaller for Person objects
31
public class PersonMarshaller implements Marshaller<Person> {
32
    public String marshall(Person person) {
33
        return "{\"name\":\"" + person.getName() + "\",\"age\":" + person.getAge() + "}";
34
    }
35
}
36

37
// Use the marshaller
38
PersonMarshaller marshaller = new PersonMarshaller();
39
Person person = new Person("John", 30);
40
String json = marshaller.marshall(person);
41
```
42

43
### Demarshaller Interface
44

45
Interface for converting JSON objects back to typed Java objects.
46

47
```java { .api }
48
/**
49
 * Interface for demarshalling JSONObject to typed objects
50
 * @param <T> - Type of object to demarshall to
51
 */
52
public interface Demarshaller<T> {
53
    /**
54
     * Demarshall JSONObject to typed object
55
     * @param o - JSONObject to demarshall
56
     * @return Typed object instance
57
     */
58
    public T demarshall(JSONObject o);
59
}
60
```
61

62
**Usage Example:**
63

64
```java
65
import org.jboss.errai.common.client.types.Demarshaller;
66
import com.google.gwt.json.client.JSONObject;
67

68
// Custom demarshaller for Person objects
69
public class PersonDemarshaller implements Demarshaller<Person> {
70
    public Person demarshall(JSONObject o) {
71
        String name = o.get("name").isString().stringValue();
72
        int age = (int) o.get("age").isNumber().doubleValue();
73
        return new Person(name, age);
74
    }
75
}
76

77
// Use the demarshaller
78
PersonDemarshaller demarshaller = new PersonDemarshaller();
79
JSONObject jsonObject = /* parsed JSON object */;
80
Person person = demarshaller.demarshall(jsonObject);
81
```
82

83
### Type Marshallers Registry
84

85
Static registry for managing marshaller instances by type.
86

87
```java { .api }
88
/**
89
 * Registry for managing marshaller instances
90
 */
91
public class TypeMarshallers {
92
    /**
93
     * Register marshaller for specific type
94
     * @param type - Class to register marshaller for
95
     * @param d - Marshaller implementation
96
     */
97
    public static void addMarshaller(Class type, Marshaller d);
98
    
99
    /**
100
     * Get marshaller by class type
101
     * @param type - Class to get marshaller for
102
     * @return Marshaller instance for the type
103
     */
104
    public static <T> Marshaller<T> getMarshaller(Class<? extends T> type);
105
    
106
    /**
107
     * Get marshaller by class name
108
     * @param type - Class name to get marshaller for
109
     * @return Marshaller instance for the type
110
     */
111
    public static Marshaller getMarshaller(String type);
112
    
113
    /**
114
     * Check if marshaller exists for class
115
     * @param type - Class to check
116
     * @return true if marshaller is registered
117
     */
118
    public static boolean hasMarshaller(Class type);
119
    
120
    /**
121
     * Check if marshaller exists for class name
122
     * @param type - Class name to check
123
     * @return true if marshaller is registered
124
     */
125
    public static boolean hasMarshaller(String type);
126
}
127
```
128

129
**Usage Examples:**
130

131
```java
132
import org.jboss.errai.common.client.types.TypeMarshallers;
133

134
// Register custom marshaller
135
TypeMarshallers.addMarshaller(Person.class, new PersonMarshaller());
136

137
// Check if marshaller exists
138
if (TypeMarshallers.hasMarshaller(Person.class)) {
139
    // Get and use marshaller
140
    Marshaller<Person> marshaller = TypeMarshallers.getMarshaller(Person.class);
141
    String json = marshaller.marshall(person);
142
}
143

144
// Get marshaller by class name
145
Marshaller marshaller = TypeMarshallers.getMarshaller("com.example.Person");
146
```
147

148
### Type Demarshallers Registry
149

150
Static registry for managing demarshaller instances by type.
151

152
```java { .api }
153
/**
154
 * Registry for managing demarshaller instances
155
 */
156
public class TypeDemarshallers {
157
    /**
158
     * Register demarshaller for specific type
159
     * @param type - Class to register demarshaller for
160
     * @param d - Demarshaller implementation
161
     */
162
    public static void addDemarshaller(Class type, Demarshaller d);
163
    
164
    /**
165
     * Get demarshaller by class type
166
     * @param type - Class to get demarshaller for
167
     * @return Demarshaller instance for the type
168
     */
169
    public static <T> Demarshaller<T> getDemarshaller(Class<? extends T> type);
170
    
171
    /**
172
     * Get demarshaller by class name
173
     * @param type - Class name to get demarshaller for
174
     * @return Demarshaller instance for the type
175
     */
176
    public static Demarshaller getDemarshaller(String type);
177
    
178
    /**
179
     * Check if demarshaller exists for class
180
     * @param type - Class to check
181
     * @return true if demarshaller is registered
182
     */
183
    public static boolean hasDemarshaller(Class type);
184
    
185
    /**
186
     * Check if demarshaller exists for class name
187
     * @param type - Class name to check
188
     * @return true if demarshaller is registered
189
     */
190
    public static boolean hasDemarshaller(String type);
191
}
192
```
193

194
**Usage Examples:**
195

196
```java
197
import org.jboss.errai.common.client.types.TypeDemarshallers;
198
import com.google.gwt.json.client.JSONObject;
199

200
// Register custom demarshaller
201
TypeDemarshallers.addDemarshaller(Person.class, new PersonDemarshaller());
202

203
// Check if demarshaller exists
204
if (TypeDemarshallers.hasDemarshaller(Person.class)) {
205
    // Get and use demarshaller
206
    Demarshaller<Person> demarshaller = TypeDemarshallers.getDemarshaller(Person.class);
207
    Person person = demarshaller.demarshall(jsonObject);
208
}
209

210
// Get demarshaller by class name
211
Demarshaller demarshaller = TypeDemarshallers.getDemarshaller("com.example.Person");
212
```
213

214
## Built-in Marshallers
215

216
The library includes built-in marshallers for common Java types:
217

218
### Date Marshallers
219

220
Pre-configured marshallers for date types that convert dates to timestamp strings.
221

222
**Built-in Date Marshallers:**
223
- `java.sql.Date` → timestamp string
224
- `java.util.Date` → timestamp string
225

226
**Usage Example:**
227

228
```java
229
import java.util.Date;
230
import java.sql.Date as SQLDate;
231
import org.jboss.errai.common.client.types.TypeMarshallers;
232

233
// Built-in marshallers are automatically registered
234
Date utilDate = new Date();
235
Marshaller<Date> utilDateMarshaller = TypeMarshallers.getMarshaller(Date.class);
236
String utilDateString = utilDateMarshaller.marshall(utilDate); // "1234567890000"
237

238
SQLDate sqlDate = new SQLDate(System.currentTimeMillis());
239
Marshaller<SQLDate> sqlDateMarshaller = TypeMarshallers.getMarshaller(SQLDate.class);
240
String sqlDateString = sqlDateMarshaller.marshall(sqlDate); // "1234567890000"
241
```
242

243
## Complete Marshalling Workflow
244

245
Here's a complete example showing custom marshalling and demarshalling:
246

247
```java
248
import org.jboss.errai.common.client.types.*;
249
import org.jboss.errai.common.client.json.*;
250
import com.google.gwt.json.client.JSONObject;
251
import java.io.Serializable;
252

253
// 1. Define custom class
254
public class User implements Serializable {
255
    private String username;
256
    private String email;
257
    private boolean active;
258
    
259
    public User(String username, String email, boolean active) {
260
        this.username = username;
261
        this.email = email;
262
        this.active = active;
263
    }
264
    
265
    // getters and setters...
266
}
267

268
// 2. Implement marshaller
269
public class UserMarshaller implements Marshaller<User> {
270
    public String marshall(User user) {
271
        return "{\"username\":\"" + user.getUsername() + 
272
               "\",\"email\":\"" + user.getEmail() + 
273
               "\",\"active\":" + user.isActive() + 
274
               ",\"__EncodedType\":\"User\"}";
275
    }
276
}
277

278
// 3. Implement demarshaller
279
public class UserDemarshaller implements Demarshaller<User> {
280
    public User demarshall(JSONObject o) {
281
        String username = o.get("username").isString().stringValue();
282
        String email = o.get("email").isString().stringValue();
283
        boolean active = o.get("active").isBoolean().booleanValue();
284
        return new User(username, email, active);
285
    }
286
}
287

288
// 4. Register marshallers
289
TypeMarshallers.addMarshaller(User.class, new UserMarshaller());
290
TypeDemarshallers.addDemarshaller(User.class, new UserDemarshaller());
291

292
// 5. Use with JSON processing
293
JSONEncoderCli encoder = new JSONEncoderCli();
294
JSONDecoderCli decoder = new JSONDecoderCli();
295

296
User user = new User("john", "john@example.com", true);
297

298
// Marshall to JSON
299
String json = encoder.encode(user);
300
// Result: {"username":"john","email":"john@example.com","active":true,"__EncodedType":"User"}
301

302
// Demarshall from JSON
303
User decodedUser = (User) decoder.decode(json);
304
```
305

306
## Error Handling
307

308
**Missing Marshaller:**
309
- JSON encoder throws `RuntimeException` when no marshaller is available for `Serializable` objects
310

311
**Missing Demarshaller:**
312
- JSON decoder throws `RuntimeException` when encountering `__EncodedType` without available demarshaller
313
- Error includes detailed message with class name
314
- GWT.log() used for debugging information
315

316
**Example Error Handling:**
317

318
```java
319
// Handle missing marshaller
320
try {
321
    if (!TypeMarshallers.hasMarshaller(MyClass.class)) {
322
        TypeMarshallers.addMarshaller(MyClass.class, new MyClassMarshaller());
323
    }
324
    String json = encoder.encode(myObject);
325
} catch (RuntimeException e) {
326
    System.err.println("Marshalling error: " + e.getMessage());
327
}
328

329
// Handle missing demarshaller
330
try {
331
    if (!TypeDemarshallers.hasDemarshaller("MyClass")) {
332
        TypeDemarshallers.addDemarshaller(MyClass.class, new MyClassDemarshaller());
333
    }
334
    Object obj = decoder.decode(jsonString);
335
} catch (RuntimeException e) {
336
    System.err.println("Demarshalling error: " + e.getMessage());
337
}
338
```