//******************************************************************************************************
// MeasurementKey.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.Concurrent;
using System.Data;
using System.Threading;
using GSF.Data;
namespace GSF.TimeSeries
{
///
/// Represents a primary key for a measurement.
///
///
/// In the Static section of this class, all edits to as well as the
/// ConcurrentDictionaries in should occur within a lock on SyncEdits.
///
[Serializable]
public class MeasurementKey
{
#region [ Members ]
// Fields
private readonly Guid m_signalID;
private uint m_id;
private string m_source;
private readonly int m_hashCode;
private readonly int m_runtimeID;
#endregion
#region [ Constructors ]
private MeasurementKey(Guid signalID, uint id, string source)
{
m_signalID = signalID;
m_id = id;
m_source = source;
m_hashCode = base.GetHashCode();
m_runtimeID = Interlocked.Increment(ref s_nextRuntimeID) - 1; //Returns the incremented value. Hints the -1
}
#endregion
#region [ Properties ]
///
/// Gets or sets ID of signal associated with this .
///
public Guid SignalID
{
get
{
return m_signalID;
}
}
///
/// Gets or sets the numeric ID of this .
///
public uint ID
{
get
{
return m_id;
}
}
///
/// Gets or sets the source of this .
///
///
/// This value is typically used to track the archive name in which the measurement, that this represents, is stored.
///
public string Source
{
get
{
return m_source;
}
}
///
/// A unique ID that is assigned at runtime to identify this instance of .
/// This value will change between runtimes, so it cannot be used to compare s
/// that are running out of process or in a separate .
///
///
/// Since each is only tied to a single object,
/// this provides another unique identifier that is zero indexed.
/// This allows certain optimizations such as array lookups.
///
public int RuntimeID
{
get
{
return m_runtimeID;
}
}
#endregion
#region [ Methods ]
///
/// Returns a that represents the current .
///
/// A that represents the current .
public override string ToString()
{
return string.Format("{0}:{1}", m_source, m_id);
}
///
/// Serves as a hash function for the current .
///
/// A hash code for the current .
public override int GetHashCode()
{
return m_hashCode;
}
#endregion
#region [ Static ]
// Static Fields
private static readonly ConcurrentDictionary IDCache = new ConcurrentDictionary();
private static readonly ConcurrentDictionary> KeyCache = new ConcurrentDictionary>(StringComparer.OrdinalIgnoreCase);
private static readonly object SyncEdits = new object();
private static int s_nextRuntimeID = 0;
///
/// Represents an undefined measurement key.
///
public static readonly MeasurementKey Undefined = CreateUndefinedMeasurementKey();
// Static Methods
///
/// Constructs a new given the specified parameters.
///
/// ID of associated signal, if defined.
/// A string representation of the .
/// cannot be empty
/// The value is not in the correct format for a value.
public static MeasurementKey CreateOrUpdate(Guid signalID, string value)
{
string source;
uint id;
if (!TrySplit(value, out source, out id))
throw new FormatException("The value is not in the correct format for a MeasurementKey value");
return CreateOrUpdate(signalID, source, id);
}
///
/// Constructs a new given the specified parameters.
///
/// ID of associated signal, if defined.
/// Source of the measurement that this represents (e.g., name of archive).
/// Numeric ID of the measurement that this represents.
/// cannot be empty.
/// cannot be null.
public static MeasurementKey CreateOrUpdate(Guid signalID, string source, uint id)
{
Func addValueFactory;
Func updateValueFactory;
if (signalID == Guid.Empty)
throw new ArgumentException("Unable to update undefined measurement key", "signalID");
if (string.IsNullOrWhiteSpace(source))
throw new ArgumentNullException("source", "MeasurementKey source cannot be null or empty");
addValueFactory = guid =>
{
// Create a new measurement key and add it to the KeyCache
ConcurrentDictionary idLookup = KeyCache.GetOrAdd(source, s => new ConcurrentDictionary());
return idLookup[id] = new MeasurementKey(guid, id, source);
};
updateValueFactory = (guid, key) =>
{
ConcurrentDictionary idLookup;
// If existing measurement key is exactly the same as the
// one we are trying to create, simply return that key
if (key.ID == id && key.Source == source)
return key;
// Update source and ID and re-insert it into the KeyCache
key.m_source = source;
key.m_id = id;
idLookup = KeyCache.GetOrAdd(source, s => new ConcurrentDictionary());
idLookup[id] = key;
return key;
};
// https://msdn.microsoft.com/en-us/library/ee378675(v=vs.110).aspx
//
// If you call AddOrUpdate simultaneously on different threads,
// addValueFactory may be called multiple times, but its key/value
// pair might not be added to the dictionary for every call.
//
// This lock prevents race conditions that might occur in the addValueFactory that
// could cause different MeasurementKey objects to be written to the KeyCache and IDCache
lock (SyncEdits)
{
return IDCache.AddOrUpdate(signalID, addValueFactory, updateValueFactory);
}
}
///
/// Constructs a new given the specified parameters.
///
/// ID of associated signal, if defined.
/// A string representation of the .
/// The measurement key that was created or updated or .
/// True if the measurement key was successfully created or updated, false otherwise.
/// cannot be empty.
/// Measurement key Source cannot be null.
public static bool TryCreateOrUpdate(Guid signalID, string value, out MeasurementKey key)
{
try
{
key = CreateOrUpdate(signalID, value);
return true;
}
catch
{
key = Undefined;
return false;
}
}
///
/// Constructs a new given the specified parameters.
///
/// ID of associated signal, if defined.
/// Source of the measurement that this represents (e.g., name of archive).
/// Numeric ID of the measurement that this represents.
/// The measurement key that was created or updated or .
/// True if the measurement key was successfully created or updated, false otherwise.
/// cannot be empty.
/// cannot be null.
public static bool TryCreateOrUpdate(Guid signalID, string source, uint id, out MeasurementKey key)
{
try
{
key = CreateOrUpdate(signalID, source, id);
return true;
}
catch
{
key = Undefined;
return false;
}
}
///
/// Looks up the measurement key associated with the given signal ID.
///
/// The signal ID of the measurement key.
/// The measurement key associated with the given signal ID.
///
/// If no measurement key is found with the given signal ID,
/// this method returns .
///
public static MeasurementKey LookUpBySignalID(Guid signalID)
{
MeasurementKey key;
if (signalID == Guid.Empty)
key = Undefined;
else if (!IDCache.TryGetValue(signalID, out key))
key = Undefined;
return key;
}
///
/// Looks up the measurement key associated with the given source and ID.
///
/// The source of the signal.
/// The source-specific unique integer identifier.
/// The measurement key associated with the given source and ID.
///
/// If no measurement key is found with the given source and ID,
/// this method returns .
///
public static MeasurementKey LookUpBySource(string source, uint id)
{
ConcurrentDictionary idLookup;
MeasurementKey key;
if (!KeyCache.TryGetValue(source, out idLookup))
return Undefined;
if (!idLookup.TryGetValue(id, out key))
return Undefined;
return key;
}
///
/// Performs a lookup by signal ID and, failing that, attempts to create
/// the key using the given signal ID and the parsed source, and ID.
///
/// The signal ID of the key to be looked up.
/// A string representation of the .
///
/// If the lookup succeeds, an existing measurement key with a matching signalID.
/// If creation succeeds, a new measurement key with matching signal ID, source, and ID.
/// Otherwise, .
///
public static MeasurementKey LookUpOrCreate(Guid signalID, string value)
{
string source;
uint id;
if (!TrySplit(value, out source, out id))
return LookUpOrCreate(signalID, Undefined.Source, Undefined.ID);
return LookUpOrCreate(signalID, source, id);
}
///
/// Performs a lookup by signal ID and, failing that, attempts to
/// create the key using the given signal ID, source, and ID.
///
/// The signal ID of the key to be looked up.
/// The source to use for the key if the lookup fails.
/// The ID to use for the key if the lookup fails.
///
/// If the lookup succeeds, an existing measurement key with a matching signalID.
/// If creation succeeds, a new measurement key with matching signal ID, source, and ID.
/// Otherwise, .
///
public static MeasurementKey LookUpOrCreate(Guid signalID, string source, uint id)
{
MeasurementKey key = LookUpBySignalID(signalID);
if (key == Undefined && !TryCreateOrUpdate(signalID, source, id, out key))
return Undefined;
return key;
}
///
/// Performs a lookup by source and, failing that, attempts to create
/// the key using a newly generated signal ID and the parsed source and ID.
///
/// A string representation of the .
///
/// If the lookup succeeds, an existing measurement key with a matching signalID.
/// If creation succeeds, a new measurement key with matching signal ID, source, and ID.
/// Otherwise, .
///
public static MeasurementKey LookUpOrCreate(string value)
{
string source;
uint id;
if (!TrySplit(value, out source, out id))
return Undefined;
return LookUpOrCreate(source, id);
}
///
/// Performs a lookup by source and, failing that, attempts to create
/// the key using a newly generated signal ID and the given source and ID.
///
/// The source to use for the key if the lookup fails.
/// The ID to use for the key if the lookup fails.
///
/// If the lookup succeeds, an existing measurement key with a matching signalID.
/// If creation succeeds, a new measurement key with matching signal ID, source, and ID.
/// Otherwise, .
///
public static MeasurementKey LookUpOrCreate(string source, uint id)
{
MeasurementKey key = LookUpBySource(source, id);
if (key == Undefined && !TryCreateOrUpdate(Guid.NewGuid(), source, id, out key))
return Undefined;
return key;
}
///
/// Converts the string representation of a into its value equivalent.
///
/// A string representing the to convert.
/// A value equivalent the representation contained in .
/// The value is not in the correct format for a value.
public static MeasurementKey Parse(string value)
{
MeasurementKey key;
if (TryParse(value, out key))
return key;
throw new FormatException("The value is not in the correct format for a MeasurementKey value");
}
///
/// Attempts to convert the string representation of a into its value equivalent.
///
/// A string representing the to convert.
/// Output in which to stored parsed value.
/// A true if representation contained in could be parsed; otherwise false.
public static bool TryParse(string value, out MeasurementKey key)
{
string source;
uint id;
// Split the input into source and ID
if (TrySplit(value, out source, out id))
{
// First attempt to look up an existing key
key = LookUpBySource(source, id);
if (key == Undefined)
{
try
{
// Lookup failed - attempt to create it with a newly generated signal ID
key = CreateOrUpdate(Guid.NewGuid(), source, id);
}
catch
{
// source is null or empty
key = Undefined;
}
}
}
else
{
// Incorrect format for a measurement key
key = Undefined;
}
return (key != Undefined);
}
///
/// Establish default cache.
///
/// The database connection.
/// The database adapter type.
/// Measurement table name used to load measurement key cache.
///
/// Source tables are expected to have at least the following fields:
///
/// ID NVARCHAR Measurement key formatted as: ArchiveSource:PointID
/// SignalID GUID Unique identification for measurement
///
///
public static void EstablishDefaultCache(IDbConnection connection, Type adapterType, string measurementTable = "ActiveMeasurement")
{
string source;
uint id;
// Establish default measurement key cache
foreach (DataRow measurement in connection.RetrieveData(adapterType, string.Format("SELECT ID, SignalID FROM {0}", measurementTable)).Rows)
{
if (TrySplit(measurement["ID"].ToString(), out source, out id))
CreateOrUpdate(measurement["SignalID"].ToNonNullString(Guid.Empty.ToString()).ConvertToType(), source, id);
}
}
///
/// Creates the undefined measurement key. Used to initialize .
///
private static MeasurementKey CreateUndefinedMeasurementKey()
{
MeasurementKey key = new MeasurementKey(Guid.Empty, uint.MaxValue, "__");
//Note. No lock on SyncEdit is required since this method is only called by the static constructor.
KeyCache.GetOrAdd(key.Source, kcf => new ConcurrentDictionary())[uint.MaxValue] = key;
return key;
}
///
/// Attempts to split the given string representation
/// of a measurement key into a source and ID pair.
///
private static bool TrySplit(string value, out string source, out uint id)
{
string[] elem;
if (!string.IsNullOrEmpty(value))
{
elem = value.Split(':');
if (elem.Length == 2 && uint.TryParse(elem[1].Trim(), out id))
{
source = elem[0].Trim();
return true;
}
}
source = Undefined.Source;
id = Undefined.ID;
return false;
}
#endregion
}
}