hibernate-orm/reference/en/modules/persistent_classes.xml

<chapter id="persistent-classes" revision="1">
    <title>Persistent Classes</title>

    <para>
        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).
        Persistent classes have, as the name implies, transient and also persistent
        instance stored in the database.
    </para>

    <para>
        Hibernate works best if these classes follow some simple rules, also known
        as the Plain Old Java Object (POJO) programming model. However, Hibernate3
        also allows you to express a domain model as nested dynamic <literal>Map</literal>s,
        if required.
    </para>

    <sect1 id="persistent-classes-pojo">
        <title>A simple POJO example</title>

        <para>
            Most Java applications require a persistent class representing felines.
        </para>

        <programlisting><![CDATA[package eg;
import java.util.Set;
import java.util.Date;

public class Cat {
    private Long id; // identifier
    private String name;
    private Date birthdate;
    private Cat mate;
    private Set kittens
    private Color color;
    private char sex;
    private float weight;

    private void setId(Long id) {
        this.id=id;
    }
    public Long getId() {
        return id;
    }

    void setName(String name) {
        this.name = name;
    }
    public String getName() {
        return name;
    }

    void setMate(Cat mate) {
        this.mate = mate;
    }
    public Cat getMate() {
        return mate;
    }

    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 setKittens(Set kittens) {
        this.kittens = kittens;
    }
    public Set getKittens() {
        return kittens;
    }
    // addKitten not needed by Hibernate
    public void addKitten(Cat kitten) {
        kittens.add(kitten);
    }
    void setSex(char sex) {
        this.sex=sex;
    }
    public char getSex() {
        return sex;
    }
}]]></programlisting>

        <para>
            There are four main rules to follow here:
        </para>


        <sect2 id="persistent-classes-pojo-accessors" revision="1">
            <title>Declare accessors and mutators for persistent fields</title>

            <para>
                <literal>Cat</literal> declares accessor methods for all its persistent fields.
                Many other ORM tools directly persist instance variables. We believe 
                it is far better to decouple this implementation detail from the persistence 
                mechanism. Hibernate persists JavaBeans style properties, and recognizes method 
                names of the form <literal>getFoo</literal>, <literal>isFoo</literal> and
                <literal>setFoo</literal>. You may however switch to direct field access for
                particular properties, if needed.
            </para>

            <para>
                Properties need <emphasis>not</emphasis> be declared public - Hibernate can
                persist a property with a default, <literal>protected</literal> or <literal>
                private</literal> get / set pair.
            </para>
        </sect2>

        <sect2 id="persistent-classes-pojo-constructor" revision="1">
            <title>Implement a no-argument constructor</title>

            <para>
                <literal>Cat</literal> has a no-argument constructor. All
                persistent classes must have a default constructor (which may be non-public) so 
                Hibernate can instantiate them using <literal>Constructor.newInstance()</literal>.
                We recommend to give the constructor at least <emphasis>package</emphasis> visibility
                for runtime proxy generation in Hibernate.
            </para>
        </sect2>

        <sect2 id="persistent-classes-pojo-identifier">
            <title>Provide an identifier property (optional)</title>

            <para>
                <literal>Cat</literal> has a property called <literal>id</literal>. This property 
                holds the primary key column of a database table. The property might have been called 
                anything, and its type might have been any primitive type, any primitive "wrapper" 
                type, <literal>java.lang.String</literal> or <literal>java.util.Date</literal>. (If 
                your legacy database table has composite keys, you can even use a user-defined class 
                with properties of these types - see the section on composite identifiers later.)
            </para>

            <para>
                The identifier property is optional. You can leave it off and let Hibernate keep track 
                of object identifiers internally. However, for many applications it is still
                a good (and very popular) design decision.
            </para>

            <para>
                What's more, some functionality is available only to classes which declare an
                identifier property:
            </para>

            <itemizedlist spacing="compact">
                <listitem>
                    <para>
                        Cascaded updates (see "Lifecycle Objects")
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <literal>Session.saveOrUpdate()</literal>
                    </para>
                </listitem>
            </itemizedlist>

            <para>
                We recommend you declare consistently-named identifier properties on persistent
                classes. We further recommend that you use a nullable (ie. non-primitive) type.
            </para>
        </sect2>

        <sect2 id="persistent-classes-pojo-final">
            <title>Prefer non-final classes (optional)</title>
            <para>
                A central feature of Hibernate, <emphasis>proxies</emphasis>, depends upon the
                persistent class being either non-final, or the implementation of an interface
                that declares all public methods.
            </para>
            <para>
                You can persist <literal>final</literal> classes that do not implement an interface
                with Hibernate, but you won't be able to use proxies - which will limit your options
                for performance tuning somewhat.
            </para>
        </sect2>
        
    </sect1>

    <sect1 id="persistent-classes-inheritance">
        <title>Implementing inheritance</title>

        <para>
            A subclass must also observe the first and second rules. It inherits its
            identifier property from <literal>Cat</literal>.
        </para>

        <programlisting><![CDATA[package eg;

public class DomesticCat extends Cat {
        private String name;

        public String getName() {
                return name;
        }
        protected void setName(String name) {
                this.name=name;
        }
}]]></programlisting>
    </sect1>

    <sect1 id="persistent-classes-equalshashcode">
        <title>Implementing <literal>equals()</literal> and <literal>hashCode()</literal></title>

        <para>
            You have to override the <literal>equals()</literal> and <literal>hashCode()</literal>
            methods if you intend to mix objects of persistent classes (e.g. in a <literal>Set</literal>).
        </para>

        <para>
            <emphasis>This only applies if these objects are loaded in two different
            <literal>Session</literal>s, as Hibernate only guarantees JVM identity (<literal> a == b </literal>,
            the default implementation of <literal>equals()</literal>) inside a single
            <literal>Session</literal>!</emphasis>
        </para>

        <para>
            Even if both objecs <literal>a</literal> and <literal>b</literal> are the same database row
            (they have the same primary key value as their identifier), we can't guarantee that they are
            the same Java instance outside of a particular <literal>Session</literal> context.
        </para>

        <para>
            The most obvious way is to implement <literal>equals()</literal>/<literal>hashCode()</literal>
            by comparing the identifier value of both objects. If the value is the same, both must
            be the same database row, they are therefore equal (if both are added to a <literal>Set</literal>,
            we will only have one element in the <literal>Set</literal>). Unfortunately, we can't use that
            approach. Hibernate will only assign identifier values to objects that are persistent,
            a newly created instance will not have any identifier value! We recommend implementing
            <literal>equals()</literal> and <literal>hashCode()</literal> using
            <emphasis>Business key equality</emphasis>.
        </para>

        <para>
            Business key equality means that the <literal>equals()</literal>
            method compares only the properties that form the business key, a key that would
            identify our instance in the real world (a <emphasis>natural</emphasis> candidate key):
        </para>

        <programlisting><![CDATA[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 (!getName().equals(cat.getName())) return false;
        if (!getBirthday().equals(cat.getBirthday())) return false;

        return true;
    }

    public int hashCode() {
        int result;
        result = getName().hashCode();
        result = 29 * result + getBirthday().hashCode();
        return result;
    }

}]]></programlisting>

        <para>
            Keep in mind that our candidate key (in this case a composite of name and birthday)
            has to be only valid for a particular comparison operation (maybe even only in a
            single use case). We don't need the stability criteria we usually apply to a real
            primary key!
        </para>

    </sect1>

    <sect1 id="persistent-classes-dynamic">
        <title>Dynamic models</title>

        <para>
            Hibernate also supports dynamic domain models, using <literal>Map</literal>s of
            <literal>Map</literal>s. With this approach, you don't write persistent classes,
            a Hibernate mapping file for each "entity" is sufficient:
        </para>

        <programlisting><![CDATA[<hibernate-mapping>
    <dynamic-class entity-name="TestMap">
        <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="parent" column="PARENT_ID" class="TestMap"/>
        <bag name="children" inverse="true" lazy="false">
            <key column="PARENT_ID"/>
            <one-to-many class="TestMap"/>
        </bag>
    </dynamic-class>
</hibernate-mapping>]]></programlisting>

        <para>
            At runtime, you only use <literal>Map</literal>s and use the Hibernate entity
            name to refer to a particular type.
        </para>

        <programlisting><![CDATA[Session s = openSession();
Map parent = new HashMap();
parent.put("type", "TestMap");
parent.put("name", "foo");
parent.put("address", "bar");

Map child = new HashMap();
child.put("type", "TestMap");
child.put("name", "fooTwo");
child.put("address", "barTwo");
child.put("parent", parent);

s.save(parent);
s.save(child);
]]></programlisting>

        <!-- TODO: Document user-extension framework in the property and proxy package -->
        <para>
            TODO: Document user-extension framework in the property and proxy package
        </para>

    </sect1>

</chapter>