diff --git a/reference/en/modules/basic_mapping.xml b/reference/en/modules/basic_mapping.xml index 9fc7a640bf..dc1811c2d3 100644 --- a/reference/en/modules/basic_mapping.xml +++ b/reference/en/modules/basic_mapping.xml @@ -195,7 +195,7 @@ - + class, dynamic-class @@ -247,8 +247,8 @@ entity-name="EntityName" catalog="catalog" check="arbitrary sql check condition" - rowid="TODO" - subselect="TODO" + rowid="rowid" + subselect="SQL expression" abstract="true|false" />]]> @@ -356,7 +356,12 @@ - entity-name (optional): TODO + entity-name (optional): Hibernate3 supports class-less persistence: + use the <dynamic-class> instead of a <class> + mapping and an entity-name attribute instead of a class name. This + allows you to implement your domain model using maps of maps or any other dynamic + approach. See for more information. + @@ -373,12 +378,17 @@ - rowid (optional): TODO + rowid (optional): Hibernate can use so called ROWIDs on databases + which support. E.g. on Oracle, Hibernate can use the rowid extra + column for fast updates if you set this option to rowid. A ROWID + is an implementation detail and represents the physical location of a stored tuple. - subselect (optional): TODO + subselect (optional): Maps an immutable and read-only entity + to a database subselect. Useful if you want to have a view instead of a base table, + but don't. See below for more information. @@ -442,7 +452,8 @@ Use of select-before-update will usually decrease performance. It is very - useful to prevent a database update trigger being called unnecessarily. + useful to prevent a database update trigger being called unnecessarily if you reattach a + graph of detached instances to a Session. @@ -462,7 +473,7 @@ - dirty check the changed columns + dirty check the changed columns, allowing some concurrent updates @@ -475,15 +486,34 @@ We very strongly recommend that you use version/timestamp columns for optimistic locking with Hibernate. This is the optimal strategy with respect to performance and is the only strategy that correctly handles modifications - made to detached instances (ie. when Session.update() is used). + made to detached instances (ie. when Session.merge() is used). - TODO: Document entity name and dynamic class + There is no difference between a view and a base table for a Hibernate mapping, as + expected this is transparent at the database level (note that some DBMS don't support + views properly, especially with updates). Sometimes you want to use a view, but can't + create one in the database (ie. with a legacy schema). In this case, you can map an + immutable and read-only entity to a given SQL subselect expression: + + + + select id, name as ident, address as loc, 'human' as species from humans + union + select id, ident, planet as loc, species from aliens + + + + + ...]]> + - TODO: Document subselect and and synchronize for view simulation + Declare the tables to synchronize this entity, to ensure that auto-flush happens + correctly, and that queries against the derived entity do not return stale data. + The <subselect> is available as both an attribute and + a nested mapping element. @@ -1108,7 +1138,7 @@ - + property @@ -1266,7 +1296,24 @@ - TODO: Document the nested column formula="" attribute with an example + An especially powerful feature are derived properties. These properties are by + definition read-only, the property value is computed at load time. You declare + the computation as a SQL expression, this translates to a SELECT + clause subquery in the SQL query that loads an instance: + + + ]]> + + + Note that you can reference the entities own table by not declaring an alias on + a particular column (customerId in the given example). Also note + that you can use the nested <formula> mapping element + if you don't like to use the attribute. @@ -1738,7 +1785,7 @@ - + joined-subclass @@ -1765,7 +1812,7 @@ catalog="catalog" extends="SuperclassName" persister="ClassName" - subselect="TODO"> + subselect="SQL expression"> @@ -1798,10 +1845,6 @@ - - TODO - - No discriminator column is required for this mapping strategy. Each subclass must, however, declare a table column holding the object identifier using the @@ -1830,8 +1873,8 @@ - - + + @@ -1843,7 +1886,7 @@ - + union-subclass @@ -1852,7 +1895,8 @@ persistent state of the class, including inherited state. In Hibernate, it is not absolutely necessary to explicitly map such inheritance hierarchies. You can simply map each class with a separate <class> - declaration. However, if you wish use polymorphic associations, you need to + declaration. However, if you wish use polymorphic associations (e.g. an association + directed at the superclass of your hierarchy), you need to use the <union-subclass> mapping. @@ -1862,14 +1906,6 @@ - - - - - - - - + subselect="SQL expression"> ..... @@ -1910,21 +1946,17 @@ lazy (optional, defaults to true): Setting lazy="false" disables the use of lazy fetching. - + - - TODO - - No discriminator column or key column is required for this mapping strategy. - + join @@ -1958,7 +1990,7 @@ - tabe: The name of the joined table. + table: The name of the joined table. @@ -1999,7 +2031,28 @@ - TODO: Document join with an example + For example, the address information for a person can be mapped to a separate + table (while preserving value type semantics for all properties): + + + + + ... + + + + + + + + ...]]> + + + This feature is often only useful for legacy data models, we recommend fewer + tables than classes and a fine-grained domain model. However, it is useful + for switching between inheritance mapping strategies in a single hierarchy, as + explained later. @@ -2483,23 +2536,24 @@ - + Modular mapping files - It is possible to define subclass and joined-subclass - mappings in seperate mapping documents, directly beneath hibernate-mapping. - This allows you to extend a class hierachy just by adding a new mapping file. You must - specify an extends attribute in the subclass mapping, naming a previously - mapped superclass. Note: Previously this feature made the ordering of the mapping documents important. Since Hibernate 3, the - ordering of mapping files does not matter when using the extends keyword. The ordering inside a single mapping file - still needs to be defined as superclasses before subclasses. + It is possible to define subclass, union-subclass, + and joined-subclass mappings in seperate mapping documents, directly beneath + hibernate-mapping. This allows you to extend a class hierachy just by adding + a new mapping file. You must specify an extends attribute in the subclass mapping, + naming a previously mapped superclass. Note: Previously this feature made the ordering of the mapping + documents important. Since Hibernate 3, the ordering of mapping files does not matter when using the + extends keyword. The ordering inside a single mapping file still needs to be defined as superclasses + before subclasses. - - - + + + ]]> @@ -2625,5 +2679,26 @@ public class Cat { + + Using JDK 5.0 Annotations + + + JDK 5.0 introduced XDoclet-style annotations at the language level, type-safe and + checked at compile time. This mechnism is more powerful than XDoclet annotations and + better supported by tools and IDEs. IntelliJ IDEA, for example, supports auto-completion + and syntax highlighting of JDK 5.0 annotations. The new revision of the EJB specification + (JSR-220) uses JDK 5.0 annotations as the primary metadata mechanism for entity beans. + Hibernate3 implements the EntityManager of JSR-220 (the persistence API), + support for mapping metadata is available via the Hibernate Annotations + package, as a separate download. Both EJB3 (JSR-220) and Hibernate3 metadata is supported. + + + + Note that support for JDK 5.0 Annotations (and JSR-220) is still work in progress and + not completed. + + + +