Hibernate.org Community Documentation

- Précédent
- Suivant

## Chapitre 4. Classes persistantes

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 (see Section 11.1, « États des objets Hibernate » 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 of `java.util.Map` instances, for example).

## 4.1. Un exemple simple de POJO

Exemple 4.1. Simple POJO representing a cat

    package eg;

    import java.util.Set;

    import java.util.Date;

    public class Cat {

    private Long id; // identifier

    private 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.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);

        }

    }

On explore quatre règles principales de classes persistantes en détail dans les sections qui suivent :

### 4.1.1. Implémenter un constructeur sans argument

`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 using ``java.lang.reflect.Constructor`.newInstance()`. It is recommended that this constructor be defined with at least package visibility in order for runtime proxy generation to work properly.

### 4.1.2. Provide an identifier property

## Note

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 named `id`. 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 ???). See Section 9.4, « Les composants en tant qu'identifiants composites » for information on mapping composite (multi-column) identifiers.

## Note

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.

Nous recommandons que vous déclariez les propriétés d'identifiant de manière uniforme. Nous recommandons également que vous utilisiez un type nullable (c'est-à-dire non primitif).

### 4.1.3. Prefer non-final classes (semi-optional)

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 persist `final` 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 a `final` class which does not implement a "full" interface you must disable proxy generation. See Exemple 4.2, « Disabling proxies in hbm.xml » and Exemple 4.3, « Disabling proxies in annotations ».

Exemple 4.2. Disabling proxies in `hbm.xml`

    <class name="Cat" lazy="false"...>...</class>

Exemple 4.3. Disabling proxies in annotations

    @Entity @Proxy(lazy=false) public class Cat { ... }

If the `final` class does implement a proper interface, you could alternatively tell Hibernate to use the interface instead when generating the proxies. See Exemple 4.4, « Proxying an interface in hbm.xml » and Exemple 4.5, « Proxying an interface in annotations ».

Exemple 4.4. Proxying an interface in `hbm.xml`

    <class name="Cat" proxy="ICat"...>...</class>

Exemple 4.5. Proxying an interface in annotations

    @Entity @Proxy(proxyClass=ICat.class) public class Cat implements ICat { ... }

You should also avoid declaring `public final` methods as this will again limit the ability to generate proxies from this class. If you want to use a class with `public final` methods, you must explicitly disable proxying. Again, see Exemple 4.2, « Disabling proxies in hbm.xml » and Exemple 4.3, « Disabling proxies in annotations ».

### 4.1.4. Déclarer les accesseurs et mutateurs des attributs persistants (optionnel)

`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 form `getFoo`, `isFoo` and `setFoo`. If required, you can switch to direct field access for particular properties.

Properties need not be declared public. Hibernate can persist a property declared with `package`, `protected` or `private` visibility as well.

## 4.2. Implémenter l'héritage

Une sous-classe doit également suivre la première et la seconde règle. Elle hérite sa propriété d'identifiant de la classe mère `Cat`. Par exemple :

    package eg;

    public class DomesticCat extends Cat {

            private String name;

            public String getName() {

                    return name;

            }

            protected void setName(String name) {

                    this.name=name;

            }

    }

## 4.3. Implémenter `equals()` et `hashCode()`

Vous devez surcharger les méthodes `equals()` et `hashCode()` si vous :

- avez l'intention de mettre des instances de classes persistantes dans un `Set` (la manière recommandée pour représenter des associations pluri-valuées); et

- avez l'intention d'utiliser le rattachement d'instances détachées

Hibernate garantit l'équivalence de l'identité persistante (ligne de base de données) et l'identité Java seulement à l'intérieur de la portée d'une session particulière. Donc dès que nous mélangeons des instances venant de différentes sessions, nous devons implémenter `equals()` et `hashCode()` si nous souhaitons avoir une sémantique correcte pour les `Set` s.

La manière la plus évidente est d'implémenter `equals()`/`hashCode()` en comparant la valeur de l'identifiant des deux objets. Si cette valeur est identique, les deux doivent représenter la même ligne de base de données, ils sont donc égaux (si les deux sont ajoutés à un `Set`, nous n'aurons qu'un seul élément dans le `Set`). Malheureusement, nous ne pouvons pas utiliser cette approche avec des identifiants générés ! Hibernate n'assignera de valeur d'identifiant qu'aux objets qui sont persistants, une instance nouvellement créée n'aura donc pas de valeur d'identifiant ! De plus, si une instance est non sauvegardée et actuellement dans un `Set`, le sauvegarder assignera une valeur d'identifiant à l'objet. Si `equals()` et `hashCode()` sont basées sur la valeur de l'identifiant, le code de hachage devrait changer, rompant le contrat du `Set`. Consultez le site web de Hibernate pour des informations plus approfondies. Notez que ceci n'est pas un problème Hibernate, mais concerne la sémantique normale de Java pour l'identité et l'égalité d'un objet.

Nous recommandons donc d'implémenter `equals()` et `hashCode()` en utilisant l'égalité par clé métier. L'égalité par clé métier signifie que la méthode `equals()` compare uniquement les propriétés qui forment une clé métier, une clé qui identifierait notre instance dans le monde réel (une clé candidate naturelle) :

    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 (see Section 13.1.3, « L'identité des objets »). Immutable or unique properties are usually good candidates for a business key.

## 4.4. Modèles dynamiques

## Remarque

The following features are currently considered experimental and may change in the near future.

Les entités persistantes ne doivent pas nécessairement être représentées comme des classes POJO ou des objets JavaBean à l'exécution. Hibernate supporte aussi les modèles dynamiques (en utilisant des `Map` s de `Map` s à l'exécution) et la représentation des entités comme des arbres DOM4J. Avec cette approche, vous n'écrivez pas de classes persistantes, seulement des fichiers de mappage.

By default, Hibernate works in normal POJO mode. You can set a default entity representation mode for a particular `SessionFactory` using the `default_entity_mode` configuration option (see Tableau 3.3, « Propriétés de configuration Hibernate »).

Les exemples suivants démontrent la représentation utilisant des `Map` s. D'abord, dans le fichier de mappage, un `entity-name` doit être déclaré au lieu (ou en plus) d'un nom de classe :

    <hibernate-mapping>

        <class entity-name="Customer">

            <id name="id"

                type="long"

                column="ID">

                <generator class="sequence"/>

            </id>

            <property name="name"

                column="NAME"

                type="string"/>

            <property name="address"

                column="ADDRESS"

                type="string"/>

            <many-to-one name="organization"

                column="ORGANIZATION_ID"

                class="Organization"/>

            <bag name="orders"

                inverse="true"

                lazy="false"

                cascade="all">

                <key column="CUSTOMER_ID"/>

                <one-to-many class="Order"/>

            </bag>

        </class>

    </hibernate-mapping>

Notez que même si des associations sont déclarées en utilisant des noms de classe cible, le type de cible d'une association peut aussi être une entité dynamique au lieu d'un POJO.

Après avoir configuré le mode d'entité par défaut à `dynamic-map` pour la `SessionFactory`, nous pouvons lors de l'exécution fonctionner avec des `Map` s de `Map` s :

    Session s = openSession();

    Transaction tx = s.beginTransaction();

    // Create a customer

    Map david = new HashMap();

    david.put("name", "David");

    // Create an organization

    Map foobar = new HashMap();

    foobar.put("name", "Foobar Inc.");

    // Link both

    david.put("organization", foobar);

    // Save both

    s.save("Customer", david);

    s.save("Organization", foobar);

    tx.commit();

    s.close();

Les avantages d'un mappage dynamique sont un gain de temps pour le prototypage sans la nécessité d'implémenter les classes d'entité. Pourtant, vous perdez la vérification du typage au moment de la compilation et aurez plus d'exceptions à gérer lors de l'exécution. Grâce au mappage de Hibernate, le schéma de la base de données peut facilement être normalisé et solidifié, permettant de rajouter une implémentation propre du modèle de domaine plus tard.

Les modes de représentation d'une entité peuvent aussi être configurés en se basant sur `Session` :

    Session dynamicSession = pojoSession.getSession(EntityMode.MAP);

    // Create a customer

    Map david = new HashMap();

    david.put("name", "David");

    dynamicSession.save("Customer", david);

    ...

    dynamicSession.flush();

    dynamicSession.close()

    ...

    // Continue on pojoSession

Veuillez noter que l'appel à `getSession()` en utilisant un `EntityMode` se fait sur l'API `Session`, et non sur `SessionFactory`. De cette manière, la nouvelle `Session` partage les connexions JDBC, transactions et autres informations de contexte sous-jacentes. Cela signifie que vous n'avez pas à appeler `flush()` et `close()` sur la `Session` secondaire, et laissez aussi la gestion de la transaction et de la connexion à l'unité de travail primaire.

More information about the XML representation capabilities can be found in Chapitre 20, Mappage XML.

## 4.5. Tuplizers

`org.hibernate.tuple.Tuplizer` and its sub-interfaces are responsible for managing a particular representation of a piece of data given that representation's `org.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 that `java.util.Map` implementation other than `java.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 our `Customer` entity, Exemple 4.6, « Specify custom tuplizers in annotations » shows how to specify a custom `org.hibernate.tuple.entity.EntityTuplizer` using annotations while Exemple 4.7, « Specify custom tuplizers in hbm.xml » shows how to do the same in `hbm.xml`

Exemple 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);

    }

Exemple 4.7. Specify custom tuplizers in `hbm.xml`

    <hibernate-mapping>

        <class entity-name="Customer">

            <!--

                Override the dynamic-map entity-mode

                tuplizer for the customer entity

            -->

            <tuplizer entity-mode="dynamic-map"

                    class="CustomMapTuplizerImpl"/>

            <id name="id" type="long" column="ID">

                <generator class="sequence"/>

            </id>

            <!-- other properties -->

            ...

        </class>

    </hibernate-mapping>

## 4.6. EntityNameResolvers

`org.hibernate.EntityNameResolver` is a contract for resolving the entity name of a given entity instance. The interface defines a single method `resolveEntityName` 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, an `org.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 the org.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;

        }

        ...

Pour enregistrer un `org.hibernate.EntityNameResolver`, les utilisateurs doivent soit :

1. Implement a custom tuplizer (see Section 4.5, « Tuplizers »), implementing the `getEntityNameResolvers` method

2. L'enregistrer dans `org.hibernate.impl.SessionFactoryImpl` (qui est la classe d'implémentation de `org.hibernate.SessionFactory`) à l'aide de la méthode `registerEntityNameResolver`.

Copyright © 2004 Red Hat, Inc.

- PrécédentChapitre 3. Configuration
- Niveau supérieur
- Sommaire
- SuivantChapitre 5. Mappage O/R de base