using System.Collections.Generic;
using Volpe.Cafe.MarketData.BaselineInfo;

namespace Volpe.Cafe.MarketData.Design
{
    /// <summary>
    /// Defines any component family produced by an original equipment manufacturer (OEM), that encapsulates a
    /// description of its engineering characteristics as well as provides an annual historic view of its revisions.
    /// </summary>
    /// <remarks>
    /// OEM component families provide extensions to the <see cref="IOEMProduct"/>s, allowing multiple components (e.g,
    /// platforms, engines, or transmissions) to be "grouped" for the purpose of technology evaluation and inheriting.
    /// Component families include platform families, engine families, and transmission families; however, they <b>may
    /// not</b> be used directly by a vehicle.
    /// </remarks>
    /// <seealso cref="IOEMComponentFamilyInfo"/>
    /// <seealso cref="IOEMComponentFamilyRevision"/>
    public interface IOEMComponentFamily : IOEMProduct, IOEMComponentFamilyInfo
    {
        /// <summary>
        /// Gets a description of baseline engineering characteristics for the <see cref="IOEMComponentFamily"/>.
        /// </summary>
        new BaselineComponentFamily BaselineInfo { get; }

        /// <summary>
        /// Gets a list of components that belong to this family.
        /// </summary>
        IReadOnlyList<IOEMComponent> Components { get; }

        /// <summary>
        /// Gets a list of vehicles that use any of the <see cref="Components"/> that belong to this family.
        /// </summary>
        IReadOnlyList<IVehicle> Vehicles { get; }

        /// <summary>
        /// Removes the specified <paramref name="vehicle"/> from this family.
        /// </summary>
        /// <param name="vehicle">The vehicle to remove.</param>
        /// <param name="analysisYear">
        ///     The model year that was being analyzed when the remove action was triggered.
        /// </param>
        /// <param name="applicationYear">
        ///     The initial model year during which a technology that triggered the remove action was installed on a
        ///     vehicle.
        /// </param>
        void RemoveVehicle(IVehicle vehicle, int analysisYear, int applicationYear);

        /// <summary>
        /// Determines whether the specified <paramref name="component"/> is the leader of this family.
        /// </summary>
        /// <param name="component">The component to search for.</param>
        /// <returns>
        /// true, if the specified <paramref name="component"/> is the leader of this family; false, otherwise.
        /// </returns>
        bool IsLeaderComponent(IOEMComponent component);

        /// <summary>
        /// Returns the leader component of this family.
        /// </summary>
        /// <returns>The leader component of this family.</returns>
        IOEMComponent GetLeaderComponent();

    }
}
