//****************************************************************************************************** // IsamDataFileBase.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: // ---------------------------------------------------------------------------------------------------- // 03/08/2007 - Pinal C. Patel // Original version of source code generated. // 11/30/2007 - Pinal C. Patel // Modified the "design time" check in EndInit() method to use LicenseManager.UsageMode property // instead of DesignMode property as the former is more accurate than the latter. // 09/19/2008 - J. Ritchie Carroll // Converted to C#. // 10/28/2008 - Pinal C. Patel // Edited code comments. // 12/04/2008 - J. Ritchie Carroll // Modified class an example to use new ISupportBinaryImage. // 05/12/2009 - Pinal C. Patel // Optimized Read() for better memory management by using "yield return". // 05/19/2009 - Pinal C. Patel // Implemented the IProvideStatus interface. // 07/02/2009 - Pinal C. Patel // Modified state alternating properties to reopen the file when changed. // 08/10/2009 - Pinal C. Patel // Modified Write() to write empty intermediate records that are missing to avoid garbage data // for the missing intermediate records when records are being written to disk directly. // 09/14/2009 - Stephen C. Wills // Added new header and license agreement. // 09/16/2009 - Pinal C. Patel // Modified Save() to flush buffered data to disk. // Removed MinimumRecordCount property - not very useful. // 09/17/2009 - Pinal C. Patel // Added exception handling to event handlers. // 12/04/2009 - Pinal C. Patel // Fixed thread synchronization issue in ReadFromDisk(). // 04/07/2011 - Pinal C. Patel // Removed inheritance from Component class to allow for serialization. // 11/23/2011 - J. Ritchie Carroll // Modified to support buffer optimized ISupportBinaryImage. // 12/06/2011 - Pinal C. Patel // Updated to instantiate a FileSystemWatcher object that watches for changes to the file content // only if needed to avoid a issue introduced in .NET 4.0 that causes memory leak. // 12/14/2012 - Starlynn Danyelle Gilliam // Modified Header. // //****************************************************************************************************** using System; using System.Collections.Generic; using System.Configuration; using System.IO; using System.Text; using System.Threading; using System.Timers; using System.Xml.Serialization; using GSF.Configuration; using GSF.Parsing; using Timer = System.Timers.Timer; namespace GSF.IO { ///

/// An abstract class that defines the read/write capabilities for ISAM (Indexed Sequential Access Method) file. ///

/// /// of the records the file contains. This must implement the interface. /// /// /// /// This ISAM implementation keeps all the records in memory, so it may not be suitable for very large files. Since data is stored /// in memory using a list, the maximum number of possible supported records will be 2,147,483,647 (i.e., Int32.MaxValue). /// /// /// See http://en.wikipedia.org/wiki/ISAM for more information on ISAM files. /// /// /// /// This example shows a sample implementation of : ///


    /// using System;
    /// using System.Text;
    /// using GSF;
    /// using GSF.IO;
    /// using GSF.Parsing;
    /// 
    /// class Program
    /// {
    ///     static void Main(string[] args)
    ///     {
    ///         // Create a few test records.
    ///         TestIsamFileRecord r1 = new TestIsamFileRecord(1);
    ///         r1.Name = "TestRecord1";
    ///         r1.Value = double.MinValue;
    ///         r1.Description = "Test record with minimum double value";
    ///         TestIsamFileRecord r2 = new TestIsamFileRecord(2);
    ///         r2.Name = "TestRecord2";
    ///         r2.Value = double.MaxValue;
    ///         r2.Description = "Test record with maximum double value";
    /// 
    ///         // Open ISAM file.
    ///         TestIsamFile testFile = new TestIsamFile();
    ///         testFile.FileName = "TestIsamFile.dat";
    ///         testFile.Open();
    /// 
    ///         // Write test records.
    ///         testFile.Write(r1.Index, r1);
    ///         testFile.Write(r2.Index, r2);
    /// 
    ///         // Read test records.
    ///         Console.WriteLine(testFile.Read(1));
    ///         Console.WriteLine(testFile.Read(2));
    /// 
    ///         // Close ISAM file.
    ///         testFile.Close();
    /// 
    ///         Console.ReadLine();
    ///     }
    /// }
    /// 
    /// class TestIsamFile : IsamDataFileBase<TestIsamFileRecord>
    /// {
    ///     /// 
    ///     /// Size of a single file record.
    ///     /// 
    ///     protected override int GetRecordSize()
    ///     {
    ///         return TestIsamFileRecord.RecordLength;
    ///     }
    /// 
    ///     /// 
    ///     /// Creates a new empty file record.
    ///     /// 
    ///     protected override TestIsamFileRecord CreateNewRecord(int id)
    ///     {
    ///         return new TestIsamFileRecord(id);
    ///     }
    /// }
    /// 
    /// class TestIsamFileRecord : ISupportBinaryImage
    /// {
    ///     private int m_index;
    ///     private string m_name;                  // 20  * 1 =  20
    ///     private double m_value;                 // 1   * 8 =   8
    ///     private string m_description;           // 100 * 1 = 100
    ///     
    ///     public const int RecordLength = 128;    // Total   = 128
    /// 
    ///     public TestIsamFileRecord(int recordIndex)
    ///     {
    ///         m_index = recordIndex;
    ///         
    ///         Name = string.Empty;
    ///         Value = double.NaN;
    ///         Description = string.Empty;
    ///     }
    /// 
    ///     /// 
    ///     /// 1-based index of the record.
    ///     /// 
    ///     public int Index
    ///     {
    ///         get { return m_index; }
    ///     }
    /// 
    ///     /// 
    ///     /// Name of the record.
    ///     /// 
    ///     public string Name
    ///     {
    ///         get { return m_name; }
    ///         set { m_name = value.TruncateRight(20).PadRight(20); }
    ///     }
    /// 
    ///     /// 
    ///     /// Value of the record.
    ///     /// 
    ///     public double Value
    ///     {
    ///         get { return m_value; }
    ///         set { m_value = value; }
    ///     }
    /// 
    ///     /// 
    ///     /// Description of the record.
    ///     /// 
    ///     public string Description
    ///     {
    ///         get { return m_description; }
    ///         set { m_description = value.TruncateRight(100).PadRight(100); }
    ///     }
    /// 
    ///     /// 
    ///     /// Serialized record length.
    ///     /// 
    ///     public int BinaryLength
    ///     {
    ///         get { return RecordLength; }
    ///     }
    /// 
    ///     /// 
    ///     /// Serialized record data.
    ///     /// 
    ///     public byte[] BinaryImage
    ///     {
    ///         get
    ///         {
    ///             // Serialize TestIsamFileRecord into byte array.
    ///             byte[] image = new byte[RecordLength];
    ///             Buffer.BlockCopy(Encoding.ASCII.GetBytes(Name), 0, image, 0, 20);
    ///             Buffer.BlockCopy(BitConverter.GetBytes(Value), 0, image, 20, 8);
    ///             Buffer.BlockCopy(Encoding.ASCII.GetBytes(Description), 0, image, 28, 100);
    /// 
    ///             return image;
    ///         }
    ///     }
    /// 
    ///     /// 
    ///     /// Deserializes the record.
    ///     /// 
    ///     public int Initialize(byte[] binaryImage, int startIndex, int length)
    ///     {
    ///         if (length >= RecordLength)
    ///         {
    ///             // Deserialize byte array into TestIsamFileRecord.
    ///             Name = Encoding.ASCII.GetString(binaryImage, startIndex, 20);
    ///             Value = BitConverter.ToDouble(binaryImage, startIndex + 20);
    ///             Description = Encoding.ASCII.GetString(binaryImage, startIndex + 28, 100);
    ///         }
    ///         else
    ///             throw new InvalidOperationException("Invalid record size, not enough data to deserialize record"); 
    /// 
    ///         return RecordLength;
    ///     }
    /// 
    ///     /// 
    ///     /// String representation of the record.
    ///     /// 
    ///     public override string ToString()
    ///     {
    ///         return string.Format("Name: {0}, Value: {1}, Description: {2}", Name, Value, Description);
    ///     }
    /// }
    ///

/// public abstract class IsamDataFileBase : ISupportLifecycle, IProvideStatus, IPersistSettings where T : ISupportBinaryImage { #region [ Members ] // Constants ///