Free cookie consent management tool by TermsFeed Policy Generator

Ignore:
Timestamp:
03/11/10 12:54:14 (14 years ago)
Author:
epitzer
Message:

add complete persistence API docs (#548)

Location:
trunk/sources/HeuristicLab.Persistence/3.3/Core
Files:
17 edited

Legend:

Unmodified
Added
Removed

  • trunk/sources/HeuristicLab.Persistence/3.3/Core/Configuration.cs

    r2994 r3004  
    66namespace HeuristicLab.Persistence.Core {
    77
     8  /// <summary>
     9  /// Defines the set of primitive and composite serializers that are to be used
     10  /// for a certain seraial format. The configuration can be obtained from the
     11  /// <code>ConfigurationService</code>.
     12  /// </summary>
    813  [StorableClass(StorableClassType.MarkedOnly)]   
    914  public class Configuration {

  • trunk/sources/HeuristicLab.Persistence/3.3/Core/ConfigurationService.cs

    r2876 r3004  
    1313namespace HeuristicLab.Persistence.Core {
    1414
     15  /// <summary>
     16  /// Provides a persistable configuration of primitive and composite serializers for
     17  /// all registered serial formats. Custom formats can be defined and will be saved
     18  /// for future sessions. A default configuration can be generated through reflection.
     19  ///
     20  /// This class has only a single instance.
     21  /// </summary>
    1522  public class ConfigurationService {
    1623
    1724    private static ConfigurationService instance;
    1825    private readonly Dictionary<IFormat, Configuration> customConfigurations;
     26
     27    /// <summary>
     28    /// List of all available primitive serializers.
     29    /// </summary>
    1930    public Dictionary<Type, List<IPrimitiveSerializer>> PrimitiveSerializers { get; private set; }
     31
     32    /// <summary>
     33    /// List of all available composite serializers (discovered through reflection).
     34    /// </summary>
    2035    public List<ICompositeSerializer> CompositeSerializers { get; private set; }
     36
     37    /// <summary>
     38    /// List of all available formats (discovered through reflection).   
     39    /// </summary>
    2140    public List<IFormat> Formats { get; private set; }
    2241
    … …  
    92111    }
    93112
     113
     114    /// <summary>
     115    /// Rediscover available serializers and discard all custom configurations.
     116    /// </summary>
    94117    public void Reset() {
    95118      customConfigurations.Clear();
    … …  
    108131    }
    109132
    110     class PriortiySorter : IComparer<ICompositeSerializer> {
     133    private class PriortiySorter : IComparer<ICompositeSerializer> {
    111134      public int Compare(ICompositeSerializer x, ICompositeSerializer y) {
    112135        return y.Priority - x.Priority;
    … …  
    169192    }
    170193
     194    /// <summary>
     195    /// Get the default (automatically discovered) configuration for a certain format.
     196    /// </summary>   
    171197    public Configuration GetDefaultConfig(IFormat format) {
    172198      Dictionary<Type, IPrimitiveSerializer> primitiveConfig = new Dictionary<Type, IPrimitiveSerializer>();
    … …  
    188214    }
    189215
     216
     217    /// <summary>
     218    /// Get a configuration for a certain format. This returns a custom configuration
     219    /// if defined, otherwise returns the default (automatically discovered) configuration.
     220    /// </summary>   
    190221    public Configuration GetConfiguration(IFormat format) {
    191222      if (customConfigurations.ContainsKey(format))
    … …  
    194225    }
    195226
     227    /// <summary>
     228    /// Define a new custom configuration for a ceratin format.
     229    /// </summary>   
    196230    public void DefineConfiguration(Configuration configuration) {
    197231      customConfigurations[configuration.Format] = configuration;

  • trunk/sources/HeuristicLab.Persistence/3.3/Core/DeSerializer.cs

    r2873 r3004  
    99namespace HeuristicLab.Persistence.Core {
    1010
     11  /// <summary>
     12  /// Core hub for deserialization. Reads the serialization token stream,
     13  /// instantiates objects and fills in values.
     14  /// </summary>
    1115  public class Deserializer {
    1216
    13     class Midwife {
     17    /// <summary>
     18    /// Helps in delivering the class instance and acts as proxy while
     19    /// the object cannot yet be instantiate.
     20    /// </summary>
     21    private class Midwife {
    1422
    1523      public int? Id { get; private set; }
    … …  
    5361      }
    5462    }
    55 
     63   
    5664    private readonly Dictionary<int, object> id2obj;
    5765    private readonly Dictionary<Type, object> serializerMapping;
    … …  
    5967    private readonly Dictionary<int, Type> typeIds;
    6068
     69    /// <summary>
     70    /// Instantiates a new deserializer with the given type cache,
     71    /// that contains information about the serializers to use
     72    /// for every type and their type ids.
     73    /// </summary>   
    6174    public Deserializer(
    6275      IEnumerable<TypeMapping> typeCache) {
    … …  
    92105    }
    93106
    94 
     107    /// <summary>
     108    /// Process the token stream and deserialize an instantate a new object graph.
     109    /// </summary>   
    95110    public object Deserialize(IEnumerable<ISerializationToken> tokens) {
    96111      foreach (ISerializationToken token in tokens) {

  • trunk/sources/HeuristicLab.Persistence/3.3/Core/FormatBase.cs

    r2994 r3004  
    44namespace HeuristicLab.Persistence.Interfaces {
    55
     6  /// <summary>
     7  /// Common base class for defining a new serialization format.
     8  /// </summary> 
    69  [StorableClass(StorableClassType.Empty)]
    710  public abstract class FormatBase<SerialDataFormat> : IFormat<SerialDataFormat> where SerialDataFormat : ISerialData {
    8 
     11   
    912    public abstract string Name { get; }
    1013
     14   
     15    /// <summary>
     16    /// Datatype that describes the atoms used for serialization serialization.
     17    /// </summary>
    1118    public Type SerialDataType { get { return typeof(SerialDataFormat); } }
    1219
     20    /// <summary>
     21    /// Compares formats by name.
     22    /// </summary>   
    1323    public bool Equals(FormatBase<SerialDataFormat> f) {
    1424      if (f == null)
    … …  
    1727    }
    1828
     29    /// <summary>
     30    /// Compares foramts by name.
     31    /// </summary>
    1932    public override bool Equals(object obj) {
    2033      FormatBase<SerialDataFormat> f = obj as FormatBase<SerialDataFormat>;

  • trunk/sources/HeuristicLab.Persistence/3.3/Core/GeneratorBase.cs

    r2718 r3004  
    1111namespace HeuristicLab.Persistence.Core {
    1212
     13  /// <summary>
     14  /// Base class for serialization generators. Provides a common entry point
     15  /// <code>Format</code> and dispatches to different abstract methods for
     16  /// every token type.
     17  /// </summary> 
    1318  public abstract class GeneratorBase<T> {
    1419

  • trunk/sources/HeuristicLab.Persistence/3.3/Core/PrimitiveSerializerBase.cs

    r2994 r3004  
    55namespace HeuristicLab.Persistence.Interfaces {
    66
     7  /// <summary>
     8  /// Base class for primitive serializers. These are serializers that map
     9  /// directly to a single datatype and directly produce a serializable object.
     10  /// </summary>
    711  [StorableClass(StorableClassType.Empty)]
    812  public abstract class PrimitiveSerializerBase<Source, SerialData> :

  • trunk/sources/HeuristicLab.Persistence/3.3/Core/Serializer.cs

    r2993 r3004  
    1313namespace HeuristicLab.Persistence.Core {
    1414
     15  /// <summary>
     16  /// The core hub for serialization. This class transforms an object graph
     17  /// into a tree and later into a stream of serialization tokens using
     18  /// the given configuration.
     19  ///
     20  /// <para>Primitive serializers directly format an object to a serializable type.</para>
     21  ///
     22  /// <para>Composite serializers decompose an object into other object that are then
     23  /// recursively serialized.</para> 
     24  ///
     25  /// A constructed serializer is enumerable and continuously analyses
     26  /// and traverses the object graph while the enumerator is iterated
     27  /// </summary> 
    1528  public class Serializer : IEnumerable<ISerializationToken> {
    1629
    17     class ReferenceEqualityComparer : IEqualityComparer<object> {
     30    private class ReferenceEqualityComparer : IEqualityComparer<object> {
    1831
    1932      public new bool Equals(object a, object b) {
    … …  
    3750    private readonly List<Exception> exceptions;
    3851
     52    /// <summary>
     53    /// Contains a mapping of type id to type and serializer.
     54    /// </summary>
    3955    public List<TypeMapping> TypeCache {
    4056      get {
    … …  
    4359      }
    4460    }
    45 
     61   
     62    /// <summary>
     63    /// Contains a list of files (mostly assemblies) that are
     64    /// necessary to deserialize the object graph again.   
     65    /// </summary>
    4666    public List<string> RequiredFiles {
    4767      get {
    … …  
    7696      requiredFiles = new List<string>(files.Keys);
    7797    }
    78 
     98   
    7999    public Serializer(object obj, Configuration configuration) :
    80100      this(obj, configuration, "ROOT") { }
    … …  
    83103      : this(obj, configuration, rootName, false) { }
    84104
     105    /// <param name="isTestRun">Try to complete the whole object graph,
     106    /// don't stop at the first exception</param>
    85107    public Serializer(object obj, Configuration configuration, string rootName, bool isTestRun) {
    86108      this.obj = obj;
    … …  
    106128    }
    107129
    108     public IEnumerator<ISerializationToken> AddExceptionCompiler(IEnumerator<ISerializationToken> enumerator) {
     130    private IEnumerator<ISerializationToken> AddExceptionCompiler(IEnumerator<ISerializationToken> enumerator) {
    109131      while (enumerator.MoveNext())
    110132        yield return enumerator.Current;

  • trunk/sources/HeuristicLab.Persistence/3.3/Core/Tag.cs

    r1623 r3004  
    33namespace HeuristicLab.Persistence.Core {
    44
     5  /// <summary>
     6  /// Vehicle used inside the serialization/deserizalisation process
     7  /// between composite serializers and the core.
     8  /// </summary> 
    59  public class Tag {
    610    public string Name { get; private set; }

  • trunk/sources/HeuristicLab.Persistence/3.3/Core/Tokens/BeginToken.cs

    r1562 r3004  
    33namespace HeuristicLab.Persistence.Core.Tokens {
    44
     5
     6  /// <summary>
     7  /// Marks the beginning of a composite element.
     8  /// </summary>
    59  public class BeginToken : CompositeTokenBase {
    610    public BeginToken(string name, int typeId, int? id) : base(name, typeId, id) { }

  • trunk/sources/HeuristicLab.Persistence/3.3/Core/Tokens/CompositeTokenBase.cs

    r1562 r3004  
    22namespace HeuristicLab.Persistence.Core.Tokens {
    33
     4  /// <summary>
     5  /// Common base class of <code>BeginToken</code> and <code>EndToken</code>
     6  /// that surround a composite element.
     7  /// </summary>
    48  public abstract class CompositeTokenBase : SerializationTokenBase {
    59    public readonly int TypeId;

  • trunk/sources/HeuristicLab.Persistence/3.3/Core/Tokens/EndToken.cs

    r1562 r3004  
    33namespace HeuristicLab.Persistence.Core.Tokens {
    44
     5  /// <summary>
     6  /// Marks the end of a composite element.
     7  /// </summary>
    58  public class EndToken : CompositeTokenBase {
    69    public EndToken(string name, int typeId, int? id) : base(name, typeId, id) { }

  • trunk/sources/HeuristicLab.Persistence/3.3/Core/Tokens/MetaInfoBeginToken.cs

    r1556 r3004  
    22
    33namespace HeuristicLab.Persistence.Core.Tokens {
    4 
     4 
    55  public class MetaInfoBeginToken : ISerializationToken { }
    66

  • trunk/sources/HeuristicLab.Persistence/3.3/Core/Tokens/NulLReferenceToken.cs

    r1566 r3004  
    22
    33namespace HeuristicLab.Persistence.Core.Tokens {
    4 
     4 
    55  public class NullReferenceToken : SerializationTokenBase {
    66    public NullReferenceToken(string name) : base(name) { }

  • trunk/sources/HeuristicLab.Persistence/3.3/Core/Tokens/PrimitiveToken.cs

    r1566 r3004  
    33namespace HeuristicLab.Persistence.Core.Tokens {
    44
     5  /// <summary>
     6  /// Encapsulated the serialization of a single primitive value.
     7  /// </summary>
    58  public class PrimitiveToken : SerializationTokenBase {
    69    public readonly int TypeId;

  • trunk/sources/HeuristicLab.Persistence/3.3/Core/Tokens/ReferenceToken.cs

    r1566 r3004  
    33namespace HeuristicLab.Persistence.Core.Tokens {
    44
     5
     6  /// <summary>
     7  /// References a previously used token (composite or primitive).
     8  /// </summary>
    59  public class ReferenceToken : SerializationTokenBase {
    610    public readonly int Id;

  • trunk/sources/HeuristicLab.Persistence/3.3/Core/Tokens/SerializationTokenBase.cs

    r1615 r3004  
    44
    55namespace HeuristicLab.Persistence.Core.Tokens {
    6 
     6 
    77  public abstract class SerializationTokenBase : ISerializationToken {
    88    public readonly string Name;

  • trunk/sources/HeuristicLab.Persistence/3.3/Core/TypeMapping.cs

    r1623 r3004  
    33namespace HeuristicLab.Persistence.Core {
    44
     5  /// <summary>
     6  /// Association of id, type name and serializer
     7  /// </summary>
    58  public class TypeMapping {
    69
Note: See TracChangeset for help on using the changeset viewer.