第 20 章工具箱指南

Roundtrip engineering with Hibernate is possible using a set of Eclipse plugins, commandline tools, and Ant tasks.

Hibernate Tools currently include plugins for the Eclipse IDE as well as Ant tasks for reverse engineering of existing databases:

Mapping Editor: an editor for Hibernate XML mapping files that supports auto-completion and syntax highlighting. It also supports semantic auto-completion for class names and property/field names, making it more versatile than a normal XML editor.
Console: the console is a new view in Eclipse. In addition to a tree overview of your console configurations, you are also provided with an interactive view of your persistent classes and their relationships. The console allows you to execute HQL queries against your database and browse the result directly in Eclipse.
Development Wizards: several wizards are provided with the Hibernate Eclipse tools. You can use a wizard to quickly generate Hibernate configuration (cfg.xml) files, or to reverse engineer an existing database schema into POJO source files and Hibernate mapping files. The reverse engineering wizard supports customizable templates.

Please refer to the Hibernate Tools package documentation for more information.

However, the Hibernate main package comes bundled with an integrated tool : SchemaExport aka hbm2ddl.It can even be used from "inside" Hibernate.

20.1. Schema自动生成（Automatic schema generation）

DDL can be generated from your mapping files by a Hibernate utility. The generated schema includes referential integrity constraints, primary and foreign keys, for entity and collection tables. Tables and sequences are also created for mapped identifier generators.

You must specify a SQL Dialect via the hibernate.dialect property when using this tool, as DDL is highly vendor-specific.

First, you must customize your mapping files to improve the generated schema. The next section covers schema customization.

20.1.1. 对schema定制化(Customizing the schema)

Many Hibernate mapping elements define optional attributes named length, precision and scale. You can set the length, precision and scale of a column with this attribute.

<property name="zip" length="5"/>

<property name="balance" precision="12" scale="2"/>

Some tags also accept a not-null attribute for generating a NOT NULL constraint on table columns, and a unique attribute for generating UNIQUE constraint on table columns.

<many-to-one name="bar" column="barId" not-null="true"/>

<element column="serialNumber" type="long" not-null="true" unique="true"/>

A unique-key attribute can be used to group columns in a single, unique key constraint. Currently, the specified value of the unique-key attribute is not used to name the constraint in the generated DDL. It is only used to group the columns in the mapping file.

<many-to-one name="org" column="orgId" unique-key="OrgEmployeeId"/>
<property name="employeeId" unique-key="OrgEmployee"/>

An index attribute specifies the name of an index that will be created using the mapped column or columns. Multiple columns can be grouped into the same index by simply specifying the same index name.

<property name="lastName" index="CustName"/>
<property name="firstName" index="CustName"/>

A foreign-key attribute can be used to override the name of any generated foreign key constraint.

<many-to-one name="bar" column="barId" foreign-key="FKFooBar"/>

很多映射元素还接受<column>子元素。这在定义跨越多字段的类型时特别有用。

<property name="name" type="my.customtypes.Name"/>
    <column name="last" not-null="true" index="bar_idx" length="30"/>
    <column name="first" not-null="true" index="bar_idx" length="20"/>
    <column name="initial"/>
</property>

The default attribute allows you to specify a default value for a column.You should assign the same value to the mapped property before saving a new instance of the mapped class.

<property name="credits" type="integer" insert="false">
    <column name="credits" default="10"/>
</property>

<version name="version" type="integer" insert="false">
    <column name="version" default="0"/>
</property>

sql-type属性允许用户覆盖默认的Hibernate类型到SQL数据类型的映射。

<property name="balance" type="float">
    <column name="balance" sql-type="decimal(13,3)"/>
</property>

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>

The following table summarizes these optional attributes.

表 20.1. Summary

属性(Attribute)	值（Values）	解释（Interpretation）
`length`	数字	字段长度
`precision`	数字	精度(decimal precision)
`scale`	数字	小数点位数(decimal scale)
`not-null`	`true\|false`	specifies that the column should be non-nullable
`unique`	`true\|false`	指明是否该字段具有惟一约束
`index`	`index_name`	指明一个（多字段）的索引(index)的名字
`unique-key`	`unique_key_name`	指明多字段惟一约束的名字（参见上面的说明）
`foreign-key`	`foreign_key_name`	specifies the name of the foreign key constraint generated for an association, for a `<one-to-one>`, `<many-to-one>`, `<key>`, or `<many-to-many>` mapping element. Note that `inverse="true"` sides will not be considered by `SchemaExport`.
`sql-type`	`SQL 字段类型`	overrides the default column type (attribute of `<column>` element only)
`default`	SQL expression	为字段指定默认值
`check`	SQL expression	对字段或表加入SQL约束检查

<comment>元素可以让你在生成的schema中加入注释。

<class name="Customer" table="CurCust">
    <comment>Current customers only</comment>
    ...
</class>

<property name="balance">
    <column name="bal">
        <comment>Balance in USD</comment>
    </column>
</property>

This results in a comment on table or comment on column statement in the generated DDL where supported.

20.1.2. 运行该工具

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

The following table displays the SchemaExport command line options

java -cp hibernate_classpaths org.hibernate.tool.hbm2ddl.SchemaExport options mapping_files

表 20.2. SchemaExport命令行选项

选项	Description
`--quiet`	do not output the script to stdout
`--drop`	只进行drop tables的步骤
`--create`	只创建表
`--text`	do not export to the database
`--output=my_schema.ddl`	把输出的ddl脚本输出到一个文件
`--naming=eg.MyNamingStrategy`	select a `NamingStrategy`
`--config=hibernate.cfg.xml`	从XML文件读入Hibernate配置
`--properties=hibernate.properties`	read database properties from a file
`--format`	把脚本中的SQL语句对齐和美化
`--delimiter=;`	为脚本设置行结束符

You can even embed SchemaExport in your application:

Configuration cfg = ....;
new SchemaExport(cfg).create(false, true);

20.1.3. 属性(Properties)

Database properties can be specified:

通过-D<property>系统参数
在hibernate.properties文件中
位于一个其它名字的properties文件中,然后用 --properties参数指定

所需的参数包括:

表 20.3. SchemaExport 连接属性

属性名	Description
`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)

20.1.4. 使用Ant(Using Ant)

你可以在你的Ant build脚本中调用SchemaExport:

<target name="schemaexport">
    <taskdef name="schemaexport"
        classname="org.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>

20.1.5. 对schema的增量更新(Incremental schema updates)

The SchemaUpdate tool will update an existing schema with "incremental" changes. The SchemaUpdate depends upon the JDBC metadata API and, as such, will not work with all JDBC drivers.

java -cp hibernate_classpaths org.hibernate.tool.hbm2ddl.SchemaUpdate options mapping_files

表 20.4. SchemaUpdate命令行选项

选项	Description
`--quiet`	do not output the script to stdout
`--text`	do not export the script to the database
`--naming=eg.MyNamingStrategy`	select a `NamingStrategy`
`--properties=hibernate.properties`	read database properties from a file
`--config=hibernate.cfg.xml`	specify a `.cfg.xml` file

You can embed SchemaUpdate in your application:

Configuration cfg = ....;
new SchemaUpdate(cfg).execute(false);

20.1.6. 用Ant来增量更新schema(Using Ant for incremental schema updates)

你可以在Ant脚本中调用SchemaUpdate：

<target name="schemaupdate">
    <taskdef name="schemaupdate"
        classname="org.hibernate.tool.hbm2ddl.SchemaUpdateTask"
        classpathref="class.path"/>
    
    <schemaupdate
        properties="hibernate.properties"
        quiet="no">
        <fileset dir="src">
            <include name="**/*.hbm.xml"/>
        </fileset>
    </schemaupdate>
</target>

20.1.7. Schema 校验

The SchemaValidator tool will validate that the existing database schema "matches" your mapping documents. The SchemaValidator depends heavily upon the JDBC metadata API and, as such, will not work with all JDBC drivers. This tool is extremely useful for testing.

java -cp hibernate_classpaths org.hibernate.tool.hbm2ddl.SchemaValidator options mapping_files

表 20.5. SchemaValidator命令行参数

选项	Description
`--naming=eg.MyNamingStrategy`	select a `NamingStrategy`
`--properties=hibernate.properties`	read database properties from a file
`--config=hibernate.cfg.xml`	specify a `.cfg.xml` file

You can embed SchemaValidator in your application:

Configuration cfg = ....;
new SchemaValidator(cfg).validate();

20.1.8. 使用Ant进行schema校验

你可以在Ant脚本中调用SchemaValidator:

<target name="schemavalidate">
    <taskdef name="schemavalidator"
        classname="org.hibernate.tool.hbm2ddl.SchemaValidatorTask"
        classpathref="class.path"/>
    
    <schemavalidator
        properties="hibernate.properties">
        <fileset dir="src">
            <include name="**/*.hbm.xml"/>
        </fileset>
    </schemavalidator>
</target>