Changes between Version 3 and Version 4 of Documentation/DevelopmentCenter/UsePersistence

Timestamp:

06/26/14 20:18:06 (10 years ago)

Author:

abeham

Comment:

--

Documentation/DevelopmentCenter/UsePersistence

@@ -1 @@
-= HeuristicLab Persistence Quick Start Guide =
+= Quick guide: HeuristicLab persistence =
 
 == Invocation ==
-Use the classes `XmlGenerator` and `XmlParser` to transform an object graph into XML and read it back again. You can serialize into a file that is essentially a ZIP file with two entries or directly to a stream.
+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 ==
- * Add the `[StorableClass]` attribute to your class
- * Add the `[Storable]` attribute to any fields or properties you would like to be persisted 
- * Choose a constructor that is available to the persistence:
-   * Either a default constructor with no arguments (can be private)
-   * Or a `[StorableConstructor]` with a single bool argument (e.g. `isDeserializing`) that is set to true when invoked by the persistence
+Content types that should be saved and restored have to be decorated with attributes.
 
-If you need more logic you can add a `[PersistenceHook]` attribute to parameterless methods that will be called before serialization starts or after serialization finishes for an object.
+ * 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 ==