hibernate2 参考文档之十九.txt

Hibernate使用说明书

Chapter 19. 工具箱指南 
Prev     Next 

--------------------------------------------------------------------------------

Chapter 19. 工具箱指南
通过Hibernate项目中提供的几个命令行工具(他们也被当作项目的一部分不断得到维护),还有XDoclet,Middlegen和AndroMDA内置的对Hibernate的支持,可以在几个不同的环境(SQL,java代码,xml映射文件)中进行相互转换(roundtrip)。 

Hibernate的主发行包中附带了最重要的工具（甚至在Hibernate内部也可以快速调用这个工具）： 

从映射文件到DDL schema的生成器（也就是SchemaExport和hbm2ddl） 

Hibernate项目直接提供的其他工具在一个单独的发行包中发布，Hibernate Extensions。这个发行包包含了下列任务的工具： 

从映射文件到Java源代码的生成器(也就是CodeGenerator，hbm2java） 

从已编译的Java类或者带有XDoclet标记的Java源代码生成映射文件（它们是MapGenerator,class2hbm） 

实际上Hibernate Extensions里面还有一个工具：ddl2hbm。但是它已经被废弃了，已经不再被维护了。Middlegen完成了同样的任务，并且更加出色。 

对Hibernate提供支持的第三方工具有： 

Middlegen (从现有的数据库schema中生成映射文件） 

AndroMDA ( 使用MDA思想(Model-Driven Architecture ，模型驱动体系)的代码生成器，它从UML图和其XML/XMI等价形式中生成持久化类的代码） 

这些第三方工具没有在这篇指南中说明。请查阅Hibernate 网站得到关于它们目前的情况。（Hibernate主发行包中有关于整个网站的快照） 

19.1. Schema 生成器（Schema Generation）
可以从你的映射文件使用一个命令行工具生成DDL。在Hibernate主发行包的hibernate-x.x.x/bin目录下有一个批处理文件。 

生成的schema包含有对实体和集合类表的完整性引用约束（主键和外键）。涉及到的标示符生成器所需的表和sequence也会同时生成。 

在使用这个工具的时候，你必须 通过hibernate.dialet属性指定一个SQL方言(Dialet)。 

19.1.1. 对schema定制化(Customizing the schema)
很多Hibernate映射元素定义了一个可选的length属性。你可以通过这个属性设置字段的长度。 

有些tag接受not-null属性（用来在表字段上生成NOT NULL约束）和unique属性（用来在表字段上生成UNIQUE约束）。 

有些tag接受index属性，用来指定字段的index名字。unique-key属性可以对成组的字段指定一个组合键约束(unit key constraint)。目前，unique-key属性指定的值并不会被当作这个约束的名字，它们只是在用来在映射文件内部用作区分的。 

示例： 

<property name="foo" type="string" length="64" not-null="true"/>

<many-to-one name="bar" foreign-key="fk_foo_bar" not-null="true"/>

<element column="serial_number" type="long" not-null="true" unique="true"/>
另外，这些元素还接受<column>子元素。在定义跨越多字段的类型时特别有用。 

<property name="foo" type="string">
    <column name="foo" length="64" not-null="true" sql-type="text"/>
</property>

<property name="bar" type="my.customtypes.MultiColumnType"/>
    <column name="fee" not-null="true" index="bar_idx"/>
    <column name="fi" not-null="true" index="bar_idx"/>
    <column name="fo" not-null="true" index="bar_idx"/>
</property>
sql-type属性允许用户覆盖默认的Hibernate类型到SQL数据类型的映射。 

check属性允许用户指定一个约束检查。 

<property name="foo" type="integer">
    <column name="foo" check="foo > 10"/>
</property>

<class name="Foo" table="foos" check="bar < 100.0">
    ...
    <property name="bar" type="float"/>
</class>
Table 19.1. Summary

属性(Attribute) 值（Values） 解释（Interpretation） 
length true|false 字段长度 
not-null true|false 指明字段是否应该是非空的 
unique true|false 指明是否该字段具有惟一约束 
index index_name 指明一个（多字段）的索引(index)的名字 
unique-key unique_key_name 指明多字段惟一约束的名字（参见上面的说明） 
foreign-key foreign_key_name 指明一个外键的名字，它是为关联生成的。  
sql-type column_type 覆盖默认的字段类型(只能用于<column>属性）  
check SQL 表达式 对字段或表加入SQL约束检查  

19.1.2. 运行该工具
SchemaExport工具把DDL脚本写到标准输出，同时/或者执行DDL语句。 

java -cp hibernate_classpaths net.sf.hibernate.tool.hbm2ddl.SchemaExport options mapping_files 

Table 19.2. SchemaExport命令行选项

选项 说明 
--quiet 不要把脚本输出到stdout 
--drop 只进行drop tables的步骤 
--text 不执行在数据库中运行的步骤 
--output=my_schema.ddl 把输出的ddl脚本输出到一个文件 
--config=hibernate.cfg.xml 从XML文件读入Hibernate配置 
--properties=hibernate.properties 从文件读入数据库属性 
--format 把脚本中的SQL语句对齐和美化 
--delimiter=x 为脚本设置行结束符 

你甚至可以在你的应用程序中嵌入SchemaExport工具: 

Configuration cfg = ....;
new SchemaExport(cfg).create(false, true);
19.1.3. 属性(Properties)
可以通过如下方式指定数据库属性: 

通过-D<property>系统参数

在hibernate.properties文件中

位于一个其它名字的properties文件中,然后用 --properties参数指定

所需的参数包括: 

Table 19.3. SchemaExport 连接属性

属性名 说明 
hibernate.connection.driver_class jdbc driver class 
hibernate.connection.url jdbc url 
hibernate.connection.username database user 
hibernate.connection.password user password 
hibernate.dialect 方言(dialect) 

19.1.4. 使用Ant(Using Ant)
你可以在你的Ant build脚本中调用SchemaExport: 

<target name="schemaexport">
    <taskdef name="schemaexport"
        classname="net.sf.hibernate.tool.hbm2ddl.SchemaExportTask"
        classpathref="class.path"/>
    
    <schemaexport
        properties="hibernate.properties"
        quiet="no"
        text="no"
        drop="no"
        delimiter=";"
        output="schema-export.sql">
        <fileset dir="src">
            <include name="**/*.hbm.xml"/>
        </fileset>
    </schemaexport>
</target>
19.1.5. 对schema的增量更新(Incremental schema updates)
SchemaUpdate工具对已存在的schema采用"增量"方式进行更新。注意SchemaUpdate严重依赖于JDBC metadata API,所以它并非对所有JDBC驱动都有效。 

java -cp hibernate_classpaths net.sf.hibernate.tool.hbm2ddl.SchemaUpdate options mapping_files 

Table 19.4. SchemaUpdate命令行选项

选项 说明 
--quiet 不要把脚本输出到stdout 
--properties=hibernate.properties 从指定文件读入数据库属性 

你可以在你的应用程序中嵌入SchemaUpdate工具: 

Configuration cfg = ....;
new SchemaUpdate(cfg).execute(false);
19.1.6. 用Ant来增量更新schema(Using Ant for incremental schema updates)
你可以在Ant脚本中调用SchemaUpdate： 

<target name="schemaupdate">
    <taskdef name="schemaupdate"
        classname="net.sf.hibernate.tool.hbm2ddl.SchemaUpdateTask"
        classpathref="class.path"/>
    
    <schemaupdate
        properties="hibernate.properties"
        quiet="no">
        <fileset dir="src">
            <include name="**/*.hbm.xml"/>
        </fileset>
    </schemaupdate>
</target>
19.2. 代码生成（Code Generation）
Hibernate代码生成器可以用来为Hibernate映射文件生成Java实现类的骨架。这个工具在Hibernate Extensions发行包中提供（需要单独下载）。 

hbm2java解析映射文件，生成可工作的Java源代码文件。使用hbm2java，你可以“只”提供.hbm文件，不用担心要去手工编写Java文件。 

java -cp hibernate_classpaths net.sf.hibernate.tool.hbm2java.CodeGenerator options mapping_files 

Table 19.5. 代码生成器命令行选项

选项 说明 
--output=output_dir 生成代码输出的根目录 
--config=config_file 可选的hvm2java配置文件 

19.2.1. 配置文件(可选)
配置文件提供了配置生成源代码的多个"渲染器(renders)"的途径,也可以声明在全局范围生效的<meta>属性。详情请参见<meta>属性的部分。 

<codegen>
    <meta attribute="implements">codegen.test.IAuditable</meta>
    <generate renderer="net.sf.hibernate.tool.hbm2java.BasicRenderer"/>
    <generate
        package="autofinders.only"
        suffix="Finder"
        renderer="net.sf.hibernate.tool.hbm2java.FinderRenderer"/>
</codegen>
这个配置文件声明了一个全局的meta(元）属性“implements”，指定了两个渲染器，默认渲染器(BadicRender)和生成Finder（参见下面的“基本Finder 生成器”）的渲染器。 

定义第二个渲染器需要一个包名和后缀属性。 

包名属性指定生成后的源代码应该保存的位置，覆盖在.hbm文件中指定的包范围。 

后缀属性指定生成的文件的后缀。比如说，如果有一个Foo.java文件，应该变成FooFinder.java。 

19.2.2. meta属性
<meta>标签时对hbm.xml文件进行的简单注解，工具可以用这个位置来保存/阅读和Hibernate内核不是直接相关的一些信息。 

你可以用<meta>标签来告诉hbm2java只生成"protectd"