|
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