NHibernate中文文档.doc

第1章 NHibernate体系结构
总览
对NHibernate体系结构的非常高层的概览:

这幅图展示了NHibernate使用数据库和配置文件数据来为应用程序提供持久化服务（和持久化的对象）。
我们试图显示更多NHibernate运行时体系结构的细节。 但挺不幸的，NHibernate是比较灵活的并且提供了好几种不同的运行方式。我们展示一下两种极端情况。轻型体系中，应用程序自己提供ADO.NET连接，并且自行管理事务。这种方式使用了NHibernate API的一个最小子集。

全面解决体系中，对于应用程序来说，所有的底层ADO.NET API都被抽象了，NHibernate会替你照管所有的细节。

下面是图中一些对象的定义：
SessionFactory (NHibernate.ISessionFactory)
对属于单一数据库的编译过的映射文件的一个线程安全的，不可变的缓存快照。它是Session的工厂，是ConnectionProvider的客户。可以持有一个可选的（第二级）数据缓存，可以在进程级别或集群级别保存可以在事物中重用的数据。
会话Session (NHibernate.ISession)
单线程，生命期短促的对象，代表应用程序和持久化层之间的一次对话。封装了一个ADO.NET连接。也是Transaction的工厂。保存有必需的（第一级）持久化对象的缓存，用于遍历对象图，或者通过标识符查找对象。
持久化对象(Persistent)及其集合(Collections)
生命期短促的单线程的对象，包含了持久化状态和商业功能。它们可能是普通的对象，唯一特别的是他们现在从属于且仅从属于一个Session。一旦Session被关闭，他们都将从Session中取消联系，可以在任何程序层自由使用（比如，直接作为传送到表现层的DTO,数据传输对象）。
临时对象(Transient Object)及其集合（Collection）
目前没有从属于一个Session的持久化类的实例。他们可能是刚刚被程序实例化，还没有来得及被持久化，或者是被一个已经关闭的Session所实例化的。
事务Transaction (NHibernate.ITransaction)
（可选） 单线程，生命期短促的对象，应用程序用它来表示一批工作的原子操作。是底层的ADO.NET事务的抽象。一个Session某些情况下可能跨越多个Transaction 事务。
ConnectionProvider (NHibernate.Connection.ConnectionProvider)
（可选）ADO.NET连接的工厂。从底层的IDbConnection抽象而来。对应用程序不可见，但可以被开发者扩展/实现。
TransactionFactory (net.sf.hibernate.TransactionFactory)
（可选）事务实例的工厂。对应用程序不可见，但可以被开发者扩展/实现。

在上面的轻型结构中，程序没有使用Transaction / TransactionFactory 或ConnectionProvider API,直接和ADO.NET对话了。
第2章 ISessionFactory配置
目录
可编程配置方式
获取ISessionFactory
用户自行提供ADO.NET连接
NHibernate提供ADO.NET连接
可选配置属性
SQL 方言 (SQL Dialects)
外连接抓取（Outer Join Fetching )
自定义 CacheProvider
查询语言替换
Logging

因为NHibernate被设计为可以在许多不同环境下工作，所以它有很多配置参数。幸运的是，大部分都已经有默认值了。 NHibernate.Test.dll包含了一个示例的配置文件app.config，它演示了一些可变的参数。
可编程配置方式
NHibernate.Cfg.Configuration的一个实例代表了应用程序中所有的.NET类到SQL数据库的映射的集合。Configuration用于构造一个(不可变的)ISessionFactory。这些映射是从一些XML映射文件中编译得来的。
你可以得到一个Configuration的实例，直接实例化它即可。下面有一个例子，用来从两个XML配置文件（和exe文件在同一个目录下）中的映射中初始化：
Configuration cfg = new Configuration()
.AddXmlFile("Item.hbm.xml")
.AddXmlFile("Bid.hbm.xml");

另外一个（某些时候更好的）方法是让NHibernate自行用GetManifestResourceStream()来装载映射文件
Configuration cfg = new Configuration()
.AddClass( typeof(NHibernate.Auction.Item) )
.AddClass( typeof(NHibernate.Auction.Bid) );
NHibernate 就会在这些类型的程序集的嵌入的资源中寻找叫做NHibernate.Auction.Item.hbm.xml 和NHibernate.Auction.Bid.hbm.xml 的映射文件。这种方法取消了所有对文件名的硬编码。

另外一个（可能是最好的）方法是让NHibernate读取一个程序集中所有的配置文件:
Configuration cfg = new Configuration()
.AddAssembly( "NHibernate.Auction" );
NHibernate将会遍历程序集查找任何以hbm.xml结尾的文件。 这种方法取消了所有对文件名的硬编码并且确保程序集中的配置文件文件都会被加载。
在使用VisualStudio.NET或者NAnt生成程序集时请确保hbm.xml文件是作为嵌入资源(Embedded Resources)添加的。

Configuration也可以指定一些可选的配置项
Hashtable props = new Hashtable();
...
Configuration cfg = new Configuration()
.AddClass( typeof(NHibernate.Auction.Item) )
.AddClass( typeof(NHibernate.Auction.Bid) );
cfg.Properties = props;
Configuration是仅在配置期使用的对象，从第一个SessionFactory开始建立的时候，它就失效了。
获取ISessionFactory
当所有的映射都被Configuration解析之后，应用程序为了得到ISession实例，必须先得到它的工厂。这个工厂应该是被应用程序的所有线程共享的：ISessionFactory sessions = cfg.BuildSessionFactory();
当然，NHibernate并不禁止你的程序实例化多个ISessionFactory。在你使用不止一个数据库的时候，这就有用了。
用户自行提供ADO.NET连接
ISessionFactory可以使用一个用户自行提供的ADO.NET连接来打开一个ISession。这种设计可以让应用程序来自己管理ADO.NET连接:
IDbConnection conn = myapp.GetOpenConnection();
ISession session = sessions.OpenSession(conn);
// do some data access work
应用程序必须小心，不能在同一个连接上打开两个并行的 ISession!
NHibernate提供ADO.NET连接
另一种方法就是，你可以让ISessionFactory替你打开连接。SessionFactory必须事先知道ADO.NET连接的参数，有几种不同的方法设置参数：
1. 通过提供一个IDictionary实例给Configuration.Properties。
2. 在名为nhibernate的System.Configuration.NameValueSectionHandler类型的配置节点添加属性。
3. 在hibernate.cfg.xml 中包含<property>元素。

如果你使用这种方法，打开一个ISession是非常简单的：
ISession session = sessions.OpenSession(); // open a new Session
// do some data access work, an ADO connection will be used on demand

所有的NHibernate属性名和约束都在 NHibernate.Cfg.Environment类中定义。我们讨论一下ADO.NET连接配置最重要的几项设置：
假若你设置了如下的属性，Hibernate会使用ADO.NET Data Provider来得到连接：
表 2.1. NHibernate ADO.NET 属性
属性名
用途
hibernate.connection.provider_class
定制IConnectionProvider的类型.
例如：full.classname.of.ConnectionProvider （如果提供者创建在NHibernate中）, 或者 full.classname.of.ConnectionProvider, assembly （如果使用一个自定义的IConnectionProvider接口的实现，它不属于NHibernate）。
hibernate.connection.driver_class
定制IDriver的类型.
full.classname.of.Driver （如果驱动类创建在NHibernate中）, 或者 full.classname.of.Driver, assembly （如果使用一个自定义IDriver接口的实现，它不属于NHibernate）。
hibernate.connection.connection_string
用来获得连接的连接字符串.
hibernate.connection.isolation
设置事务隔离级别. 请检查 System.Data.IsolationLevel 来得到取值的具体意义并且查看数据库文档以确保级别是被支持的。
例如： Chaos, ReadCommitted, ReadUncommitted, RepeatableRead, Serializable, Unspecified

下面是一个在web.config文件中指定连接属性的例子:
<?xml version="1.0" encoding="utf-8" ?>
<configuration>
<configSections>
<section name="nhibernate" type="System.Configuration.NameValueSectionHandler, System,
Version=1.0.5000.0,Culture=neutral, PublicKeyToken=b77a5c561934e089" />
<section name="log4net" type="log4net.Config.Log4NetConfigurationSectionHandler,log4net" />
</configSections>

<nhibernate>
<add
key="hibernate.connection.provider"
value="NHibernate.Connection.DriverConnectionProvider"
/>
<add
key="hibernate.connection.driver_class"
value="NHibernate.Driver.SqlClientDriver"
/>
<add
key="hibernate.connection.connection_string"
value="Server=127.0.0.1;Initial Catalog=thedatabase;Integrated Security=SSPI"
/>
<add
key="hibernate.connection.isolation"
value="ReadCommitted"
/>
<add
key="hibernate.dialect"
value="NHibernate.Dialect.MsSql2000Dialect"
/>

</nhibernate>

<!-- log4net (required by NHibernate) and other app specific config follows -->
</configuration>
可选配置属性
下面是一些在运行时可以改变NHibernate行为的其他配置。所有这些都是可选的，也有合理的默认值。
表 2.2. NHibernate 配置属性
属性名
用途
hibernate.dialect
NHibernate方言（Dialect）的类名 - 可以让NHibernate使用某些特定的数据库平台的特性
例如： full.classname.of.Dialect（如果方言创建在NHibernate中）, 或者full.classname.of.Dialect, assembly （如果使用一个自定义的方言的实现，它不属于NHibernate）。
hibernate.default_schema
在生成的SQL中，scheml/tablespace的全限定名.
例如： SCHEMA_NAME
hibernate.prepare_sql
是否准备sql语句
例如： true | false
hibernate.session_factory_name
SessionFactory被创建后将自动绑定这个名称.
例如： some.name
hibernate.use_outer_join
允许使用外连接抓取。
例如：true | false
hibernate.cache.provider_class
指定一个自定义的CacheProvider缓存提供者的类名
例如： full.classname.of.CacheProvider（如果ICacheProvider创建在NHibernate中）, 或full.classname.of.CacheProvider, assembly（如果使用一个自定义的ICacheProvider，它不属于NHibernate）。
hibernate.query.substitutions
把NHibernate查询中的一些短语替换为SQL短语（比如说短语可能是函数或者字符）。
例如： hqlLiteral=SQL_LITERAL, hqlFunction=SQLFUNC

SQL 方言 (SQL Dialects)
你总是可以为你的数据库设置一个hibernate.dialect方言，它是NHibernate.Dialect.Dialect 的一个子类。如果你不需要使用基于native或者sequence的主键自动生成算法，或者悲观锁定（使用ISession.Lock() 或者 IQuery.SetLockMode())的话，方言就可以不必指定。然而，假若你指定了一个方言，Hibernate会为上面列出的一些属性使用特殊默认值，省得你手工指定它们。
表 2.3. NHibernate SQL 方言 (hibernate.dialect)
RDBMS
方言
DB2
NHibernate.Dialect.DB2Dialect
PostgreSQL
NHibernate.Dialect.PostgreSQLDialect
MySQL
NHibernate.Dialect.MySQLDialect
Oracle (any version)
NHibernate.Dialect.OracleDialect
Oracle 9/10g
NHibernate.Dialect.Oracle9Dialect
Sybase
NHibernate.Dialect.SybaseDialect
Microsoft SQL Server 2000
NHibernate.Dialect.MsSql2000Dialect
Microsoft SQL Server 7
NHibernate.Dialect.MsSql7Dialect
Firebird
NHibernate.Dialect.FirebirdDialect

外连接抓取（Outer Join Fetching ）
如果你的数据库支持ANSI或者Oracle风格的外连接，外连接抓取可能提高性能，因为可以限制和数据库交互的数量（代价是数据库自身进行了更多的工作）。外连接抓取允许你在一个SELECT语句中就可以得到一个由多对一或者一对一连接构成的对象图。
默认情况下，抓取在叶对象，拥有代理的对象或者产生对自身的引用时终止。
对一个特定关联来说，通过在XML映射文件中设置outer-join属性可以控制是否开启抓取功能。
设置hibernate.use_outer_join为false将禁用全局的外连接抓取.设置为true将启用所有一对一(one-to-one)和多对一(many-to-one)关联中的外连接抓取,默认情况下，它被设置为auto，即自动外连接。但是，一对多关联和集合永远不会使用外连接抓取，除非对每个特定的关联进行明确声明。这一行为可以在运行时通过NHibernate 查询重载。

自定义 CacheProvider
通过实现NHibernate.Cache.ICacheProvider接口，你可以整合一个第二级缓存进来。你可以通过hibernate.cache.provider_class选择某个自定义的实现。

查询语言替换
你可以使用hibernate.query.substitutions定义新的NHibernate查询短语。比如说：
hibernate.query.substitutions true=1, false=0
会在生成的SQL中把短语true和 false替换成整数值。
hibernate.query.substitutions toLowercase=LOWER
这可以让你重新命名SQL的LOWER 函数。
Logging
通过Apache log4net，NHibernate记录很多事件。
你可以从 http://logging.apache.org/log4net/下载 log4net. 要使用log4net,你要在app.config或者web.config中配置log4net节点.在src/NHibernate.Test工程中有一个配置的例子.
我们强烈建议你熟悉NHibernate's的log信息。NHibernate's的很多工作都会尽量详细的留下log,也没有让它变的难以阅读。这是用来解决问题的最基本的设施。

第3章 持久化类(Persistent Classes)
目录
POCO 简单示例
为持久化字段声明访问器(getters 和 setters)
实现一个默认的构造方法（constructor）
提供一个标识属性（identifier property）（可选）
建议使用不是sealed的类 (可选)
实现继承（Inheritance）
实现Equals()和GetHashCode()
持久化生命周期（Lifecycle）中的回调（Callbacks）
合法性检查（Validatable）回调
用属性替代 XML

持久化类是应用程序用来解决商业问题的类（比如，在电子交易程序中的Customer和Order）。持久化类，就如同它的名字暗示的，是短暂存在的，它的实例会被持久性保存于数据库中。
如果这些类符合简单的规则，NHibernate能够工作得最好，这些规则就是Plain Old CLR Object (POJO，简单传统CLR对象)编程模型。
POCO 简单示例
用一个类描述一只猫。
public class Cat
{
private long _id; // identifier
private string _name;
private DateTime _birthdate;
private Cat _mate;
private Set _kittens;
private Color _color;
private char _sex;
private float _weight;
public long Id
{
get { return _id; }
set { _id = value; }
}
public string Name
{
get { return _name; }
set { _name = value; }
}
public DateTime Birthdate
{
get { return _birthdate; }
set { _birthdate = value; }
}
public Cat Mate
{
get { return _mate; }
set { _mate = value; }
}
public Set Kittens
{
get { return _kittens; }
set { _kittens = value; }
}
public Color Color
{
get { return _color; }
set { _color = value; }
}
public char Sex
{
get { return _sex; }
set { _sex = value; }
}
public float Weight
{
get { return _weight; }
set { _weight = value; }
}
}
有四条主要的规则：

为持久化字段声明访问器(getters 和 setters)
Cat为它的所有可持久化字段声明了getters 和 setters访问器。用访问器来替代直接访问字段是个好习惯。然而也可以通过字段（field）来使用NNHibernate。
属性不一定需要声明为public的。NHibernate可以对default,procted, internal, or private的属性一视同仁地执行持久化。

实现一个默认的构造方法（constructor）
Cat有一个显式的无参数默认构造方法。所有的持久化类都必须具有一个默认的构造方法（可以不是public的），这样的话NHibernate就可以使用Constructor.Invoke()来实例化它们。

提供一个标识属性（identifier property）（可选）
建议使用不是sealed的类 (可选)

实现继承（Inheritance）
实现Equals()和GetHashCode()
持久化生命周期（Lifecycle）中的回调（Callbacks）
合法性检查（Validatable）回调
用属性替代 XML
第4章 O/R Mapping基础
目录
映射声明(Mapping declaration)
Schema
hibernate-mapping
class
id
联合ID(composite-id)
识别器（discriminator）
版本（version）(可选)
时间戳（timestamp ）(可选)
property
多对一（many-to-one）
一对一(one-to-one)
组件（component）
子类(subclass)
连接的子类（joined-subclass）
map, set, list, bag
引用（import）
NHibernate的类型
实体（Entities）和值（values）
基本值类型
自定义值类型
映射到"任意"(any)类型
SQL中引号包围的标识符
映射文件的模块化（Modular mapping files）
映射声明(Mapping declaration)

对象和关系数据库之间的映射是用一个XML文档(XML document)来定义的。这个映射文档被设计为易读的，并且可以手工修改。映射语言是以.NET为中心的，意味着映射是按照持久化类的定义来创建的，而非表的定义。
请注意，虽然很多Hibernate用户选择手工定义XML映射文档，也有一些工具来生成映射文档，包括XDoclet,Middlegen和AndroMDA. （译者注：这里是NHibernate文档中一处没有从Hibernate文档中转换过来的部分，NHibernate中并没有像XDoclet,Middlegen和AndroMDA这样的工具,我一般会采用MyGeneration这样的代码生成工具来生成XML配置文档。）

让我们从一个映射的例子开始：
<?xml version="1.0" ?>
<hibernate-mapping xmlns="urn:nhibernate-mapping-2.0"
namespace="Eg" assembly="Eg">
<class name="Cat" table="CATS" discriminator-value="C">
<id name="Id" column="uid" type="Int64">
<generator class="hilo"/>
</id>
<discriminator column="subclass" type="Char"/>
<property name="Birthdate" type="Date"/>
<property name="Color" not-null="true"/>
<property name="Sex" not-null="true" update="false"/>
<property name="Weight"/>
<many-to-one name="Mate" column="mate_id"/>
<set name="Kittens">
<key column="mother_id"/>
<one-to-many class="Cat"/>
</set>
<subclass name="DomesticCat" discriminator-value="D">
<property name="Name" type="String"/>
</subclass>
</class>
<class name="Dog">
<!-- mapping for Dog could go here -->
</class>
</hibernate-mapping>

我们现在开始讨论映射文档的内容。我们只描述NHibernate在运行时用到的文档元素和属性。映射文档还包括一些额外的可选属性和元素，它们在使用schema导出工具的时候会影响导出的数据库schema结果。（比如， not-null 属性。）
Schema
所有的XML映射都需要使用nhibernate-mapping-2.0 schema。目前的schema可以在NHibernate的资源路径或者是NHibernate.dll的嵌入资源（Embedded Resource）中找到。NHibernate总是会优先使用嵌入在资源中的schema文件。
在使用VisualStudio.NET时，你应该将hibernate-mapping拷贝到C:\Program Files\Microsoft Visual Studio .NET 2003\Common7\Packages\schemas\xml路径中，以获得智能感知功能。
hibernate-mapping
这个元素包括四个可选的属性。schema属性，指明了这个映射所引用的表所在的schema名称。假若指定了这个属性，表名会加上所指定的schema的名字扩展为全限定名。假若没有指定，表名就不会使用全限定名。default-cascade指定了未明确注明cascade属性的属性和集合类会采取什么样的默认级联风格。auto-import属性默认让我们在查询语言中可以使用非全限定名的类名。default-access告诉我们怎么访问属性值。
<hibernate-mapping
schema="schemaName" (1)
default-cascade="none|save-update" (2)
auto-import="true|false" (3)
default-access="property|field|nosetter|ClassName" (4)
assembly="assembly.name" (5)
namespace="namespace.name" (6)
>
(1)
schema (可选): 数据库schema名称.
(2)
default-cascade (可选 - 默认为 none): 默认的级联风格.
(3)
auto-import (可选 - 默认为 true): 指定是否我们可以在查询语言中使用非全限定的类名（仅限于本映射文件中的类）。
(4)
default-access (可选 - 默认为 property): NHibernate访问属性值时的策略。
(5)
assembly (可选): 指定一个程序集，如果在映射文档中没有指定程序集，就使用这个程序集。
(6)
namespace (可选): 指定一个命名空间前缀，如果在映射文档中没有指定全限定名，就使用这个命名空间名。
假若你有两个持久化类，它们的非全限定名是一样的（就是在不同的命名空间里面--译者注），你应该设置auto-import="false"。假若说你把一个“import过”的名字同时对应两个类， NHibernate会抛出一个异常。
class
你可以使用class元素来定义一个持久化类：
<class
name="ClassName" (1)
table="tableName"(2)
discriminator-value="discriminator_value"(3)
mutable="true|false"(4)
schema="owner"(5)
proxy="ProxyInterface"(6)
dynamic-update="true|false"(7)
dynamic-insert="true|false"(8)
polymorphism="implicit|explicit"(9)
where="arbitrary sql where condition"(10)
persister="PersisterClass"(11)
lazy="true|false"(12)
/>
(1)
name: 持久化类（或者接口）的全限定名。
(2)
table: 对应的数据库表名。
(3)
discriminator-value (可选 - 默认和类名一样): 一个用于区分不同的子类的值，在多态行为时使用。
(4)
mutable (可选, 默认为 true): 表明该类的实例可变（不可变）。
(5)
schema (可选): 覆盖在根<hibernate-mapping> 元素中指定的schema名字。
(6)
proxy (可选): 指定一个接口，在延迟装载时作为代理使用。你可以在这里使用该类自己的名字。
(7)
dynamic-update (可选, 默认为 false): 指定用于UPDATE 的SQL将会在运行时动态生成，并且只更新那些改变过的字段。
(8)
dynamic-insert (可选, 默认为 false): 指定用于INSERT的 SQL 将会在运行时动态生成，并且只包含那些非空值字段。
(9)
polymorphism (可选, 默认为 implicit(隐式)): 界定是隐式还是显式的使用查询多态。
(10)
where (可选) 指定一个附加的SQL WHERE 条件，在抓取这个类的对象时会一直增加这个条件。
(11)
persister (可选): 指定一个定制的 IClassPersister.
(12)
lazy(可选):假若设置 lazy="true"，就是设置这个类自己的名字作为proxy接口的一种等价快捷形式。

若指明的持久化类实际上是一个接口，也可以被完美地接受。其后你可以用 <subclass> 来指定该接口的实际实现类名。你可以持久化任何static（静态的）内部类。记得应该使用标准的类名格式，就是说比如：Eg.Foo+Bar
不可变类，mutable="false"不可以被应用程序更新或者删除。这可以让NHibernate做一些小小的性能优化。
可选的proxy属性可以允许延迟加载类的持久化实例。NHibernate开始会返回实现了这个命名接口或者子类(通过的Castle.DynamicProxy)。当代理的某个方法被实际调用的时候，真实的持久化对象才会被装载。参见下面的“用于延迟装载的代理”。
Implicit (隐式)的多态是指，如果查询中给出的是任何超类、该类实现的接口或者该类的名字，都会返回这个类的实例；如果查询中给出的是子类的名字，则会返回子类的实例。Explicit （显式）的多态是指，只有在查询