Changeset 776 for trunk/sources/HeuristicLab.Core/PersistenceManager.cs

Timestamp:

11/19/08 12:12:39 (16 years ago)

Author:

vdorfer

Message:

Created API documentation for HeuristicLab.Core namespace (#331)

File:

• trunk/sources/HeuristicLab.Core/PersistenceManager.cs (modified) (11 diffs)

trunk/sources/HeuristicLab.Core/PersistenceManager.cs

@@ -29 +29 @@
 
 namespace HeuristicLab.Core {
+  /// <summary>
+  /// Static class for serializing and deserializing objects.
+  /// </summary>
   public static class PersistenceManager {
+    /// <summary>
+    /// Creates an <see cref="XmlDocument"/> to persist an object with xml declaration.
+    /// </summary>
+    /// <returns>The created <see cref="XmlDocument"/>.</returns>
     public static XmlDocument CreateXmlDocument() {
       XmlDocument document = new XmlDocument();
@@ -35 +42 @@
       return document;
     }
+    /// <summary>
+    /// Saves the specified <paramref name="instance"/> in the specified <paramref name="document"/>
+    /// if it has not already been serialized.
+    /// </summary>
+    /// <remarks>The tag name of the saved instance is its type name.<br/>
+    /// The guid is saved as an <see cref="XmlAttribute"/> with tag name <c>GUID</c>.</remarks>
+    /// <param name="instance">The object that should be saved.</param>
+    /// <param name="document">The <see cref="XmlDocument"/> where to save the data.</param>
+    /// <param name="persistedObjects">The dictionary of all already persisted objects. (Needed to avoid cycles.)</param>
+    /// <returns>The saved <see cref="XmlNode"/>.</returns>
     public static XmlNode Persist(IStorable instance, XmlDocument document, IDictionary<Guid, IStorable> persistedObjects) {
       string name = instance.GetType().Name;
@@ -40 +57 @@
       return Persist(name, instance, document, persistedObjects);
     }
+    /// <summary>
+    /// Saves the specified <paramref name="instance"/> in the specified <paramref name="document"/>
+    /// if it has not already been serialized.
+    /// </summary>
+    /// <param name="name">The (tag)name of the <see cref="XmlNode"/>.</param>
+    /// <param name="instance">The object that should be saved.</param>
+    /// <param name="document">The <see cref="XmlDocument"/> where to save the data.</param>
+    /// <param name="persistedObjects">The dictionary of all already persisted objects. (Needed to avoid cycles.)</param>
+    /// <returns>The saved <see cref="XmlNode"/>.</returns>
     public static XmlNode Persist(string name, IStorable instance, XmlDocument document, IDictionary<Guid, IStorable> persistedObjects) {
       if(persistedObjects.ContainsKey(instance.Guid)) {
@@ -53 +79 @@
       }
     }
-    public static IStorable Restore(XmlNode node, IDictionary<Guid, IStorable> restoredObjects) {
+    /// <summary>
+    /// Loads a persisted object from the specified <paramref name="node"/>.
+    /// </summary>
+    /// <remarks>The guid is saved as an attribute with tag name <c>GUID</c>. The type of the 
+    /// persisted object is saved as attribute with tag name <c>Type</c>.<br/>
+    /// Calls <c>instance.Populate</c>.</remarks>
+    /// <param name="node">The <see cref="XmlNode"/> where the object is saved.</param>
+    /// <param name="restoredObjects">A dictionary of all already restored objects. 
+    /// (Needed to avoid cycles.)</param>
+    /// <returns>The loaded object.</returns>
+    public static IStorable Restore(XmlNode node, IDictionary<Guid,IStorable> restoredObjects) {
       Guid guid = new Guid(node.Attributes["GUID"].Value);
       if(restoredObjects.ContainsKey(guid)) {
@@ -65 +101 @@
       }
     }
+    /// <summary>
+    /// Saves the specified <paramref name="instance"/> in the specified file through creating an 
+    /// <see cref="XmlDocument"/>.
+    /// </summary>
+    /// <param name="instance">The object that should be saved.</param>
+    /// <param name="filename">The name of the file where the <paramref name="object"/> should be saved.</param>
     public static void Save(IStorable instance, string filename) {
       using(FileStream stream = File.Create(filename)) {
@@ -71 +113 @@
       }
     }
+    /// <summary>
+    /// Saves the specified <paramref name="instance"/> in the specified <paramref name="stream"/> 
+    /// through creating an <see cref="XmlDocument"/>.
+    /// </summary>
+    /// <param name="instance">The object that should be saved.</param>
+    /// <param name="stream">The (file) stream where the object should be saved.</param>
     public static void Save(IStorable instance, Stream stream) {
       XmlDocument document = PersistenceManager.CreateXmlDocument();
@@ -98 +146 @@
       document.Save(stream);
     }
+    /// <summary>
+    /// Loads an object from a file with the specified <paramref name="filename"/>.
+    /// </summary>
+    /// <remarks>The object must be saved as an <see cref="XmlDocument"/>. <br/>
+    /// Calls <see cref="Restore"/>.</remarks>
+    /// <param name="filename">The filename of the file where the data is saved.</param>
+    /// <returns>The loaded object.</returns>
     public static IStorable Load(string filename) {
       using(FileStream stream = File.OpenRead(filename)) {
@@ -105 +160 @@
       }
     }
+    /// <summary>
+    /// Loads an object from the specified <paramref name="stream"/>.
+    /// </summary>
+    /// <remarks>The object must be saved as an <see cref="XmlDocument"/>. <br/>
+    /// Calls <see cref="Restore"/>.</remarks>
+    /// <param name="stream">The stream from where to load the data.</param>
+    /// <returns>The loaded object.</returns>
     public static IStorable Load(Stream stream) {
       XmlDocument doc = new XmlDocument();
@@ -118 +180 @@
     }
 
+    /// <summary>
+    /// Loads an object from a zip file.
+    /// </summary>
+    /// <param name="serializedStorable">The zip file from where to load as byte array.</param>
+    /// <returns>The loaded object.</returns>
     public static IStorable RestoreFromGZip(byte[] serializedStorable) {
       GZipStream stream = new GZipStream(new MemoryStream(serializedStorable), CompressionMode.Decompress);
@@ -123 +190 @@
     }
 
+    /// <summary>
+    /// Saves the specified <paramref name="storable"/> in a zip file.
+    /// </summary>
+    /// <remarks>Calls <see cref="Save(HeuristicLab.Core.IStorable, Stream)"/>.</remarks>
+    /// <param name="storable">The object to save.</param>
+    /// <returns>The zip stream as byte array.</returns>
     public static byte[] SaveToGZip(IStorable storable) {
       MemoryStream memStream = new MemoryStream();
@@ -131 +204 @@
     }
 
+    /// <summary>
+    /// Builds a meaningful string for the given <paramref name="type"/> with the namespace information, 
+    /// all its arguments, the assembly name...
+    /// </summary>
+    /// <param name="type">The type for which a string should be created.</param>
+    /// <returns>A string value of this type containing different additional information.</returns>
     public static string BuildTypeString(Type type) {
       string assembly = type.Assembly.FullName;