///////////////////////////////////////////////////////////////////////////
// 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
}
}