Database Helper Class Library to Ease Database Operation

///////////////////////////////////////////////////////////////////////////
// Copyright 2003-2005 Falcon Soon
//
// Author: Soon Chun Boon
// Date: 05 October 2004
// Description: 
// Class that groups a number of DBRelation instance.
///////////////////////////////////////////////////////////////////////////

using System;
using System.Data;
using System.Collections;
using System.Globalization;

namespace DBHelper
{
	/// <summary>
	/// Class that groups a number of <see cref="DBHelper.DBRelation"/> instances.
	/// </summary>
	public abstract class DBRelationCollection : InternalDataCollectionBase
	{
        /// <summary>
        /// Initialize a new instance of <see cref="DBHelper.DBRelationCollection"/>.
        /// </summary>
        public DBRelationCollection() 
		{           
		}

        #region Collection Adding and Removal Methods
        /// <summary>
        /// Adds a <see cref="DBHelper.DBRelation"/> to <see cref="DBHelper.DBRelationCollection"/>.
        /// </summary>
        /// <param name="objRelation">The <see cref="DBHelper.DBRelation"/> instance to been added
        /// to collection.</param>
        /// <exception cref="System.ArgumentNullException">
        /// The <i>objRelation</i> parameter is null.
        /// </exception>
        /// <exception cref="DBHelper.DataException.CaseLocaleMismatch">
        /// Case sensitivity and locale between parent table and
        /// child table is mismatched.
        /// </exception>
        /// <exception cref="DBHelper.DataException.DuplicateNameException">
        /// The collection already has a relation with the specified name. 
        /// (The comparison is not case sensitive.)
        /// </exception>
        public void Add(DBRelation objRelation)
        {
            this.AddCore(objRelation);
        }

        /// <summary>
        /// Create a new instance of <see cref="DBHelper.DBRelation"/> with the specified parent and
        /// child storage and parent and child column, and adds to collection.
        /// </summary>
        /// <param name="itcParent">The parent storage instance.</param>
        /// <param name="itcChild">The child storage instance.</param>
        /// <param name="colParent">Parent column in relation.</param>
        /// <param name="colChild">Child column in relation.</param>
        /// <returns>The created <see cref="DBHelper.DBRelation"/>.</returns>
        /// <remarks>
        /// Created relation name is empty string.
        /// </remarks>
        /// <exception cref="DBHelper.DataException.CaseLocaleMismatch">
        /// Case sensitivity and locale between parent table and
        /// child table is mismatched.
        /// </exception>
        /// <exception cref="DBHelper.DataException.DuplicateNameException">
        /// The collection already has a relation with the specified name. 
        /// (The comparison is not case sensitive.)
        /// </exception>
        public virtual DBRelation Add(ICommonDBAccess itcParent, ICommonDBAccess itcChild,
            DataColumn colParent, DataColumn colChild)
        {
            DBRelation objRelation = new DBRelation(null, itcParent, itcChild, colParent, colChild);
            this.Add(objRelation);
            return (objRelation);
        }

        /// <summary>
        /// Create a new instance of <see cref="DBHelper.DBRelation"/> with the specified parent and
        /// child storage and parent and child columns, and adds to collection.
        /// </summary>
        /// <param name="itcParent">The parent storage instance.</param>
        /// <param name="itcChild">The child storage instance.</param>
        /// <param name="acolParent">An array of parent columns in relation.</param>
        /// <param name="acolChild">An array of child columns in relation.</param>
        /// <returns>The created <see cref="DBHelper.DBRelation"/>.</returns>
        /// <remarks>
        /// Created relation name is empty string.
        /// </remarks>
        /// <exception cref="DBHelper.DataException.CaseLocaleMismatch">
        /// Case sensitivity and locale between parent table and
        /// child table is mismatched.
        /// </exception>
        /// <exception cref="DBHelper.DataException.DuplicateNameException">
        /// The collection already has a relation with the specified name. 
        /// (The comparison is not case sensitive.)
        /// </exception>
        public virtual DBRelation Add(ICommonDBAccess itcParent, ICommonDBAccess itcChild,
            DataColumn[] acolParent, DataColumn[] acolChild)
        {
            DBRelation objRelation = new DBRelation(null, itcParent, itcChild, acolParent, acolChild);
            this.Add(objRelation);
            return (objRelation);
        }

        /// <summary>
        /// Create a new instance of <see cref="DBHelper.DBRelation"/> with the specified relation name, 
        /// parent and child storage and parent and child column, and adds to collection.
        /// </summary>
        /// <param name="strName">The relation name.</param>
        /// <param name="itcParent">The parent storage instance.</param>
        /// <param name="itcChild">The child storage instance.</param>
        /// <param name="colParent">Parent column in relation.</param>
        /// <param name="colChild">Child column in relation.</param>
        /// <returns>The created <see cref="DBHelper.DBRelation"/>.</returns>
        /// <exception cref="DBHelper.DataException.CaseLocaleMismatch">
        /// Case sensitivity and locale between parent table and
        /// child table is mismatched.
        /// </exception>
        /// <exception cref="DBHelper.DataException.DuplicateNameException">
        /// The collection already has a relation with the specified name. 
        /// (The comparison is not case sensitive.)
        /// </exception>
        public virtual DBRelation Add(string strName, ICommonDBAccess itcParent, ICommonDBAccess itcChild,
            DataColumn colParent, DataColumn colChild)
        {
            DBRelation objRelation = new DBRelation(strName, itcParent, itcChild, colParent, colChild);
            this.Add(objRelation);
            return (objRelation);
        }

        /// <summary>
        /// Create a new instance of <see cref="DBHelper.DBRelation"/> with the specified relation name, 
        /// parent and child storage and parent and child columns, and adds to collection.
        /// </summary>
        /// <param name="strName">The relation name.</param>
        /// <param name="itcParent">The parent storage instance.</param>
        /// <param name="itcChild">The child storage instance.</param>
        /// <param name="acolParent">An array of parent columns in relation.</param>
        /// <param name="acolChild">An array of child columns in relation.</param>
        /// <returns>The created <see cref="DBHelper.DBRelation"/>.</returns>
        /// <exception cref="DBHelper.DataException.CaseLocaleMismatch">
        /// Case sensitivity and locale between parent table and
        /// child table is mismatched.
        /// </exception>
        /// <exception cref="DBHelper.DataException.DuplicateNameException">
        /// The collection already has a relation with the specified name. 
        /// (The comparison is not case sensitive.)
        /// </exception>
        public virtual DBRelation Add(string strName, ICommonDBAccess itcParent, ICommonDBAccess itcChild,
            DataColumn[] acolParent, DataColumn[] acolChild)
        {
            DBRelation objRelation = new DBRelation(strName, itcParent, itcChild, acolParent, acolChild);
            this.Add(objRelation);
            return (objRelation);
        }

        /// <summary>
        /// Create a new instance of <see cref="DBHelper.DBRelation"/> with the specified relation name, 
        /// parent and child storage, parent and child column and value specifies whether to create constraints,
        /// and adds to collection.
        /// </summary>
        /// <param name="strName">The relation name.</param>
        /// <param name="itcParent">The parent storage instance.</param>
        /// <param name="itcChild">The child storage instance.</param>
        /// <param name="colParent">Parent column in relation.</param>
        /// <param name="colChild">Child column in relation.</param>
        /// <param name="bCreateConstraints">True if creates constraints, otherwise False.</param>
        /// <returns>The created <see cref="DBHelper.DBRelation"/>.</returns>
        /// <exception cref="DBHelper.DataException.CaseLocaleMismatch">
        /// Case sensitivity and locale between parent table and
        /// child table is mismatched.
        /// </exception>
        /// <exception cref="DBHelper.DataException.DuplicateNameException">
        /// The collection already has a relation with the specified name. 
        /// (The comparison is not case sensitive.)
        /// </exception>
        public virtual DBRelation Add(string strName, ICommonDBAccess itcParent, ICommonDBAccess itcChild,
            DataColumn colParent, DataColumn colChild, bool bCreateConstraints)
        {
            DBRelation objRelation = new DBRelation(strName, itcParent, itcChild, colParent, colChild, bCreateConstraints);
            this.Add(objRelation);
            return (objRelation);
        }

        /// <summary>
        /// Create a new instance of <see cref="DBHelper.DBRelation"/> with the specified relation name, 
        /// parent and child storage, parent and child columns and value specifies whether to create constraints,
        /// and adds to collection.
        /// </summary>
        /// <param name="strName">The relation name.</param>
        /// <param name="itcParent">The parent storage instance.</param>
        /// <param name="itcChild">The child storage instance.</param>
        /// <param name="acolParent">An array of parent columns in relation.</param>
        /// <param name="acolChild">An array of child columns in relation.</param>
        /// <param name="bCreateConstraints">True if creates constraints, otherwise False.</param>
        /// <returns>The created <see cref="DBHelper.DBRelation"/>.</returns>
        /// <exception cref="DBHelper.DataException.CaseLocaleMismatch">
        /// Case sensitivity and locale between parent table and
        /// child table is mismatched.
        /// </exception>
        /// <exception cref="DBHelper.DataException.DuplicateNameException">
        /// The collection already has a relation with the specified name. 
        /// (The comparison is not case sensitive.)
        /// </exception>
        public virtual DBRelation Add(string strName, ICommonDBAccess itcParent, ICommonDBAccess itcChild,
            DataColumn[] acolParent, DataColumn[] acolChild, bool bCreateConstraints)
        {
            DBRelation objRelation = new DBRelation(strName, itcParent, itcChild, acolParent, acolChild, bCreateConstraints);
            this.Add(objRelation);
            return (objRelation);
        }

        /// <summary>
        /// Performs verification on the relation.
        /// </summary>
        /// <param name="objRelation">The relation to be verified.</param>
        /// <exception cref="System.ArgumentNullException">
        /// <i>objRelation</i> parameter is null.
        /// </exception>
        /// <exception cref="DBHelper.DataException.CaseLocaleMismatch">
        /// The case sensitivity and locale between parent table and
        /// child table is mismatched.
        /// </exception>
        protected virtual void AddCore(DBRelation objRelation)
        {
            if (objRelation == null)
            {
                throw new ArgumentNullException("objRelation");
            }
            objRelation.CheckState();
            if ((objRelation.ChildTable.Locale.LCID != objRelation.ParentTable.Locale.LCID) || 
                (objRelation.ChildTable.CaseSensitive != objRelation.ParentTable.CaseSensitive))
            {
                throw new DataException.CaseLocaleMismatch();
            }
        }

        /// <summary>
        /// Adds an array of <see cref="DBHelper.DBRelation"/> to collection.
        /// </summary>
        /// <param name="aobjRelation">An array of relations.</param>
        public virtual void AddRange(DBRelation[] aobjRelation)
        {
            if (aobjRelation != null)
            {
                DBRelation[] aobjRelation1 = aobjRelation;
                for (int iIndex = 0; iIndex < aobjRelation1.Length; iIndex++)
                {
                    DBRelation objRelation = aobjRelation1[iIndex];
                    if (objRelation != null)
                    {
                        this.Add(objRelation);
                    }
                }
            }
        }

        /// <summary>
        /// Remove a <see cref="DBHelper.DBRelation"/> from collection.
        /// </summary>
        /// <param name="objRelation">The relation to remove.</param>
        /// <exception cref="System.ArgumentNullException">
        /// <i>objRelation</i> parameter is null.
        /// </exception>
        public void Remove(DBRelation objRelation)
        {
            this.RemoveCore(objRelation);
        }

        /// <summary>
        /// Remove a <see cref="DBHelper.DBRelation"/> with the specified name from collection.
        /// </summary>
        /// <param name="strName">The relation name.</param>
        /// <exception cref="DBHelper.DataException.RelationNotInTheCollection">
        /// Relation is not found in collection.
        /// </exception>
        public void Remove(string strName)
        {
            DBRelation objRelation = this[strName];
            if (objRelation == null)
            {
                throw new DataException.RelationNotInTheCollection(strName);
            }

            this.Remove(objRelation);
        }

        /// <summary>
        /// Remove a <see cref="DBHelper.DBRelation"/> with the specified index from collection.
        /// </summary>
        /// <param name="iIndex">The relation index.</param>
        /// <exception cref="DBHelper.DataException.RelationOutOfRange">
        /// The specified index is out of range of collection.
        /// </exception>
        public void RemoveAt(int iIndex)
        {
            DBRelation objRelation = this[iIndex];
            if (objRelation == null)
            {
                throw new DataException.RelationOutOfRange(iIndex);
            }
            this.Remove(objRelation);
        }

        /// <summary>
        /// Verifies the <see cref="DBHelper.DBRelation"/> instance.
        /// </summary>
        /// <param name="objRelation">The relation to verify.</param>
        /// <exception cref="System.ArgumentNullException">
        /// <i>objRelation</i> parameter is null.
        /// </exception>
        protected virtual void RemoveCore(DBRelation objRelation)
        {
            if (objRelation == null)
            {
                throw new ArgumentNullException("objRelation");
            }
        }

        /// <summary>
        /// Clears the collection.
        /// </summary>
        public virtual void Clear()
        {
            this.List.Clear();           
        }
        #endregion

        #region Collection Indexing Methods
        /// <summary>
        /// Get the index of the specified <see cref="DBHelper.DBRelation"/> object.
        /// </summary>
        /// <param name="objRelation">The relation to search for.</param>
        /// <returns>The 0-based index of the relation, or -1 if the relation 
        /// isn't found in the collection.</returns>
        public virtual int IndexOf(DBRelation objRelation)
        {
            int iCount = this.List.Count;
            for (int iIndex = 0; iIndex < iCount; iIndex++)
            {
                if (objRelation == ((DBRelation) this.List[iIndex]))
                {
                    return (iIndex);
                }
            }
            return (-1);
        }

        /// <summary>
        /// Get the index of <see cref="DBHelper.DBRelation"/> with the specified name.
        /// </summary>
        /// <param name="strRelationName">The relation name to search for.</param>
        /// <returns>The 0-based index of the relation, or -1 if the relation 
        /// isn't found in the collection.</returns>
        /// <remarks>
        /// Comparison is case-insensitive.
        /// </remarks>
        public virtual int IndexOf(string strRelationName)
        {
            int iIndex = this.InternalIndexOf(strRelationName);
            if (iIndex >= 0)
            {
                return (iIndex);
            }
            return (-1);
        }

        /// <summary>
        /// Get the index of <see cref="DBHelper.DBRelation"/> with the specified name.
        /// </summary>
        /// <param name="strName">The relation name to search for.</param>
        /// <returns>The 0-based index of the relation, or -1 if the relation 
        /// isn't found in the collection, or -2 if 2 or more relations with the same name
        /// are found. </returns>
        /// <remarks>
        /// Comparison is case-insensitive.
        /// </remarks>
        internal int InternalIndexOf(string strName)
        {
            int iFoundIndex = -1;
            if ((strName == null) || (0 >= strName.Length))
            {
                return (iFoundIndex);
            }
            int iCount = this.List.Count;
            int iSeekIndex = 0;
            for (int iIndex = 0; iIndex < iCount; iIndex++)
            {
                DBRelation objRelation = (DBRelation) this.List[iIndex];
                iSeekIndex = InternalDataComparationBase.NamesEqual(objRelation.RelationName, strName, false, CultureInfo.InvariantCulture);
                if (iSeekIndex == 1) //relation is found (case sensitive)
                {
                    return (iIndex);
                }
                if (iSeekIndex == -1) //relation is found (case insensitive)
                {
                    iFoundIndex = (iFoundIndex == -1) ? iIndex : -2;
                }
            }
            return (iFoundIndex);
        }
        #endregion

        #region Collection Consisting Methods
        /// <summary>
        /// Checks whether collection contains the specified relation name.
        /// </summary>
        /// <param name="strName">The relation name to search for.</param>
        /// <returns>True if collection contains the relation, otherwise False.</returns>
        /// <remarks>
        /// Comparison is case-insensitive.
        /// </remarks>
        public virtual bool Contains(string strName)
        {
            return (this.InternalIndexOf(strName) >= 0);
        }

        /// <summary>
        /// Checks whether the collection contains the specified relation name
        /// with a value specifies the checking is case sensitive or insensitive.
        /// </summary>
        /// <param name="strName">The relation name to search for.</param>
        /// <param name="bCaseSensitive">Value specifies checking is case sensitive or 
        /// insensitive.</param>
        /// <returns>True if collection contains the relation ortherwise False.</returns>
        /// <remarks>
        /// If 2 or more relations with the same name (case insensitive) are found,
        /// False is returned.
        /// </remarks>
        internal bool Contains(string strName, bool bCaseSensitive)
        {
            if (!bCaseSensitive)
            {
                return this.Contains(strName);
            }
            int iIndex = this.InternalIndexOf(strName);
            if (iIndex < 0)
            {
                return false;
            }
            return (strName == ((DBRelation) this.List[iIndex]).RelationName);
        }
        #endregion

        #region Collection Accessing Methods
        /// <summary>
        /// Gets the <see cref="DBHelper.DBRelation"/> object with the specified index.
        /// </summary>
        public abstract DBRelation this[int iIndex] { get; }

        /// <summary>
        /// Gets the <see cref="DBHelper.DBRelation"/> object with the specified relation name.
        /// </summary>
        public abstract DBRelation this[string strName] { get; }

        #endregion
	}
}