|
1 | 1 | # Built JSON for Dart
|
2 |
| -[](https://travis-ci.org/google/built_json.dart) |
3 |
| -## Introduction |
4 | 2 |
|
5 |
| -Built JSON provides serialization for the [Libraries for Object Oriented Dart] |
6 |
| -(https://github.com/google/built_value.dart/blob/master/libraries_for_object_oriented_dart.md#libraries-for-object-oriented-dart). |
7 |
| - |
8 |
| -This allows a complete serializable object oriented data model to be based on |
9 |
| -[Enum Classes](https://github.com/google/enum_class.dart#enum-classes-for-dart), |
10 |
| -[Built Collections] |
11 |
| -(https://github.com/google/built_collection.dart#built-collections-for-dart) and |
12 |
| -[Built Values] |
13 |
| -(https://github.com/google/built_value.dart#built-values-for-dart). |
14 |
| - |
15 |
| -Built JSON for Java, a separate project, will provide compatible serialization |
16 |
| -for Java, mapping Enum Classes to standard Java enums, Built Collections to |
17 |
| -[Immutable Collections] |
18 |
| -(https://github.com/google/guava/wiki/ImmutableCollectionsExplained) and Built |
19 |
| -Values to [AutoValues] |
20 |
| -(https://github.com/google/auto/tree/master/value#autovalue). |
21 |
| - |
22 |
| - |
23 |
| -## Example Code |
24 |
| - |
25 |
| -[Simple examples] |
26 |
| -(https://github.com/google/built_json.dart/tree/master/example); for a more |
27 |
| -realistic project see the |
28 |
| -[chat example](https://github.com/google/built_json.dart/tree/master/chat_example) |
29 |
| -for an end to end use of built_json on server and client. |
30 |
| - |
31 |
| - |
32 |
| -## Motivation |
33 |
| - |
34 |
| -There are many ways to serialize data. Why do we need another? |
35 |
| - |
36 |
| -Built JSON is about serialization of object oriented data. There are many ways |
37 |
| -to do this, too. Built JSON is different to other libraries for a number of |
38 |
| -reasons: |
39 |
| - |
40 |
| -Built JSON _fully supports object oriented design_: any object model that you |
41 |
| -can design can be serialized, including full use of generics and interfaces. |
42 |
| -Some other libraries require concrete types or do not fully support generics. |
43 |
| - |
44 |
| -Built JSON _allows different object oriented models over the same data_. For |
45 |
| -example, in a client server application, it's likely that the client and server |
46 |
| -want different functionality from their data model. So, they are allowed to have |
47 |
| -different classes that map to the same data. Most other libraries enforce a 1:1 |
48 |
| -mapping between classes and types on the wire. |
49 |
| - |
50 |
| -Built JSON _requires well behaved types_. They must be immutable, can use |
51 |
| -interface but not concrete inheritance, must have predictable nullability, |
52 |
| -`hashCode`, `equals` and `toString`. In fact, they must be Enum Classes, Built |
53 |
| -Collections or Built Values. Some other libraries allow badly behaved types to |
54 |
| -be serialized. |
55 |
| - |
56 |
| -Built JSON _supports changes to the data model_. Optional fields can be added or |
57 |
| -removed, and fields can be switched from optional to required, allowing your |
58 |
| -data model to evolve without breaking compatbility. Some other libraries break |
59 |
| -compatability on any change to any serializable class. |
60 |
| - |
61 |
| -Built JSON _is modular_. Each endpoint can choose which classes to know about; |
62 |
| -for example, you can have multiple clients that each know about only a subset of |
63 |
| -the classes the server knows. Most other libraries are monolithic, requiring all |
64 |
| -endpoints to know all types. |
65 |
| - |
66 |
| -Built JSON _is multi language_. Support will be come first for Dart, Java and |
67 |
| -Java/GWT. Many other libraries support a single language only. |
68 |
| - |
69 |
| -Built JSON _has first class support for validation_ via Built Values. An |
70 |
| -important part of a powerful data model is ensuring it's valid, so classes can |
71 |
| -make guarantees about what they can do. Other libraries also support validation |
72 |
| -but usually in a less prominent way. |
73 |
| - |
74 |
| -And, finally, Built JSON _is pluggable_. Arbitrary extensions can be added to |
75 |
| -give custom JSON serialization for your own types. This could be used to |
76 |
| -interoperate with other tools or to add hand coded high performance serializers |
77 |
| -for specific classes. Some other libraries are not so extensible. |
78 |
| - |
79 |
| -## Features and bugs |
80 |
| - |
81 |
| -Please file feature requests and bugs at the [issue tracker][tracker]. |
82 |
| - |
83 |
| -[tracker]: https://github.com/google/built_json.dart/issues |
| 3 | +Now available from [built_value](https://github.com/google/built_value.dart). |
0 commit comments