Skip to content

Commit fc1881f

Browse files
committed
Update README.md
1 parent 7f0a37f commit fc1881f

File tree

1 file changed

+38
-8
lines changed

1 file changed

+38
-8
lines changed

README.md

Lines changed: 38 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,7 @@ JsonBeans is a lightweight library that makes it easy to serialize and deseriali
2121

2222
The `Json` class uses reflection to automatically serialize objects to JSON. For example, here are two classes (getters/setters and constructors omitted):
2323

24+
```java
2425
public class Person {
2526
private String name;
2627
private int age;
@@ -31,29 +32,36 @@ The `Json` class uses reflection to automatically serialize objects to JSON. For
3132
private String name;
3233
private String number;
3334
}
35+
```
3436

3537
Example object graph using these classes:
3638

39+
```java
3740
Person person = new Person();
3841
person.setName("Nate");
3942
person.setAge(31);
4043
ArrayList numbers = new ArrayList();
4144
numbers.add(new PhoneNumber("Home", "206-555-1234"));
4245
numbers.add(new PhoneNumber("Work", "425-555-4321"));
4346
person.setNumbers(numbers);
47+
```
4448

4549
The JsonBeans code to serialize this object graph:
4650

51+
```java
4752
Json json = new Json();
4853
System.out.println(json.toJson(person));
49-
50-
{"numbers":[{"class":"com.example.PhoneNumber","name":"Home","number":"206-555-1234"},{"class":"com.example.PhoneNumber","name":"Work","number":"425-555-4321"}],"age":31,"name":"Nate"}
54+
```
55+
```json {"numbers":[{"class":"com.example.PhoneNumber","name":"Home","number":"206-555-1234"},{"class":"com.example.PhoneNumber","name":"Work","number":"425-555-4321"}],"age":31,"name":"Nate"}
56+
```
5157

5258
That is compact, but hardly legible. The `prettyPrint` method can be used:
5359

60+
```java
5461
Json json = new Json();
5562
System.out.println(json.prettyPrint(person));
56-
63+
```
64+
```json
5765
{
5866
"name": "Nate",
5967
"age": 31,
@@ -70,13 +78,16 @@ That is compact, but hardly legible. The `prettyPrint` method can be used:
7078
}
7179
]
7280
}
81+
```
7382

7483
Note that the class for the `PhoneNumber` objects in the `ArrayList numbers` field appears in the JSON. This is required to recreate the object graph from the JSON because `ArrayList` can hold any type of object. Class names are only output when they are required for deserialization. If the field was `ArrayList<PhoneNumber> numbers` then class names would only appear when an item in the list extends `PhoneNumber`. If you know the concrete type or aren't using generics, you can avoid class names being written by telling the `Json` class the types:
7584

85+
```java
7686
Json json = new Json();
7787
json.setElementType(Person.class, "numbers", PhoneNumber.class);
7888
System.out.println(json.prettyPrint(person));
79-
89+
```
90+
```json
8091
{
8192
"name": "Nate",
8293
"age": 31,
@@ -91,13 +102,16 @@ Note that the class for the `PhoneNumber` objects in the `ArrayList numbers` fie
91102
}
92103
]
93104
}
105+
```
94106

95107
When writing the class cannot be avoided, an alias can be given:
96108

109+
```java
97110
Json json = new Json();
98111
json.addClassTag("phoneNumber", PhoneNumber.class);
99112
System.out.println(json.prettyPrint(person));
100-
113+
```
114+
```json
101115
{
102116
"name": "Nate",
103117
"age": 31,
@@ -114,14 +128,17 @@ When writing the class cannot be avoided, an alias can be given:
114128
}
115129
]
116130
}
131+
```
117132

118133
JsonBeans can write and read both JSON and a couple JSON-like formats. It supports "javascript", where the object property names are only quoted when needed. It also supports a "minimal" format, where both object property names and values are only quoted when needed.
119134

135+
```java
120136
Json json = new Json();
121137
json.setOutputType(OutputType.minimal);
122138
json.setElementType(Person.class, "numbers", PhoneNumber.class);
123139
System.out.println(json.prettyPrint(person));
124-
140+
```
141+
```json
125142
{
126143
name: Nate,
127144
age: 31,
@@ -136,23 +153,28 @@ JsonBeans can write and read both JSON and a couple JSON-like formats. It suppor
136153
}
137154
]
138155
}
156+
```
139157

140158
## Reading object graphs
141159

142160
The Json class uses reflection to automatically deserialize objects from JSON. Here is how to deserialize the JSON from the previous examples:
143161

162+
```java
144163
Json json = new Json();
145164
String text = json.toJson(person);
146165
Person person2 = json.fromJson(Person.class, text);
166+
```
147167

148168
The type passed to `fromJson` is the type of the root of the object graph. From this, JsonBeans can determine the types of all the fields and all other objects encountered, recursively. The "knownType" and "elementType" of the root can be passed to `toJson`. This is useful if the type of the root object is not known:
149169

170+
```java
150171
Json json = new Json();
151172
json.setOutputType(OutputType.minimal);
152173
String text = json.toJson(person, Object.class);
153174
System.out.println(json.prettyPrint(text));
154175
Object person2 = json.fromJson(Object.class, text);
155-
176+
```
177+
```json
156178
{
157179
class: com.example.Person,
158180
name: Nate,
@@ -170,19 +192,23 @@ The type passed to `fromJson` is the type of the root of the object graph. From
170192
}
171193
]
172194
}
195+
```
173196

174197
To read the JSON as a DOM of maps, arrays, and values, the `JsonReader` class can be used:
175198

199+
```java
176200
Json json = new Json();
177201
String text = json.toJson(person, Object.class);
178202
JsonValue root = new JsonReader().parse(text);
203+
```
179204

180205
The `JsonValue` describes a JSON object, array, string, float, long, boolean, or null.
181206

182207
## Customizing serialization
183208

184209
Serialization can be customized by either having the class to be serialized implement the `Json.Serializable` interface, or by registering a `Json.Serializer` with the `Json` instance. This example writes the phone numbers as an object with a single field:
185210

211+
```java
186212
static public class PhoneNumber implements Json.Serializable {
187213
private String name;
188214
private String number;
@@ -202,7 +228,8 @@ Serialization can be customized by either having the class to be serialized impl
202228
String text = json.prettyPrint(person);
203229
System.out.println(text);
204230
Person person2 = json.fromJson(Person.class, text);
205-
231+
```
232+
```json
206233
{
207234
"name": "Nate",
208235
"age": 31
@@ -215,11 +242,13 @@ Serialization can be customized by either having the class to be serialized impl
215242
}
216243
]
217244
}
245+
```
218246

219247
In the `Json.Serializable` interface methods, the `Json` instance is given. It has many methods to read and write data to the JSON. When using `Json.Serializable`, the surrounding JSON object is handled automatically in the `write` method. This is why the `read` method always receives a `JsonMap`.
220248

221249
`Json.Serializer` provides more control over what is output, requiring `writeObjectStart` and `writeObjectEnd` to be called to achieve the same effect. A JSON array or a simple value could be output instead of an object. `Json.Serializer` also allows the object creation to be customized.
222250

251+
```java
223252
Json json = new Json();
224253
json.setSerializer(PhoneNumber.class, new Json.Serializer<PhoneNumber>() {
225254
public void write (Json json, PhoneNumber number, Class knownType) {
@@ -239,6 +268,7 @@ In the `Json.Serializable` interface methods, the `Json` instance is given. It h
239268
String text = json.prettyPrint(person);
240269
System.out.println(text);
241270
Person person2 = json.fromJson(Person.class, text);
271+
```
242272

243273
## Event based parsing
244274

0 commit comments

Comments
 (0)