Some fixes to work better with the services framework

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.
 
 /**
  * This provides 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.
  *
  * Setup
  * =====
  * A simple example of usage is
  *
  *      var address = new Address();
  *      address.street = 'N 34th';
  *      address.city = 'Seattle';
  *      var serialization = new Serialization()
  *          ..addRuleFor(address);
  *      String output = serialization.write(address);
  *
  * This creates a new serialization and adds a rule for address objects. Right
  * now it has to be passed an address instance because of limitations using
  * Address as a literal. Then we ask the Serialization to write the address
- * and we get back a String which is a [JSON] representation of the state of
- * it and related objects.
+ * and we get back a Map which is a [json]able representation of the state of
+ * the address and related objects.
  *
  * 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"]);
  *
@@ skipping 62 matching lines @@
  * [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, it will be
+ * 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(fooHolderInstance).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 encoded as a [json] string.
+ * 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 [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
  *
- *      String output = serialization.write(address, new SimpleMapFormat());
+ *      Map output = serialization.write(address, new SimpleMapFormat());
  *      List output = serialization.write(address, new SimpleFlatFormat());
- *      Map output = serialization.write(address, new SimpleJsonFormat());
+ *      var output = serialization.write(address, new SimpleJsonFormat());
  * Or, using a [Writer] explicitly
  *      var writer = serialization.newWriter(new SimpleFlatFormat());
- *      var output = writer.write(address);
+ *      List output = writer.write(address);
  *
  * These representations are not yet considered stable.
  *
  * Reading
  * =======
  * To read objects, the corresponding [read] method can be used.
  *
- *       Address input = serialization.read(aString);
+ *       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 [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
  * [selfDescribing] variable is true by default, but the [SimpleJsonFormat] does
@@ skipping 68 matching lines @@
    */
   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.
     if (_selfDescribing != null) return _selfDescribing;
     return !_rules.any((x) => x is CustomRule);
   }
 
   /**
    * 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.
    */
@@ skipping 89 matching lines @@
   /**
    * 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. If there are objects that need to be resolved
+   * 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.
+   * 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 [externalObjects] map.
+   * values will be looked up in the [namedObjects] map.
    */
-  read(String input, [Map externals = const {}]) {
+  read(input, [Map externals = const {}]) {
     return newReader().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);
 
@@ skipping 95 matching lines @@
 }
 
 /**
  * An exception class for errors during serialization.
  */
 class SerializationException implements Exception {
   final String message;
   const SerializationException([this.message]);
   toString() => "SerializationException($message)";
 }