//---------------------------------------------------------------------
// <copyright file="IRelatedEnd.cs" company="Microsoft">
//      Copyright (c) Microsoft Corporation.  All rights reserved.
// </copyright>
//
// @owner       mirszy
// @backupOwner sparra
//---------------------------------------------------------------------
using System.Data;
using System.Data.Common;
using System.Data.Common.CommandTrees;
using System.Collections;
using System.Collections.Generic;
using System.Diagnostics;
using System.Data.Metadata.Edm;

namespace System.Data.Objects.DataClasses
{
    /// <summary>
    /// Represents one end of a relationship.
    /// </summary>
    [System.Diagnostics.CodeAnalysis.SuppressMessage("Microsoft.Naming", "CA1710:IdentifiersShouldHaveCorrectSuffix")]
    public interface IRelatedEnd
    {
        // ----------
        // Properties
        // ----------

        /// <summary>
        /// IsLoaded returns true if and only if Load was called.
        /// </summary>
        bool IsLoaded { get;}

        /// <summary>
        /// Name of the relationship in which this IRelatedEnd is participating        
        /// </summary>
        string RelationshipName { get; }

        /// <summary>
        /// Name of the relationship source role used to generate this IRelatedEnd
        /// </summary>
        string SourceRoleName { get; }

        /// <summary>
        /// Name of the relationship target role used to generate this IRelatedEnd
        /// </summary>
        string TargetRoleName { get; }

        /// <summary>
        /// The relationship metadata cooresponding to this IRelatedEnd
        /// </summary>
        RelationshipSet RelationshipSet { get; }

        // -------
        // Methods
        // -------

        /// <summary>
        /// Loads the related entity or entities into the related end using the default merge option
        /// </summary>
        void Load();

        /// <summary>
        /// Loads the related entity or entities into the related end using the specified merge option
        /// </summary>
        void Load(MergeOption mergeOption);

        /// <summary>
        ///   Adds an entity to the related end.  If the owner is
        ///   attached to a cache then the all the connected ends are
        ///   added to the object cache and their corresponding relationships 
        ///   are also added to the ObjectStateManager. The RelatedEnd of the
        ///   relationship is also fixed.
        /// </summary>
        /// <param name="entity">
        ///   Entity instance to add to the related end
        /// </param>
        void Add(IEntityWithRelationships entity);

        /// <summary>
        ///   Adds an entity to the related end.  If the owner is
        ///   attached to a cache then the all the connected ends are
        ///   added to the object cache and their corresponding relationships 
        ///   are also added to the ObjectStateManager. The RelatedEnd of the
        ///   relationship is also fixed.
        /// 
        /// This overload is meant to be used by classes that do not implement IEntityWithRelationships.
        /// </summary>
        /// <param name="entity">
        ///   Entity instance to add to the related end
        /// </param>
        void Add(object entity);

        /// <summary>
        ///   Removes an entity from the related end.  If owner is
        ///   attached to a cache, marks relationship for deletion and if
        ///   the relationship is composition also marks the entity for deletion.
        /// </summary>
        /// <param name="entity">
        ///   Entity instance to remove from the related end
        /// </param>
        /// <returns>Returns true if the entity was successfully removed, false if the entity was not part of the IRelatedEnd.</returns>
        bool Remove(IEntityWithRelationships entity);

        /// <summary>
        ///   Removes an entity from the related end.  If owner is
        ///   attached to a cache, marks relationship for deletion and if
        ///   the relationship is composition also marks the entity for deletion.
        /// 
        /// This overload is meant to be used by classes that do not implement IEntityWithRelationships.
        /// </summary>
        /// <param name="entity">
        ///   Entity instance to remove from the related end
        /// </param>
        /// <returns>Returns true if the entity was successfully removed, false if the entity was not part of the IRelatedEnd.</returns>
        bool Remove(object entity);

        /// <summary>
        /// Attaches an entity to the related end. If the related end is already filled
        /// or partially filled, this merges the existing entities with the given entity. The given
        /// entity is not assumed to be the complete set of related entities.
        /// 
        /// Owner and all entities passed in must be in Unchanged or Modified state. 
        /// Deleted elements are allowed only when the state manager is already tracking the relationship
        /// instance.
        /// </summary>
        /// <param name="entity">The entity to attach to the related end</param>
        /// <exception cref="ArgumentNullException">Thrown when <paramref name="entity"/> is null.</exception>
        /// <exception cref="InvalidOperationException">Thrown when the entity cannot be related via the current relationship end.</exception>
        void Attach(IEntityWithRelationships entity);

        /// <summary>
        /// Attaches an entity to the related end. If the related end is already filled
        /// or partially filled, this merges the existing entities with the given entity. The given
        /// entity is not assumed to be the complete set of related entities.
        /// 
        /// Owner and all entities passed in must be in Unchanged or Modified state. 
        /// Deleted elements are allowed only when the state manager is already tracking the relationship
        /// instance.
        /// 
        /// This overload is meant to be used by classes that do not implement IEntityWithRelationships.
        /// </summary>
        /// <param name="entity">The entity to attach to the related end</param>
        /// <exception cref="ArgumentNullException">Thrown when <paramref name="entity"/> is null.</exception>
        /// <exception cref="InvalidOperationException">Thrown when the entity cannot be related via the current relationship end.</exception>
        void Attach(object entity);

        /// <summary>
        /// This is the query which represents the source of the
        /// related end.  It is constructed on demand using the
        /// _connection and _cache fields and a query string based on
        /// the type of relationship end and the metadata passed into its
        /// constructor.
        /// </summary>
        IEnumerable CreateSourceQuery();

        /// <summary>
        /// Returns an enumerator of all of the values contained within this related end
        /// </summary>        
        IEnumerator GetEnumerator();
    }
}