|
|
Hibernate example source code file (toolset_guide.xml)
This example Hibernate source code file (toolset_guide.xml) is included in the DevDaily.com
"Java Source Code
Warehouse" project. The intent of this project is to help you "Learn Java by Example" TM.
The Hibernate toolset_guide.xml source code
<?xml version='1.0' encoding="UTF-8"?>
<!--
~ Hibernate, Relational Persistence for Idiomatic Java
~
~ Copyright (c) 2008, Red Hat Middleware LLC or third-party contributors as
~ indicated by the @author tags or express copyright attribution
~ statements applied by the authors. All third-party contributions are
~ distributed under license by Red Hat Middleware LLC.
~
~ This copyrighted material is made available to anyone wishing to use, modify,
~ copy, or redistribute it subject to the terms and conditions of the GNU
~ Lesser General Public License, as published by the Free Software Foundation.
~
~ This program is distributed in the hope that it will be useful,
~ but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
~ or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
~ for more details.
~
~ You should have received a copy of the GNU Lesser General Public License
~ along with this distribution; if not, write to:
~ Free Software Foundation, Inc.
~ 51 Franklin Street, Fifth Floor
~ Boston, MA 02110-1301 USA
-->
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % BOOK_ENTITIES SYSTEM "../HIBERNATE_-_Relational_Persistence_for_Idiomatic_Java.ent">
%BOOK_ENTITIES;
]>
<chapter id="toolsetguide" revision="2">
<title>Toolset Guide
<para>
Roundtrip engineering with Hibernate is possible using a set of Eclipse plugins,
commandline tools, and Ant tasks.
</para>
<para>
<emphasis>Hibernate Tools currently include plugins for the Eclipse
IDE as well as Ant tasks for reverse engineering of existing databases:
</para>
<itemizedlist>
<listitem>
<emphasis>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.
</para>
<listitem>
<emphasis>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.
</para>
<listitem>
<emphasis>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.
</para>
<listitem>
<!-- -->
</para>
</itemizedlist>
<para>
Please refer to the <emphasis>Hibernate Tools package documentation
for more information.
</para>
<para>
However, the Hibernate main package comes bundled with an integrated tool : <emphasis>SchemaExport aka
<literal>hbm2ddl.It can even
be used from "inside" Hibernate.
</para>
<section id="toolsetguide-s1" revision="2">
<title>Automatic schema generation
<para>
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.
</para>
<para>
You <emphasis>must specify a SQL Dialect via the
<literal>hibernate.dialect property when using this tool, as DDL
is highly vendor-specific.
</para>
<para>
First, you must customize your mapping files to improve the generated schema. The next section covers schema customization.
</para>
<section id="toolsetguide-s1-2" revision="3">
<title>Customizing the schema
<para>
Many Hibernate mapping elements define optional attributes named <literal>length,
<literal>precision and scale. You can set the length, precision
and scale of a column with this attribute.
</para>
<programlisting role="XML">]]>
<programlisting role="XML">]]>
<para>
Some tags also accept a <literal>not-null attribute for generating a
<literal>NOT NULL constraint on table columns, and a unique
attribute for generating <literal>UNIQUE constraint on table columns.
</para>
<programlisting role="XML">]]>
<programlisting role="XML">]]>
<para>
A <literal>unique-key attribute can be used to group columns in
a single, unique key constraint. Currently, the specified value of the
<literal>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.
</para>
<programlisting role="XML">
<property name="employeeId" unique-key="OrgEmployee"/>]]>
<para>
An <literal>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.
</para>
<programlisting role="XML">
<property name="firstName" index="CustName"/>]]>
<para>
A <literal>foreign-key attribute can be used to override the name
of any generated foreign key constraint.
</para>
<programlisting role="XML">]]>
<para>
Many mapping elements also accept a child <literal><column> element.
This is particularly useful for mapping multi-column types:
</para>
<programlisting role="XML">
<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>]]>
<para>
The <literal>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.
</para>
<programlisting role="XML">
<column name="credits" default="10"/>
</property>]]>
<programlisting role="XML">
<column name="version" default="0"/>
</property>]]>
<para>
The <literal>sql-type attribute allows the user to override the default
mapping of a Hibernate type to SQL datatype.
</para>
<programlisting role="XML">
<column name="balance" sql-type="decimal(13,3)"/>
</property>]]>
<para>
The <literal>check attribute allows you to specify a check constraint.
</para>
<programlisting role="XML">
<column name="foo" check="foo > 10"/>
</property>]]>
<programlisting role="XML">
...
<property name="bar" type="float"/>
</class>]]>
<para>The following table summarizes these optional attributes.
<table frame="topbot" id="schemattributes-summary" revision="2">
<title>Summary
<tgroup cols="3">
<colspec colwidth="1*"/>
<colspec colwidth="1*"/>
<colspec colwidth="2.5*"/>
<thead>
<row>
<entry>Attribute
<entry>Values
<entry>Interpretation
</row>
</thead>
<tbody>
<row>
<entry>length
<entry>number
<entry>column length
</row>
<row>
<entry>precision
<entry>number
<entry>column decimal precision
</row>
<row>
<entry>scale
<entry>number
<entry>column decimal scale
</row>
<row>
<entry>not-null
<entry>true|false
<entry>specifies that the column should be non-nullable
</row>
<row>
<entry>unique
<entry>true|false
<entry>specifies that the column should have a unique constraint
</row>
<row>
<entry>index
<entry>index_name
<entry>specifies the name of a (multi-column) index
</row>
<row>
<entry>unique-key
<entry>unique_key_name
<entry>specifies the name of a multi-column unique constraint
</row>
<row>
<entry>foreign-key
<entry>foreign_key_name
<entry>
specifies the name of the foreign key constraint generated
for an association, for a <literal><one-to-one>,
<literal><many-to-one>, <key>,
or <literal><many-to-many> mapping element. Note that
<literal>inverse="true" sides will not be considered
by <literal>SchemaExport.
</entry>
</row>
<row>
<entry>sql-type
<entry>SQL column type
<entry>
overrides the default column type (attribute of
<literal><column> element only)
</entry>
</row>
<row>
<entry>default
<entry>SQL expression
<entry>
specify a default value for the column
</entry>
</row>
<row>
<entry>check
<entry>SQL expression
<entry>
create an SQL check constraint on either column or table
</entry>
</row>
</tbody>
</tgroup>
</table>
<para>
The <literal><comment> element allows you to specify comments
for the generated schema.
</para>
<programlisting role="XML">
<comment>Current customers only
...
</class>]]>
<programlisting role="XML">
<column name="bal">
<comment>Balance in USD
</column>
</property>]]>
<para>
This results in a <literal>comment on table or
<literal>comment on column statement in the generated
DDL where supported.
</para>
</section>
<section id="toolsetguide-s1-3" revision="2">
<title>Running the tool
<para>
The <literal>SchemaExport tool writes a DDL script to standard out and/or
executes the DDL statements.
</para>
<para>The following table displays the SchemaExport command line options
<para>
<literal>java -cp hibernate_classpaths
<literal>org.hibernate.tool.hbm2ddl.SchemaExport options mapping_files
</para>
<table frame="topbot">
<title>SchemaExport Command Line Options
<tgroup cols="2">
<colspec colwidth="1.5*"/>
<colspec colwidth="2*"/>
<thead>
<row>
<entry>Option
<entry>Description
</row>
</thead>
<tbody>
<row>
<entry>--quiet
<entry>do not output the script to stdout
</row>
<row>
<entry>--drop
<entry>only drop the tables
</row>
<row>
<entry>--create
<entry>only create the tables
</row>
<row>
<entry>--text
<entry>do not export to the database
</row>
<row>
<entry>--output=my_schema.ddl
<entry>output the ddl script to a file
</row>
<row>
<entry>--naming=eg.MyNamingStrategy
<entry>select a NamingStrategy
</row>
<row>
<entry>--config=hibernate.cfg.xml
<entry>read Hibernate configuration from an XML file
</row>
<row>
<entry>--properties=hibernate.properties
<entry>read database properties from a file
</row>
<row>
<entry>--format
<entry>format the generated SQL nicely in the script
</row>
<row>
<entry>--delimiter=;
<entry>set an end of line delimiter for the script
</row>
</tbody>
</tgroup>
</table>
<para>
You can even embed <literal>SchemaExport in your application:
</para>
<programlisting role="JAVA">
</section>
<section id="toolsetguide-s1-4">
<title>Properties
<para>
Database properties can be specified:
</para>
<itemizedlist spacing="compact">
<listitem>
<para>as system properties with -D<property>
</listitem>
<listitem>
<para>in hibernate.properties
</listitem>
<listitem>
<para>in a named properties file with --properties
</listitem>
</itemizedlist>
<para>
The needed properties are:
</para>
<table frame="topbot">
<title>SchemaExport Connection Properties
<tgroup cols="2">
<colspec colwidth="1.5*"/>
<colspec colwidth="2*"/>
<thead>
<row>
<entry>Property Name
<entry>Description
</row>
</thead>
<tbody>
<row>
<entry>hibernate.connection.driver_class
<entry>jdbc driver class
</row>
<row>
<entry>hibernate.connection.url
<entry>jdbc url
</row>
<row>
<entry>hibernate.connection.username
<entry>database user
</row>
<row>
<entry>hibernate.connection.password
<entry>user password
</row>
<row>
<entry>hibernate.dialect
<entry>dialect
</row>
</tbody>
</tgroup>
</table>
</section>
<section id="toolsetguide-s1-5">
<title>Using Ant
<para>
You can call <literal>SchemaExport from your Ant build script:
</para>
<programlisting role="XML">
<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>]]>
</section>
<section id="toolsetguide-s1-6" revision="2">
<title>Incremental schema updates
<para>
The <literal>SchemaUpdate tool will update an existing schema with "incremental" changes.
The <literal>SchemaUpdate depends upon the JDBC metadata API and, as such, will
not work with all JDBC drivers.
</para>
<para>
<literal>java -cp hibernate_classpaths
<literal>org.hibernate.tool.hbm2ddl.SchemaUpdate options mapping_files
</para>
<table frame="topbot">
<title>SchemaUpdate Command Line Options
<tgroup cols="2">
<colspec colwidth="1.5*"/>
<colspec colwidth="2*"/>
<thead>
<row>
<entry>Option
<entry>Description
</row>
</thead>
<tbody>
<row>
<entry>--quiet
<entry>do not output the script to stdout
</row>
<row>
<entry>--text
<entry>do not export the script to the database
</row>
<row>
<entry>--naming=eg.MyNamingStrategy
<entry>select a NamingStrategy
</row>
<row>
<entry>--properties=hibernate.properties
<entry>read database properties from a file
</row>
<row>
<entry>--config=hibernate.cfg.xml
<entry>specify a .cfg.xml file
</row>
</tbody>
</tgroup>
</table>
<para>
You can embed <literal>SchemaUpdate in your application:
</para>
<programlisting role="JAVA">
</section>
<section id="toolsetguide-s1-7">
<title>Using Ant for incremental schema updates
<para>
You can call <literal>SchemaUpdate from the Ant script:
</para>
<programlisting role="XML">
<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>]]>
</section>
<section id="toolsetguide-s1-8" revision="1">
<title>Schema validation
<para>
The <literal>SchemaValidator tool will validate that the existing database schema "matches"
your mapping documents. The <literal>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.
</para>
<para>
<literal>java -cp hibernate_classpaths
<literal>org.hibernate.tool.hbm2ddl.SchemaValidator options mapping_files
</para>
<para>The following table displays the SchemaValidator command line options:
</para>
<table frame="topbot">
<title>SchemaValidator Command Line Options
<tgroup cols="2">
<colspec colwidth="1.5*"/>
<colspec colwidth="2*"/>
<thead>
<row>
<entry>Option
<entry>Description
</row>
</thead>
<tbody>
<row>
<entry>--naming=eg.MyNamingStrategy
<entry>select a NamingStrategy
</row>
<row>
<entry>--properties=hibernate.properties
<entry>read database properties from a file
</row>
<row>
<entry>--config=hibernate.cfg.xml
<entry>specify a .cfg.xml file
</row>
</tbody>
</tgroup>
</table>
<para>
You can embed <literal>SchemaValidator in your application:
</para>
<programlisting role="JAVA">
</section>
<section id="toolsetguide-s1-9">
<title>Using Ant for schema validation
<para>
You can call <literal>SchemaValidator from the Ant script:
</para>
<programlisting role="XML">
<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>]]>
</section>
</section>
</chapter>
Other Hibernate examples (source code examples)
Here is a short list of links related to this Hibernate toolset_guide.xml source code file:
|
The search page
Other Hibernate source code examples at this package level
Click here to learn more about this project
