diff --git a/documentation/manual/src/main/docbook/en-US/content/basic_mapping.xml b/documentation/manual/src/main/docbook/en-US/content/basic_mapping.xml index d0674076d1..08cd9c5596 100644 --- a/documentation/manual/src/main/docbook/en-US/content/basic_mapping.xml +++ b/documentation/manual/src/main/docbook/en-US/content/basic_mapping.xml @@ -371,6 +371,182 @@ public class Dog { ... } Dog.hbm.xml, or if using inheritance, Animal.hbm.xml. + +
+ Key + + The <key> element is featured a few + times within this guide. It appears anywhere the parent mapping + element defines a join to a new table that references the primary key + of the original table. It also defines the foreign key in the joined + table: + + + + + + + + + + + + + + + + + <key + column="columnname" + on-delete="noaction|cascade" + property-ref="propertyName" + not-null="true|false" + update="true|false" + unique="true|false" +/> + + + + column (optional): the name of the + foreign key column. This can also be specified by nested + <column> element(s). + + + + on-delete (optional - defaults to + noaction): specifies whether the foreign key + constraint has database-level cascade delete enabled. + + + + property-ref (optional): specifies that + the foreign key refers to columns that are not the primary key + of the original table. It is provided for legacy data. + + + + not-null (optional): specifies that the + foreign key columns are not nullable. This is implied whenever + the foreign key is also part of the primary key. + + + + update (optional): specifies that the + foreign key should never be updated. This is implied whenever + the foreign key is also part of the primary key. + + + + unique (optional): specifies that the + foreign key should have a unique constraint. This is implied + whenever the foreign key is also the primary key. + + + + + For systems where delete performance is important, we recommend + that all keys should be defined + on-delete="cascade". Hibernate uses a + database-level ON CASCADE DELETE constraint, + instead of many individual DELETE statements. Be + aware that this feature bypasses Hibernate's usual optimistic locking + strategy for versioned data. + + The not-null and update + attributes are useful when mapping a unidirectional one-to-many + association. If you map a unidirectional one-to-many association to a + non-nullable foreign key, you must declare the + key column using <key + not-null="true">. +
+ +
+ Import + + If your application has two persistent classes with the same + name, and you do not want to specify the fully qualified package name + in Hibernate queries, classes can be "imported" explicitly, rather + than relying upon auto-import="true". You can also + import classes and interfaces that are not explicitly mapped: + + <import class="java.lang.Object" rename="Universe"/> + + + + + + + + + <import + class="ClassName" + rename="ShortName" +/> + + + + class: the fully qualified class name + of any Java class. + + + + rename (optional - defaults to the + unqualified class name): a name that can be used in the query + language. + + + + + + This feature is unique to hbm.xml and is not supported in + annotations. + +
+ +
+ Column and formula elements + + Mapping elements which accept a column + attribute will alternatively accept a + <column> subelement. Likewise, + <formula> is an alternative to the + formula attribute. For example: + + <column + name="column_name" + length="N" + precision="N" + scale="N" + not-null="true|false" + unique="true|false" + unique-key="multicolumn_unique_key_name" + index="index_name" + sql-type="sql_type_name" + check="SQL expression" + default="SQL expression" + read="SQL expression" + write="SQL expression"/> + + <formula>SQL expression</formula> + + Most of the attributes on column provide a + means of tailoring the DDL during automatic schema generation. The + read and write attributes allow + you to specify custom SQL that Hibernate will use to access the + column's value. For more on this, see the discussion of column read and write + expressions. + + The column and formula + elements can even be combined within the same property or association + mapping to express, for example, exotic join conditions. + + <many-to-one name="homeAddress" class="Address" + insert="false" update="false"> + <column name="person_id" not-null="true" length="10"/> + <formula>'MAILING'</formula> +</many-to-one> +
@@ -4574,155 +4750,6 @@ public long getObjectVolume() recommended.
-
- Key - - The <key> element has featured a few - times within this guide. It appears anywhere the parent mapping element - defines a join to a new table that references the primary key of the - original table. It also defines the foreign key in the joined - table: - - - - - - - - - - - - - - - - - <key - column="columnname" - on-delete="noaction|cascade" - property-ref="propertyName" - not-null="true|false" - update="true|false" - unique="true|false" -/> - - - - column (optional): the name of the - foreign key column. This can also be specified by nested - <column> element(s). - - - - on-delete (optional - defaults to - noaction): specifies whether the foreign key - constraint has database-level cascade delete enabled. - - - - property-ref (optional): specifies that - the foreign key refers to columns that are not the primary key of - the original table. It is provided for legacy data. - - - - not-null (optional): specifies that the - foreign key columns are not nullable. This is implied whenever the - foreign key is also part of the primary key. - - - - update (optional): specifies that the - foreign key should never be updated. This is implied whenever the - foreign key is also part of the primary key. - - - - unique (optional): specifies that the - foreign key should have a unique constraint. This is implied - whenever the foreign key is also the primary key. - - - - - For systems where delete performance is important, we recommend - that all keys should be defined on-delete="cascade". - Hibernate uses a database-level ON CASCADE DELETE - constraint, instead of many individual DELETE - statements. Be aware that this feature bypasses Hibernate's usual - optimistic locking strategy for versioned data. - - The not-null and update - attributes are useful when mapping a unidirectional one-to-many - association. If you map a unidirectional one-to-many association to a - non-nullable foreign key, you must declare the key - column using <key not-null="true">. -
- -
- Column and formula elements - - Mapping elements which accept a column - attribute will alternatively accept a <column> - subelement. Likewise, <formula> is an - alternative to the formula attribute. For - example: - - <column - name="column_name" - length="N" - precision="N" - scale="N" - not-null="true|false" - unique="true|false" - unique-key="multicolumn_unique_key_name" - index="index_name" - sql-type="sql_type_name" - check="SQL expression" - default="SQL expression" - read="SQL expression" - write="SQL expression"/> - - <formula>SQL expression</formula> - - Most of the attributes on column provide a - means of tailoring the DDL during automatic schema generation. The - read and write attributes allow - you to specify custom SQL that Hibernate will use to access the column's - value. For more on this, see the discussion of column read and write - expressions. - - The column and formula - elements can even be combined within the same property or association - mapping to express, for example, exotic join conditions. - - <many-to-one name="homeAddress" class="Address" - insert="false" update="false"> - <column name="person_id" not-null="true" length="10"/> - <formula>'MAILING'</formula> -</many-to-one> -
- -
- Import - - If your application has two persistent classes with the same name, - and you do not want to specify the fully qualified package name in - Hibernate queries, classes can be "imported" explicitly, rather than - relying upon auto-import="true". You can also import - classes and interfaces that are not explicitly mapped: - - <import class="java.lang.Object" rename="Universe"/> - - - - - - - - <import class="ClassName" rename="ShortName"