//---------------------------------------------------------------------
// <copyright file="ObjectParameterCollection.cs" company="Microsoft">
// Copyright (c) Microsoft Corporation. All rights reserved.
// </copyright>
//
// @owner Microsoft
// @backupowner Microsoft
//---------------------------------------------------------------------
namespace System.Data.Objects
{
using System;
using System.Collections;
using System.Collections.Generic;
using System.Data;
using System.Data.Entity;
using System.Data.Metadata.Edm;
using System.Text;
/// <summary>
/// This class represents a collection of query parameters at the object layer.
/// </summary>
public sealed class ObjectParameterCollection : ICollection<ObjectParameter>
{
// Note: There are NO public constructors for this class - it is for internal
// ObjectQuery<T> use only, but must be public so that an instance thereof can be
// a public property on ObjectQuery<T>.
#region Internal Constructors
// ---------------------
// Internal Constructors
// ---------------------
#region ObjectParameterCollection (ClrPerspective)
/// <summary>
/// This internal constructor creates a new query parameter collection and
/// initializes the internal parameter storage.
/// </summary>
internal ObjectParameterCollection(ClrPerspective perspective)
{
EntityUtil.CheckArgumentNull(perspective, "perspective");
// The perspective is required to do type-checking on parameters as they
// are added to the collection.
this._perspective = perspective;
// Create a new list to store the parameters.
_parameters = new List<ObjectParameter>();
}
#endregion
#endregion
#region Private Fields
// --------------
// Private Fields
// --------------
/// <summary>
/// Can parameters be added or removed from this collection?
/// </summary>
private bool _locked;
/// <summary>
/// The internal storage for the query parameters in the collection.
/// </summary>
private List<ObjectParameter> _parameters;
/// <summary>
/// A CLR perspective necessary to do type-checking on parameters as they
/// are added to the collection.
/// </summary>
private ClrPerspective _perspective;
/// <summary>
/// A string that can be used to represent the current state of this parameter collection in an ObjectQuery cache key.
/// </summary>
private string _cacheKey;
#endregion
#region Public Properties
// -----------------
// Public Properties
// -----------------
/// <summary>
/// The number of parameters currently in the collection.
/// </summary>
public int Count
{
get
{
return this._parameters.Count;
}
}
/// <summary>
/// This collection is read-write - parameters may be added, removed
/// and [somewhat] modified at will (value only) - provided that the
/// implementation the collection belongs to has not locked its parameters
/// because it's command definition has been prepared.
/// </summary>
bool ICollection<ObjectParameter>.IsReadOnly
{
get
{
return (this._locked);
}
}
#endregion
#region Public Indexers
// ---------------
// Public Indexers
// ---------------
/// <summary>
/// This indexer allows callers to retrieve parameters by name. If no
/// parameter by the given name exists, an exception is thrown. For
/// safe existence-checking, use the Contains method instead.
/// </summary>
/// <param name="name">
/// The name of the parameter to find.
/// </param>
/// <returns>
/// The parameter object with the specified name.
/// </returns>
/// <exception cref="ArgumentOutOfRangeException">
/// If no parameter with the specified name is found in the collection.
/// </exception>
public ObjectParameter this[string name]
{
get
{
int index = this.IndexOf(name);
if (index == -1)
{
throw EntityUtil.ArgumentOutOfRange(System.Data.Entity.Strings.ObjectParameterCollection_ParameterNameNotFound(name), "name");
}
return this._parameters[index];
}
}
#endregion
#region Public Methods
// --------------
// Public Methods
// --------------
#region Add
/// <summary>
/// This method adds the specified parameter object to the collection. If
/// the parameter object already exists in the collection, an exception is
/// thrown.
/// </summary>
/// <param name="parameter">
/// The parameter object to add to the collection.
/// </param>
/// <returns></returns>
/// <exception cref="ArgumentNullException">
/// If the value of the parameter argument is null.
/// </exception>
/// <exception cref="ArgumentException">
/// If the parameter argument already exists in the collection. This
/// behavior differs from that of most collections which allow duplicate
/// entries.
/// </exception>
/// <exception cref="ArgumentException">
/// If another parameter with the same name as the parameter argument
/// already exists in the collection. Note that the lookup is case-
/// insensitive. This behavior differs from that of most collections,
/// and is more like that of a Dictionary.
/// </exception>
/// <exception cref="ArgumentOutOfRangeException">
/// If the type of the specified parameter is invalid.
/// </exception>
public void Add (ObjectParameter parameter)
{
EntityUtil.CheckArgumentNull(parameter, "parameter");
CheckUnlocked();
if (this.Contains(parameter))
{
throw EntityUtil.Argument(System.Data.Entity.Strings.ObjectParameterCollection_ParameterAlreadyExists(parameter.Name), "parameter");
}
if (this.Contains(parameter.Name))
{
throw EntityUtil.Argument(System.Data.Entity.Strings.ObjectParameterCollection_DuplicateParameterName(parameter.Name), "parameter");
}
if (!parameter.ValidateParameterType(this._perspective))
{
throw EntityUtil.ArgumentOutOfRange(System.Data.Entity.Strings.ObjectParameter_InvalidParameterType(parameter.ParameterType.FullName), "parameter");
}
this._parameters.Add(parameter);
this._cacheKey = null;
}
#endregion
#region Clear
/// <summary>
/// This method empties the entire parameter collection.
/// </summary>
/// <returns></returns>
public void Clear()
{
CheckUnlocked();
this._parameters.Clear();
this._cacheKey = null;
}
#endregion
#region Contains (ObjectParameter)
/// <summary>
/// This methods checks for the existence of a given parameter object in the
/// collection by reference.
/// </summary>
/// <param name="parameter">
/// The parameter object to look for in the collection.
/// </param>
/// <returns>
/// True if the parameter object was found in the collection, false otherwise.
/// Note that this is a reference-based lookup, which means that if the para-
/// meter argument has the same name as a parameter object in the collection,
/// this method will only return true if it's the same object.
/// </returns>
/// <exception cref="ArgumentNullException">
/// If the value of the parameter argument is null.
/// </exception>
public bool Contains (ObjectParameter parameter)
{
EntityUtil.CheckArgumentNull(parameter, "parameter");
return this._parameters.Contains(parameter);
}
#endregion
#region Contains (string)
/// <summary>
/// This method checks for the existence of a given parameter in the collection
/// by name.
/// </summary>
/// <param name="name">
/// The name of the parameter to look for in the collection.
/// </param>
/// <returns>
/// True if a parameter with the specified name was found in the collection,
/// false otherwise. Note that the lookup is case-insensitive.
/// </returns>
/// <exception cref="ArgumentNullException">
/// If the value of the parameter argument is null.
/// </exception>
public bool Contains (string name)
{
EntityUtil.CheckArgumentNull(name, "name");
if (this.IndexOf(name) != -1)
{
return true;
}
return false;
}
#endregion
#region CopyTo
/// <summary>
/// This method allows the parameters in the collection to be copied into a
/// supplied array, beginning at the specified index therein.
/// </summary>
/// <param name="array">
/// The array into which to copy the parameters.
/// </param>
/// <param name="index">
/// The index in the array at which to start copying the parameters.
/// </param>
/// <returns></returns>
public void CopyTo (ObjectParameter[] array, int index)
{
this._parameters.CopyTo(array, index);
}
#endregion
#region Remove
/// <summary>
/// This method removes an instance of a parameter from the collection by
/// reference if it exists in the collection. To remove a parameter by name,
/// first use the Contains(name) method or this[name] indexer to retrieve
/// the parameter instance, then remove it using this method.
/// </summary>
/// <param name="parameter">
/// The parameter object to remove from the collection.
/// </param>
/// <returns>
/// True if the parameter object was found and removed from the collection,
/// false otherwise. Note that this is a reference-based lookup, which means
/// that if the parameter argument has the same name as a parameter object
/// in the collection, this method will remove it only if it's the same object.
/// </returns>
/// <exception cref="ArgumentNullException">
/// If the value of the parameter argument is null.
/// </exception>
public bool Remove (ObjectParameter parameter)
{
EntityUtil.CheckArgumentNull(parameter, "parameter");
CheckUnlocked();
bool removed = this._parameters.Remove(parameter);
// If the specified parameter was found in the collection and removed,
// clear out the cached string representation of this parameter collection
// so that the next call to GetCacheKey (if any) will regenerate it based on
// the new state of this collection.
if (removed)
{
this._cacheKey = null;
}
return removed;
}
#endregion
#region GetEnumerator
/// <summary>
/// These methods return enumerator instances, which allow the collection to
/// be iterated through and traversed.
/// </summary>
IEnumerator<ObjectParameter> IEnumerable<ObjectParameter>.GetEnumerator()
{
return ((System.Collections.Generic.ICollection<ObjectParameter>)this._parameters).GetEnumerator();
}
IEnumerator IEnumerable.GetEnumerator()
{
return ((System.Collections.ICollection)this._parameters).GetEnumerator();
}
#endregion
#endregion
#region Internal Methods
// ---------------
// Internal Methods
// ---------------
/// <summary>
/// Retrieves a string that may be used to represent this parameter collection in an ObjectQuery cache key.
/// If this collection has not changed since the last call to this method, the same string instance is returned.
/// Note that this string is used by various ObjectQueryImplementations to version the parameter collection.
/// </summary>
/// <returns>A string that may be used to represent this parameter collection in an ObjectQuery cache key.</returns>
internal string GetCacheKey()
{
if (null == this._cacheKey)
{
if(this._parameters.Count > 0)
{
// Future Enhancement: If the separate branch for a single parameter does not have a measurable perf advantage, remove it.
if (1 == this._parameters.Count)
{
// if its one parameter only, there is no need to use stringbuilder
ObjectParameter theParam = this._parameters[0];
this._cacheKey = "@@1" + theParam.Name + ":" + theParam.ParameterType.FullName;
}
else
{
// Future Enhancement: Investigate whether precalculating the required size of the string builder is a better time/space tradeoff.
StringBuilder keyBuilder = new StringBuilder(this._parameters.Count * 20);
keyBuilder.Append("@@");
keyBuilder.Append(this._parameters.Count);
for (int idx = 0; idx < this._parameters.Count; idx++)
{
//
//
if (idx > 0)
{
keyBuilder.Append(";");
}
ObjectParameter thisParam = this._parameters[idx];
keyBuilder.Append(thisParam.Name);
keyBuilder.Append(":");
keyBuilder.Append(thisParam.ParameterType.FullName);
}
this._cacheKey = keyBuilder.ToString();
}
}
}
return this._cacheKey;
}
/// <summary>
/// Locks or unlocks this parameter collection, allowing its contents to be added to, removed from, or cleared.
/// Calling this method consecutively with the same value has no effect but does not throw an exception.
/// </summary>
/// <param name="isReadOnly">If <c>true</c>, this parameter collection is now locked; otherwise it is unlocked</param>
internal void SetReadOnly(bool isReadOnly) { this._locked = isReadOnly; }
/// <summary>
/// Creates a new copy of the specified parameter collection containing copies of its element <see cref="ObjectParameter"/>s.
/// If the specified argument is <c>null</c>, then <c>null</c> is returned.
/// </summary>
/// <param name="copyParams">The parameter collection to copy</param>
/// <returns>The new collection containing copies of <paramref name="copyParams"/> parameters, if <paramref name="copyParams"/> is non-null; otherwise <c>null</c>.</returns>
internal static ObjectParameterCollection DeepCopy(ObjectParameterCollection copyParams)
{
if (null == copyParams)
{
return null;
}
ObjectParameterCollection retParams = new ObjectParameterCollection(copyParams._perspective);
foreach (ObjectParameter param in copyParams)
{
retParams.Add(param.ShallowCopy());
}
return retParams;
}
#endregion
#region Private Methods
// ---------------
// Private Methods
// ---------------
/// <summary>
/// This private method checks for the existence of a given parameter object
/// by name by iterating through the list and comparing each parameter name
/// to the specified name. This is a case-insensitive lookup.
/// </summary>
private int IndexOf (string name)
{
int index = 0;
foreach (ObjectParameter parameter in this._parameters)
{
if (0 == String.Compare(name, parameter.Name, StringComparison.OrdinalIgnoreCase))
{
return index;
}
index++;
}
return -1;
}
/// <summary>
/// This method successfully returns only if the parameter collection is not considered 'locked';
/// otherwise an <see cref="InvalidOperationException"/> is thrown.
/// </summary>
private void CheckUnlocked()
{
if (this._locked)
{
throw EntityUtil.InvalidOperation(Strings.ObjectParameterCollection_ParametersLocked);
}
}
#endregion
}
}