iBATIS In Action：使用映射语句(二).doc

4.3 映射参数（Mapping Parameters） 对于大多数SQL语句来说，它们有用是因为我们可以在运行时向其传入参数。 有两种方式可以将参数（parameter）映射到语句中：内联（inline）参数和外部（external）参数。使用内联参数，配置一般较为简单，iBATIS会根据您的配置进行“揣测”，以获取其它细节信息。而使用外部参数时，配置一般更为显式的（具体）因为您告诉iBATIS它该如何去做。 4.3.1 外部参数映射 参数映射（Parameter Map）定义了一个参数的有序列表，它与查询语句的占位符相匹配。注意，参数对象的属性定义可以按任意顺序，参数映射会确保每个值得以正确地传入。 使用外部参数映射时，我们可以指定多达10个的特性。如果没有完全指定，iBATIS会藉由反射来确定出一些合理的默认值，这个过程会花费一定的时间，也有可能不够准确。表4.4列出了适用于映射参数的特性，并对其做了简要的介绍。 映射参数的特性（attribute）特性 描述 property 表示参数对应的对象的属性名称。如果输入参数对象为IDictionary，则property是相应key的名称。同一property值可以出现多次，这取决于它在语句中出现的次数。 column 用于定义存储过程的参数名称。 direction 可用于指定存储过程参数的方向。其值可以是Input，Output或InputOutput。 dbType 用于显式地指定参数对应的列类型。对于某些操作，一些ADO.NET provider不能判断列的类型，此时dbType必须指定。此特性仅在列为nullable时是必需的。此外，在显式指定日期类型时也需要此特性。尽管.NET仅有一种日期值类型（System.DateTime），大多数数据库却不止一个。通常情况下，数据库至少有三种不同的日期类型（Date，DateTime，TimeStamp）。为使映射过程能够正确，我们可能需要指定列的dbType。 type 用于指定前面的property的CLR类型。在向存储过程传入InputOput和Output类型的参数时，该特性很有用。正常情况下，property的类型可通过反射获得，但对于IDictionary类型的参数就无能为力了，此时类型被假定为Object。 nullValue nullValue可以设置为任何的有效值（这取决于property的类型）。注意：对于值类型（int，double，datetime等）的属性，它们是不能为null的，那如何向数据库中插入null值呢？可以采用nullValue，比如对于Age列（int类型），我们可以指定nullValue为0，这意味着如果该属性未设置（C#中，int属性的默认值为0），那么会向数据库插入NULL。在.NET2.0中也可以使用nullable类型，此时更为方便。请参考我的小文。 size 设置列的最大尺寸。 precision 设置数字值的精度。 scale 设置小数的位数。 typeHandler 用于自定义类型处理器（Custom Type Handler）。 内联参数在多数情况下效果不错。如果您希望改善性能，或者遇到了意外的情况，外部参数可能就用得上了。在第5章中，我们会更全面地讨论外部参数，在这里，暂不需要。 4.3.2 重温内联参数 如果您更喜欢使用内联参数，同样可以为参数指定更多的信息，如属性的类型，类的类型以及null值替换（即nullValue特性）。看下面四个例子： insert into PRODUCT (PRD_ID, PRD_DESCRIPTION) values (#id#, #description#)这是最简单的情况，下面这个例子指定了dbType： insert into PRODUCT (PRD_ID, PRD_DESCRIPTION) values (#id:int#, #description:VarChar#)下面这个例子指定了nullValue： insert into PRODUCT (PRD_ID, PRD_DESCRIPTION) values (#id:int:-999999#, #description:VarChar#)类似于Java中的DataMapper，内联参数还有另外一种语法，使用逗号。 update Accounts set Account_FirstName = #FirstName#, Account_LastName = #LastName#, Account_Email = #EmailAddress,type=string,dbType=Varchar,nullValue=no_# where Account_ID = #Id#4.3.3 标准类型的参数（standard type parameter） 在实际开发中，我们会发现很多语句只接受单个参数，通常为int或string。此时并不需要将其封装在另一个对象中，直接使用标准库对象（string, int等）就可以了，下面是一个例子： select * from PRODUCT where PRD_ID = #value#假定PRD_ID为数字类型，在调用该语句时，可以传入一个标准的int对象。#value#参数会替换为传入的int值。此处的value仅仅是一个占位符，您可以根据需要将其替换为其它名称。 为方便起见，iBATIS框架提供了基元类型的别名，比如，int可用于代替System.Int32。要了解这些别名的完整内容，请参考iBATIS.NET的官方文档。 4.3.4 IDictionary类型的参数 select * from PRODUCT where PRD_CAT_ID = #catId# and PRD_CODE = #code#我们也可以使用IDictionary类型的对象作为参数。通常可以使用Hashtable。看下面的例子： 看看这条语句，跟前面出现的没有什么不同。如果传入的对象是Hashtable类型，它必须要包含有名称为catId和code的键，而键所对应的值必须要适合于列的类型，这些要求与使用普通的对象是一样的。 为方便起见，iBATIS框架也提供了IDictionary类型的别名。因此，可以用map或hashtable来代替System.Collections.Hashtable。要了解这些别名的完整内容，请参考iBATIS.NET的官方文档。 OK，至此我们已经知道了如何输入参数了，下面就来看看如何获取输出值了。 4.4结果映射（result map） Result Map将从数据库查询所得的结果映射到对象的属性。在使用映射语句时，Result Map是我们要理解的最常用也是最重要的特性之一。 通过Result Map我们可以控制如何从查询结果中获取数据，以及列是如何映射到对象的属性的。Result Map可以描述列的类型、null值的替换以及复杂属性（包括集合）的映射。 4.4.1 扩展Result Map 可选的extends特性值可以设置为另一个Result Map的名称，这样就可以复用指定Result Map的映射方式了。“父级”Result Map的所有属性都将作为当前Result Map的一部分，“父级”Result Map的值在当前Result Map之前进行设置，其效果类似于类的继承。 提示：“父级”Result Map必须在“子级”Result Map之前定义。 4.4.2 的特性 接受三个特性： 特性 描述 id 必需的，为Result Map提供唯一标识。 class 可选的，指定当前Result Map使用的类。可以设置为类的完整名称或别名。 extends 可选的，指定要进行“继承”的Result Map。 4.4.3 元素 元素必须与result class的构造函数签名相匹配。如果指定了此元素，iBATIS用它来实例化结果对象（result object）。 4.4.4 元素 元素包含一个或多个子元素，用以将执行SQL的结果集映射至对象的属性。 特性 描述 property 必需的，表示结果对象的属性名称。 column 必需的，指定结果集中的列名称，使用该列来产生当前属性。 columnIndex 可选的，指定列的索引，该特性对性能会有轻微的帮助。99%的应用程序中是不需要的，而且它还会牺牲可维护性和可读性。另外一些provider中，该特性可能对性能没有任何帮助。 dbType 用于显式地指定列的类型。由于CLR和数据库中类型的不一致，该特性比较有用，尤其是对datetime和string类型。 type 用于显式地指定结果对象属性的CLR类型。通常属性的类型可通过反射获得，但在映射到Hashtable之类的对象时就无能为力了。 resultMapping 该特性的值可以设置为另一个Result Map的名称，借助后者来填充属性。如果使用的Result Map位于另一个文件中，则必须要使用它的完全限定名称（加上命名空间）。 nullValue 用于指定null值的替代值，该特性可以设置为任何有效的值（取决于属性的类型）。如果属性类型为值类型，则其值不可能为null，如果列的值为null，那么通过该特性可以将属性设定为某个常量值。另一方面，如果属性可以为null，我们可能想用某个常量值而不是null来表示它，这个时候nullValue特性也是有用的。 select 用于描述对象间的关系，并自动加载复杂类型（即用户定义类型）。其值必须为另一映射语句的名称。 lazyLoad 联合使用lazyLoad和select特性，可以指定select特性所指定语句的结果是否要延迟加载。延迟加载对IList和IList的支持是透明的，对强类型的集合类的支持则需要Castle.DynamicProxy组件。 typeHandler 允许使用自定义类型处理器（Custom Type Handler）。这样就可以扩展DataMapper的能力，来处理那些provider特定的类型或者是provider不支持的类型。 代码示例：nullValue的使用 注意：如果PRD_SUB_CODE列的值为null，则subCode属性的值将设置为-9999。记住，在插入/更新数据时，Parameter Map的nullValue特性也要进行设置，这样才能一致。实际上有了nullable类型后，该特性可以不使用了。 4.4.5 隐式的结果映射 如果SQL语句返回的列与结果对象的属性相匹配，那么显式的Result Map就不再必要了。在下面的例子中，列的名称和属性的名称已然匹配，因此无需声明Result Map。 select id, description from PRODUCT where id = #value#但是，如果列的名称和属性名称不一致，而列名不可能修改（比如使用其它公司开发的数据库），那该怎么办呢？可以使用列的别名，看下例： select PRD_ID as id, PRD_DESCRIPTION as description from PRODUCT where PRD_ID = #value#当然，此时就不能指定dbType、nullValue或者其它的特性了（不要太贪心）。 区分大小写是隐式Result Map的另一个问题。诚然，我们可为一个类同时定义“FirstName”和“Firstname”两个属性，在iBATIS进行映射时，它就不能保证是匹配哪个属性了（当然了，没几个开发人员会定义这样相近的两个属性）。 最后，隐式Result Map会有性能损失，如果我们使用第三方的.NET数据库provider，而它又对ResultSetMetaData支持很差，那损失就更明显了。 4.4.6 返回基元类型的结果（如string，int等） 很多时候，并不需要返回一个具有多个属性的对象，我们需要的仅仅是单个的string，int，bool等类型的值。这时，您可以指定标准类型作为结果类型，如： select count(*) from PRODUCT结果类型也可使用iBATIS框架提供的别名，比如，int可用于代替System.Int32。要了解这些别名的完整内容，请参考iBATIS.NET的官方文档。 4.4.7 返回IDictionary类型的结果 有些时候我们需要的只是包含数据的键/值列表。Result Map可以生成一个IDictionary类型的实例，其语法与普通的POCO对象一样： 在这个例子中，iBATIS会为每一行创建一个Hashtable实例，这个实例包含了返回的数据，属性名id、code等均作为Hashtable的key，列的值则作为Hashtable的值。 也可以使用IDictionary类型作为隐式的Result Map： select * from PRODUCTHashtable包含的值取决于列的值。如果列发生了变化（比如添加或删除了列），返回的结果也会随之发生变化。 注意：某些provider可能将返回的列名称定为大写或小写，此时要注意使用正确的key名称。 4.5 小结 在本章中，我们探讨了POCO