| OLD | NEW |
| 1 // Copyright (c) 2012, the Dart project authors. Please see the AUTHORS file | 1 // Copyright (c) 2012, the Dart project authors. Please see the AUTHORS file |
| 2 // for details. All rights reserved. Use of this source code is governed by a | 2 // for details. All rights reserved. Use of this source code is governed by a |
| 3 // BSD-style license that can be found in the LICENSE file. | 3 // BSD-style license that can be found in the LICENSE file. |
| 4 | 4 |
| 5 /** | 5 /** |
| 6 * A general-purpose serialization facility for Dart objects. | 6 * A general-purpose serialization facility for Dart objects. |
| 7 * | 7 * |
| 8 * A [Serialization] is defined in terms of [SerializationRule]s and supports | 8 * A [Serialization] is defined in terms of [SerializationRule]s and supports |
| 9 * reading and writing to different formats. | 9 * reading and writing to different formats. |
| 10 * | 10 * |
| 11 * For information on installing and importing this library, see the | 11 * For information on installing and importing this library, see the |
| 12 * [serialization package on pub.dartlang.org] | 12 * [serialization package on pub.dartlang.org] |
| 13 * (http://pub.dartlang.org/packages/serialization). | 13 * (http://pub.dartlang.org/packages/serialization). |
| 14 * | 14 * |
| 15 * ## Setup | 15 * ## Setup |
| 16 * | 16 * |
| 17 * A simple example of usage is | 17 * A simple example of usage is |
| 18 * | 18 * |
| 19 * var address = new Address(); | 19 * var address = new Address(); |
| 20 * address.street = 'N 34th'; | 20 * address.street = 'N 34th'; |
| 21 * address.city = 'Seattle'; | 21 * address.city = 'Seattle'; |
| 22 * var serialization = new Serialization() | 22 * var serialization = new Serialization() |
| 23 * ..addRuleFor(address); | 23 * ..addRuleFor(Address); |
| 24 * Map output = serialization.write(address); | 24 * Map output = serialization.write(address); |
| 25 * | 25 * |
| 26 * This creates a new serialization and adds a rule for address objects. Right | 26 * This creates a new serialization and adds a rule for address objects. |
| 27 * now it has to be passed an address instance because of limitations using | 27 * Then we ask the [Serialization] to write the address |
| 28 * Address as a literal. Then we ask the [Serialization] to write the address | |
| 29 * and we get back a Map which is a [json]able representation of the state of | 28 * and we get back a Map which is a [json]able representation of the state of |
| 30 * the address and related objects. Note that while the output in this case | 29 * the address and related objects. Note that while the output in this case |
| 31 * is a [Map], the type will vary depending on which output format we've told | 30 * is a [Map], the type will vary depending on which output format we've told |
| 32 * the [Serialization] to use. | 31 * the [Serialization] to use. |
| 33 * | 32 * |
| 34 * The version above used reflection to automatically identify the public | 33 * The version above used reflection to automatically identify the public |
| 35 * fields of the address object. We can also specify those fields explicitly. | 34 * fields of the address object. We can also specify those fields explicitly. |
| 36 * | 35 * |
| 37 * var serialization = new Serialization() | 36 * var serialization = new Serialization() |
| 38 * ..addRuleFor(address, | 37 * ..addRuleFor(Address, |
| 39 * constructor: "create", | 38 * constructor: "create", |
| 40 * constructorFields: ["number", "street"], | 39 * constructorFields: ["number", "street"], |
| 41 * fields: ["city"]); | 40 * fields: ["city"]); |
| 42 * | 41 * |
| 43 * This rule still uses reflection to access the fields, but does not try to | 42 * This rule still uses reflection to access the fields, but does not try to |
| 44 * identify which fields to use, but instead uses only the "number" and "street" | 43 * identify which fields to use, but instead uses only the "number" and "street" |
| 45 * fields that we specified. We may also want to tell it to identify the | 44 * fields that we specified. We may also want to tell it to identify the |
| 46 * fields, but to specifically omit certain fields that we don't want | 45 * fields, but to specifically omit certain fields that we don't want |
| 47 * serialized. | 46 * serialized. |
| 48 * | 47 * |
| 49 * var serialization = new Serialization() | 48 * var serialization = new Serialization() |
| 50 * ..addRuleFor(address, | 49 * ..addRuleFor(Address, |
| 51 * constructor: "", | 50 * constructor: "", |
| 52 * excludeFields: ["other", "stuff"]); | 51 * excludeFields: ["other", "stuff"]); |
| 53 * | 52 * |
| 54 * ## Writing rules | 53 * ## Writing rules |
| 55 * | 54 * |
| 56 * We can also use a completely non-reflective rule to serialize and | 55 * We can also use a completely non-reflective rule to serialize and |
| 57 * de-serialize objects. This can be more work, but it does work in | 56 * de-serialize objects. This can be more work, but it does work in |
| 58 * dart2js, where mirrors are not yet implemented. We can specify this in two | 57 * dart2js, where mirrors are not yet implemented. We can specify this in two |
| 59 * ways. First, we can write our own SerializationRule class that has methods | 58 * ways. First, we can write our own SerializationRule class that has methods |
| 60 * for our Address class. | 59 * for our Address class. |
| (...skipping 121 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 182 * connected up to other instances on the receiving side. A notable example of | 181 * connected up to other instances on the receiving side. A notable example of |
| 183 * this is when serialization rules have been stored. Instances of BasicRule | 182 * this is when serialization rules have been stored. Instances of BasicRule |
| 184 * take a [ClassMirror] in their constructor, and we cannot serialize those. So | 183 * take a [ClassMirror] in their constructor, and we cannot serialize those. So |
| 185 * when we read the rules, we must provide a Map<String, Object> which maps from | 184 * when we read the rules, we must provide a Map<String, Object> which maps from |
| 186 * the simple name of classes we are interested in to a [ClassMirror]. This can | 185 * the simple name of classes we are interested in to a [ClassMirror]. This can |
| 187 * be provided either in the [Serialization.namedObjects], | 186 * be provided either in the [Serialization.namedObjects], |
| 188 * or as an additional parameter to the reading and writing methods on the | 187 * or as an additional parameter to the reading and writing methods on the |
| 189 * [Reader] or [Writer] respectively. | 188 * [Reader] or [Writer] respectively. |
| 190 * | 189 * |
| 191 * new Serialization() | 190 * new Serialization() |
| 192 * ..addRuleFor(new Person(), constructorFields: ["name"]) | 191 * ..addRuleFor(Person, constructorFields: ["name"]) |
| 193 * ..namedObjects['Person'] = reflect(new Person()).type; | 192 * ..namedObjects['Person'] = reflect(new Person()).type; |
| 194 */ | 193 */ |
| 195 library serialization; | 194 library serialization; |
| 196 | 195 |
| 197 import 'src/mirrors_helpers.dart'; | 196 import 'src/mirrors_helpers.dart'; |
| 198 import 'src/serialization_helpers.dart'; | 197 import 'src/serialization_helpers.dart'; |
| 199 import 'dart:collection'; | 198 import 'dart:collection'; |
| 200 | 199 |
| 201 part 'src/reader_writer.dart'; | 200 part 'src/reader_writer.dart'; |
| 202 part 'src/serialization_rule.dart'; | 201 part 'src/serialization_rule.dart'; |
| (...skipping 288 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 491 } | 490 } |
| 492 | 491 |
| 493 /** | 492 /** |
| 494 * An exception class for errors during serialization. | 493 * An exception class for errors during serialization. |
| 495 */ | 494 */ |
| 496 class SerializationException implements Exception { | 495 class SerializationException implements Exception { |
| 497 final String message; | 496 final String message; |
| 498 const SerializationException(this.message); | 497 const SerializationException(this.message); |
| 499 String toString() => "SerializationException($message)"; | 498 String toString() => "SerializationException($message)"; |
| 500 } | 499 } |
| OLD | NEW |