Chapter 6. Controlling reverse engineering

When using the <jdbcconfiguration> tag, the Ant task will read the database metadata and then reverse engineer the database schema into a normal Hibernate Configuration. It is from this object (e.g. <hbm2java>) that other artifacts, such as .java and .hbm.xml, can be generated.

To govern this process Hibernate™ uses a reverse engineering strategy. A reverse engineering strategy is mainly called to provide more Java like names for tables, column and foreign keys into classes, properties and associations. It is also used to provide mappings from SQL types to Hibernate™ types.

The strategy can be customized by the user. This can be done by providing a custom reverse engineering strategy should the default strategy does not include the required functionality, or simply define a small component of the strategy and delegate the rest to the default strategy.

Further in this chapter we will discuss how you can configure the process of reverse engineering, what the default reverse engineering strategy includes, as well as some custom concepts.

6.1. Default reverse engineering strategy

The default strategy uses a collection of rules for mapping JDBC artifact names to Java artifact names. It also provide basic type mappings from JDBC types to Hibernate™ types. It is the default strategy that uses the packagename attribute to convert a table name into a fully qualified class name.

6.2. hibernate.reveng.xml file

A hibernate.reveng.xml file can provide a finer degree of control of the reverse engineering process. In this file you can specify type mappings and table filtering. This file can be created by hand (it's just basic XML) or you can use the Section 4.9, “Reveng.xml Editor”, which provides a specialized editor.

Note:

Many databases have case-sensitive names, so if a table does not match, and you are sure it is not excluded by a <table-filter>, check that the case matches. Most databases stores table names in upper case.

Below you can see an example of a reveng.xml file.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE hibernate-reverse-engineering 
  SYSTEM "http://hibernate.sourceforge.net/hibernate-reverse-engineering-3.0.dtd" >

<hibernate-reverse-engineering>

<type-mapping>
 <!-- jdbc-type is name for java.sql.Types -->
 <sql-type jdbc-type="VARCHAR" length='20' hibernate-type="SomeUserType" /> 
 <sql-type jdbc-type="VARCHAR" length='1' hibernate-type="yes_no" />
 <!-- length, scale and precision can be used to specify the mapping precisely -->
 <sql-type jdbc-type="NUMERIC"  precision='1' hibernate-type="boolean" /> 
 <!-- the type-mappings are ordered. This mapping will be consulted last, 
  thus overridden by the previous one if precision=1 for the column -->
 <sql-type jdbc-type="NUMERIC"  hibernate-type="long" /> 
</type-mapping>

<!-- BIN$ is recycle bin tables in Oracle -->
<table-filter match-name="BIN$.*" exclude="true" /> 

<!-- Exclude DoNotWantIt from all catalogs/schemas -->
<table-filter match-name="DoNotWantIt" exclude="true" /> 

<!-- exclude all tables from the schema SCHEMA in catalog BAD. -->
<table-filter match-catalog="BAD" match-schema="SCHEMA" match-name=".*" exclude="true" /> 

<!-- table allows you to override/define how reverse engineering 
     is done for a specific table -->
<table name="ORDERS"> 
 <primary-key>
   <!-- setting up a specific id generator for a table -->
  <generator class="sequence">
    <param name="table">seq_table</param>
  </generator>
   <key-column name="CUSTID"/>
 </primary-key>
 <column name="NAME" property="orderName" type="string" />
 <!-- control many-to-one and set names for a specific named foreign key constraint -->
 <foreign-key constraint-name="ORDER_CUST">
   <many-to-one property="customer"/>
   <set property="orders"/>
 </foreign-key>
 <!-- can also control a pure (shared pk) one-to-one  -->
  <foreign-key constraint-name="ADDRESS_PERSON">
   <one-to-one exclude="false"/>
   <inverse-one-to-one exclude="true"/>
  </foreign-key>
</table>

</hibernate-reverse-engineering>

6.2.1. Schema Selection (<schema-selection>)

The <schema-selection> tag is used to determine which schemas the reverse engineering will try and process.

By default the reverse engineering will read all schemas and then use the <table-filter> tag to decide which tables are reverse engineered and which are not. This makes it easy to get started but can be inefficient on databases with many schemas.

With the <schema-selection> tag it is thus possible to limit which schemas are processed, which in turn can significantly speed-up the reverse engineering. The <table-filter> tag is still used to then decide which tables will be included and excluded.

Note:

If no <schema-selection> tag is specified, the reverse engineering works as if all schemas should be processed. This is equal to: <schema-selection/>, which in turn is equal to: <schema-selection match-catalog=".*" match-schema=".*" match-table=".*"/>

6.2.1.1. Examples

The following will process all tables from "MY_SCHEMA".

<schema-selection match-schema="MY_SCHEMA"/>

It is possible to have multiple schema-selection's to support multi-schema reading, or to limit the processing to very specific tables. The following example processes all tables in "MY_SCHEMA", a specific "CITY" table plus all tables that start with "CODES_" in "COMMON_SCHEMA".

<schema-selection match-schema="MY_SCHEMA"/>
<schema-selection match-schema="COMMON_SCHEMA" match-table="CITY"/>
<schema-selection match-schema="COMMON_SCHEMA" match-table="CODES_.*"/>

6.2.2. Type mappings (<type-mapping>)

The <type-mapping> section specifies how the JDBC types found in the database should be mapped to Hibernate types. e.g. java.sql.Types.VARCHAR with a length of 1 should be mapped to the Hibernate type yes_no, or java.sql.Types.NUMERIC should generally just be converted to the Hibernate type long.

<type-mapping>
 <sql-type
  jdbc-type="integer value or name from java.sql.Types"
  length="a numeric value"
  precision="a numeric value"
  scale="a numeric value"
  not-null="true|false"  
  hibernate-type="hibernate type name"  
 />
</type-mapping>

The number of attributes specified and the sequence of the sql-type tags are important. This is because Hibernate™ will search for the most specific first, and if no specific match is found it will seek from top to bottom when trying to resolve a type mapping.

6.2.2.1. Example

The following is an example of a type-mapping which shows the flexibility and importance of the ordering of the type mappings.

<type-mapping>
 <sql-type jdbc-type="NUMERIC" precision="15" hibernate-type="big_decimal"/>
 <sql-type jdbc-type="NUMERIC" not-null="true" hibernate-type="long" />
 <sql-type jdbc-type="NUMERIC" not-null="false" hibernate-type="java.lang.Long" />
 <sql-type jdbc-type="VARCHAR" length="1" not-null="true" 
       hibernate-type="java.lang.Character"/>
 <sql-type jdbc-type="VARCHAR" hibernate-type="your.package.TrimStringUserType"/>
 <sql-type jdbc-type="VARCHAR" length="1" hibernate-type="char"/>
 <sql-type jdbc-type="VARCHAR" hibernate-type="string"/>
</type-mapping>

The following table shows how this affects an example table named CUSTOMER:

Table 6.1. sql-type examples

Column	jdbc-type	length	precision	not-null	Resulting hibernate-type	Rationale
ID	INTEGER		10	true	int	Nothing is defined for INTEGER. Falling back to default behavior.
NAME	VARCHAR	30		false	your.package.TrimStringUserType	No type-mapping matches `length=30` and `not-null=false`, but type-mapping matches the 2 mappings which only specifies `VARCHAR`. The type-mapping that comes first is chosen.
INITIAL	VARCHAR	1		false	char	Even though there is a generic match for `VARCHAR`, the more specific type-mapping for `VARCHAR` with `not-null="false"` is chosen. The first `VARCHAR` sql-type matches in length but has no value for not-null and thus is not considered.
CODE	VARCHAR	1		true	java.lang.Character	The most specific `VARCHAR` with `not-null="true"` is selected
SALARY	NUMERIC		15	false	big_decimal	There is a precise match for `NUMERIC` with precision 15
AGE	NUMERIC		3	false	java.lang.Long	type-mapping for `NUMERIC` with `not-null="false"`

6.2.3. Table filters (<table-filter>)

The <table-filter> tag lets you specify matching rules for performing general filtering and setup of tables, e.g. let you include or exclude specific tables based on the schema or even a specific prefix.

<table-filter
 match-catalog="catalog_matching_rule"
 match-schema="schema_matching_rule"
 match-name="table_matching_rule"
 exclude="true|false"
 package="package.name"
/>

Table 6.2. Table-filter attributes

Attribute name	Definition	Default value
match-catalog	Pattern for matching catalog part of the table	.*
match-schema	Pattern for matching schema part of the table	.*
match-table	Pattern for matching table part of the table	.*
exclude	If true the table will not be part of the reverse engineering	false
package	The default package name to use for classes based on tables matched by this table-filter	""

6.2.4. Specific table configuration (<table>)

The <table> tag allows you to explicitly define how a table should be reverse engineered. It allows control over the naming of a class for the table, provides a way to specify which identifier generator should be used for the primary key and more.

<table 
 catalog="catalog_name"
 schema="schema_name"
 name="table_name"
 class="ClassName"
>
 <primary-key.../>
 <column.../>
 <foreign-key.../>
 </table>

Table 6.3. Table attributes

Attribute name	Definition	Attribute use
catalog	Catalog name for a table. It has to be specified if you are reverse engineering multiple catalogs or if it is not equal to hiberante.default_catalog.	Optional
schema	Schema name for a table. It has to be specified if you are reverse engineering multiple schemas or if it is not equal to hiberante.default_schema.	Optional
name	Name for a table.	Required
class	The class name for a table. Default name is a CamelCase version of the table name.	Optional

6.2.4.1. <primary-key>

A <primary-key> tag allows you to define a primary-key for tables that do not have one defined in the database, and more importantly it allows you to define which identifier strategy should be used (even for preexisting primary-key's).

<primary-key
 <generator class="generatorname">
   <param name="param_name">parameter value</param>
 </generator>
 <key-column...>
 </primary-key>

Table 6.4. Primary-key attributes

Attribute name	Definition	Attribute use
generator/class	Defines which identifier generator should be used. The class name is any hibernate short hand name or fully qualified class name for an identifier strategy.	Optional
generator/param	Allows to specify which parameter with a name and value should be passed to the identifier generator.	Optional
key-column	Specifies which column(s ) the primary-key consists of. A key-column is same as column, but does not have the exclude property.	Optional

6.2.4.2. <column>

With a <column> tag it is possible to explicitly name the resulting property for a column, to redefine what JDBC and/or Hibernate type a column should be processed as, and to completely exclude a column from processing.

<column
 name="column_name"
 jdbc-type="java.sql.Types type"
 type="hibernate_type"
 property="propertyName"
 exclude="true|false"
/>

Table 6.5. Column attributes

Attribute name	Definition	Attribute use
name	Column name	Required
jdbc-type	Which jdbc-type this column should be processed as. A value from `java.sql.Types`, either numerical (e.g. 93) or the constant name (e.g. `TIMESTAMP`).	Optional
type	Which hibernate-type to use for this specific column	Optional
property	What property name will be generated for this column	Optional
exclude	Set to true if this column should be ignored	default: false

6.2.4.3. <foreign-key>

The <foreign-key> tag has two purposes. The first is to define foreign-keys in databases that does not support them or do not have them defined in their schema. The second is to define the name of the resulting properties (many-to-one, one-to-one and one-to-many's).

<foreign-key
  constraint-name="foreignKeyName"
  foreign-catalog="catalogName"
  foreign-schema="schemaName"
  foreign-table="tableName"
 >
 <column-ref local-column="columnName" foreign-column="foreignColumnName"/>
 <many-to-one 
   property="aPropertyName"
   exclude="true|false"/>
 <set 
   property="aCollectionName"
   exclude="true|false"
   
 <one-to-one 
   property="aPropertyName"
   exclude="true|false"/>
 <inverse-one-to-one
   property="aPropertyName"
   exclude="true|false"/>
   </foreign-key>

Table 6.6. Foreign-key attributes

Attribute name	Definition	Attribute use
constraint-name	Name of the foreign key constraint. Important when naming many-to-one, one-to-one and set. It is the constraint-name that is used to link the processed foreign-keys with the resulting property names.	Required
foreign-catalog	Name of the foreign table's catalog. (Only relevant if you want to explicitly define a foreign key).	Optional
foreign-schema	Name of the foreign table's schema. (Only relevant if you want to explicitly define a foreign key).	Optional
foreign-table	Name of the foreign table. (Only relevant if you want to explicitly define a foreign key).	Optional
column-ref	Defines the foreign-key constraint between a local-column and foreign-column name. (Only relevant if you want to explicitly define a foreign key).	Optional
many-to-one	Defines that a many-to-one should be created and the property attribute specifies the name of the resulting property. Exclude can be used to explicitly define that it should be created or not.	Optional
set	Defines that a set should be created based on this foreign-key and the property attribute specifies the name of the resulting (set) property. Exclude can be used to explicitly define that it should be created or not.	Optional
one-to-one	Defines that a one-to-one should be created and the property attribute specifies the name of the resulting property. Exclude can be used to explicitly define that it should be created or not.	Optional
inverse-one-to-one	Defines that an inverse one-to-one should be created based on this foreign-key and the property attribute specifies the name of the resulting property. Exclude can be used to explicitly define that it should be created or not.	Optional

6.3. Custom strategy

It is possible to implement a user strategy. Such a strategy must implement org.hibernate.cfg.reveng.ReverseEngineeringStrategy. It is recommended that you use the DelegatingReverseEngineeringStrategy and provide a public constructor which takes another ReverseEngineeringStrategy as an argument. This will allow you to only implement the relevant methods and provide a fall back strategy. An example is shown below of a custom delegating strategy that converts all column names ending with "PK" into a property named "id".

public class ExampleStrategy extends DelegatingReverseEngineeringStrategy {

 public ExampleStrategy(ReverseEngineeringStrategy delegate) {
  super(delegate);
 }

 public String columnToPropertyName(TableIdentifier table, String column) {
  if(column.endsWith("PK")) {
   return "id";
  } else {
   return super.columnToPropertyName(table, column);
  }
 }
}

6.4. Custom Database Metadata

By default the reverse engineering is performed using the JDBC database metadata API. This is done via the class org.hibernate.cfg.reveng.dialect.JDBCMetaDataDialect, which is an implementation of org.hibernate.cfg.reveng.dialect.MetaDataDialect.

The default implementation can be replaced with an alternative implementation by setting the hibernatetool.metadatadialect property to a fully qualified class name for a class that implements JDBCMetaDataDialect.

This can be used to provide database specific optimized metadata reading. If you create an optimized metadata reader for your database it will be a very welcome contribution.