//******************************************************************************************************//  IAdapter.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://  ----------------------------------------------------------------------------------------------------//  09/02/2010 - J. Ritchie Carroll//       Generated original version of source code.//  12/20/2012 - Starlynn Danyelle Gilliam//       Modified Header.////****************************************************************************************************** using System;using System.Collections.Generic;using System.Data;using System.Linq;using System.Threading; namespace GSF.TimeSeries.Adapters{    /// <summary>    /// Represents the abstract interface for any adapter.    /// </summary>    public interface IAdapter : ISupportLifecycle, IProvideStatus    {        /// <summary>        /// Provides status messages to consumer.        /// </summary>        /// <remarks>        /// <see cref="EventArgs{T}.Argument"/> is new status message.        /// </remarks>        event EventHandler<EventArgs<string>> StatusMessage;         /// <summary>        /// Event is raised when there is an exception encountered while processing.        /// </summary>        /// <remarks>        /// <para>        /// Implementations of this interface are expected to capture any exceptions that might be thrown by        /// user code in any processing to prevent third-party code from causing an unhandled exception        /// in the host.  Errors are reported via this event so host administrators will be aware of the exception.        /// Any needed connection cycle to data adapter should be restarted when an exception is encountered.        /// </para>        /// <para>        /// <see cref="EventArgs{T}.Argument"/> is the exception that was thrown.        /// </para>        /// </remarks>        event EventHandler<EventArgs<Exception>> ProcessException;         /// <summary>        /// Event is raised when <see cref="InputMeasurementKeys"/> are updated.        /// </summary>        event EventHandler InputMeasurementKeysUpdated;         /// <summary>        /// Event is raised when <see cref="OutputMeasurements"/> are updated.        /// </summary>        event EventHandler OutputMeasurementsUpdated;         /// <summary>        /// Event is raised when adapter is aware of a configuration change.        /// </summary>        event EventHandler ConfigurationChanged;         /// <summary>        /// Gets or sets <see cref="DataSet"/> based data source available to <see cref="IAdapter"/>.        /// </summary>        DataSet DataSource        {            get;            set;        }         /// <summary>        /// Gets or sets key/value pair connection information specific to <see cref="IAdapter"/>.        /// </summary>        string ConnectionString        {            get;            set;        }         /// <summary>        /// Gets connection info for adapter, if any.        /// </summary>        /// <remarks>        /// For example, this could return IP or host name of source connection.        /// </remarks>        string ConnectionInfo        {            get;        }         /// <summary>        /// Gets settings <see cref="Dictionary{TKey,TValue}"/> parsed when <see cref="ConnectionString"/> was assigned.        /// </summary>        Dictionary<string, string> Settings        {            get;        }         /// <summary>        /// Gets or sets name of this <see cref="IAdapter"/>.        /// </summary>        new string Name        {            get;            set;        }         /// <summary>        /// Gets or sets the numeric ID associated with this <see cref="IAdapter"/>.        /// </summary>        uint ID        {            get;            set;        }         /// <summary>        /// Gets or sets flag indicating if the adapter has been initialized successfully.        /// </summary>        /// <remarks>        /// Implementers only need to track this value.        /// </remarks>        bool Initialized        {            get;            set;        }         /// <summary>        /// Gets or sets maximum time system will wait during <see cref="Start"/> for initialization.        /// </summary>        /// <remarks>        /// Implementers should use value <see cref="Timeout.Infinite"/> to wait indefinitely.        /// </remarks>        int InitializationTimeout        {            get;            set;        }         /// <summary>        /// Gets or sets flag indicating if adapter should automatically start or connect on demand.        /// </summary>        bool AutoStart        {            get;            set;        }         /// <summary>        /// Gets or sets primary keys of input measurements the adapter expects.        /// </summary>        MeasurementKey[] InputMeasurementKeys        {            get;            set;        }         /// <summary>        /// Gets or sets output measurements that the adapter will produce, if any.        /// </summary>        IMeasurement[] OutputMeasurements        {            get;            set;        }         /// <summary>        /// Gets the total number of measurements processed thus far by the <see cref="IAdapter"/>.        /// </summary>        long ProcessedMeasurements        {            get;        }         /// <summary>        /// Gets the flag indicating if this adapter supports temporal processing.        /// </summary>        bool SupportsTemporalProcessing        {            get;        }         /// <summary>        /// Gets the start time temporal processing constraint defined by call to <see cref="SetTemporalConstraint"/>.        /// </summary>        /// <remarks>        /// This value will be <see cref="DateTime.MinValue"/> when start time constraint is not set - meaning the adapter        /// is processing data in real-time.        /// </remarks>        DateTime StartTimeConstraint        {            get;        }         /// <summary>        /// Gets the stop time temporal processing constraint defined by call to <see cref="SetTemporalConstraint"/>.        /// </summary>        /// <remarks>        /// This value will be <see cref="DateTime.MaxValue"/> when stop time constraint is not set - meaning the adapter        /// is processing data in real-time.        /// </remarks>        DateTime StopTimeConstraint        {            get;        }         /// <summary>        /// Gets or sets the desired processing interval, in milliseconds, for the adapter.        /// </summary>        /// <remarks>        /// With the exception of the values of -1 and 0, this value specifies the desired processing interval for data, i.e.,        /// basically a delay, or timer interval, over which to process data. A value of -1 means to use the default processing        /// interval while a value of 0 means to process data as fast as possible.        /// </remarks>        int ProcessingInterval        {            get;            set;        }         /// <summary>        ///  Starts the adapter, if it is not already running.        /// </summary>        void Start();         /// <summary>        /// Stops the adapter.        /// </summary>        void Stop();         /// <summary>        /// Gets a short one-line adapter status.        /// </summary>        /// <param name="maxLength">Maximum number of available characters for display.</param>        /// <returns>A short one-line summary of the current adapter status.</returns>        string GetShortStatus(int maxLength);         /// <summary>        /// Defines a temporal processing constraint for the adapter.        /// </summary>        /// <param name="startTime">Defines a relative or exact start time for the temporal constraint.</param>        /// <param name="stopTime">Defines a relative or exact stop time for the temporal constraint.</param>        /// <param name="constraintParameters">Defines any temporal parameters related to the constraint.</param>        /// <remarks>        /// <para>        /// This method defines a temporal processing constraint for an adapter, i.e., the start and stop time over which an        /// adapter will process data. Actual implementation of the constraint will be adapter specific. Implementations        /// should be able to dynamically handle multiple calls to this function with new constraints. Passing in <c>null</c>        /// for the <paramref name="startTime"/> and <paramref name="stopTime"/> should cancel the temporal constraint and        /// return the adapter to standard / real-time operation.        /// </para>        /// <para>        /// The <paramref name="startTime"/> and <paramref name="stopTime"/> parameters can be specified in one of the        /// following formats:        /// <list type="table">        ///     <listheader>        ///         <term>Time Format</term>        ///         <description>Format Description</description>        ///     </listheader>        ///     <item>        ///         <term>12-30-2000 23:59:59.033</term>        ///         <description>Absolute date and time.</description>        ///     </item>        ///     <item>        ///         <term>*</term>        ///         <description>Evaluates to <see cref="DateTime.UtcNow"/>.</description>        ///     </item>        ///     <item>        ///         <term>*-20s</term>        ///         <description>Evaluates to 20 seconds before <see cref="DateTime.UtcNow"/>.</description>        ///     </item>        ///     <item>        ///         <term>*-10m</term>        ///         <description>Evaluates to 10 minutes before <see cref="DateTime.UtcNow"/>.</description>        ///     </item>        ///     <item>        ///         <term>*-1h</term>        ///         <description>Evaluates to 1 hour before <see cref="DateTime.UtcNow"/>.</description>        ///     </item>        ///     <item>        ///         <term>*-1d</term>        ///         <description>Evaluates to 1 day before <see cref="DateTime.UtcNow"/>.</description>        ///     </item>        /// </list>        /// </para>        /// </remarks>        void SetTemporalConstraint(string startTime, string stopTime, string constraintParameters);    }     /// <summary>    /// Defines static extension functions for <see cref="IAdapter"/> implementations.    /// </summary>    public static class IAdapterExtensions    {        /// <summary>        /// Returns <c>true</c> if <see cref="IAdapter"/> has a temporal constraint defined, i.e., either        /// <see cref="IAdapter.StartTimeConstraint"/> or <see cref="IAdapter.StopTimeConstraint"/> is not        /// set to its default value.        /// </summary>        /// <param name="adapter"><see cref="IAdapter"/> instance to test.</param>        /// <returns><c>true</c> if <see cref="IAdapter"/> has a temporal constraint defined.</returns>        public static bool TemporalConstraintIsDefined(this IAdapter adapter)        {            return adapter.StartTimeConstraint != DateTime.MinValue || adapter.StopTimeConstraint != DateTime.MaxValue;        }         /// <summary>        /// Returns the <see cref="MeasurementKey"/> values of the <see cref="IAdapter"/> input measurements.        /// </summary>        /// <param name="adapter"><see cref="IAdapter"/> instance input measurements to convert.</param>        /// <returns><see cref="MeasurementKey"/> values of the <see cref="IAdapter"/> input measurements.</returns>        public static MeasurementKey[] InputMeasurementKeys(this IAdapter adapter)        {            return adapter.InputMeasurementKeys ?? new MeasurementKey[0];        }         /// <summary>        /// Returns the <see cref="MeasurementKey"/> values of the <see cref="IAdapter"/> output measurements.        /// </summary>        /// <param name="adapter"><see cref="IAdapter"/> instance output measurements to convert.</param>        /// <returns><see cref="MeasurementKey"/> values of the <see cref="IAdapter"/> output measurements.</returns>        public static MeasurementKey[] OutputMeasurementKeys(this IAdapter adapter)        {            return adapter.OutputMeasurements.MeasurementKeys().ToArray();        }         /// <summary>        /// Gets a distinct list of input measurement keys for all of the provided adapters.        /// </summary>        /// <typeparam name="T">Type of <see cref="IAdapter"/>.</typeparam>        /// <param name="adapters">Source <see cref="IAdapter"/> enumeration.</param>        /// <returns>Distinct list of input measurement keys for all of the provided adapters.</returns>        public static MeasurementKey[] InputMeasurementKeys<T>(this IEnumerable<T> adapters) where T : IAdapter        {            List<MeasurementKey> inputMeasurementKeys = new List<MeasurementKey>();             foreach (T adapter in adapters)            {                MeasurementKey[] adapterInputMeasurementKeys = adapter.InputMeasurementKeys;                 if (adapterInputMeasurementKeys != null && adapterInputMeasurementKeys.Length > 0)                    inputMeasurementKeys.AddRange(adapterInputMeasurementKeys);            }             return inputMeasurementKeys.Distinct().ToArray();        }         /// <summary>        /// Gets a distinct list of output measurement keys for all of the provided adapters.        /// </summary>        /// <typeparam name="T">Type of <see cref="IAdapter"/>.</typeparam>        /// <param name="adapters">Source <see cref="IAdapter"/> enumeration.</param>        /// <returns>Distinct list of output measurement keys for all of the provided adapters.</returns>        public static MeasurementKey[] OutputMeasurementKeys<T>(this IEnumerable<T> adapters) where T : IAdapter        {            List<MeasurementKey> outputMeasurementKeys = new List<MeasurementKey>();             foreach (T adapter in adapters)            {                IEnumerable<MeasurementKey> adapterOutputMeasurementKeys = adapter.OutputMeasurementKeys();                 if ((object)adapterOutputMeasurementKeys != null && adapterOutputMeasurementKeys.Any())                    outputMeasurementKeys.AddRange(adapterOutputMeasurementKeys);            }             return outputMeasurementKeys.Distinct().ToArray();        }    }}