Parameter Maps

Parameter Maps        
        首先来看一下ParameterMap的定义：

< parameterMap  id ="parameterMapIdentifier"  
  [class ="fullyQualifiedClassName, assembly|typeAlias" ]
  [extends ="[sqlMapNamespace.]parameterMapId" ] >
   < parameter 
     property  ="propertyName"  
    [column ="columnName" ]
    [direction ="Input|Output|InputOutput" ]
    [dbType ="databaseType" ] 
    [type ="propertyCLRType" ]
    [nullValue ="nullValueReplacement" ] 
    [size ="columnSize" ] 
    [precision ="columnPrecision" ] 
    [scale ="columnScale" ]  
    [typeHandler ="fullyQualifiedClassName, assembly|typeAlias" ]  
  <parameter    />
   < parameter     />  
</ parameterMap >

其中只有id这个属性是必须的，其它都为可选。下面我们来看一个parameterMap在SQLMAP中的具体应用：

< parameterMap  id ="insert-employee-param"  class ="Employees" >
   < parameter  property ="id"   />
   < parameter  property ="empcode" />
</ parameterMap >

< statement  id ="insertEmployee"  parameterMap ="insert-employee-param" >
  insert into Employees (Id, EmpCode) values (?,?);
</ statement >

注意：我们通常在statement中使用的parameterMap都是在当前DataMap中定义的，其实我们可以引用应用程序里其它的DataMap中的parameterMap，但是前面要加上DataMap的namespace作为前缀。如：

< statement  id ="insertEmployee"  parameterMap ="otherDataMap.insert-employee-param" >
  insert into Employees (Id, EmpCode) values (?,?);
</ statement >

1、<parameterMap> attributes
      <parameterMap>包括三个属性：id(必须)，class(可选)，extends(可选)
      1.1、id
               是该parameterMap在当前DataMap中的唯一标识。
      1.2、class
               可以是property object或是IDictionary的实例，虽然class不是必须Attribute，但是我们最好去设置它的值，这样可以帮助我们验证传入参数的有效性并且能够优化性能。
      1.3、extends
               这个在statement中已经说过了，大概的意思都是一样的，这里不再多说，parameterMap可以继承其它DataMap中的parameterMap，继承的时候要加上DataMap的namespace。
2、<parameter> Elements
      <parameterMap>有一个或多个<parameter>的子元素，用于匹配SQL Statement中的占位符。
      2.1、property
               可以指定参数类中的一个属性，也可以是IDictionary instance中的一项的名称。它可以在SQL Statement中使用多次。
      2.2、column
               column通常用于定义存储过程中的参数名称。
      2.3、direction
               用于指定参数的类型：输出(Output)、输入(Input)、双向(InputOutput)。
      2.4、dbType
               指定参数对应于数据库的列的类型。通常情况下仅当列为nullable时需要指定dbType。另外，对于一些特殊的数据类型如DateTime，在.net中只有System.DateTime一种时间的数据类型，而数据库（MSSQL）中有DateTime,Date等，为了区分参数的类型，此时我们也需要指定dbType。
      2.5、type
               参数property在CLR中的类型。通常用于存储过程中的InputOutput和Output参数。
      2.6、nullValue
               当property的值为nullValue中设定的值的时候，就会将property的值替换为null。这个通常用于那些在程序中无法直接赋null值的数据类型，比如：int,double,float等类型。
      2.7、size
               一般用于设置property值的最大值。
      2.8、precision
               设置property值的精度。(?)
      2.9、scale
               设置property值的范围。(?)
      2.10、typeHandler
               typeHandler允许用户使用自定义的typeHandler,我们可以通过创建自定义的typeHandler来从数据库中存储或获取Boolean、Guid类型的数据。关于自定义typeHandler，将在后面的文章中专门介绍。

二、Inline Parameter Maps
        如果使用Inline Parameter(内置参数)来代替parameterMap，我们需要为它添加额外的类别信息。InlineParameter的语法允许你在有参数的sql statement中嵌入参数的property name,property type,column type和null value replacement。下面我们来一一示例：
1、 A <statement> using inline parameters
      

< statement  id ="insertEmployee"  parameterClass ="Employees" >
  insert into Employees(Id,EmpCode)
  values (#id#, #empcode#)
</ statement >

2、 A <statement> using an inline parameter map with a type

< statement  id ="insertEmployee"  parameterClass ="Employees" >
  insert into Employees(Id,EmpCode)
  values (#id:int#, #empcode:varchar#)
</ statement >

3、 A <statement> using an inline parameter map with a null value replacement

< statement  id ="insertEmployee"  parameterClass ="Employees" >
  insert into Employees(Id,EmpCode)
  values (#id:int:-99999#, #empcode:varchar#)
</ statement >

4、 A <statement> using alternate inline syntax with property, type, dbType, and null value replacement

< update  id ="UpdateEmployee"  parameterClass ="Employees" >
      update Employees set
      empcode=#EmpCode#,
      empname=#EmpName#,
      email = #Email,type=string,dbType=Varchar,nullValue=no_email@provided.com#
      where id = #Id#
</ update >

使用InlineParameter需注意几点：
      不能单独设置null value replacement，必须和dbType同时使用。
      对于既是参数又在resultMap中的null value,必须在resultMap中指定数据库列的null value replacement.
      对于有大量类型描述符或null value replacement的复杂查询，建议采用parameterMap.

三、Standard Type Parameters
      在实际的应用中，存在很多只带一个Int或是String型的参数的statement，这时候我们可以直接用standard library object(int ,string,etc)来作为Statement的参数，而不需要另外指定其它的object。如下：
A <statement> using standard type parameters

< update  id ="DeleteEmployee"  parameterClass ="int" >
      Update Employees Set
        isdelete = 'y'
      Where id=#value#
</ update >

四、Map or IDictionary Type Parameters
      我们还可以使用System.Collection.IDictionary的实例来作为Statement的参数类，最常用的也就是Hashtable了，如下：

< update  id ="ChangePassword"  parameterClass ="Hashtable" >
      Update Employees
      Set password=#Password#
      Where id=#Id#
</ update >

注意：在我们传入的hashtable中必须包括名为Password和Id的两个键，其值的类型必须匹配它们对应的数据库列的类型，否则将会出错。

关于parameterMap就说到这里。