= Quick guide: HeuristicLab persistence =

== Invocation ==
If you want to save to a file you are advised to use the //ContentManager// static class of the HeuristicLab.Common namespace. A concrete content manager is set when the //MainForm// is initializing, by default this is the //PersistenceContentManager// in HeuristicLab.Core.

The HeuristicLab persistence can be used directly in case the output should be a stream. Use the classes //XmlGenerator// and //XmlParser// in the HeuristicLab.Persistence.Default.Xml namespace to transform an object graph into XML and read it back again.

== Custom Classes ==
Content types that should be saved and restored have to be decorated with attributes.

 * Add the [StorableClass] attribute to a new class
 * Add the [Storable] attribute to any fields or properties you would like to be persisted 
 * If the default constructor takes longer to initialize, persistence can be directed to use a different constructor by decorating it with the [StorableConstructor] attribute. This constructor has to have a single boolean parameter which will be set to true.

{{{
#!csharp
[Storable]
public class SomeClass : Item {
  [StorableConstructor]
  protected SomeClass(bool deserializing) : base(deserializing) { }
  public SomeClass() {
    // a lot of initialization code that should be skipped during deserialization
  }
}
}}}

If you need more control you can add a [StorableHook] attribute to a parameterless method that will be called after deserialization finishes or before serialization starts.

{{{
#!csharp
[StorableClass]
public class SomeClass {
  [StorableHook(HookType.AfterDeserialization)]
  private void AfterDeserialization() {
    // backwards-compatible code (loading files stored with previous versions)
    // register event handlers
  }
}
}}}

== Support for Other Classes ==
 * An `IPrimitiveSerializer` directly transforms an object and its components into serialized form. This is mainly used for primitive types such as int or float.
 * An `ICompositeSerializer` does not directly transform an object into serialized form but decomposes it into other objects that can then be used to recompose the same object.

== Other Formats ==
You can use the core persistence components to generate other formats. This is done through a stream of serialization tokens. The `Serializer` and `Deserializer` use classes of type `ISerializationToken` to talk to the back end. They describes a hierarchical format of composites that can contain other composites, primitives or references. Additionally, type information is conveyed in type information tokens.