diff --git a/reference/en/modules/basic_mapping.xml b/reference/en/modules/basic_mapping.xml index 490882e53a..05deda7dea 100644 --- a/reference/en/modules/basic_mapping.xml +++ b/reference/en/modules/basic_mapping.xml @@ -237,6 +237,8 @@ + + ]]> @@ -403,6 +406,12 @@ <union-subclass> hierarchies. + + + entity-name (optional, defaults to the class name): Explicitly + specify an entity name. + + @@ -537,11 +546,11 @@ - - - - - + + + + + + node="element-name|@attribute-name|element/@attribute|." ]]> @@ -861,6 +871,7 @@ class="ClassName" unsaved-value="undefined|any|none" access="field|property|ClassName"> + node="element-name|." @@ -1020,11 +1031,11 @@ - - - - - + + + + + ]]> @@ -1096,16 +1108,17 @@ - - - - + + + + ]]> @@ -1156,19 +1169,19 @@ - - - + + + - - + + - - - - - - + + + + + + ]]> @@ -1338,22 +1352,23 @@ - - - - - + + + + + - - + + - - - - - - - + + + + + + + + ]]> @@ -1449,11 +1466,12 @@ - lazy (optional - defaults to false): Specifies - that this property should be fetched lazily when the instance variable is first - accessed (requires build-time bytecode instrumentation). Note that this does not - influence Hibernate's proxy behavior - like the lazy attribute - on class or collection mappings, but uses interception for deferred loading. + lazy (optional - defaults to proxy): + By default, single point associations are proxied. lazy="true" + specifies that the property should be fetched lazily when the instance variable + is first accessed (requires build-time bytecode instrumentation). + lazy="false" specifies that the association will always + be eagerly fetched. @@ -1463,6 +1481,11 @@ ignore will treat a missing row as a null association. + + + entity-name (optional): The entity name of the associated class. + + @@ -1522,14 +1545,16 @@ - - - - - - - - + + + + + + + + + + ]]> @@ -1596,6 +1624,22 @@ org.hibernate.test.onetooneformula for an example.) + + + lazy (optional - defaults to proxy): + By default, single point associations are proxied. lazy="true" + specifies that the property should be fetched lazily when the instance variable + is first accessed (requires build-time bytecode instrumentation). + lazy="false" specifies that the association will always + be eagerly fetched. Note that if constrained="false", + proxying is impossible and Hibernate will eager fetch the association! + + + + + entity-name (optional): The entity name of the associated class. + + @@ -1696,6 +1740,7 @@ lazy="true|false" optimistic-lock="true|false" unique="true|false" + node="element-name|." > @@ -1901,7 +1946,8 @@ lazy="true|false" dynamic-update="true|false" dynamic-insert="true|false" - entity-name="EntityName"> + entity-name="EntityName" + node="element-name"> ..... @@ -1993,7 +2039,8 @@ extends="SuperclassName" persister="ClassName" subselect="SQL expression" - entity-name="EntityName"> + entity-name="EntityName" + node="element-name"> @@ -2105,7 +2152,8 @@ abstract="true|false" persister="ClassName" subselect="SQL expression" - entity-name="EntityName"> + entity-name="EntityName" + node="element-name"> ..... diff --git a/reference/en/modules/collection_mapping.xml b/reference/en/modules/collection_mapping.xml index a94b888000..8a00ec14a4 100644 --- a/reference/en/modules/collection_mapping.xml +++ b/reference/en/modules/collection_mapping.xml @@ -129,6 +129,8 @@ kittens = cat.getKittens(); // Okay, kittens collection is a Set batch-size="N" access="field|property|ClassName" optimistic-lock="true|false" + node="element-name|." + embed-xml="true|false" > @@ -156,7 +158,8 @@ kittens = cat.getKittens(); // Okay, kittens collection is a Set lazy (optional - defaults to true) - enable lazy initialization (not available for arrays) + may be used to disable lazy fetching and specify that the association is + always eagerly fetched (not available for arrays) @@ -328,6 +331,7 @@ kittens = cat.getKittens(); // Okay, kittens collection is a Set column="column_name" formula="any SQL expression" type="type_name" + node="@attribute-name" length="N"/>]]> @@ -464,6 +468,7 @@ kittens = cat.getKittens(); // Okay, kittens collection is a Set + ]]> @@ -516,6 +523,12 @@ kittens = cat.getKittens(); // Okay, kittens collection is a Set ignore will treat a missing row as a null association. + + + entity-name (optional): The entity name of the associated class, + as an alternative to class. + + @@ -617,11 +630,15 @@ kittens = cat.getKittens(); // Okay, kittens collection is a Set + ]]> + entity-name="EntityName" + node="element-name|element/@attribute" + embed-xml="true|false" + />]]> @@ -635,6 +652,12 @@ kittens = cat.getKittens(); // Okay, kittens collection is a Set ignore will treat a missing row as a null association. + + + entity-name (optional): The entity name of the associated class, + as an alternative to class. + + diff --git a/reference/en/modules/performance.xml b/reference/en/modules/performance.xml index 40881adccf..6f01a352ab 100644 --- a/reference/en/modules/performance.xml +++ b/reference/en/modules/performance.xml @@ -5,11 +5,10 @@ Fetching strategies - A fetching strategy is the strategy Hibernate will - use for retrieving associated objects if the application needs to - navigate the association. Fetch strategies may be declared in the O/R - mapping metadata, or over-ridden by a particular HQL or - Criteria query. + A fetching strategy is the strategy Hibernate will use for + retrieving associated objects if the application needs to navigate the association. + Fetch strategies may be declared in the O/R mapping metadata, or over-ridden by a + particular HQL or Criteria query. @@ -51,25 +50,77 @@ - - - By default, Hibernate3 uses lazy select fetching, which is the best choice for most entities - and collections in most applications. If you set - hibernate.default_batch_fetch_size, Hibernate will use the batch fetch - optimization to lazy fetching (this optimization may also be enabled at a more granular level). - - However, there is one problem to be aware of. Access to a lazy association - outside of the context of an open Hibernate session will result in an exception. - For example: + Hibernate also distinguishes between: + + + + Immediate fetching - an association, collection or + attribute is fetched immediately, when the owner is loaded. + + + + + Lazy collection fetching - a collection is fetched + when the application invokes an operation upon that collection. (This + is the default for collections.) + + + + + Proxy fetching - a single-valued association is + fetched when a method other than the identifier getter is invoked + upon the associated object. + + + + + Lazy attribute fetching - an attribute or single + valued association is fetched when the instance variable is accessed + (required buildtime bytecode instrumentation). This approach is + rarely necessary. + + + + + + We have two orthogonal notions here: when is the association + fetched, and how is it fetched (what SQL is used). Don't + confuse them! We use fetch to tune performance. We may use + lazy to define a contract for what data is always available + in any detached instance of a particular class. + + + + Working with lazy associations + + + By default, Hibernate3 uses lazy select fetching for collections and lazy proxy + fetching for single-valued associations. These defaults make sense for almost + all associations in almost all applications. + + + + Note: if you set + hibernate.default_batch_fetch_size, Hibernate will use the + batch fetch optimization for lazy fetching (this optimization may also be enabled + at a more granular level). + + + + However, lazy fetching poses one problem that you must be aware of. Access to a + lazy association outside of the context of an open Hibernate session will result + in an exception. For example: + + - - Since the permissions collection was not - initialized when the Session was closed, the collection - will not be able to load its state. Hibernate does not support lazy - initialization for detached objects. The fix is to move the - code that reads from the collection to just before the commit. (There are - other more advanced ways to solve this problem, some are discussed later.) - - - - It is also possible to use a non-lazy collection or join fetching, which is - non-lazy by nature. However, it is intended that lazy initialization be used - for almost all collections, especially for collections of entity references. - If you define too many non-lazy associations in your object model, Hibernate - will end up needing to fetch the entire database into memory in every - transaction! - - - - On the other hand, we often want to choose join fetching (which is non-lazy by - nature) instead of select fetching in a particular transaction. We'll now see - how to customize the fetching strategy. In Hibernate3, the mechanisms for - choosing a fetch strategy are identical for single-valued associations and - collections. - - + + Since the permissions collection was not initialized when the + Session was closed, the collection will not be able to + load its state. Hibernate does not support lazy initialization + for detached objects. The fix is to move the code that reads + from the collection to just before the transaction is committed. + + + + Alternatively, we could use a non-lazy collection or association, + by specifying lazy="false" for the association mapping. + However, it is intended that lazy initialization be used for almost all + collections and associations. If you define too many non-lazy associations + in your object model, Hibernate will end up needing to fetch the entire + database into memory in every transaction! + + + + On the other hand, we often want to choose join fetching (which is non-lazy by + nature) instead of select fetching in a particular transaction. We'll now see + how to customize the fetching strategy. In Hibernate3, the mechanisms for + choosing a fetch strategy are identical for single-valued associations and + collections. + + + + Tuning fetch strategies - - - Select fetching (the default) is extremely vulnerable to N+1 selects problems, - so we might want to enable join fetching in the mapping document: - - + + + Select fetching (the default) is extremely vulnerable to N+1 selects problems, + so we might want to enable join fetching in the mapping document: + + @@ -142,10 +194,10 @@ Integer accessLevel = (Integer) permissions.get("accounts"); // Error!]]> - - Specifying join as the fetch strategy in the mapping - document does not affect HQL queries. - + + Specifying join as the fetch strategy in the mapping + document does not affect HQL queries. + Usually, we don't use the mapping document to customize fetching. Instead, we @@ -157,16 +209,16 @@ Integer accessLevel = (Integer) permissions.get("accounts"); // Error!]]> - If you ever feel like you wish you could change the fetching strategy used by - get() or load(), simply use a - Criteria query, for example: + If you ever feel like you wish you could change the fetching strategy used by + get() or load(), simply use a + Criteria query, for example: - + .setFetchMode("permissions", FetchMode.JOIN) + .add( Restrictions.idEq(userId) ) + .uniqueResult();]]> + (This is Hibernate's equivalent of what some ORM solutions call a "fetch plan".)