Revert "remove serialization. it's moved to github"

pkg/serialization/lib/serialization.dart

+// Copyright (c) 2012, the Dart project authors.  Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+/**
+ * A general-purpose serialization facility for Dart objects.
+ *
+ * A [Serialization] is defined in terms of [SerializationRule]s and supports
+ * reading and writing to different formats.
+ *
+ * For information on installing and importing this library, see the
+ * [serialization package on pub.dartlang.org]
+ * (http://pub.dartlang.org/packages/serialization).
+ *
+ * ## Setup
+ *
+ * A simple example of usage is
+ *
+ *      var address = new Address();
+ *      address.street = 'N 34th';
+ *      address.city = 'Seattle';
+ *      var serialization = new Serialization()
+ *          ..addRuleFor(Address);
+ *      Map output = serialization.write(address);
+ *
+ * This creates a new serialization and adds a rule for address objects.
+ * Then we ask the [Serialization] to write the address
+ * and we get back a Map which is a [json]able representation of the state of
+ * the address and related objects. Note that while the output in this case
+ * is a [Map], the type will vary depending on which output format we've told
+ * the [Serialization] to use.
+ *
+ * The version above used reflection to automatically identify the public
+ * fields of the address object. We can also specify those fields explicitly.
+ *
+ *      var serialization = new Serialization()
+ *        ..addRuleFor(Address,
+ *            constructor: "create",
+ *            constructorFields: ["number", "street"],
+ *            fields: ["city"]);
+ *
+ * This rule still uses reflection to access the fields, but does not try to
+ * identify which fields to use, but instead uses only the "number" and "street"
+ * fields that we specified. We may also want to tell it to identify the
+ * fields, but to specifically omit certain fields that we don't want
+ * serialized.
+ *
+ *      var serialization = new Serialization()
+ *        ..addRuleFor(Address,
+ *            constructor: "",
+ *            excludeFields: ["other", "stuff"]);
+ *
+ * ## Writing rules
+ *
+ * We can also use a completely non-reflective rule to serialize and
+ * de-serialize objects. This can be more work, but it does work in
+ * dart2js, where mirrors are not yet implemented. We can specify this in two
+ * ways. First, we can write our own SerializationRule class that has methods
+ * for our Address class.
+ *
+ *      class AddressRule extends CustomRule {
+ *        bool appliesTo(instance, Writer w) => instance.runtimeType == Address;
+ *        getState(instance) => [instance.street, instance.city];
+ *        create(state) => new Address();
+ *        setState(Address a, List state) {
+ *          a.street = state[0];
+ *          a.city = state[1];
+ *        }
+ *      }
+ *
+ * The class needs four different methods. The [CustomRule.appliesTo]
+ * method tells us if
+ * the rule should be used to write an object. In this example we use a test
+ * based on runtimeType. We could also use an "is Address" test, but if Address
+ * has subclasses that would find those as well, and we want a separate rule
+ * for each. The [CustomRule.getState] method should
+ * return all the state of the object that we want to recreate,
+ * and should be either a Map or a List. If you want to write to human-readable
+ * formats where it's useful to be able to look at the data as a map from
+ * field names to values, then it's better to return it as a map. Otherwise it's
+ * more efficient to return it as a list. You just need to be sure that the
+ * [CustomRule.create] and [CustomRule.setState] methods interpret the data the
+ * same way as [CustomRule.getState] does.
+ *
+ * The [CustomRule.create] method will create the new object and return it. While it's
+ * possible to create the object and set all its state in this one method, that
+ * increases the likelihood of problems with cycles. So it's better to use the
+ * minimum necessary information in [CustomRule.create] and do more of the work
+ * in [CustomRule.setState].
+ *
+ * The other way to do this is not creating a subclass, but by using a
+ * [ClosureRule] and giving it functions for how to create
+ * the address.
+ *
+ *      addressToMap(a) => {"number" : a.number, "street" : a.street,
+ *          "city" : a.city};
+ *      createAddress(Map m) => new Address.create(m["number"], m["street"]);
+ *      fillInAddress(Address a, Map m) => a.city = m["city"];
+ *      var serialization = new Serialization()
+ *        ..addRule(
+ *            new ClosureRule(anAddress.runtimeType,
+ *                addressToMap, createAddress, fillInAddress);
+ *
+ * In this case we have created standalone functions rather than
+ * methods in a subclass and we pass them to the constructor of
+ * [ClosureRule]. In this case we've also had them use maps rather than
+ * lists for the state, but either would work as long as the rule is
+ * consistent with the representation it uses. We pass it the runtimeType
+ * of the object, and functions equivalent to the methods on [CustomRule]
+ *
+ * ## Constant values
+ *
+ * There are cases where the constructor needs values that we can't easily get
+ * from the serialized object. For example, we may just want to pass null, or a
+ * constant value. To support this, we can specify as constructor fields
+ * values that aren't field names. If any value isn't a String, or is a string
+ * that doesn't correspond to a field name, it will be
+ * treated as a constant and passed unaltered to the constructor.
+ *
+ * In some cases a non-constructor field should not be set using field
+ * access or a setter, but should be done by calling a method. For example, it
+ * may not be possible to set a List field "foo", and you need to call an
+ * addFoo() method for each entry in the list. In these cases, if you are using
+ * a BasicRule for the object you can call the setFieldWith() method.
+ *
+ *       s..addRuleFor(FooHolder).setFieldWith("foo",
+ *           (parent, value) => for (var each in value) parent.addFoo(value));
+ *
+ * ## Writing
+ *
+ * To write objects, we use the write() method.
+ *
+ *       var output = serialization.write(someObject);
+ *
+ * By default this uses a representation in which objects are represented as
+ * maps keyed by field name, but in which references between objects have been
+ * converted into Reference objects. This is then typically encoded as
+ * a [json] string, but can also be used in other ways, e.g. sent to another
+ * isolate.
+ *
+ * We can write objects in different formats by passing a [Format] object to
+ * the [Serialization.write] method or by getting a [Writer] object.
+ * The available formats
+ * include the default, a simple "flat" format that doesn't include field names,
+ * and a simple JSON format that produces output more suitable for talking to
+ * services that expect JSON in a predefined format. Examples of these are
+ *
+ *      Map output = serialization.write(address, new SimpleMapFormat());
+ *      List output = serialization.write(address, new SimpleFlatFormat());
+ *      var output = serialization.write(address, new SimpleJsonFormat());
+ * Or, using a [Writer] explicitly
+ *      var writer = serialization.newWriter(new SimpleFlatFormat());
+ *      List output = writer.write(address);
+ *
+ * These representations are not yet considered stable.
+ *
+ * ## Reading
+ *
+ * To read objects, the corresponding [Serialization.read] method can be used.
+ *
+ *       Address input = serialization.read(input);
+ *
+ * When reading, the serialization instance doing the reading must be configured
+ * with compatible rules to the one doing the writing. It's possible for the
+ * rules to be different, but they need to be able to read the same
+ * representation. For most practical purposes right now they should be the
+ * same. The simplest way to achieve this is by having the serialization
+ * variable [Serialization.selfDescribing] be true. In that case the rules
+ * themselves are also
+ * stored along with the serialized data, and can be read back on the receiving
+ * end. Note that this may not work for all rules or all formats. The
+ * [Serialization.selfDescribing] variable is true by default, but the
+ * [SimpleJsonFormat] does not support it, since the point is to provide a
+ * representation in a form
+ * other services might expect. Using CustomRule or ClosureRule also does not
+ * yet work with the [Serialization.selfDescribing] variable.
+ *
+ * ## Named objects
+ *
+ * When reading, some object references should not be serialized, but should be
+ * connected up to other instances on the receiving side. A notable example of
+ * this is when serialization rules have been stored. Instances of BasicRule
+ * take a [ClassMirror] in their constructor, and we cannot serialize those. So
+ * when we read the rules, we must provide a Map<String, Object> which maps from
+ * the simple name of classes we are interested in to a [ClassMirror]. This can
+ * be provided either in the [Serialization.namedObjects],
+ * or as an additional parameter to the reading and writing methods on the
+ * [Reader] or [Writer] respectively.
+ *
+ *     new Serialization()
+ *       ..addRuleFor(Person, constructorFields: ["name"])
+ *       ..namedObjects['Person'] = reflect(new Person()).type;
+ */
+library serialization;
+
+import 'src/mirrors_helpers.dart';
+import 'src/serialization_helpers.dart';
+import 'dart:collection';
+
+part 'src/reader_writer.dart';
+part 'src/serialization_rule.dart';
+part 'src/basic_rule.dart';
+part 'src/format.dart';
+
+/**
+ * This class defines a particular serialization scheme, in terms of
+ * [SerializationRule] instances, and supports reading and writing them.
+ * See library comment for examples of usage.
+ */
+class Serialization {
+  final List<SerializationRule> _rules;
+
+  /**
+   * The serialization is controlled by the list of Serialization rules. These
+   * are most commonly added via [addRuleFor].
+   */
+  final UnmodifiableListView<SerializationRule> rules;
+
+  /**
+   * When reading, we may need to resolve references to existing objects in
+   * the system. The right action may not be to create a new instance of
+   * something, but rather to find an existing instance and connect to it.
+   * For example, if we have are serializing an Email message and it has a
+   * link to the owning account, it may not be appropriate to try and serialize
+   * the account. Instead we should just connect the de-serialized message
+   * object to the account object that already exists there.
+   */
+  Map<String, dynamic> namedObjects = {};
+
+  /**
+   * When we write out data using this serialization, should we also write
+   * out a description of the rules. This is on by default unless using
+   * CustomRule subclasses, in which case it requires additional setup and
+   * is off by default.
+   */
+  bool _selfDescribing;
+
+  /**
+   * When we write out data using this serialization, should we also write
+   * out a description of the rules. This is on by default unless using
+   * CustomRule subclasses, in which case it requires additional setup and
+   * is off by default.
+   */
+  bool get selfDescribing {
+    // TODO(alanknight): Should this be moved to the format?
+    // TODO(alanknight): Allow self-describing in the presence of CustomRule.
+    // TODO(alanknight): Don't do duplicate work creating a writer and
+    // serialization here and then re-creating when we actually serialize.
+    if (_selfDescribing != null) return _selfDescribing;
+    var meta = ruleSerialization();
+    var w = meta.newWriter();
+    _selfDescribing = !rules.any((rule) =>
+        meta.rulesFor(rule, w, create: false).isEmpty);
+    return _selfDescribing;
+  }
+
+  /**
+   * When we write out data using this serialization, should we also write
+   * out a description of the rules. This is on by default unless using
+   * CustomRule subclasses, in which case it requires additional setup and
+   * is off by default.
+   */
+  void set selfDescribing(bool value) {
+    _selfDescribing = value;
+  }
+
+  /**
+   * Creates a new serialization with a default set of rules for primitives
+   * and lists.
+   */
+  factory Serialization() =>
+    new Serialization.blank()
+      ..addDefaultRules();
+
+  /**
+   * Creates a new serialization with no default rules at all. The most common
+   * use for this is if we are reading self-describing serialized data and
+   * will populate the rules from that data.
+   */
+  factory Serialization.blank()
+    => new Serialization._(new List<SerializationRule>());
+
+  Serialization._(List<SerializationRule> rules) :
+    this._rules = rules,
+    this.rules = new UnmodifiableListView(rules);
+
+  /**
+   * Create a [BasicRule] rule for [instanceOrType]. Normally this will be
+   * a type, but for backward compatibilty we also allow you to pass an
+   * instance (except an instance of Type), and the rule will be created
+   * for its runtimeType. Optionally
+   * allows specifying a [constructor] name, the list of [constructorFields],
+   * and the list of [fields] not used in the constructor. Returns the new
+   * rule. Note that [BasicRule] uses reflection, and so will not work with the
+   * current state of dartj2s. If you need to run there, consider using
+   * [CustomRule] instead.
+   *
+   * If the optional parameters aren't specified, the default constructor will
+   * be used, and the list of fields will be computed. Alternatively, you can
+   * omit [fields] and provide [excludeFields], which will then compute the
+   * list of fields specifically excluding those listed.
+   *
+   * The fields can be actual public fields, but can also be getter/setter
+   * pairs or getters whose value is provided in the constructor. For the
+   * [constructorFields] they can also be arbitrary objects. Anything that is
+   * not a String will be treated as a constant value to be used in any
+   * construction of these objects.
+   *
+   * If the list of fields is computed, fields from the superclass will be
+   * included. However, each subclass needs its own rule, since the constructors
+   * are not inherited, and so may need to be specified separately for each
+   * subclass.
+   */
+  BasicRule addRuleFor(
+      instanceOrType,
+      {String constructor,
+        List constructorFields,
+        List<String> fields,
+        List<String> excludeFields}) {
+
+    var rule = new BasicRule(
+        turnInstanceIntoSomethingWeCanUse(
+            instanceOrType),
+        constructor, constructorFields, fields, excludeFields);
+    addRule(rule);
+    return rule;
+  }
+
+  /** Set up the default rules, for lists and primitives. */
+  void addDefaultRules() {
+    addRule(new PrimitiveRule());
+    addRule(new ListRule());
+    // Both these rules apply to lists, so unless otherwise indicated,
+    // it will always find the first one.
+    addRule(new ListRuleEssential());
+    addRule(new MapRule());
+    addRule(new SymbolRule());
+    addRule(new DateTimeRule());
+  }
+
+  /**
+   * Add a new SerializationRule [rule]. The addRuleFor method will probably
+   * handle most simple cases, but for adding an arbitrary rule, including
+   * a SerializationRule subclass which you have created, you can use this
+   * method.
+   */
+  void addRule(SerializationRule rule) {
+    rule.number = _rules.length;
+    _rules.add(rule);
+  }
+
+  /**
+   * This writes out an object graph rooted at [object] and returns the result.
+   * The [format] parameter determines the form of the result. The default
+   * format is [SimpleMapFormat] and returns a Map.
+   */
+  write(Object object, {Format format}) {
+    return newWriter(format).write(object);
+  }
+
+  /**
+   * Return a new [Writer] object for this serialization. This is useful if you
+   * want to do something more complex with the writer than just returning
+   * the final result.
+   */
+  Writer newWriter([Format format]) => new Writer(this, format);
+
+  /**
+   * Read the serialized data from [input] and return the root object
+   * from the result. The [input] can be of any type that the [Format]
+   * reads/writes, but normally will be a [List], [Map], or a simple type.
+   * The [format] parameter determines the form of the result. The default
+   * format is [SimpleMapFormat] and expects a Map as input.
+   * If there are objects that need to be resolved
+   * in the current context, they should be provided in [externals] as a
+   * Map from names to values. In particular, in the current implementation
+   * any class mirrors needed should be provided in [externals] using the
+   * class name as a key. In addition to the [externals] map provided here,
+   * values will be looked up in the [namedObjects] map.
+   */
+  read(input, {Format format, Map externals: const {}}) {
+    return newReader(format).read(input, externals);
+  }
+
+  /**
+   * Return a new [Reader] object for this serialization. This is useful if
+   * you want to do something more complex with the reader than just returning
+   * the final result.
+   */
+  Reader newReader([Format format]) => new Reader(this, format);
+
+  /**
+   * Return the list of SerializationRule that apply to [object]. For
+   * internal use, but public because it's used in testing.
+   */
+  Iterable<SerializationRule> rulesFor(object, Writer w, {create : true}) {
+    // This has a couple of edge cases.
+    // 1) The owning object may have indicated we should use a different
+    // rule than the default.
+    // 2) We may not have a rule, in which case we lazily create a BasicRule.
+    // 3) Rules are allowed to say mustBePrimary, meaning that they can be used
+    // iff no other rule was chosen first.
+    // TODO(alanknight): Can the mustBePrimary mechanism be removed or changed.
+    // It adds an order dependency to the rules, and is messy. Reconsider in the
+    // light of a more general mechanism for multiple rules per object.
+    // TODO(alanknight): Finding which rules apply seems likely to be a
+    // bottleneck, particularly with the current reflective implementation.
+    // Consider how to improve it. e.g. cache the list of rules by class. But
+    // be careful of issues like rules which have arbitrary predicates. Or
+    // consider having the arbitrary predicates be secondary to an initial
+    // class-based lookup mechanism.
+    var target, candidateRules;
+    if (object is DesignatedRuleForObject) {
+      target = object.target;
+      candidateRules = object.possibleRules(rules);
+    } else {
+      target = object;
+      candidateRules = rules;
+    }
+    Iterable applicable = candidateRules.where(
+        (each) => each.appliesTo(target, w));
+
+    if (applicable.isEmpty) {
+      return create ? [addRuleFor(target)] : applicable;
+    }
+
+    if (applicable.length == 1) return applicable;
+    var first = applicable.first;
+    var finalRules = applicable.where(
+        (x) => !x.mustBePrimary || (x == first));
+
+    if (finalRules.isEmpty) throw new SerializationException(
+        'No valid rule found for object $object');
+    return finalRules;
+  }
+
+  /**
+   * Create a Serialization for serializing SerializationRules. This is used
+   * to save the rules in a self-describing format along with the data.
+   * If there are new rule classes created, they will need to be described
+   * here.
+   */
+  Serialization ruleSerialization() {
+    // TODO(alanknight): There's an extensibility issue here with new rules.
+    // TODO(alanknight): How to handle rules with closures? They have to
+    // exist on the other side, but we might be able to hook them up by name,
+    // or we might just be able to validate that they're correctly set up
+    // on the other side.
+
+    var meta = new Serialization()
+      ..selfDescribing = false
+      ..addRuleFor(ListRule)
+      ..addRuleFor(MapRule)
+      ..addRuleFor(PrimitiveRule)
+      ..addRuleFor(ListRuleEssential)
+      ..addRuleFor(BasicRule,
+          constructorFields: ['type',
+            'constructorName',
+            'constructorFields', 'regularFields', []],
+          fields: [])
+      ..addRule(new NamedObjectRule())
+      ..addRule(new MirrorRule())
+      ..addRuleFor(MirrorRule)
+      ..addRuleFor(SymbolRule)
+      ..addRuleFor(DateTimeRule);
+    meta.namedObjects = namedObjects;
+    return meta;
+  }
+
+  /** Return true if our [namedObjects] collection has an entry for [object].*/
+  bool _hasNameFor(object) {
+    var sentinel = const _Sentinel();
+    return _nameFor(object, () => sentinel) != sentinel;
+  }
+
+  /**
+   * Return the name we have for [object] in our [namedObjects] collection or
+   * the result of evaluating [ifAbsent] if there is no entry.
+   */
+  _nameFor(object, [ifAbsent]) {
+    for (var key in namedObjects.keys) {
+      if (identical(namedObjects[key], object)) return key;
+    }
+    return ifAbsent == null ? null : ifAbsent();
+  }
+}
+
+/**
+ * An exception class for errors during serialization.
+ */
+class SerializationException implements Exception {
+  final String message;
+  const SerializationException(this.message);
+  String toString() => "SerializationException($message)";
+}