using System;
using Chernobyl.Event;

namespace Chernobyl.DesignPatterns.Extension
{
    /// <summary>
    /// The base interface for the <see cref="IExtension{TExtended}"/> 
    /// type. This type allows the <see cref="IExtendable"/> to hold onto it's 
    /// extensions regardless of their attachment type.
    /// </summary>
    public interface IExtension : INamed
    {}

    /// <summary>
    /// This interface provides a standardized way to extend the functionality 
    /// of an object dynamically at runtime. In this way, it is similar to the
    /// decorator pattern (see http://en.wikipedia.org/wiki/Decorator_pattern).
    /// However, this interface has several differences from the decorator 
    /// pattern:
    ///     1) It does not require the implementation to derive from the type to 
    ///        be extended. 
    ///     2) It requires that the instance to be extended be passed into a 
    ///        method rather than a constructor.
    ///     3) It allows for the extension to be removed from the instance being
    ///        extended.
    /// </summary>
    /// <typeparam name="TExtended">The type to extend. If the ExtendedType  
    /// is an <see cref="IExtendable"/> type then it is highly recommended that, 
    /// when an instance is extended, the extension add itself to the 
    /// <see cref="IExtendable.Extensions"/> list of the extended instance. When
    /// the instance is un-extended, the extension should remove itself 
    /// from the extensions list of the instance.</typeparam>
    public interface IExtension<TExtended> : IExtension
    {
        /// <summary>
        /// The instance being extended. Setting on instance on this property 
        /// will cause that instance to be extended. If a previous instance was 
        /// already being extended, then this extension will detach itself from 
        /// that instance (stop extending it) and attach itself to the new 
        /// instance (begin extending it). If null is set on this property then 
        /// the previous instance will being extended will no longer be extended 
        /// (if applicable). Note to implementors: it is highly recommended you 
        /// store the extended instance in either a 
        /// <see cref="Chernobyl.WeakReference{ExtendedType}"/> or a 
        /// <see cref="System.WeakReference"/> to allow the extended instance to 
        /// be properly garbage collected.
        /// </summary>
        TExtended Extended { get; set; }

        /// <summary>
        /// An event that is raised right after the instance being extended has 
        /// changed (or whenever the <see cref="Extended"/> property has been 
        /// changed).
        /// </summary>
        event EventHandler<ValueChangedEventArgs<TExtended>> ExtendedChanged;
    }
}