/*
 * ExceptionalDictionary.cs
 * 
 * Copyright © 2009
 * Diversified Technical Systems, Inc.
 * All Rights Reserved
 */

using System;
using System.Collections.Generic;
using System.Diagnostics;
using System.Linq;
using System.Text;

namespace DTS.Common.Utilities
{
    /// <summary>
    /// Represents a collection of keys and values, with its own exception type.
    /// </summary>
    /// 
    /// <typeparam name="TKey">
    /// The type of the keys in the dictionary.
    /// </typeparam>
    /// 
    /// <typeparam name="TValue">
    /// The type of the values in the dictionary.
    /// </typeparam>
    /// 
    /// <remarks>
    /// Sample usage:
    ///   public class A : ExceptionalDictionary &lt;int, int&gt;
    ///   {
    ///      public void ScrewItUp( )
    ///      {
    ///         private bool error = true;
    ///         if ( error ) throw new A.Exception( "Class A-specific screwup." );
    ///      }
    ///   }
    /// 
    ///   ...
    /// 
    ///   try
    ///   {
    ///     A.ScrewItUp( );
    ///     B.ScrewItUp( );
    ///     C.ScrewItUp( );
    ///   }
    ///   catch ( A.Exception ex )
    ///   {
    ///      // Can pick A's exceptions out of a crowd, or not and just treat it
    ///      // polymorphically as a System.Exception.
    ///   }
    /// </remarks>
    /// 
    [global::System.Serializable]
    public class ExceptionalDictionary<TKey, TValue> : Dictionary<TKey, TValue>
    {
        /// <summary>
        /// Initializes a new instance of the ExceptionalDictionary
        /// class that is empty, has the default initial capacity, and uses the default quality
        /// comparer for the key type.
        /// </summary>
        public ExceptionalDictionary()
            : base()
        {
        }

        /// <summary>
        /// Initializes a new instance of the ExceptionalDictionary
        /// class that is empty, has the specified initial capacity, and uses the default quality
        /// comparer for the key type.
        /// </summary>
        /// 
        /// <param name="capacity">
        /// The initial number of elements that the ExceptionalDictionary
        /// can contain.
        /// </param>
        /// 
        public ExceptionalDictionary(int capacity)
            : base(capacity)
        {
        }

        /// <summary>
        /// Initializes a new instance of the ExceptionalDictionary
        /// class that is empty, has the default initial capacity, and uses the specified quality
        /// comparer for the key type.
        /// </summary>
        /// 
        /// <param name="comparer">
        /// The T:System.Collections.Generic.IEqualityComparer implementation to use when comparaing
        /// keys, or null to use the default T:System.Collections.Generic.IEqualityComparer for the
        /// type of the key.
        /// </param>
        /// 
        public ExceptionalDictionary(IEqualityComparer<TKey> comparer)
            : base(comparer)
        {
        }

        /// <summary>
        /// Initializes a new instance of the ExceptionalDictionary
        /// class initialized to the settings and contents of the specified
        /// System.Collections.Generic.IDictionary-sporting object.
        /// </summary>
        /// 
        /// <param name="dictionary">
        /// The System.Collections.Generic.IDictionary whose elements are copied
        /// to the new ExceptionalDictionary.
        /// </param>
        /// 
        public ExceptionalDictionary(IDictionary<TKey, TValue> dictionary)
            : base(dictionary)
        {
        }

        /// <summary>
        /// Initializes a new instance of the ExceptionalDictionary
        /// class that is empty, has the specified initial capacity, and uses the specified quality
        /// comparer for the key type.
        /// </summary>
        /// 
        /// <param name="capacity">
        /// The initial number of elements that the ExceptionalDictionary
        /// can contain.
        /// </param>
        /// 
        /// <param name="comparer">
        /// The T:System.Collections.Generic.IEqualityComparer implementation to use when comparing
        /// keys, or null to use the default T:System.Collections.Generic.IEqualityComparer for the
        /// type of the key.
        /// </param>
        /// 
        public ExceptionalDictionary(int capacity, IEqualityComparer<TKey> comparer)
            : base(capacity, comparer)
        {
        }

        /// <summary>
        /// Initializes a new instance of the ExceptionalDictionary
        /// class with the specified serialization information and context.
        /// </summary>
        /// 
        /// <param name="info">
        /// A System.Runtime.Serialization.SerializationInfo object containing the information
        /// required to serialize the ExceptionalDictionary.
        /// </param>
        /// 
        /// <param name="context">
        /// A System.Runtime.Serialization.StreamingContext structure containing the source and
        /// destination of the serialized stream associated with the
        /// DTS.UtilitiesExceptionalDictionary.
        /// </param>
        /// 
        public ExceptionalDictionary(System.Runtime.Serialization.SerializationInfo info, System.Runtime.Serialization.StreamingContext context)
            : base(info, context)
        {
        }

        /// <summary>
        /// Initializes a new instance of the ExceptionalDictionary
        /// class with the specified dictionary key/value pairs and the specified comparer implementation.
        /// </summary>
        /// 
        /// <param name="dictionary">
        /// The System.Collections.Generic.IDictionary whose elements are copied to the new
        /// ExceptionalDictionary.
        /// </param>
        /// 
        /// <param name="comparer">
        /// The T:System.Collections.Generic.IEqualityComparer implementation to use when comparing keys, or null to use the default
        /// T:System.Collections.Generic.IEqualityComparer for the type of the key.
        /// </param>
        /// 
        public ExceptionalDictionary(IDictionary<TKey, TValue> dictionary, IEqualityComparer<TKey> comparer)
            : base(dictionary, comparer)
        {
        }

        /// <summary>
        /// A representation of the DerivedClass.Exception class.
        /// </summary>
        public class Exception : ApplicationException
        {
            public Exception() { }
            public Exception(string msg) : base(msg) { }
            public Exception(string msg, System.Exception innerEx) : base(msg, innerEx) { }
            protected Exception(
                System.Runtime.Serialization.SerializationInfo info,
                System.Runtime.Serialization.StreamingContext context) : base(info, context) { }
        }
    }
}