Skip to content

Commit 6ea3fe6

Browse files
NathanSweetNathanSweet
committed
Create README.md
1 parent 43e21b8 commit 6ea3fe6

1 file changed

Lines changed: 270 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 270 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,270 @@
1+
## Overview
2+
3+
!YamlBeans makes it easy to serialize and deserialize Java object graphs to and from YAML, a human-friendly data format. Replace XML and properties files with YAML for more expressive power (lists, maps, anchors, etc) and easier hand-editing.
4+
5+
Maven Central:
6+
http://repo1.maven.org/maven2/com/esotericsoftware/yamlbeans/yamlbeans/
7+
8+
## Basic deserialization
9+
10+
The !YamlReader class is used to deserialize YAML to Java objects. The following YAML defines a Map with four entries. The "phone numbers" entry is a List of two items, each of which is a Map.
11+
12+
```yaml
13+
name: Nathan Sweet
14+
age: 28
15+
address: 4011 16th Ave S
16+
phone numbers:
17+
- name: Home
18+
number: 206-555-5138
19+
- name: Work
20+
number: 425-555-2306
21+
```
22+
23+
The "read" method reads the next YAML document and deserializes it into !HashMaps, !ArrayLists, and Strings. Since we know the root object defined in the YAML of our example is a Map, we can cast the object and make use of it.
24+
25+
```java
26+
YamlReader reader = new YamlReader(new FileReader("contact.yml"));
27+
Object object = reader.read();
28+
System.out.println(object);
29+
Map map = (Map)object;
30+
System.out.println(map.get("address"));
31+
```
32+
33+
## Multiple objects
34+
35+
A stream of YAML can contain more than one YAML document. Each call to !YamlReader#read() deserializes the next document into an object. YAML documents are delimited by "---" (this is optional for the first document).
36+
37+
```yaml
38+
name: Nathan Sweet
39+
age: 28
40+
---
41+
name: Some One
42+
age: 25
43+
```
44+
45+
This prints the String "28" then "25":
46+
47+
```java
48+
YamlReader reader = new YamlReader(new FileReader("contact.yml"));
49+
while (true) {
50+
Map contact = reader.read();
51+
if (contact == null) break;
52+
System.out.println(contact.get("age"));
53+
}
54+
```
55+
56+
## Deserializing other classes
57+
58+
There are two ways to deserialize something other than !HashMaps, !ArrayLists, and Strings. Imagine this YAML document and Java class:
59+
60+
```yaml
61+
name: Nathan Sweet
62+
age: 28
63+
```
64+
```java
65+
public class Contact {
66+
public String name;
67+
public int age;
68+
}
69+
```
70+
71+
The "read" method can be passed a class, so the !YamlReader knows what it is deserializing:
72+
73+
```java
74+
YamlReader reader = new YamlReader(new FileReader("contact.yml"));
75+
Contact contact = reader.read(Contact.class);
76+
System.out.println(contact.age);
77+
```
78+
79+
The !YamlReader creates an instance of the Contact class and sets the "name" and "age" fields. The !YamlReader determines the "age" value in the YAML needs to be converted into a int. Deserialization would have failed if the age was not a valid int. The !YamlReader can set public fields and bean setter methods.
80+
81+
Instead of telling the !YamlReader what type to deserialize, the type can alternatively be specified in the YAML using a tag:
82+
83+
```yaml
84+
!com.example.Contact
85+
name: Nathan Sweet
86+
age: 28
87+
```
88+
89+
## Serializing objects
90+
91+
The !YamlWriter class is used to serialize Java objects to YAML. The "write" method automatically handles this by recognizing public fields and bean getter methods.
92+
93+
```java
94+
Contact contact = new Contact();
95+
contact.name = "Nathan Sweet";
96+
contact.age = 28;
97+
YamlWriter writer = new YamlWriter(new FileWriter("output.yml"));
98+
writer.write(contact);
99+
writer.close();
100+
```
101+
102+
This outputs:
103+
104+
```yaml
105+
!com.example.Contact
106+
name: Nathan Sweet
107+
age: 28
108+
```
109+
110+
The tags are automatically output as needed so that the !YamlReader class will be able to reconstruct the object graph. For example, serializing this !ArrayList does not output any tag for the list because !YamlReader uses an !ArrayList by default.
111+
112+
```java
113+
List list = new ArrayList();
114+
list.add("moo");
115+
list.add("cow");
116+
```
117+
```yaml
118+
- moo
119+
- cow
120+
```
121+
122+
If the list was a !LinkedList, then !YamlWriter knows that a tag is needed and outputs:
123+
124+
```java
125+
List list = new LinkedList();
126+
list.add("moo");
127+
list.add("cow");
128+
```
129+
```yaml
130+
!java.util.LinkedList
131+
- moo
132+
- cow
133+
```
134+
135+
Note that it is not advisable to subclass Collection or Map. !YamlBeans will only serialize the collection or map and its elements, not any additional fields.
136+
137+
## Complex graphs
138+
139+
!YamlBeans can serialize any object graph.
140+
141+
```java
142+
public class Contact {
143+
public String name;
144+
public int age;
145+
public List phoneNumbers;
146+
}
147+
148+
public class Phone {
149+
public String name;
150+
public String number;
151+
}
152+
```
153+
```yaml
154+
friends:
155+
- !com.example.Contact
156+
name: Bob
157+
age: 29
158+
phoneNumbers:
159+
- !com.example.Phone
160+
name: Home
161+
number: 206-555-1234
162+
- !com.example.Phone
163+
name: Work
164+
number: 206-555-5678
165+
- !com.example.Contact
166+
name: Mike
167+
age: 31
168+
phoneNumbers:
169+
- !com.example.Phone
170+
number: 206-555-4321
171+
enemies:
172+
- !com.example.Contact
173+
name: Bill
174+
phoneNumbers:
175+
- !com.example.Phone
176+
name: Cell
177+
number: 206-555-1234
178+
```
179+
180+
This is a map of lists of contacts, each with a list of phone numbers. Again, the public fields could also have been bean properties.
181+
182+
## Tag shortcuts
183+
184+
Tags can be lengthy sometimes and can clutter up the YAML. Alternate tags can be defined for a class and will be used instead of the full class name.
185+
186+
```java
187+
YamlWriter writer = new YamlWriter(new FileWriter("output.yml"));
188+
writer.getConfig().setClassTag("contact", Contact.class);
189+
writer.write(contact);
190+
writer.close();
191+
```
192+
193+
The output no longer contains the full classname for the Contact class.
194+
195+
```yaml
196+
!contact
197+
name: Nathan Sweet
198+
age: 28
199+
```
200+
201+
## Lists and maps
202+
203+
When reading or writing a List or Map, !YamlBeans cannot know what type of objects are supposed to be in the List or Map, so it will write out a tag.
204+
205+
```yaml
206+
!com.example.Contact
207+
name: Bill
208+
phoneNumbers:
209+
- !com.example.Phone
210+
number: 206-555-1234
211+
- !com.example.Phone
212+
number: 206-555-5678
213+
- !com.example.Phone
214+
number: 206-555-7654
215+
```
216+
217+
This can make the YAML less readable. To improve this, you may define what element type should be expected for a List or Map field on your object.
218+
219+
```java
220+
YamlWriter writer = new YamlWriter(new FileWriter("output.yml"));
221+
writer.getConfig().setPropertyElementType(Contact.class, "phoneNumbers", Phone.class);
222+
writer.write(contact);
223+
writer.close();
224+
```
225+
226+
Now !YamlBeans knows what to expect for elements of the "phoneNumbers" field, so extra tags will not be output.
227+
228+
```yaml
229+
!com.example.Contact
230+
name: Bill
231+
phoneNumbers:
232+
- number: 206-555-1234
233+
- number: 206-555-5678
234+
- number: 206-555-7654
235+
```
236+
237+
Setting the element type for a Map field tells !YamlBeans what to expect for values in the Map. Keys in a Map are always Strings.
238+
239+
## Anchors
240+
241+
When an object graph contains multiple references to the same object, an anchor may be used so that the object only needs to be defined once in the YAML.
242+
243+
```yaml
244+
oldest friend:
245+
&1 !contact
246+
name: Bob
247+
age: 29
248+
best friend: *1
249+
```
250+
251+
In this map, the "oldest friend" and "best friend" keys reference the same object. The !YamlReader automatically handles the anchors in the YAML when rebuilding the object graph. By default, the !YamlWriter automatically outputs anchors when writing objects.
252+
253+
```java
254+
Contact contact = new Contact();
255+
contact.name = "Bob";
256+
contact.age = 29;
257+
Map map = new HashMap();
258+
map.put("oldest friend", contact);
259+
map.put("best friend", contact);
260+
```
261+
262+
## Architecture
263+
264+
The YAML tokenizer, parser, and emitter are based on those from the JvYAML project. They have been heavily refactored, bugs fixed, etc. The rest of the JvYAML project was not used because of its complexity. !YamlBeans strives for the simplest possible thing that works, with the goal being to make it easy to use the YAML data format with Java.
265+
266+
!YamlBeans supports YAML version 1.0 and 1.1.
267+
268+
## More info
269+
270+
See the javadocs for various other features available on the !YamlConfig class.

0 commit comments

Comments
 (0)