Perspective.cs

Go to the documentation of this file.

using System;
using System.Collections.Concurrent;
using System.Collections.Generic;
using System.Diagnostics;
using System.Linq;
using AnalyzeRe.Utilities;
 
namespace AnalyzeRe
{
    public class Perspective : APIType, IEquatable<Perspective>
    {
        #region Enumerations
        [Flags]
        public enum Base
        {
            LossGross,
            NetLoss,
            ReinstatementPremium,
            ReinstatementBrokerage,
            Premium,
            FixedExpense,
            ProportionalExpense,
            ProfitCommission,
            NoClaimsBonus,
            SlidingScaleCommission,
            LossNetOfAggregateTerms
        }
        #endregion Enumerations
 
        #region Public Static Singletons
        public static readonly Perspective LossGross = new Perspective(Base.LossGross);
 
        public static readonly Perspective NetLoss = new Perspective(Base.NetLoss);
 
        public static readonly Perspective Premium = new Perspective(Base.Premium);
 
        public static readonly Perspective ReinstatementPremium = new Perspective(Base.ReinstatementPremium);
 
        public static readonly Perspective ReinstatementBrokerage = new Perspective(Base.ReinstatementBrokerage);
 
        public static readonly Perspective FixedExpense = new Perspective(Base.FixedExpense);
 
        public static readonly Perspective ProportionalExpense = new Perspective(Base.ProportionalExpense);
 
        public static readonly Perspective ProfitCommission = new Perspective(Base.ProfitCommission);
 
        public static readonly Perspective NoClaimsBonus = new Perspective(Base.NoClaimsBonus);
 
        public static readonly Perspective SlidingScaleCommission = new Perspective(Base.SlidingScaleCommission);
 
        public static readonly Perspective LossNetOfAggregateTerms = new Perspective(Base.LossNetOfAggregateTerms);
        #endregion Public Static Singletons
 
        #region Private Properties
        private readonly string[] _perspectiveSegments;
 
        private readonly Lazy<string> _stringRepresentation;
 
        private readonly Lazy<HashSet<string>> _uniqueElements;
 
        private readonly Lazy<int> _hashCode;
 
        #region Static Caches
        private static readonly IEqualityComparer<HashSet<string>> SetComparer = HashSet<string>.CreateSetComparer();
 
        private static readonly ConcurrentDictionary<string, Perspective> CachedComplexPerspectivesByString =
            new ConcurrentDictionary<string, Perspective>(StringComparer.OrdinalIgnoreCase);
        #endregion Static Caches
        #endregion Private Properties
 
        #region Constructors
        private Perspective(string[] perspectiveSegments)
        {
            if (perspectiveSegments == null || perspectiveSegments.Length == 0)
                throw new ArgumentException("At least one perspective value is required to instantiate a perspective.");
            _perspectiveSegments = perspectiveSegments;
            // The following internal members (once instantiated) will consume additional memory (when compared
            // to computing these values on-the-fly), but have the beneficial trade-off of significantly improving
            // the performance of repeatedly hashing, comparing, and serializing Perspective instances - which
            // is generally expected to be the case when clients are using the provided static singleton instances,
            // but also known to be the case within the Excel Add-In's current request architecture.
            _stringRepresentation = new Lazy<string>(BuildStringRepresentation);
            _uniqueElements = new Lazy<HashSet<string>>(BuildElementHashSet);
            _hashCode = new Lazy<int>(ComputeHashCode);
        }
 
        private Perspective(Base[] perspectiveValues) :
            this(perspectiveValues.Select(Enum<Base>.GetName).ToArray())
        { }
 
        private Perspective(Base perspectiveValue) : this(new[] { Enum<Base>.GetName(perspectiveValue) }) { }
 
        #region Obsolete Public Constructors
        [Obsolete("Use the static Perspective.FromString factory method so that cached immutable Perspectives can be returned.")]
        public Perspective(string perspective) : this(SplitPerspectiveString(perspective).ToArray()) { }
 
        [Obsolete("Use the static Perspective.FromEnums factory method. Perspectives are now built from any combination of Base enum values.")]
        public Perspective(Base perspective_base, IEnumerable<Option> options = null) : this(new[] { perspective_base }
            // Convert the legacy options into their corresponding "Base" enum values.
            .Concat(options?.Select(o => o == Option.Premium ? Base.Premium :
                o == Option.ReinstatementPremium ? Base.ReinstatementPremium :
                Base.ReinstatementBrokerage) ?? Enumerable.Empty<Base>()).ToArray())
        { }
        #endregion Obsolete Public Constructors
        #endregion Constructors
 
        #region Public Static Factories
        public static Perspective FromEnums(params Base[] perspectives) =>
            perspectives != null && perspectives.Length > 0 ?
                // Return the corresponding singleton if there is only a single value.
                perspectives.Length == 1 ? FromEnum(perspectives[0]) :
                // If is a complex perspective of multiple values, create a new Perspective instance
                // TODO: This could benefit from caching, like the FromString factory, but only if we can quickly
                //       hash the incoming array of perspectives. (Compared to the time to instantiate a new Perspective)
                new Perspective(perspectives) :
                // If no values were provided, raise an exception
                throw new ArgumentException("At least one perspective value is required to instantiate a perspective.");
 
        public static Perspective FromEnums(IEnumerable<Base> perspectives) =>
            FromEnums(perspectives?.ToArray() ?? new Base[] { });
 
        public static Perspective FromEnum(Base perspective)
        {
            // Rather than constructing a new perspective instance, we can return
            // one of the existing immutable perspective singletons (for performance)
            switch (perspective)
            {
                case Base.LossGross: return LossGross;
                case Base.NetLoss: return NetLoss;
                case Base.ReinstatementPremium: return ReinstatementPremium;
                case Base.ReinstatementBrokerage: return ReinstatementBrokerage;
                case Base.Premium: return Premium;
                case Base.FixedExpense: return FixedExpense;
                case Base.ProportionalExpense: return ProportionalExpense;
                case Base.ProfitCommission: return ProfitCommission;
                case Base.NoClaimsBonus: return NoClaimsBonus;
                case Base.SlidingScaleCommission: return SlidingScaleCommission;
#pragma warning disable 618
                case Base.LossNetOfAggregateTerms: return LossNetOfAggregateTerms;
#pragma warning restore 618
                default:
                    Debug.WriteLine($"The new perspective {perspective.ToString()} is missing " +
                        "from the enum to singleton converter. This has performance implications.");
                    return new Perspective(perspective);
            }
        }
 
        public static Perspective LossNetOf(params Base[] perspectives) =>
            FromEnums(new[] { Base.NetLoss }.Concat(perspectives).ToArray());
 
        public static Perspective FromString(string perspectiveString)
        {
            return perspectiveString == null ? null :
                // If the string matches a single perspective from the base enumeration,
                // we can use the existing singleton for a big performance boost.
                Enum<Base>.TryParse(perspectiveString, out Base parsed) ? FromEnum(parsed) :
                // For complex perspectives, construct a new instance which will parse the string.
                // Since there are a finite set of possible perspective combinations, and in practice
                // the same combinations are used over and over, users can benefit from a dictionary
                // that caches the immutable instance corresponding to each perspective string.
                CachedComplexPerspectivesByString.GetOrAdd(perspectiveString,
                    newPerspectiveString => new Perspective(SplitPerspectiveString(newPerspectiveString).ToArray()));
        }
 
        public static implicit operator Perspective(string perspectiveString) => FromString(perspectiveString);
 
        public static explicit operator Perspective(Base perspective) => FromEnum(perspective);
        #endregion Public Static Factories
 
        #region Private Methods
        private string BuildStringRepresentation() =>
            _perspectiveSegments.Length == 1 ? _perspectiveSegments[0] : String.Join(",", _perspectiveSegments);
 
        private HashSet<string> BuildElementHashSet() =>
            new HashSet<string>(_perspectiveSegments, StringComparer.OrdinalIgnoreCase);
 
        private int ComputeHashCode() => SetComparer.GetHashCode(_uniqueElements.Value);
 
        private static readonly char[] SplitChars = { ',', '[', ']' };
 
        private static IEnumerable<string> SplitPerspectiveString(string perspectiveString) =>
            perspectiveString.Split(SplitChars, StringSplitOptions.RemoveEmptyEntries)
                // For backwards-compatibility purposes, we must attempt to parse each value with our enumeration
                // (case insensitive), and convert to the proper-case string representation if successful.
                // This is because the server is case-sensitive while historically the C# client has not been.
                // Note that we still use strings as the final internal representation, because we wish to be
                // forward-compatible with newly added perspectives that have not yet been surfaced in C#,
                // hence the fall-back rule to use the string as-is when the Enum.TryParse fails.
                .Select(s => Enum<Base>.TryParse(s, out Base persp) ? Enum<Base>.GetName(persp) : s);
        #endregion Private Methods
 
        #region Overrides
        public override string ToString() => _stringRepresentation.Value;
 
        public override int GetHashCode() => _hashCode.Value;
 
        public bool Equals(Perspective other)
        {
            // First, test for reference equality (should often be true since we use static singletons where possible)
            if (ReferenceEquals(this, other)) return true;
            if (other == null) return false;
            // A fast test is whether the string representations (already built) are equal
            return String.Equals(_stringRepresentation.Value, other._stringRepresentation.Value, StringComparison.Ordinal) ||
                // Failing that, we can only be certain by using our case-insensitive HashSet of perspective components
                SetComparer.Equals(_uniqueElements.Value, other._uniqueElements.Value);
        }
 
        public override bool Equals(object other) =>
            ReferenceEquals(this, other) ||
            other is Perspective persp && Equals(persp) ||
            // Note: The value of comparing other types in this way is questionable since most
            // applications will deny the equivalence of two objects if their types aren't equal
            // and/or reject covariantly incompatible types being compared at compile time.
            // Still, for backwards-compatibility with the previous implementation, we leave this in place.
            other is Base enumValue && Equals(FromEnum(enumValue)) ||
            other is string perspString && Equals(FromString(perspString));
        #endregion Overrides
 
        #region Obsolete
        [Obsolete("Perspectives are now simply built from any combination of Base enum values.")]
        public enum Option
        {
            Premium,
            ReinstatementPremium,
            ReinstatementBrokerage
        }
 
        [Obsolete("A cached string representation can simply be returned by calling ToString()")]
        public static string GetStringRepresentation(Perspective persp) => persp._stringRepresentation.Value;
 
        public static Perspective LossNetOfAggregateTermsAnd(bool premium = false,
            bool reinstatement_premium = false, bool reinstatement_brokerage = false)
        {
            // Use a static singleton if possible.
            if (!premium && !reinstatement_premium && !reinstatement_brokerage)
                return LossNetOfAggregateTerms;
            // No need to continue using the legacy options or constructor, because the internal representation ends up the same
            List<Base> perspectives = new List<Base> { Base.LossNetOfAggregateTerms };
            if (premium) perspectives.Add(Base.Premium);
            if (reinstatement_premium) perspectives.Add(Base.ReinstatementPremium);
            if (reinstatement_brokerage) perspectives.Add(Base.ReinstatementBrokerage);
            return FromEnums(perspectives);
        }
        #endregion Obsolete
    }
}