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
```