//******************************************************************************************************
//  LogicalParser.cs - Gbtc
//
//  Copyright © 2012, Grid Protection Alliance.  All Rights Reserved.
//
//  Licensed to the Grid Protection Alliance (GPA) under one or more contributor license agreements. See
//  the NOTICE file distributed with this work for additional information regarding copyright ownership.
//  The GPA licenses this file to you under the MIT License (MIT), the "License"; you may
//  not use this file except in compliance with the License. You may obtain a copy of the License at:
//
//      http://www.opensource.org/licenses/MIT
//
//  Unless agreed to in writing, the subject software distributed under the License is distributed on an
//  "AS-IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. Refer to the
//  License for the specific language governing permissions and limitations.
//
//  Code Modification History:
//  ----------------------------------------------------------------------------------------------------
//  05/03/2012 - Stephen C. Wills, Grid Protection Alliance
//       Generated original version of source code.
//  12/17/2012 - Starlynn Danyelle Gilliam
//       Modified Header.
//
//******************************************************************************************************

using System;
using System.Collections.Generic;
using System.ComponentModel;
using System.IO;
using GSF.PQDIF.Physical;

namespace GSF.PQDIF.Logical
{
    /// <summary>
    /// Represents a parser which parses the logical structure of a PQDIF file.
    /// </summary>
    /// <remarks>
    /// <para>
    /// This class makes the data from PQD files readily available to applications and defines several
    /// redundant properties throughout the logical hierarchy of the PQDIF file to also facilitate
    /// the association of definitions with instances within the logical structure. The following
    /// list enumerates some of the more useful associations within the hierarchy.
    /// </para>
    ///
    /// <list type="bullet">
    /// <item><see cref="ObservationRecord.DataSource"/></item>
    /// <item><see cref="ObservationRecord.Settings"/></item>
    /// <item><see cref="SeriesDefinition.ChannelDefinition"/></item>
    /// <item><see cref="ChannelInstance.Definition"/></item>
    /// <item><see cref="SeriesInstance.Definition"/></item>
    /// </list>
    ///
    /// <para>
    /// Usage consists of iterating through observations (<see cref="ObservationRecord"/>) to
    /// examine each of the the measurements recorded in the file. As was noted in the list above,
    /// the data source (<see cref="DataSourceRecord"/>) and settings for the monitor
    /// (<see cref="MonitorSettingsRecord"/>) associated with each observation is exposed as a
    /// property on the observation record. Note that the same data source and monitor settings
    /// records may be referenced by multiple observation records in the file.
    /// </para>
    ///
    /// <para>
    /// The following example demonstrates how to read all observation records from a PQDIF file
    /// using the logical parser.
    /// </para>
    ///
    /// <code><![CDATA[
    /// ContainerRecord containerRecord;
    /// List<ObservationRecord> observationRecords = new List<ObservationRecord>();
    /// string fileName = args[0];
    ///
    /// using (LogicalParser parser = new LogicalParser(fileName))
    /// {
    ///     parser.Open();
    ///     containerRecord = parser.ContainerRecord;
    ///
    ///     while (parser.HasNextObservationRecord())
    ///         observationRecords.Add(parser.NextObservationRecord());
    /// }
    /// ]]></code>
    /// </remarks>
    public class LogicalParser : IDisposable
    {
        #region [ Members ]

        // Fields
        private readonly PhysicalParser m_physicalParser;
        private ContainerRecord m_containerRecord;
        private DataSourceRecord m_currentDataSourceRecord;
        private MonitorSettingsRecord m_currentMonitorSettingsRecord;
        private ObservationRecord m_nextObservationRecord;
        private List<DataSourceRecord> m_allDataSourceRecords;

        #endregion

        #region [ Constructors ]

        /// <summary>
        /// Creates a new instance of the <see cref="LogicalParser"/> class.
        /// </summary>
        /// <param name="filePath">Path to the PQDIF file to be parsed.</param>
        public LogicalParser(string filePath)
        {
            m_physicalParser = new PhysicalParser(filePath);
            m_allDataSourceRecords = new List<DataSourceRecord>();
        }

        /// <summary>
        /// Creates a new instance of the <see cref="LogicalParser"/> class.
        /// </summary>
        /// <param name="stream">The stream containing the PQDIF file data.</param>
        /// <param name="leaveOpen">True if the stream should be closed when the parser is closed; false otherwise.</param>
        /// <exception cref="ArgumentNullException"><paramref name="stream"/> is null.</exception>
        /// <exception cref="InvalidOperationException"><paramref name="stream"/> is not both readable and seekable.</exception>
        public LogicalParser(Stream stream, bool leaveOpen = false)
        {
            m_physicalParser = new PhysicalParser(null);
            m_allDataSourceRecords = new List<DataSourceRecord>();
            Open(stream, leaveOpen);
        }

        #endregion

        #region [ Properties ]

        /// <summary>
        /// Gets or sets the file path (not just the name) of the PQDIF file to be parsed.
        /// Obsolete in favor of <see cref="FilePath"/>.
        /// </summary>
        [Obsolete("Property is deprecated. Please use FilePath instead.")]
        [EditorBrowsable(EditorBrowsableState.Never)]
        public string FileName
        {
            get
            {
                return m_physicalParser.FilePath;
            }
            set
            {
                m_physicalParser.FilePath = value;
            }
        }

        /// <summary>
        /// Gets or sets the file path of the PQDIF file to be parsed.
        /// </summary>
        public string FilePath
        {
            get
            {
                return m_physicalParser.FilePath;
            }
            set
            {
                m_physicalParser.FilePath = value;
            }
        }

        /// <summary>
        /// Gets the container record from the PQDIF file. This is
        /// parsed as soon as the parser is <see cref="Open()"/>ed.
        /// </summary>
        public ContainerRecord ContainerRecord
        {
            get
            {
                return m_containerRecord;
            }
        }

        /// <summary>
        /// Gets a list of all DataSource records from the PQDIF file. This is
        /// parsed when passing throug the observation records <see cref="NextObservationRecord()"/>ed.
        /// </summary>
        public List<DataSourceRecord> DataSourceRecords
        {
            get
            {
                return m_allDataSourceRecords;
            }
        }
        #endregion

        #region [ Methods ]

        /// <summary>
        /// Opens the parser and parses the <see cref="ContainerRecord"/>.
        /// </summary>
        /// <exception cref="InvalidOperationException"><see cref="FilePath"/> has not been defined.</exception>
        /// <exception cref="NotSupportedException">An unsupported compression mode was defined in the PQDIF file.</exception>
        public void Open()
        {
            m_physicalParser.Open();
            m_containerRecord = ContainerRecord.CreateContainerRecord(m_physicalParser.NextRecord());
            m_physicalParser.CompressionAlgorithm = m_containerRecord.CompressionAlgorithm;
            m_physicalParser.CompressionStyle = m_containerRecord.CompressionStyle;
        }

        /// <summary>
        /// Opens the parser and parses the <see cref="ContainerRecord"/>.
        /// </summary>
        /// <param name="stream">The stream containing the PQDIF file data.</param>
        /// <param name="leaveOpen">True if the stream should be closed when the parser is closed; false otherwise.</param>
        /// <exception cref="ArgumentNullException"><paramref name="stream"/> is null.</exception>
        /// <exception cref="InvalidOperationException"><paramref name="stream"/> is not both readable and seekable.</exception>
        /// <exception cref="NotSupportedException">An unsupported compression mode was defined in the PQDIF file.</exception>
        public void Open(Stream stream, bool leaveOpen = false)
        {
            m_physicalParser.Open(stream, leaveOpen);
            m_containerRecord = ContainerRecord.CreateContainerRecord(m_physicalParser.NextRecord());
            m_physicalParser.CompressionAlgorithm = m_containerRecord.CompressionAlgorithm;
            m_physicalParser.CompressionStyle = m_containerRecord.CompressionStyle;
        }

        /// <summary>
        /// Determines whether there are any more
        /// <see cref="ObservationRecord"/>s to be
        /// read from the PQDIF file.
        /// </summary>
        /// <returns>true if there is another observation record to be read from PQDIF file; false otherwise</returns>
        public bool HasNextObservationRecord()
        {
            Record physicalRecord;
            RecordType recordType;

            // Read records from the file until we encounter an observation record or end of file
            while ((object)m_nextObservationRecord == null && m_physicalParser.HasNextRecord())
            {
                physicalRecord = m_physicalParser.NextRecord();
                recordType = physicalRecord.Header.TypeOfRecord;

                switch (recordType)
                {
                    case RecordType.DataSource:
                        // Keep track of the latest data source record in order to associate it with observation records
                        m_currentDataSourceRecord = DataSourceRecord.CreateDataSourceRecord(physicalRecord);
                        m_allDataSourceRecords.Add(m_currentDataSourceRecord);
                        break;

                    case RecordType.MonitorSettings:
                        // Keep track of the latest monitor settings record in order to associate it with observation records
                        m_currentMonitorSettingsRecord = MonitorSettingsRecord.CreateMonitorSettingsRecord(physicalRecord);
                        break;

                    case RecordType.Observation:
                        // Found an observation record!
                        m_nextObservationRecord = ObservationRecord.CreateObservationRecord(physicalRecord, m_currentDataSourceRecord, m_currentMonitorSettingsRecord);
                        break;

                    case RecordType.Container:
                        // The container record is parsed when the file is opened; it should never be encountered here
                        throw new InvalidOperationException("Found more than one container record in PQDIF file.");

                    default:
                        // Ignore unrecognized record types as the rest of the file might be valid.
                        //throw new ArgumentOutOfRangeException(string.Format("Unknown record type: {0}", physicalRecord.Header.RecordTypeTag));
                        break;
                }
            }

            return (object)m_nextObservationRecord != null;
        }

        /// <summary>
        /// Gets the next observation record from the PQDIF file.
        /// </summary>
        /// <returns>The next observation record.</returns>
        public ObservationRecord NextObservationRecord()
        {
            ObservationRecord nextObservationRecord;

            // Call this first to read ahead to the next
            // observation record if we haven't already
            HasNextObservationRecord();

            // We need to set m_nextObservationRecord to null so that
            // subsequent calls to HasNextObservationRecord() will
            // continue to parse new records
            nextObservationRecord = m_nextObservationRecord;
            m_nextObservationRecord = null;

            return nextObservationRecord;
        }

        /// <summary>
        /// Resets the parser to the beginning of the PQDIF file.
        /// </summary>
        public void Reset()
        {
            m_currentDataSourceRecord = null;
            m_currentMonitorSettingsRecord = null;
            m_nextObservationRecord = null;
            m_allDataSourceRecords = new List<DataSourceRecord>();

            m_physicalParser.Reset();
            m_physicalParser.NextRecord(); // skip container record
        }

        /// <summary>
        /// Closes the PQDIF file.
        /// </summary>
        public void Close()
        {
            m_physicalParser.Close();
        }

        /// <summary>
        /// Releases resources held by the parser.
        /// </summary>
        public void Dispose()
        {
            m_physicalParser.Dispose();
        }

        #endregion
    }
}