From 593064b71f01dd51520bd95e5b0bc5d24b31b1ce Mon Sep 17 00:00:00 2001 From: Emmanuel Bernard Date: Fri, 23 Apr 2010 17:09:47 +0000 Subject: [PATCH] HHH-5152 @Entity description git-svn-id: https://svn.jboss.org/repos/hibernate/core/trunk@19286 1b8cb986-b30d-0410-93ca-fae66ebed9b2 --- .../docbook/en-US/content/basic_mapping.xml | 306 ++++++++++++------ 1 file changed, 214 insertions(+), 92 deletions(-) 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 09dc108865..20ae700f9f 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 @@ -374,10 +374,218 @@ public class Dog { ... }
- Class + Entity - You can declare a persistent class using the - class element. For example: + An entity is a regular Java object (aka POJO) which will be + persisted by Hibernate. + + To mark an object as an entity in annotations, use the + @Entity annotation. + + @Entity +public class Flight implements Serializable { + Long id; + + @Id + public Long getId() { return id; } + + public void setId(Long id) { this.id = id; } +} + + That's pretty much it, the rest is optional. There are however any + options to tweak your entity mapping, let's explore them. + + @Table lets you define the table the entity + will be persisted into. If undefined, the table name is the unqualified + class name of the entity. You can also optionally define the catalog, + the schema as well as unique constraints on the table. + + @Entity +@Table(name="TBL_FLIGHT", + schema="AIR_COMMAND", + uniqueConstraints= + @UniqueConstraint( + name="flight_number", + columnNames={"comp_prefix", "flight_number"} ) ) +public class Flight implements Serializable { + @Column(name="comp_prefix") + public String getCompagnyPrefix() { return companyPrefix; } + + @Column(name="flight_number") + public String getNumber() { return number; } +} + + The constraint name is optional (generated if left undefined). The + column names composing the constraint correspond to the column names as + defined before the Hibernate NamingStrategy is + applied. + + @Entity.name lets you define the shortcut name + of the entity you can used in JP-QL and HQL queries. It defaults to the + unqualified class name of the class. + + Hibernate goes beyond the JPA specification and provide additional + configurations. Some of them are hosted on + @org.hibernate.annotations.Entity: + + + + mutable (defaults to true): Immutable + classes, mutable=false, cannot be updated or + deleted by the application. This allows Hibernate to make some minor + performance optimizations. + + + + dynamicInsert / + dynamicUpdate (defaults to false): specifies that + INSERT / UPDATE SQL should be + generated at runtime and contain only the columns whose values are + not null. The dynamic-update and + dynamic-insert settings are not inherited by + subclasses. Although these settings can increase performance in some + cases, they can actually decrease performance in others. + + + + selectBeforeUpdate (defaults to false): + specifies that Hibernate should never perform + an SQL UPDATE unless it is certain that an object + is actually modified. Only when a transient object has been + associated with a new session using update(), + will Hibernate perform an extra SQL SELECT to + determine if an UPDATE is actually required. Use + of select-before-update will usually decrease + performance. It is useful to prevent a database update trigger being + called unnecessarily if you reattach a graph of detached instances + to a Session. + + + + polymorphism (defaults to + IMPLICIT): determines whether implicit or + explicit query polymorphism is used. Implicit + polymorphism means that instances of the class will be returned by a + query that names any superclass or implemented interface or class, + and that instances of any subclass of the class will be returned by + a query that names the class itself. Explicit + polymorphism means that class instances will be returned only by + queries that explicitly name that class. Queries that name the class + will return only instances of subclasses mapped. For most purposes, + the default polymorphism=IMPLICIT is appropriate. + Explicit polymorphism is useful when two different classes are + mapped to the same table This allows a "lightweight" class that + contains a subset of the table columns. + + + + persister: specifies a custom + ClassPersister. The persister + attribute lets you customize the persistence strategy used for the + class. You can, for example, specify your own subclass of + org.hibernate.persister.EntityPersister, or you + can even provide a completely new implementation of the interface + org.hibernate.persister.ClassPersister that + implements, for example, persistence via stored procedure calls, + serialization to flat files or LDAP. See + org.hibernate.test.CustomPersister for a simple + example of "persistence" to a Hashtable. + + + + optimisticLock (defaults to + VERSION): determines the optimistic locking + strategy. If you enable dynamicUpdate, you will + have a choice of optimistic locking strategies: + + + + version: check the version/timestamp + columns + + + + all: check all columns + + + + dirty: check the changed columns, + allowing some concurrent updates + + + + none: do not use optimistic + locking + + + + It is strongly recommended that you use + version/timestamp columns for optimistic locking with Hibernate. + This strategy optimizes performance and correctly handles + modifications made to detached instances (i.e. when + Session.merge() is used). + + + + + Be sure to import + @javax.persistence.Entity to mark a class as an + entity. It's a common mistake to import + @org.hibernate.annotations.Entity by + accident. + + + You can also alter how Hibernate deals with lazy initialization + for this class. On @Proxy, use + lazy=false to disable lazy fetching (not + recommended). You can also specify an interface to use for lazy + initializing proxies (defaults to the class itself): use + proxyClass on @Proxy. + Hibernate will initially return proxies (Javassist or CGLIB) that + implement the named interface. The persistent object will load when a + method of the proxy is invoked. See "Initializing collections and + proxies" below. + + @BatchSize specifies a "batch size" for + fetching instances of this class by identifier. Not yet loaded instances + are loaded batch-size at a time (default 1). + + You can specific an arbitrary SQL WHERE condition to be used when + retrieving objects of this class. Use @Where for + that. + + In the same vein, @Check lets you define an + SQL expression used to generate a multi-row check + constraint for automatic schema generation. + + There is no difference between a view and a base table for a + Hibernate mapping. This is transparent at the database level, although + some DBMS do not support views properly, especially with updates. + Sometimes you want to use a view, but you cannot create one in the + database (i.e. with a legacy schema). In this case, you can map an + immutable and read-only entity to a given SQL subselect expression using + @org.hibernate.annotations.Subselect: + + @Entity +@Subselect("select item.name, max(bid.amount), count(*) " + + "from item " + + "join bid on bid.item_id = item.id " + + "group by item.name") +@Synchronize( {"item", "bid"} ) //tables impacted +public class Summary { + @Id + public String getId() { return id; } + ... +} + + Declare the tables to synchronize this entity with, ensuring that + auto-flush happens correctly and that queries against the derived entity + do not return stale data. The <subselect> is + available both as an attribute and a nested mapping element. + + We will now explore the same options using the hbm.xml structure. + You can declare a persistent class using the class + element. For example: @@ -600,91 +808,7 @@ public class Dog { ... } static inner class. Specify the class name using the standard form i.e. e.g.Foo$Bar. - Immutable classes, mutable="false", cannot be - updated or deleted by the application. This allows Hibernate to make - some minor performance optimizations. - - The optional proxy attribute enables lazy - initialization of persistent instances of the class. Hibernate will - initially return CGLIB proxies that implement the named interface. The - persistent object will load when a method of the proxy is invoked. See - "Initializing collections and proxies" below. - - Implicit polymorphism means that instances of - the class will be returned by a query that names any superclass or - implemented interface or class, and that instances of any subclass of - the class will be returned by a query that names the class itself. - Explicit polymorphism means that class instances - will be returned only by queries that explicitly name that class. - Queries that name the class will return only instances of subclasses - mapped inside this <class> declaration as a - <subclass> or - <joined-subclass>. For most purposes, the - default polymorphism="implicit" is appropriate. - Explicit polymorphism is useful when two different classes are mapped to - the same table This allows a "lightweight" class that contains a subset - of the table columns. - - The persister attribute lets you customize the - persistence strategy used for the class. You can, for example, specify - your own subclass of - org.hibernate.persister.EntityPersister, or you can - even provide a completely new implementation of the interface - org.hibernate.persister.ClassPersister that - implements, for example, persistence via stored procedure calls, - serialization to flat files or LDAP. See - org.hibernate.test.CustomPersister for a simple - example of "persistence" to a Hashtable. - - The dynamic-update and - dynamic-insert settings are not inherited by - subclasses, so they can also be specified on the - <subclass> or - <joined-subclass> elements. Although these - settings can increase performance in some cases, they can actually - decrease performance in others. - - Use of select-before-update will usually - decrease performance. It is useful to prevent a database update trigger - being called unnecessarily if you reattach a graph of detached instances - to a Session. - - If you enable dynamic-update, you will have a - choice of optimistic locking strategies: - - - - version: check the version/timestamp - columns - - - - all: check all columns - - - - dirty: check the changed columns, allowing - some concurrent updates - - - - none: do not use optimistic locking - - - - It is strongly recommended that you use - version/timestamp columns for optimistic locking with Hibernate. This - strategy optimizes performance and correctly handles modifications made - to detached instances (i.e. when Session.merge() is - used). - - There is no difference between a view and a base table for a - Hibernate mapping. This is transparent at the database level, although - some DBMS do not support views properly, especially with updates. - Sometimes you want to use a view, but you cannot create one in the - database (i.e. with a legacy schema). In this case, you can map an - immutable and read-only entity to a given SQL subselect - expression: + Here is how to do a virtual view (subselect) in XML: <class name="Summary"> <subselect> @@ -699,10 +823,8 @@ public class Dog { ... } ... </class> - Declare the tables to synchronize this entity with, ensuring that - auto-flush happens correctly and that queries against the derived entity - do not return stale data. The <subselect> is - available both as an attribute and a nested mapping element. + The <subselect> is available both as an + attribute and a nested mapping element.