Hibernate.orgCommunity Documentation
Table of Contents
Persistent classes are classes in an application that implement the entities of the business problem (e.g. Customer and Order in an E-commerce application). The term "persistent" here means that the classes are able to be persisted, not that they are in the persistent state (seeSection 11.1, “Hibernate object states” for discussion).
Hibernate works best if these classes follow some simple rules, also known as the Plain Old Java Object (POJO) programming model. However, none of these rules are hard requirements. Indeed, Hibernate assumes very little about the nature of your persistent objects. You can express a domain model in other ways (using trees ofjava.util.Map instances, for example).
Example 4.1. Simple POJO representing a cat
package eg;import java.util.Set;import java.util.Date;public class Cat {private Long id; // identifierprivate Date birthdate;private Color color;private char sex;private float weight; private int litterId; private Cat mother; private Set kittens = new HashSet(); private void setId(Long id) { this.xml:id=id; } public Long getId() { return id; } void setBirthdate(Date date) { birthdate = date; } public Date getBirthdate() { return birthdate; } void setWeight(float weight) { this.weight = weight; } public float getWeight() { return weight; } public Color getColor() { return color; } void setColor(Color color) { this.color = color; } void setSex(char sex) { this.sex=sex; } public char getSex() { return sex; } void setLitterId(int id) { this.litterId = id; } public int getLitterId() { return litterId; } void setMother(Cat mother) { this.mother = mother; } public Cat getMother() { return mother; } void setKittens(Set kittens) { this.kittens = kittens; } public Set getKittens() { return kittens; } // addKitten not needed by Hibernate public void addKitten(Cat kitten) { kitten.setMother(this); kitten.setLitterId( kittens.size() ); kittens.add(kitten); }}The four main rules of persistent classes are explored in more detail in the following sections.
Cat has a no-argument constructor. All persistent classes must have a default constructor (which can be non-public) so that Hibernate can instantiate them usingjava.lang.reflect.Constructor.newInstance(). It is recommended that this constructor be defined with at leastpackage visibility in order for runtime proxy generation to work properly.
Historically this was considered option. While still not (yet) enforced, this should be considered a deprecated feature as it will be completely required to provide a identifier property in an upcoming release.
Cat has a property namedid. This property maps to the primary key column(s) of the underlying database table. The type of the identifier property can be any "basic" type (see???). SeeSection 9.4, “Components as composite identifiers” for information on mapping composite (multi-column) identifiers.
Identifiers do not necessarily need to identify column(s) in the database physically defined as a primary key. They should just identify columns that can be used to uniquely identify rows in the underlying table.
We recommend that you declare consistently-named identifier properties on persistent classes and that you use a nullable (i.e., non-primitive) type.
A central feature of Hibernate,proxies (lazy loading), depends upon the persistent class being either non-final, or the implementation of an interface that declares all public methods. You can persistfinal classes that do not implement an interface with Hibernate; you will not, however, be able to use proxies for lazy association fetching which will ultimately limit your options for performance tuning. To persist afinal class which does not implement a "full" interface you must disable proxy generation. SeeExample 4.2, “Disabling proxies inhbm.xml” andExample 4.3, “Disabling proxies in annotations”.
If thefinal class does implement a proper interface, you could alternatively tell Hibernate to use the interface instead when generating the proxies. SeeExample 4.4, “Proxying an interface inhbm.xml” andExample 4.5, “Proxying an interface in annotations”.
Example 4.5. Proxying an interface in annotations
@Entity @Proxy(proxyClass=ICat.class) public class Cat implements ICat { ... } You should also avoid declaringpublic final methods as this will again limit the ability to generateproxies from this class. If you want to use a class withpublic final methods, you must explicitly disable proxying. Again, seeExample 4.2, “Disabling proxies inhbm.xml” andExample 4.3, “Disabling proxies in annotations”.
Cat declares accessor methods for all its persistent fields. Many other ORM tools directly persist instance variables. It is better to provide an indirection between the relational schema and internal data structures of the class. By default, Hibernate persists JavaBeans style properties and recognizes method names of the formgetFoo,isFoo andsetFoo. If required, you can switch to direct field access for particular properties.
Properties neednot be declared public. Hibernate can persist a property declared withpackage,protected orprivate visibility as well.
A subclass must also observe the first and second rules. It inherits its identifier property from the superclass,Cat. For example:
package eg;public class DomesticCat extends Cat { private String name; public String getName() { return name; } protected void setName(String name) { this.name=name; }}You have to override theequals() andhashCode() methods if you:
intend to put instances of persistent classes in aSet (the recommended way to represent many-valued associations);and
intend to use reattachment of detached instances
Hibernate guarantees equivalence of persistent identity (database row) and Java identity only inside a particular session scope. When you mix instances retrieved in different sessions, you must implementequals() andhashCode() if you wish to have meaningful semantics forSets.
The most obvious way is to implementequals()/hashCode() by comparing the identifier value of both objects. If the value is the same, both must be the same database row, because they are equal. If both are added to aSet, you will only have one element in theSet). Unfortunately, you cannot use that approach with generated identifiers. Hibernate will only assign identifier values to objects that are persistent; a newly created instance will not have any identifier value. Furthermore, if an instance is unsaved and currently in aSet, saving it will assign an identifier value to the object. Ifequals() andhashCode() are based on the identifier value, the hash code would change, breaking the contract of theSet. See the Hibernate website for a full discussion of this problem. This is not a Hibernate issue, but normal Java semantics of object identity and equality.
It is recommended that you implementequals() andhashCode() usingBusiness key equality. Business key equality means that theequals() method compares only the properties that form the business key. It is a key that would identify our instance in the real world (anatural candidate key):
public class Cat { ... public boolean equals(Object other) { if (this == other) return true; if ( !(other instanceof Cat) ) return false; final Cat cat = (Cat) other; if ( !cat.getLitterId().equals( getLitterId() ) ) return false; if ( !cat.getMother().equals( getMother() ) ) return false; return true; } public int hashCode() { int result; result = getMother().hashCode(); result = 29 * result + getLitterId(); return result; }}A business key does not have to be as solid as a database primary key candidate (seeSection 13.1.3, “Considering object identity”). Immutable or unique properties are usually good candidates for a business key.
The following features are currently considered experimental and may change in the near future.
Persistent entities do not necessarily have to be represented as POJO classes or as JavaBean objects at runtime. Hibernate also supports dynamic models (usingMaps ofMaps at runtime). With this approach, you do not write persistent classes, only mapping files.
By default, Hibernate works in normal POJO mode. You can set a default entity representation mode for a particularSessionFactory using thedefault_entity_mode configuration option (seeTable 3.3, “Hibernate Configuration Properties”).
The following examples demonstrate the representation usingMaps. First, in the mapping file anentity-name has to be declared instead of, or in addition to, a class name:
<hibernate-mapping> <class entity-name="Customer"> <id name="id" type="long" column="ID"> <generator/> </id> <property name="name" column="NAME" type="string"/> <property name="address" column="ADDRESS" type="string"/> <many-to-one name="organization" column="ORGANIZATION_ID" /> <bag name="orders" inverse="true" lazy="false" cascade="all"> <key column="CUSTOMER_ID"/> <one-to-many/> </bag> </class> </hibernate-mapping>
Even though associations are declared using target class names, the target type of associations can also be a dynamic entity instead of a POJO.
After setting the default entity mode todynamic-map for theSessionFactory, you can, at runtime, work withMaps ofMaps:
Session s = openSession();Transaction tx = s.beginTransaction();// Create a customerMap david = new HashMap();david.put("name", "David");// Create an organizationMap foobar = new HashMap();foobar.put("name", "Foobar Inc.");// Link bothdavid.put("organization", foobar);// Save boths.save("Customer", david);s.save("Organization", foobar);tx.commit();s.close();One of the main advantages of dynamic mapping is quick turnaround time for prototyping, without the need for entity class implementation. However, you lose compile-time type checking and will likely deal with many exceptions at runtime. As a result of the Hibernate mapping, the database schema can easily be normalized and sound, allowing to add a proper domain model implementation on top later on.
Entity representation modes can also be set on a perSession basis:
Session dynamicSession = pojoSession.getSession(EntityMode.MAP);// Create a customerMap david = new HashMap();david.put("name", "David");dynamicSession.save("Customer", david);...dynamicSession.flush();dynamicSession.close()...// Continue on pojoSessionPlease note that the call togetSession() using anEntityMode is on theSession API, not theSessionFactory. That way, the newSession shares the underlying JDBC connection, transaction, and other context information. This means you do not have to callflush() andclose() on the secondarySession, and also leave the transaction and connection handling to the primary unit of work.
org.hibernate.tuple.Tuplizer and its sub-interfaces are responsible for managing a particular representation of a piece of data given that representation'sorg.hibernate.EntityMode. If a given piece of data is thought of as a data structure, then a tuplizer is the thing that knows how to create such a data structure, how to extract values from such a data structure and how to inject values into such a data structure. For example, for the POJO entity mode, the corresponding tuplizer knows how create the POJO through its constructor. It also knows how to access the POJO properties using the defined property accessors.
There are two (high-level) types of Tuplizers:
org.hibernate.tuple.entity.EntityTuplizer which is responsible for managing the above mentioned contracts in regards to entities
org.hibernate.tuple.component.ComponentTuplizer which does the same for components
Users can also plug in their own tuplizers. Perhaps you require thatjava.util.Map implementation other thanjava.util.HashMap be used while in the dynamic-map entity-mode. Or perhaps you need to define a different proxy generation strategy than the one used by default. Both would be achieved by defining a custom tuplizer implementation. Tuplizer definitions are attached to the entity or component mapping they are meant to manage. Going back to the example of ourCustomer entity,Example 4.6, “Specify custom tuplizers in annotations” shows how to specify a customorg.hibernate.tuple.entity.EntityTuplizer using annotations whileExample 4.7, “Specify custom tuplizers inhbm.xml” shows how to do the same inhbm.xml
Example 4.6. Specify custom tuplizers in annotations
@Entity@Tuplizer(impl = DynamicEntityTuplizer.class)public interface Cuisine { @Id @GeneratedValue public Long getId(); public void setId(Long id); public String getName(); public void setName(String name); @Tuplizer(impl = DynamicComponentTuplizer.class) public Country getCountry(); public void setCountry(Country country);}Example 4.7. Specify custom tuplizers inhbm.xml
<hibernate-mapping> <class entity-name="Customer"> <!-- Override the dynamic-map entity-mode tuplizer for the customer entity --> <tuplizer entity-mode="dynamic-map" /> <id name="id" type="long" column="ID"> <generator/> </id> <!-- other properties --> ... </class></hibernate-mapping>
org.hibernate.EntityNameResolver is a contract for resolving the entity name of a given entity instance. The interface defines a single methodresolveEntityName which is passed the entity instance and is expected to return the appropriate entity name (null is allowed and would indicate that the resolver does not know how to resolve the entity name of the given entity instance). Generally speaking, anorg.hibernate.EntityNameResolver is going to be most useful in the case of dynamic models. One example might be using proxied interfaces as your domain model. The hibernate test suite has an example of this exact style of usage under theorg.hibernate.test.dynamicentity.tuplizer2. Here is some of the code from that package for illustration.
/** * A very trivial JDK Proxy InvocationHandler implementation where we proxy an * interface as the domain model and simply store persistent state in an internal * Map. This is an extremely trivial example meant only for illustration. */public final class DataProxyHandler implements InvocationHandler {private String entityName;private HashMap data = new HashMap();public DataProxyHandler(String entityName, Serializable id) {this.entityName = entityName;data.put( "Id", id );}public Object invoke(Object proxy, Method method, Object[] args) throws Throwable {String methodName = method.getName();if ( methodName.startsWith( "set" ) ) {String propertyName = methodName.substring( 3 );data.put( propertyName, args[0] );}else if ( methodName.startsWith( "get" ) ) {String propertyName = methodName.substring( 3 );return data.get( propertyName );}else if ( "toString".equals( methodName ) ) {return entityName + "#" + data.get( "Id" );}else if ( "hashCode".equals( methodName ) ) {return new Integer( this.hashCode() );}return null;}public String getEntityName() {return entityName;}public HashMap getData() {return data;}}public class ProxyHelper { public static String extractEntityName(Object object) { // Our custom java.lang.reflect.Proxy instances actually bundle // their appropriate entity name, so we simply extract it from there // if this represents one of our proxies; otherwise, we return null if ( Proxy.isProxyClass( object.getClass() ) ) { InvocationHandler handler = Proxy.getInvocationHandler( object ); if ( DataProxyHandler.class.isAssignableFrom( handler.getClass() ) ) { DataProxyHandler myHandler = ( DataProxyHandler ) handler; return myHandler.getEntityName(); } } return null; } // various other utility methods ....}/** * The EntityNameResolver implementation. * * IMPL NOTE : An EntityNameResolver really defines a strategy for how entity names * should be resolved. Since this particular impl can handle resolution for all of our * entities we want to take advantage of the fact that SessionFactoryImpl keeps these * in a Set so that we only ever have one instance registered. Why? Well, when it * comes time to resolve an entity name, Hibernate must iterate over all the registered * resolvers. So keeping that number down helps that process be as speedy as possible. * Hence the equals and hashCode implementations as is */public class MyEntityNameResolver implements EntityNameResolver { public static final MyEntityNameResolver INSTANCE = new MyEntityNameResolver(); public String resolveEntityName(Object entity) { return ProxyHelper.extractEntityName( entity ); } public boolean equals(Object obj) { return getClass().equals( obj.getClass() ); } public int hashCode() { return getClass().hashCode(); }}public class MyEntityTuplizer extends PojoEntityTuplizer {public MyEntityTuplizer(EntityMetamodel entityMetamodel, PersistentClass mappedEntity) {super( entityMetamodel, mappedEntity );}public EntityNameResolver[] getEntityNameResolvers() {return new EntityNameResolver[] { MyEntityNameResolver.INSTANCE };} public String determineConcreteSubclassEntityName(Object entityInstance, SessionFactoryImplementor factory) { String entityName = ProxyHelper.extractEntityName( entityInstance ); if ( entityName == null ) { entityName = super.determineConcreteSubclassEntityName( entityInstance, factory ); } return entityName; } ... In order to register anorg.hibernate.EntityNameResolver users must either:
Implement a custom tuplizer (seeSection 4.5, “Tuplizers”), implementing thegetEntityNameResolvers method
Register it with theorg.hibernate.impl.SessionFactoryImpl (which is the implementation class fororg.hibernate.SessionFactory) using theregisterEntityNameResolver method.