/*
AttributeCoder.cs

 * 12/18/2008 Relo'd from Dave to SVN-controlled utilities project. 
 
$Log: AttributeCoder.cs,v $
Revision 1.1  2006/09/14 18:41:54  Paul Hrissikopoulos
Moved AttributeCoder files from Dave solution.

Revision 1.3  2006/09/07 20:43:08  Paul Hrissikopoulos
Expanded commentary.

Revision 1.2  2006/08/17 23:44:46  Paul Hrissikopoulos
Removed freeloading DCX XML prototype code.

Revision 1.1  2006/08/17 23:05:11  Paul Hrissikopoulos
Added generically-derived SelectionCriterion.ComparisonType enumeration attributes.
  
Copyright © 2006
Diversified Technical Systems
All Rights Reserved
*/

using System;
using System.Collections.Generic;
using System.Diagnostics;
using System.Linq;
using DTS.Common.Utilities.DotNetProgrammingConstructs;
using DTS.Common.Utilities.Properties;

namespace DTS.Common.Utilities
{
    /// <summary>
    /// Object for manipulating object-attached attributes and attribute values.
    /// </summary>
    /// 
    /// <typeparam name="TargetType">
    /// The type of <see cref="object"/> the attributes we are concerned with are
    /// are attached to.
    /// </typeparam>
    /// 
    /// <typeparam name="AttributeType">
    /// The type of attribute to be manipulated.
    /// </typeparam>
    /// 
    /// <typeparam name="AttributeValueType">
    /// The type of value contained by the attribute to be manipulated.
    /// </typeparam>
    ///
    /// <remarks>
    /// This class was created to make it easier to "match" attributes and the data
    /// types they're attached to in a somewhat generic manner.  It is intended that
    /// attribute coder classes that deal with specific attribute types be derived
    /// from this one.
    /// </remarks>
    /// 
    public class AttributeCoder<TargetType, AttributeType, AttributeValueType> : Exceptional
    {
        /// <summary>
        /// Method that specifies how to access the value of a given "AttributeType".
        /// </summary>
        /// 
        /// <param name="attribute">
        /// The "AttributeType" attribute to have its value extracted.
        /// </param>
        /// 
        /// <returns>
        /// The "AttributeValueType" value of the specified attribute.
        /// </returns>
        /// 
        public delegate AttributeValueType AttributeValueExtractionMethod(AttributeType attribute);

        /// <summary>
        /// Method for determining the equality of two "AttributeValueType" values.
        /// </summary>
        /// 
        /// <param name="value1">
        /// A "AttributeValueType" to be equality-compared.
        /// </param>
        /// 
        /// <param name="value2">
        /// A "AttributeValueType" to be equality-compared.
        /// </param>
        /// 
        /// <returns>
        /// True if the two values are equal; false otherwise.
        /// </returns>
        /// 
        public delegate bool AttributeValueEqualityComparisonMethod(AttributeValueType value1, AttributeValueType value2);

        private readonly AttributeValueExtractionMethod _extractAttributeValue;
        private readonly AttributeValueEqualityComparisonMethod _areAttributeValuesEqual;

        /// <summary>
        /// Initializes an instance of the AttributeCoder class.
        /// </summary>
        /// 
        /// <param name="attributeValueExtractionMethod">
        /// A <see cref="AttributeValueExtractionMethod"/> that defines how "AttributeValueType"
        /// values are to be extracted from "AttributeType" attributes.
        /// </param>
        /// 
        /// <param name="attributeValueEqualityComparisonMethod">
        /// Optional parameter for specifying a custom comparison method to override default 
        /// "AttributeValueType" equality determination.  Pass null to use default
        /// comparison.
        /// </param>
        /// 
        public AttributeCoder(AttributeValueExtractionMethod attributeValueExtractionMethod,
                               AttributeValueEqualityComparisonMethod attributeValueEqualityComparisonMethod)
        {
            try
            {
                if (null == attributeValueExtractionMethod)
                    throw new Exception(Resources.AttributeCoder_AttributeCoder_NullAttributeValueExtractionMethodReferenceString);
                _extractAttributeValue = attributeValueExtractionMethod;
                if (null != attributeValueEqualityComparisonMethod)
                    _areAttributeValuesEqual = attributeValueEqualityComparisonMethod;
            }

            catch (System.Exception ex)
            {
                throw new Exception(
                    string.Format(Resources.Generic_EncounteredProblemConstructingClassString, GetType().FullName),
                ex);
            }
        }

        /// <summary>
        /// Return the "AttributeValueType" of the "AttributeType" attribute
        /// attached to the specified "TargetType".
        /// </summary>
        /// 
        /// <param name="target">
        /// The "TargetType" object whose "AttributeType" attribute is to be
        /// evaluated.
        /// </param>
        /// 
        /// <returns>
        /// The "AttributeValueType" of the "AttributeType" attribute attached
        /// to the specified "TargetType".
        /// </returns>
        /// 
        public AttributeValueType DecodeAttributeValue(TargetType target)
        {
            try
            {
                var attributes = DecodeAttributeValues(target);

                if (attributes.Count > 0) return attributes[0];
                throw new Exception(Resources.AttributeCoder_NoTypeAttributesFoundOnTargetString);
            }

            catch (System.Exception ex)
            {
                throw new Exception(Resources.AttributeCoder_DecodeAttributeExceptionString, ex);
            }
        }

        /// <summary>
        /// Return the <see cref="T:List"/> of "AttributeValueType"s of the
        /// "AttributeType" attached to the specified "TargetType".
        /// </summary>
        /// 
        /// <param name="target">
        /// The "TargetType" object whose "AttributeType" attribute is to be
        /// evaluated.
        /// </param>
        /// 
        /// <returns>
        /// The "AttributeValueType" of the "AttributeType" attribute attached
        /// to the specified "TargetType".
        /// </returns>
        /// 
        public List<AttributeValueType> DecodeAttributeValues(TargetType target)
        {
            try
            {
                var info = target.GetType().GetField(target.ToString());
                var attributes = (info.GetCustomAttributes(typeof(AttributeType), false) as AttributeType[]);
                var attributeList = new List<AttributeValueType>();
                if (attributes != null)
                {
                    attributeList.AddRange(attributes.Select(t => _extractAttributeValue(t)));
                }
                return attributeList;
            }
            catch (System.Exception ex)
            {
                throw new Exception(Resources.AttributeCoder_DecodeAttributesExceptionString, ex);
            }
        }

        /// <summary>
        /// Return the "TargetType" value that has the "AttributeType"
        /// attribute with the specified "AttributeValueType" value attached 
        /// to it.
        /// </summary>
        /// 
        /// <param name="attributeValue">
        /// The value of the "AttributeType" attribute attached to the 
        /// "TargetType" target object we're looking for.
        /// </param>
        /// 
        /// <returns>
        /// The "TargetType" target object that has the "AttributeType"
        /// attribute attached to it that has a "AttributeValueType" value of
        /// attributeValue.
        /// </returns>
        /// 
        public TargetType EncodeAttributeValue(AttributeValueType attributeValue)
        {
            try
            {
                var targets = DehashAttributeValue(attributeValue);

                if (1 != targets.Count) throw new Exception(Resources.AttributeCoder_UnableToFindTargetTypeMappingString);
                return targets[0];
            }

            catch (System.Exception ex)
            {
                throw new Exception(Resources.AttributeCoder_EncodeAttributeExceptionString, ex);
            }
        }

        /// <summary>
        /// Return a list of "TargetType" values that have the
        /// "AttributeType" attribute with the specified
        /// "AttributeValueType" value attached to them.
        /// </summary>
        /// 
        /// <param name="attributeValue">
        /// The value of the "AttributeType" attribute attached to the
        /// "TargetType" target object we're looking for.
        /// </param>
        /// 
        /// <returns>
        /// The <see cref="T:List"/> of "TargetType" target objects that has
        /// the "AttributeType" attribute attached to it that has a
        /// "AttributeValueType" value of attributeValue.
        /// </returns>
        /// 
        public List<TargetType> DehashAttributeValue(AttributeValueType attributeValue)
        {
            try
            {
                var targets = Enum.GetValues(typeof(TargetType)).Cast<TargetType>()
                    .Where(target => (null != _areAttributeValuesEqual) ?
                        _areAttributeValuesEqual(DecodeAttributeValue(target), attributeValue) : DecodeAttributeValue(target).Equals(attributeValue)).ToList();
                if (targets.Count <= 0) throw new Exception(Resources.AttributeCoder_DehashAttributeValue_UnableToMatchAttributeValueWithTargetString);
                return targets;
            }

            catch (System.Exception ex)
            {
                throw new Exception(Resources.AttributeCoder_DehashAttributeValue_DehashAttributeValueExceptionString, ex);
            }
        }
    }
}