|
//------------------------------------------------------------------------------
// <copyright file="ComponentSerializationService.cs" company="Microsoft">
// Copyright (c) Microsoft Corporation. All rights reserved.
// </copyright>
//------------------------------------------------------------------------------
namespace System.ComponentModel.Design.Serialization {
using System.Collections;
using System.ComponentModel;
using System.IO;
using System.Security.Permissions;
/// <devdoc>
/// This class serializes a set of components or serializable objects into a
/// serialization store. The store can then be deserialized at a later
/// date. ComponentSerializationService differs from other serialization
/// schemes in that the serialization format is opaque, and it allows for
/// partial serialization of objects. For example, you can choose to
/// serialize only selected properties for an object.
///
/// This class is abstract. Typically a DesignerLoader will provide a
/// concrete implementation of this class and add it as a service to
/// its DesignSurface. This allows objects to be serialized in the
/// format best suited for them.
/// </devdoc>
[HostProtection(SharedState = true)]
public abstract class ComponentSerializationService
{
/// <devdoc>
/// This method creates a new SerializationStore. The serialization store can
/// be passed to any of the various Serialize methods to build up serialization
/// state for a group of objects.
/// </devdoc>
public abstract SerializationStore CreateStore();
/// <devdoc>
/// This method loads a SerializationStore and from the given
/// stream. This store can then be used to deserialize objects by passing it to
/// the various Deserialize methods.
/// </devdoc>
public abstract SerializationStore LoadStore(Stream stream);
/// <devdoc>
/// This method serializes the given object to the store. The store
/// can be used to serialize more than one object by calling this method
/// more than once.
/// </devdoc>
public abstract void Serialize(SerializationStore store, object value);
/// <devdoc>
/// Normal serialization only serializes values that differ from the component's default state.
/// This provides the most compact serialization mechanism but assumes that during deserilalization
/// a new, freshly created object will be used. If an existing object is used properties that
/// contained default values during serialization would not be reset back to their defaults.
/// The SerializeAbsolute method does not require this assumption on the deserializing end.
/// Instead, it saves data in the serialization store about default values as well so that
/// deserialization can reset non-default properties back to their default values. This is
/// especially true for collection objects, where the collections are either cleared and
/// items re-added, or individual items are removed and added.
/// </devdoc>
public abstract void SerializeAbsolute(SerializationStore store, object value);
/// <devdoc>
/// This method serializes the given member on the given object. This method
/// can be invoked multiple times for the same object to build up a list of
/// serialized members within the serialization store. The member generally
/// has to be a property or an event.
/// </devdoc>
public abstract void SerializeMember(SerializationStore store, object owningObject, MemberDescriptor member);
/// <devdoc>
/// This method serializes the given member on the given object,
/// but also serializes the member if it contains the default value.
/// Note that for some members, containing the default value and setting
/// the same value back to the member are different concepts. For example,
/// if a property inherits its value from a parent object if no local value
/// is set, setting the value back to the property can may not be what is desired.
/// SerializeMemberAbsolute takes this into account and would clear the state of
/// the property in this case.
/// </devdoc>
public abstract void SerializeMemberAbsolute(SerializationStore store, object owningObject, MemberDescriptor member);
/// <devdoc>
/// This method deserializes the given store to produce a collection of
/// objects contained within it. If a container is provided, objects
/// that are created that implement IComponent will be added to the container.
/// </devdoc>
public abstract ICollection Deserialize(SerializationStore store);
/// <devdoc>
/// This method deserializes the given store to produce a collection of
/// objects contained within it. If a container is provided, objects
/// that are created that implement IComponent will be added to the container.
/// </devdoc>
public abstract ICollection Deserialize(SerializationStore store, IContainer container);
/// <devdoc>
/// This method deserializes the given store, but rather than produce
/// new objects, the data in the store is applied to an existing
/// set of objects that are taken from the provided container. This
/// allows the caller to pre-create an object however it sees fit. If
/// an object has deserialization state and the object is not named in
/// the set of existing objects, a new object will be created. If that
/// object also implements IComponent, it will be added to the given
/// container. Objects in the container must have names that
/// match objects in the serialization store in order for an existing
/// object to be used. If validateRecycledTypes is true it is guaranteed
/// that the deserialization will only work if applied to an object of the
/// same type.
/// </devdoc>
public abstract void DeserializeTo(SerializationStore store, IContainer container, bool validateRecycledTypes, bool applyDefaults);
public void DeserializeTo(SerializationStore store, IContainer container) {
DeserializeTo(store, container, true, true);
}
public void DeserializeTo(SerializationStore store, IContainer container, bool validateRecycledTypes) {
DeserializeTo(store, container, validateRecycledTypes, true);
}
}
}
|