0
# Errai Common
1
2
Errai Common provides foundational utilities and infrastructure for the Errai GWT-based framework. It contains essential client-side components including JSON encoding/decoding utilities, type marshalling and demarshalling infrastructure, callback frameworks, and GWT integration helpers that enable seamless communication between client and server components.
3
4
## Package Information
5
6
- **Package Name**: errai-common
7
- **Package Type**: maven
8
- **Group ID**: org.jboss.errai
9
- **Artifact ID**: errai-common
10
- **Language**: Java (GWT-compatible)
11
- **Installation**:
12
```xml
13
<dependency>
14
<groupId>org.jboss.errai</groupId>
15
<artifactId>errai-common</artifactId>
16
<version>1.0.1</version>
17
</dependency>
18
```
19
20
## Core Imports
21
22
```java
23
import org.jboss.errai.common.client.ErraiCommon;
24
import org.jboss.errai.common.client.framework.AcceptsCallback;
25
import org.jboss.errai.common.client.json.JSONEncoderCli;
26
import org.jboss.errai.common.client.json.JSONDecoderCli;
27
import org.jboss.errai.common.client.types.*;
28
```
29
30
## Basic Usage
31
32
```java
33
// JSON encoding/decoding
34
JSONEncoderCli encoder = new JSONEncoderCli();
35
String json = encoder.encode(myObject);
36
37
JSONDecoderCli decoder = new JSONDecoderCli();
38
Object decoded = decoder.decode(json);
39
40
// Type conversion
41
Object converted = TypeHandlerFactory.convert(String.class, Integer.class, "123");
42
43
// Custom marshalling
44
TypeMarshallers.addMarshaller(MyClass.class, new MyClassMarshaller());
45
Marshaller<MyClass> marshaller = TypeMarshallers.getMarshaller(MyClass.class);
46
47
// GWT text selection utility
48
ErraiCommon.disableTextSelection(element, true);
49
```
50
51
## Architecture
52
53
Errai Common is built around several key components:
54
55
- **Type Conversion System**: `TypeHandlerFactory` with built-in handlers for collections and numbers
56
- **Marshalling Framework**: `Marshaller` and `Demarshaller` interfaces with registry classes
57
- **JSON Processing**: Client-side JSON encoding/decoding with type awareness
58
- **Callback Framework**: Standard callback interface for asynchronous operations
59
- **GWT Integration**: Entry point and DOM utilities for GWT applications
60
61
### Package Structure
62
63
```
64
org.jboss.errai.common.client/
65
├── ErraiCommon # Main GWT entry point class
66
├── framework/
67
│ └── AcceptsCallback # Callback interface for async operations
68
├── json/
69
│ ├── JSONEncoderCli # Client-side JSON encoding
70
│ └── JSONDecoderCli # Client-side JSON decoding
71
└── types/
72
├── TypeHandler<V,T> # Type conversion interface
73
├── Marshaller<T> # Object to string marshalling interface
74
├── Demarshaller<T> # JSON object to typed object interface
75
├── TypeHandlerFactory # Central factory for type conversions
76
├── TypeMarshallers # Registry for marshaller instances
77
├── TypeDemarshallers # Registry for demarshaller instances
78
├── JSONTypeHelper # JSON-type conversion utilities
79
└── handlers/ # Built-in type handler implementations
80
├── collections/ # Collection to array/collection conversions
81
├── numbers/ # Number to primitive/Date conversions
82
└── primitives/ # Limited primitive conversions
83
```
84
85
## Capabilities
86
87
### Type Conversion and Handling
88
89
Core type conversion system for converting between Java types, with built-in support for collections, numbers, and custom type handlers.
90
91
```java { .api }
92
public class TypeHandlerFactory {
93
public static <T> T convert(Class from, Class<? extends T> to, Object value);
94
public static Map<Class, TypeHandler> getHandler(Class from);
95
public static void addHandler(Class from, Class to, TypeHandler handler);
96
}
97
98
public interface TypeHandler<V, T> {
99
public T getConverted(V in);
100
}
101
```
102
103
[Type Conversion](./type-conversion.md)
104
105
### JSON Processing
106
107
Client-side JSON encoding and decoding with support for custom marshalling and type-aware conversion.
108
109
```java { .api }
110
public class JSONEncoderCli {
111
public String encode(Object v);
112
public String encodeMap(Map<Object, Object> map);
113
public Map<String, String> getMarshalledTypes();
114
}
115
116
public class JSONDecoderCli {
117
public Object decode(Object value);
118
}
119
```
120
121
[JSON Processing](./json-processing.md)
122
123
### Marshalling Framework
124
125
Extensible marshalling system for converting objects to/from string representations and JSON objects.
126
127
```java { .api }
128
public interface Marshaller<T> {
129
public String marshall(T object);
130
}
131
132
public interface Demarshaller<T> {
133
public T demarshall(JSONObject o);
134
}
135
136
public class TypeMarshallers {
137
public static void addMarshaller(Class type, Marshaller d);
138
public static <T> Marshaller<T> getMarshaller(Class<? extends T> type);
139
public static boolean hasMarshaller(Class type);
140
}
141
142
public class TypeDemarshallers {
143
public static void addDemarshaller(Class type, Demarshaller d);
144
public static <T> Demarshaller<T> getDemarshaller(Class<? extends T> type);
145
public static boolean hasDemarshaller(Class type);
146
}
147
```
148
149
[Marshalling](./marshalling.md)
150
151
### Framework Integration
152
153
GWT integration utilities and callback framework for building interactive applications.
154
155
```java { .api }
156
public class ErraiCommon implements EntryPoint {
157
public void onModuleLoad();
158
public static void disableTextSelection(Element e, boolean disable);
159
}
160
161
public interface AcceptsCallback {
162
public static final String MESSAGE_OK = "OK";
163
public static final String MESSAGE_CANCEL = "CANCEL";
164
public void callback(Object message, Object data);
165
}
166
```
167
168
[Framework Integration](./framework-integration.md)
169
170
## Common Types
171
172
```java { .api }
173
// GWT JSON types
174
import com.google.gwt.json.client.JSONObject;
175
import com.google.gwt.json.client.JSONValue;
176
import com.google.gwt.json.client.JSONArray;
177
178
// GWT DOM types
179
import com.google.gwt.dom.client.Element;
180
181
// Errai type system imports
182
import org.jboss.errai.common.client.types.JSONTypeHelper;
183
184
// Standard Java types
185
import java.util.*;
186
import java.io.Serializable;
187
```