"The Ceylon serialization infrastructure.
 
 This package provides an API for *serialization libraries* to
 provide their own serialization APIs to client code. It does not 
 provide a serialization service itself.
 
 This API:
 
 * provides a way to walk the graph of instances added for serialization, 
   including those reachable via non-\\\`shared\\\` attributes,
 * copes with shared references and cyclic references in object graphs,
 * prevents access to uninitialized and partially initialized instances 
   during deserialization.  
   (this includes instances reachable from other instances, transitively).
   
 The API cannot prevent serialization libraries from obtaining access to 
 non-\\\`shared\\\` state of instances (loss of encapsulation is 
 an inevitable part of serialization).
 
 A serialization library will implement some kind of 
 serializer and/or deserializer (frequently both) using the facilities 
 of this API.
 
 ## Serializers
 
 A *serializer* takes one or many Ceylon instances and serialize them 
 (and the instances reachable from them) to 
 some external representation, usually bytes or text in some specific format. 
 
 A serializer provided by a serialization library:
 
 * obtains a [[SerializationContext]] by 
   calling [[serialization]],
 * uses [[SerializationContext.references]] to find the references that 
   an instance holds,
 * proceeds to traverse the graph of instances according to 
   library-specific rules
 
 ## Deserializers
 
 A *deserializer* constructs a graph of 
 Ceylon instances according to some external representation.
   
 A deserializer provided by a serialization library:
 
 * obtains a [[DeserializationContext]] by 
   calling [[deserialization]]
 * progressively provides information about instances:
 
     * associates an instance with its 
       [[class|DeserializationContext.instance]],
     * associates a member instance with its [[containing instance|DeserializationContext.memberInstance]],
     * associates a referred instance with its [[referring instance and attribute|DeserializationContext.attribute]],
     * associates a referred instance with its [[referring array index|DeserializationContext.element]],
     * associates an instance with a [[given other instance|DeserializationContext.instanceValue]]. 
       This is useful for instances which refer to singletons 
       (on deserialization the singleton value has to be provided, since it 
       cannot be instantiated by the serialization API).
          
 * once the context has complete information about the instance 
   and every instance reachable from it
   the instance can be 
   [[reconstructed|DeserializationContext.reconstruct]].
  
 ## Serializability
 
 *Serializability* is whether or not a particular serialization library can 
 serialize a particular instance. 
 
 Instances of classes which are annotated [[serializable]] are able to 
 enumerate their state during serialization, 
 and initialize their state during deserialization.
 However, that does not imply that every serialization library 
 can necessarily serialize instances of every `serializable` class.
   
 The serializability of an instance can depend on:
 
 * the class of the instance, and its super classes,
 * the serializability of the outer instance(s), if the object is an 
   instance of a member class. ,
 * the serialization library's support for serializing generic classes, 
   and member classes,
 * the serialization library's support for serializing anonymous objects
   (such as `true`, `null` or `smaller`),
 * the underlying serialization format the serialization library supports
    
 The deserializability of an instance can depend on:
 
 * The runtime availability and compatibility of the class of the instances, 
   and its super classes, for each instance in the object graph. 
"​
​by ("Gavin", "Tom")
​tagged("Serialization")
​since("1.2.0")
​shared package ceylon.language.serialization;
​