namespace UVC.Data.Core
{
    /// <summary>
    /// 서로 다른 JSON 데이터 구조 간에 매핑 기능을 제공하는 클래스입니다.
    /// </summary>
    /// <remarks>
    /// ...
    /// 이 클래스는 IDataObject 인터페이스를 구현한 DataObject와 DataArray로 
    /// 데이터를 변환하여 통일된 방식으로 접근할 수 있도록 합니다.
    /// </remarks>
    public interface IDataObject
    {
        /// <summary>
        /// 모든 프로퍼티를 변경된 것으로 표시합니다.
        /// 전체 데이터가 갱신되었을 때 사용합니다.
        /// </summary>
        public void MarkAllAsUpdated();

        /// <summary>
        /// 다른 DataObject와 현재 객체를 비교하여 다른 부분만 설정합니다.
        /// 변경된 키는 자동으로 추적됩니다.
        /// </summary>
        /// <param name="other">비교할 DataObject</param>
        /// <param name="updatedDataOnly">true로 설정하면, 다른 속성만 업데이트합니다. false로 설정하면, 모든 속성을 덮어씁니다.</param>
        public void UpdateDifferent(IDataObject other, bool updatedDataOnly);

        /// <summary>
        /// 업데이트된 속성만 포함하는 새로운 DataObject를 반환합니다.
        /// </summary>
        /// <param name="fromPool">객체 풀에서 복제할지 여부를 지정합니다. 기본값은 true입니다.</param>
        /// <returns>업데이트 된 항목만 가지고 있는 DataObject</returns>
        public IDataObject GetUpdatedObject(bool fromPool = true);

        /// <summary>
        /// 업데이트 된 속성의 수.
        /// </summary>
        /// <returns>업데이트된 속성의 총 개수입니다. 업데이트된 속성이 없으면 0을 반환합니다.</returns>
        public int UpdatedCount { get; }

        /// <summary>
        /// 동일한 상태와 값을 가진 현재 데이터 객체의 새 인스턴스를 생성합니다.
        /// </summary>
        /// <remarks>복제된 객체는 원본 객체와 독립적이므로, 한 객체를 변경해도 다른 객체에는 영향을 미치지 않습니다.
        ///</remarks>
        /// <param name="fromPool">객체 풀에서 복제할지 여부를 지정합니다. 기본값은 true입니다.</param>
        /// <returns>현재 객체의 복사본인 새 <see cref="IDataObject"/> 인스턴스를 반환합니다.</returns>
        public IDataObject Clone(bool fromPool = true);


        /// <summary>
        /// 재사용을 위해 객체를 풀로 반환합니다.
        /// </summary>
        /// <remarks>객체가 더 이상 필요하지 않을 때 이 메서드를 호출하여
        /// 풀에서 재사용할 수 있도록 해야 합니다. 객체를 풀로 반환하기 전에 객체가 유효한 상태인지 확인하십시오.</remarks>
        public void ReturnToPool();

        /// <summary>
        /// 업데이트가 즉시 적용되어야 하는지 여부를 나타냅니다.
        /// </summary>
        /// <returns></returns>
        public bool IsUpdateImmediately { get; set; }

    }
}