diff --git a/reference/en/modules/basic_mapping.xml b/reference/en/modules/basic_mapping.xml index b9912caae2..3b86d81534 100644 --- a/reference/en/modules/basic_mapping.xml +++ b/reference/en/modules/basic_mapping.xml @@ -37,45 +37,44 @@ + type="character"/> + type="date" + not-null="true" + update="false"/> + type="eg.types.ColorUserType" + not-null="true" + update="false"/> + not-null="true" + update="false"/> + column="litterId" + update="false"/> + column="mother_id" + update="false"/> + inverse="true" + order-by="litter_id"> - + discriminator-value="D"> + + type="string"/> @@ -107,15 +106,15 @@ - + hibernate-mapping This element has several optional attributes. The schema and - catalog attributes specify that tables referred to in this mapping - belong to the named schema and/or catalog. If specified, tablenames will be qualified - by the given schema and catalog names. If missing, tablenames will be unqualified. - The default-cascade attribute specifies what cascade style + catalog attributes specify that tables referred to in this mapping + belong to the named schema and/or catalog. If specified, tablenames will be qualified + by the given schema and catalog names. If missing, tablenames will be unqualified. + The default-cascade attribute specifies what cascade style should be assumed for properties and collections which do not specify a cascade attribute. The auto-import attribute lets us use unqualified class names in the query language, by default. @@ -128,13 +127,15 @@ - + + ]]> @@ -163,13 +164,20 @@ + + default-lazy (optional - defaults to true): + The default value for unspecifed lazy attributes of class and + collection mappings. + + + auto-import (optional - defaults to true): Specifies whether we can use unqualified class names (of classes in this mapping) in the query language. - + package (optional): Specifies a package prefix to assume for unqualified class names in the mapping document. @@ -186,7 +194,7 @@ - + class, dynamic-class @@ -223,7 +231,7 @@ discriminator-value="discriminator_value" mutable="true|false" schema="owner" - catalog="catalog" + catalog="catalog" proxy="ProxyInterface" dynamic-update="true|false" dynamic-insert="true|false" @@ -339,9 +347,8 @@ - lazy (optional): Setting lazy="true" is a shortcut - equalivalent to specifying the name of the class itself as the proxy - interface. + lazy (optional): Lazy fetching may be completely disabled by setting + lazy="false". @@ -472,7 +479,7 @@ - + id @@ -484,17 +491,17 @@ - - - - - + + + + + @@ -518,7 +525,7 @@ - unsaved-value (optional - defaults to null): + unsaved-value (optional - defaults to a "sensible" value): An identifier property value that indicates that an instance is newly instantiated (unsaved), distinguishing it from detached instances that were saved or loaded in a previous session. @@ -540,7 +547,8 @@ The unsaved-value attribute is important! If the identfier property of your - class does not default to null, then you should specify the actual default. + class does not default to the normal Java default value (null or zero), then you should specify + the actual default. @@ -548,7 +556,7 @@ legacy data with composite keys. We strongly discourage its use for anything else. - + generator @@ -558,7 +566,7 @@ <param> element. - + uid_table next_hi_value_column @@ -628,7 +636,7 @@ - uuid.hex + uuid uses a 128-bit UUID algorithm to generate identifiers of type string, @@ -638,19 +646,10 @@ - uuid.string - - - uses the same UUID algorithm. The UUID is encoded a string of length 16 - consisting of (any) ASCII characters. Do not use with PostgreSQL. - - - - guid - uses the string-based GUID algorithm available in MS SQL Server and MySQL. + uses a database-generated GUID string on MS SQL Server and MySQL. @@ -723,16 +722,11 @@ UUID Algorithm - The UUIDs contain: IP address, startup time of the JVM (accurate to a quarter + The UUID contains: IP address, startup time of the JVM (accurate to a quarter second), system time and a counter value (unique within the JVM). It's not possible to obtain a MAC address or memory address from Java code, so this is the best we can do without using JNI. - - - Don't try to use uuid.string in PostgreSQL. - - @@ -772,26 +766,25 @@ object's identifier property. Be very careful when using this feature to assign keys with business meaning (almost always a terrible design decision). - - + - If an entity uses an assigned identifier or composite identifier (below), Hibernate - cannot use the value of the identifier property to distinguish between transient - and detached instances. In this case, you have three options. Either map a version - or timestamp property, implement Interceptor.isUnsaved() (see - later), or simply disable cascades and explicitly save and update individual instances - using Session.save() and Session.update() - This is a common "gotcha" for new users! + Choosing the assigned generator makes Hibernate use + unsaved-value="undefined", forcing Hibernate to go to + the database to determine if an instance is transient or detached, unless + there is a version or timestampe property, or you define + Interceptor.isUnsaved(). + + - + composite-id @@ -843,9 +836,10 @@ - unsaved-value (optional - defaults to none): + unsaved-value (optional - defaults to undefined): Indicates that transient instances should be considered newly instantiated, if set - to any. + to any, or detached, if set to none. It is best + to leave the default value in all cases. @@ -1237,7 +1231,7 @@ - + many-to-one @@ -1268,7 +1262,7 @@ column="column_name" class="ClassName" cascade="all|none|save-update|delete" - outer-join="true|false|auto" + fetch="join|select" update="true|false" insert="true|false" property-ref="propertyNameFromAssociatedClass" @@ -1305,9 +1299,8 @@ - outer-join (optional - defaults to auto): - enables outer-join fetching for this association when - hibernate.use_outer_join is set. + join (optional - defaults to select): + Chooses between outer-join fetching or sequential select fetching. @@ -1363,31 +1356,6 @@ See "Lifecycle Objects" below. - - The outer-join attribute accepts three different values: - - - - - - auto (default) Fetch the association using an - outerjoin if the associated class has no proxy - - - - - true Always fetch the association using an - outerjoin - - - - - false Never fetch the association using an - outerjoin - - - - A typical many-to-one declaration looks as simple as @@ -1415,9 +1383,14 @@ This is certainly not encouraged, however. + + If the referenced unique key comprises multiple properties of the associated entity, you should + map the referenced properties inside a named <properties> element. + + - + one-to-one @@ -1440,7 +1413,7 @@ class="ClassName" cascade="all|none|save-update|delete" constrained="true|false" - outer-join="true|false|auto" + fetch="join|select" property-ref="propertyNameFromAssociatedClass" access="field|property|ClassName" />]]> @@ -1473,9 +1446,8 @@ - outer-join (optional - defaults to auto): - Enable outer-join fetching for this association when - hibernate.use_outer_join is set. + fetch (optional - defaults to select): + Chooses between outer-join fetching or sequential select fetching. @@ -1660,7 +1632,7 @@ - + subclass @@ -1707,9 +1679,8 @@ - lazy (optional): Setting lazy="true" is a shortcut - equalivalent to specifying the name of the class itself as the proxy - interface. + lazy (optional, defaults to true): Setting + lazy="false" disables the use of lazy fetching. @@ -1725,7 +1696,7 @@ - + joined-subclass @@ -1778,10 +1749,9 @@ - lazy (optional): Setting lazy="true" is a shortcut - equalivalent to specifying the name of the class itself as the proxy - interface. - + lazy (optional, defaults to true): Setting + lazy="false" disables the use of lazy fetching. + @@ -1895,10 +1865,9 @@ - lazy (optional): Setting lazy="true" is a shortcut - equalivalent to specifying the name of the class itself as the proxy - interface. - + lazy (optional, defaults to true): Setting + lazy="false" disables the use of lazy fetching. + @@ -1913,7 +1882,7 @@ - + join @@ -1928,13 +1897,15 @@ + + fetch="join|select" + inverse="true|false" + optional="true|false"> @@ -1962,9 +1933,10 @@ - outer-join (optional - defaults to true): - If disabled for a join defined on a subclass, then rather than joining, a sequential - select will be issued if a row turns out to represent an instance of the subclass. + fetch (optional - defaults to join): + If set to select for a join defined on a subclass, then rather + than joining, a sequential select will be issued only if a row turns out to represent + an instance of the subclass. @@ -1974,6 +1946,13 @@ by this join. + + + optional (optional - defaults to false): + If enabled, Hibernate will insert a row only if the properties defined by this + join are non-null . + + @@ -2529,7 +2508,6 @@ public class Cat { } /** * @hibernate.set - * lazy="true" * inverse="true" * order-by="BIRTH_DATE" * @hibernate.collection-key diff --git a/reference/en/modules/collection_mapping.xml b/reference/en/modules/collection_mapping.xml index 98b973ae01..e830c91a96 100644 --- a/reference/en/modules/collection_mapping.xml +++ b/reference/en/modules/collection_mapping.xml @@ -114,7 +114,7 @@ kittens = cat.getKittens(); //Okay, kittens collection is a Set - + Mapping a Collection @@ -153,7 +153,7 @@ kittens = cat.getKittens(); //Okay, kittens collection is a Set sort="unsorted|natural|comparatorClass" order-by="column_name asc|desc" where="arbitrary sql where condition" - outer-join="true|false|auto" + fetch="join|select" batch-size="N" access="field|property|ClassName" > @@ -182,8 +182,8 @@ kittens = cat.getKittens(); //Okay, kittens collection is a Set - lazy (optional - defaults to false) - enable lazy initialization (not used for arrays) + lazy (optional - defaults to true) + enable lazy initialization (not available for arrays) @@ -220,9 +220,9 @@ kittens = cat.getKittens(); //Okay, kittens collection is a Set - outer-join (optional) specify that the collection should be fetched - by outer join, whenever possible. Only one collection may be fetched by outer join per - SQL SELECT. + fetch (optional, defaults to select) Choose + between outer-join fetching and fetching by sequential select. Only one collection + may be fetched by outer join per SQL SELECT. @@ -566,7 +566,7 @@ kittens = cat.getKittens(); //Okay, kittens collection is a Set - + Lazy Initialization @@ -597,10 +597,9 @@ Integer accessLevel = (Integer) permissions.get("accounts"); // Error!]]> - It's possible to use a non-lazy collection. Since lazy initialization can lead to - bugs like that above, non-laziness is the default. However, it is intended that - lazy initialization be used for almost all collections, especially for collections - of entities (for reasons of efficiency). If you define too many non-lazy associations + It's possible to use a non-lazy collection. However, it is intended that lazy + initialization be used for almost all collections, especially for collections + of entities, and is now the default. 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! @@ -610,15 +609,6 @@ Integer accessLevel = (Integer) permissions.get("accounts"); // Error!]]>LazyInitializationException. - - Declare a lazy collection using the optional lazy attribute: - - - - - -]]> - In some application architectures, particularly where the code that accesses data using Hibernate, and the code that uses it are in different application layers, it @@ -692,7 +682,7 @@ Integer accessLevel = (Integer) permissions.get("accounts"); // Error!]]> - + @@ -723,7 +713,7 @@ Integer accessLevel = (Integer) permissions.get("accounts"); // Error!]]> - + @@ -762,7 +752,7 @@ Integer accessLevel = (Integer) permissions.get("accounts"); // Error!]]>Collection) with bag semantics. - + @@ -837,7 +827,7 @@ Integer accessLevel = (Integer) permissions.get("accounts"); // Error!]]> ... - + @@ -848,7 +838,7 @@ Integer accessLevel = (Integer) permissions.get("accounts"); // Error!]]> - + @@ -885,7 +875,7 @@ session.update(category); // The relationship will be saved]]> .... - + @@ -913,13 +903,13 @@ session.update(category); // The relationship will be saved]]> - + ]]> - + @@ -981,7 +971,7 @@ public class Parent { - + @@ -1015,7 +1005,7 @@ alter table child add constraint childfk0 (parent_id) references parent]]> - + @@ -1053,7 +1043,7 @@ alter table child add constraint childfk0 (parent_id) references parent]]> - + diff --git a/reference/en/modules/example_mappings.xml b/reference/en/modules/example_mappings.xml index c37c7be84e..61027dcfab 100644 --- a/reference/en/modules/example_mappings.xml +++ b/reference/en/modules/example_mappings.xml @@ -153,7 +153,7 @@ create sequence employer_id_seq]]> - + @@ -183,7 +183,7 @@ create sequence employer_id_seq]]> - + @@ -278,7 +278,7 @@ alter table author_work - + @@ -290,7 +290,7 @@ alter table author_work - + diff --git a/reference/en/modules/example_weblog.xml b/reference/en/modules/example_weblog.xml index d1c999967f..e3c7ad9764 100644 --- a/reference/en/modules/example_weblog.xml +++ b/reference/en/modules/example_weblog.xml @@ -100,8 +100,7 @@ public class BlogItem { + table="BLOGS"> diff --git a/reference/en/modules/performance.xml b/reference/en/modules/performance.xml index 457b609b4d..2f2bd44e53 100644 --- a/reference/en/modules/performance.xml +++ b/reference/en/modules/performance.xml @@ -209,7 +209,7 @@ achieve much higher performance, where necessary. - + Proxies for Lazy Initialization @@ -218,21 +218,11 @@ - The mapping file declares a class or interface to use as the proxy interface - for that class. The recommended approach is to specify the class itself: + The mapping file may declare an interface to use as the proxy interface for that + class. By default, Hibernate uses a subclass of the class itself. (The proxied + class must implement a default constructor with at least package visibility.) - - ]]> - - or, as a shorthand, just write lazy="true": - - ]]> - - - The runtime type of the proxies will be a subclass of Order. Note that - the proxied class must implement a default constructor with at least package visibility. - - + There are some gotchas to be aware of when extending this approach to polymorphic classes, eg. @@ -240,7 +230,7 @@ ...... - + ..... ]]> @@ -384,7 +374,7 @@ Cat fritz = (Cat) iter.next();]]> behavior by specifying a batch-size in the mapping of Person: - ...]]> + ...]]> Hibernate will now execute only three queries, the pattern is 10, 10, 5. You can see that batch fetching @@ -402,7 +392,7 @@ Cat fritz = (Cat) iter.next();]]> - + ... ]]>