<?xml version='1.0' encoding="UTF-8"?>
<!--
  ~ Hibernate, Relational Persistence for Idiomatic Java
  ~
  ~ License: GNU Lesser General Public License (LGPL), version 2.1 or later.
  ~ See the lgpl.txt file in the root directory or <http://www.gnu.org/licenses/lgpl-2.1.html>.
  -->
<chapter xml:id="types" xmlns="http://docbook.org/ns/docbook">
    <title>Types</title>

    <para>
        As an Object/Relational Mapping solution, Hibernate deals with both the Java and JDBC representations of
        application data.  An online catalog application, for example, most likely has <classname>Product</classname>
        object with a number of attributes such as a <literal>sku</literal>, <literal>name</literal>, etc.  For these
        individual attributes, Hibernate must be able to read the values out of the database and write them back.  This
        'marshalling' is the function of a <emphasis>Hibernate type</emphasis>, which is an implementation of the
        <interfacename>org.hibernate.type.Type</interfacename> interface.  In addition, a
        <emphasis>Hibernate type</emphasis> describes various aspects of behavior of the Java type such as "how is
        equality checked?" or "how are values cloned?".
    </para>

    <important>
        <para>
            A Hibernate type is neither a Java type nor a SQL datatype; it provides a information about both.
        </para>
        <para>
            When you encounter the term <emphasis>type</emphasis> in regards to Hibernate be aware that usage might
            refer to the Java type, the SQL/JDBC type or the Hibernate type.
        </para>
    </important>

    <para>
        Hibernate categorizes types into two high-level groups: value types (see <xref linkend="types-value"/>) and
        entity types (see <xref linkend="types-entity"/>).
    </para>

    <section xml:id="types-value">
        <title>Value types</title>

        <para>
            The main distinguishing characteristic of a value type is the fact that they do not define their own
            lifecycle.  We say that they are "owned" by something else (specifically an entity, as we will see later)
            which defines their lifecycle.  Value types are further classified into 3 sub-categories: basic types (see
            <xref linkend="types-value-basic"/>), composite types (see <xref linkend="types-value-composite"/>)
            amd collection types (see <xref linkend="types-value-collection"/>).
        </para>

        <section xml:id="types-value-basic">
            <title>Basic value types</title>
            <para>
                The norm for basic value types is that they map a single database value (column) to a single, 
                non-aggregated Java type.  Hibernate provides a number of built-in basic types, which we will present
                in the following sections by the Java type.  Mainly these follow the natural mappings recommended in the
                JDBC specification.  We will later cover how to override these mapping and how to provide and use
                alternative type mappings.
            </para>
            <section xml:id="types-value-basic-string">
                <title>java.lang.String</title>
                <variablelist>
                    <varlistentry>
                        <term><classname>org.hibernate.type.StringType</classname></term>
                        <listitem>
                            <para>
                                Maps a string to the JDBC VARCHAR type.  This is the standard mapping for a string if 
                                no Hibernate type is specified.
                            </para>
                            <para>
                                Registered under <literal>string</literal> and <literal>java.lang.String</literal>
                                in the type registry (see <xref linkend="types-registry"/>).
                            </para>
                        </listitem>
                    </varlistentry>
                    <varlistentry>
                        <term><classname>org.hibernate.type.MaterializedClob</classname></term>
                        <listitem>
                            <para>
                                Maps a string to a JDBC CLOB type
                            </para>
                            <para>
                                Registered under <literal>materialized_clob</literal> in the type registry (see
                                <xref linkend="types-registry"/>).
                            </para>
                        </listitem>
                    </varlistentry>
                    <varlistentry>
                        <term><classname>org.hibernate.type.TextType</classname></term>
                        <listitem>
                            <para>
                                Maps a string to a JDBC LONGVARCHAR type
                            </para>
                            <para>
                                Registered under <literal>text</literal> in the type registry (see
                                <xref linkend="types-registry"/>).
                            </para>
                        </listitem>
                    </varlistentry>
                </variablelist>
            </section>
            <section xml:id="types-basic-value-character">
                <title><classname>java.lang.Character</classname> (or char primitive)</title>
                <variablelist>
                    <varlistentry>
                        <term><classname>org.hibernate.type.CharacterType</classname></term>
                        <listitem>
                            <para>
                                Maps a char or <classname>java.lang.Character</classname> to a JDBC CHAR
                            </para>
                            <para>
                                Registered under <literal>char</literal> and <literal>java.lang.Character</literal> in the
                                type registry (see <xref linkend="types-registry"/>).
                            </para>
                        </listitem>
                    </varlistentry>
                </variablelist>
            </section>
            <section xml:id="types-value-basic-boolean">
                <title><classname>java.lang.Boolean</classname> (or boolean primitive)</title>
                <variablelist>
                    <varlistentry>
                        <term><classname>org.hibernate.type.BooleanType</classname></term>
                        <listitem>
                            <para>
                                Maps a boolean to a JDBC BIT type
                            </para>
                            <para>
                                Registered under <literal>boolean</literal> and <literal>java.lang.Boolean</literal> in
                                the type registry (see <xref linkend="types-registry"/>).
                            </para>
                        </listitem>
                    </varlistentry>
                    <varlistentry>
                        <term><classname>org.hibernate.type.NumericBooleanType</classname></term>
                        <listitem>
                            <para>
                                Maps a boolean to a JDBC INTEGER type as 0 = false, 1 = true
                            </para>
                            <para>
                                Registered under <literal>numeric_boolean</literal> in the type registry (see
                                <xref linkend="types-registry"/>).
                            </para>
                        </listitem>
                    </varlistentry>
                    <varlistentry>
                        <term><classname>org.hibernate.type.YesNoType</classname></term>
                        <listitem>
                            <para>
                                Maps a boolean to a JDBC CHAR type as ('N' | 'n') = false, ( 'Y' | 'y' ) = true
                            </para>
                            <para>
                                Registered under <literal>yes_no</literal> in the type registry (see
                                <xref linkend="types-registry"/>).
                            </para>
                        </listitem>
                    </varlistentry>
                    <varlistentry>
                        <term><classname>org.hibernate.type.TrueFalseType</classname></term>
                        <listitem>
                            <para>
                                Maps a boolean to a JDBC CHAR type as ('F' | 'f') = false, ( 'T' | 't' ) = true
                            </para>
                            <para>
                                Registered under <literal>true_false</literal> in the type registry (see
                                <xref linkend="types-registry"/>).
                            </para>
                        </listitem>
                    </varlistentry>
                </variablelist>
            </section>
            <section xml:id="types-basic-value-byte">
                <title><classname>java.lang.Byte</classname> (or byte primitive)</title>
                <variablelist>
                    <varlistentry>
                        <term><classname>org.hibernate.type.ByteType</classname></term>
                        <listitem>
                            <para>
                                Maps a byte or <classname>java.lang.Byte</classname> to a JDBC TINYINT
                            </para>
                            <para>
                                Registered under <literal>byte</literal> and <literal>java.lang.Byte</literal> in the
                                type registry (see <xref linkend="types-registry"/>).
                            </para>
                        </listitem>
                    </varlistentry>
                </variablelist>
            </section>
            <section xml:id="types-basic-value-short">
                <title><classname>java.lang.Short</classname> (or short primitive)</title>
                <variablelist>
                    <varlistentry>
                        <term><classname>org.hibernate.type.ShortType</classname></term>
                        <listitem>
                            <para>
                                Maps a short or <classname>java.lang.Short</classname> to a JDBC SMALLINT
                            </para>
                            <para>
                                Registered under <literal>short</literal> and <literal>java.lang.Short</literal> in the
                                type registry (see <xref linkend="types-registry"/>).
                            </para>
                        </listitem>
                    </varlistentry>
                </variablelist>
            </section>
            <section xml:id="types-basic-value-int">
                <title><classname>java.lang.Integer</classname> (or int primitive)</title>
                <variablelist>
                    <varlistentry>
                        <term><classname>org.hibernate.type.IntegerTypes</classname></term>
                        <listitem>
                            <para>
                                Maps an int or <classname>java.lang.Integer</classname> to a JDBC INTEGER
                            </para>
                            <para>
                                Registered under <literal>int</literal> and <literal>java.lang.Integer</literal>in the
                                type registry (see <xref linkend="types-registry"/>).
                            </para>
                        </listitem>
                    </varlistentry>
                </variablelist>
            </section>
            <section xml:id="types-basic-value-long">
                <title><classname>java.lang.Long</classname> (or long primitive)</title>
                <variablelist>
                    <varlistentry>
                        <term><classname>org.hibernate.type.LongType</classname></term>
                        <listitem>
                            <para>
                                Maps a long or <classname>java.lang.Long</classname> to a JDBC BIGINT
                            </para>
                            <para>
                                Registered under <literal>long</literal> and <literal>java.lang.Long</literal> in the
                                type registry (see <xref linkend="types-registry"/>).
                            </para>
                        </listitem>
                    </varlistentry>
                </variablelist>
            </section>
            <section xml:id="types-basic-value-float">
                <title><classname>java.lang.Float</classname> (or float primitive)</title>
                <variablelist>
                    <varlistentry>
                        <term><classname>org.hibernate.type.FloatType</classname></term>
                        <listitem>
                            <para>
                                Maps a float or <classname>java.lang.Float</classname> to a JDBC FLOAT
                            </para>
                            <para>
                                Registered under <literal>float</literal> and <literal>java.lang.Float</literal> in the
                                type registry (see <xref linkend="types-registry"/>).
                            </para>
                        </listitem>
                    </varlistentry>
                </variablelist>
            </section>
            <section xml:id="types-basic-value-double">
                <title><classname>java.lang.Double</classname> (or double primitive)</title>
                <variablelist>
                    <varlistentry>
                        <term><classname>org.hibernate.type.DoubleType</classname></term>
                        <listitem>
                            <para>
                                Maps a double or <classname>java.lang.Double</classname> to a JDBC DOUBLE
                            </para>
                            <para>
                                Registered under <literal>double</literal> and <literal>java.lang.Double</literal> in the
                                type registry (see <xref linkend="types-registry"/>).
                            </para>
                        </listitem>
                    </varlistentry>
                </variablelist>
            </section>
            <section xml:id="types-basic-value-biginteger">
                <title><classname>java.math.BigInteger</classname></title>
                <variablelist>
                    <varlistentry>
                        <term><classname>org.hibernate.type.BigIntegerType</classname></term>
                        <listitem>
                            <para>
                                Maps a <classname>java.math.BigInteger</classname> to a JDBC NUMERIC
                            </para>
                            <para>
                                Registered under <literal>big_integer</literal> and <literal>java.math.BigInteger</literal> in the
                                type registry (see <xref linkend="types-registry"/>).
                            </para>
                        </listitem>
                    </varlistentry>
                </variablelist>
            </section>
            <section xml:id="types-basic-value-bigdecimal">
                <title><classname>java.math.BigDecimal</classname></title>
                <variablelist>
                    <varlistentry>
                        <term><classname>org.hibernate.type.BigDecimalType</classname></term>
                        <listitem>
                            <para>
                                Maps a <classname>java.math.BigDecimal</classname> to a JDBC NUMERIC
                            </para>
                            <para>
                                Registered under <literal>big_decimal</literal> and <literal>java.math.BigDecimal</literal> in the
                                type registry (see <xref linkend="types-registry"/>).
                            </para>
                        </listitem>
                    </varlistentry>
                </variablelist>
            </section>
            <section xml:id="types-basic-value-timestamp">
                <title><classname>java.util.Date</classname> or <classname>java.sql.Timestamp</classname></title>
                <variablelist>
                    <varlistentry>
                        <term><classname>org.hibernate.type.TimestampType</classname></term>
                        <listitem>
                            <para>
                                Maps a <classname>java.sql.Timestamp</classname> to a JDBC TIMESTAMP
                            </para>
                            <para>
                                Registered under <literal>timestamp</literal>, <literal>java.sql.Timestamp</literal> and
                                <literal>java.util.Date</literal> in the type registry (see <xref linkend="types-registry"/>).
                            </para>
                        </listitem>
                    </varlistentry>
                </variablelist>
            </section>
            <section xml:id="types-basic-value-time">
                <title><classname>java.sql.Time</classname></title>
                <variablelist>
                    <varlistentry>
                        <term><classname>org.hibernate.type.TimeType</classname></term>
                        <listitem>
                            <para>
                                Maps a <classname>java.sql.Time</classname> to a JDBC TIME
                            </para>
                            <para>
                                Registered under <literal>time</literal> and <literal>java.sql.Time</literal> in the
                                type registry (see <xref linkend="types-registry"/>).
                            </para>
                        </listitem>
                    </varlistentry>
                </variablelist>
            </section>
            <section xml:id="types-basic-value-date">
                <title><classname>java.sql.Date</classname></title>
                <variablelist>
                    <varlistentry>
                        <term><classname>org.hibernate.type.DateType</classname></term>
                        <listitem>
                            <para>
                                Maps a <classname>java.sql.Date</classname> to a JDBC DATE
                            </para>
                            <para>
                                Registered under <literal>date</literal> and <literal>java.sql.Date</literal> in the
                                type registry (see <xref linkend="types-registry"/>).
                            </para>
                        </listitem>
                    </varlistentry>
                </variablelist>
            </section>
            <section xml:id="types-basic-value-calendar">
                <title><classname>java.util.Calendar</classname></title>
                <variablelist>
                    <varlistentry>
                        <term><classname>org.hibernate.type.CalendarType</classname></term>
                        <listitem>
                            <para>
                                Maps a <classname>java.util.Calendar</classname> to a JDBC TIMESTAMP
                            </para>
                            <para>
                                Registered under <literal>calendar</literal>, <literal>java.util.Calendar</literal> and
                                <literal>java.util.GregorianCalendar</literal> in the type registry (see
                                <xref linkend="types-registry"/>).
                            </para>
                        </listitem>
                    </varlistentry>
                    <varlistentry>
                        <term><classname>org.hibernate.type.CalendarDateType</classname></term>
                        <listitem>
                            <para>
                                Maps a <classname>java.util.Calendar</classname> to a JDBC DATE
                            </para>
                            <para>
                                Registered under <literal>calendar_date</literal> in the type registry (see
                                <xref linkend="types-registry"/>).
                            </para>
                        </listitem>
                    </varlistentry>
                </variablelist>
            </section>
            <section xml:id="types-basic-value-currency">
                <title><classname>java.util.Currency</classname></title>
                <variablelist>
                    <varlistentry>
                        <term><classname>org.hibernate.type.CurrencyType</classname></term>
                        <listitem>
                            <para>
                                Maps a <classname>java.util.Currency</classname> to a JDBC VARCHAR (using the Currency code)
                            </para>
                            <para>
                                Registered under <literal>currency</literal> and <literal>java.util.Currency</literal> in the
                                type registry (see <xref linkend="types-registry"/>).
                            </para>
                        </listitem>
                    </varlistentry>
                </variablelist>
            </section>
            <section xml:id="types-basic-value-locale">
                <title><classname>java.util.Locale</classname></title>
                <variablelist>
                    <varlistentry>
                        <term><classname>org.hibernate.type.LocaleType</classname></term>
                        <listitem>
                            <para>
                                Maps a <classname>java.util.Locale</classname> to a JDBC VARCHAR (using the Locale code)
                            </para>
                            <para>
                                Registered under <literal>locale</literal> and <literal>java.util.Locale</literal> in the
                                type registry (see <xref linkend="types-registry"/>).
                            </para>
                        </listitem>
                    </varlistentry>
                </variablelist>
            </section>
            <section xml:id="types-basic-value-timezone">
                <title><classname>java.util.TimeZone</classname></title>
                <variablelist>
                    <varlistentry>
                        <term><classname>org.hibernate.type.TimeZoneType</classname></term>
                        <listitem>
                            <para>
                                Maps a <classname>java.util.TimeZone</classname> to a JDBC VARCHAR (using the TimeZone ID)
                            </para>
                            <para>
                                Registered under <literal>timezone</literal> and <literal>java.util.TimeZone</literal> in the
                                type registry (see <xref linkend="types-registry"/>).
                            </para>
                        </listitem>
                    </varlistentry>
                </variablelist>
            </section>
            <section xml:id="types-basic-value-url">
                <title><classname>java.net.URL</classname></title>
                <variablelist>
                    <varlistentry>
                        <term><classname>org.hibernate.type.UrlType</classname></term>
                        <listitem>
                            <para>
                                Maps a <classname>java.net.URL</classname> to a JDBC VARCHAR (using the external form)
                            </para>
                            <para>
                                Registered under <literal>url</literal> and <literal>java.net.URL</literal> in the
                                type registry (see <xref linkend="types-registry"/>).
                            </para>
                        </listitem>
                    </varlistentry>
                </variablelist>
            </section>
            <section xml:id="types-basic-value-class">
                <title><classname>java.lang.Class</classname></title>
                <variablelist>
                    <varlistentry>
                        <term><classname>org.hibernate.type.ClassType</classname></term>
                        <listitem>
                            <para>
                                Maps a <classname>java.lang.Class</classname> to a JDBC VARCHAR (using the Class name)
                            </para>
                            <para>
                                Registered under <literal>class</literal> and <literal>java.lang.Class</literal> in the
                                type registry (see <xref linkend="types-registry"/>).
                            </para>
                        </listitem>
                    </varlistentry>
                </variablelist>
            </section>
            <section xml:id="types-basic-value-blob">
                <title><classname>java.sql.Blob</classname></title>
                <variablelist>
                    <varlistentry>
                        <term><classname>org.hibernate.type.BlobType</classname></term>
                        <listitem>
                            <para>
                                Maps a <classname>java.sql.Blob</classname> to a JDBC BLOB
                            </para>
                            <para>
                                Registered under <literal>blob</literal> and <literal>java.sql.Blob</literal> in the
                                type registry (see <xref linkend="types-registry"/>).
                            </para>
                        </listitem>
                    </varlistentry>
                </variablelist>
            </section>
            <section xml:id="types-basic-value-clob">
                <title><classname>java.sql.Clob</classname></title>
                <variablelist>
                    <varlistentry>
                        <term><classname>org.hibernate.type.ClobType</classname></term>
                        <listitem>
                            <para>
                                Maps a <classname>java.sql.Clob</classname> to a JDBC CLOB
                            </para>
                            <para>
                                Registered under <literal>clob</literal> and <literal>java.sql.Clob</literal> in the
                                type registry (see <xref linkend="types-registry"/>).
                            </para>
                        </listitem>
                    </varlistentry>
                </variablelist>
            </section>
            <section xml:id="types-basic-value-binary" revision="1">
                <title>byte[]</title>
                <variablelist>
                    <varlistentry>
                        <term><classname>org.hibernate.type.BinaryType</classname></term>
                        <listitem>
                            <para>
                                Maps a primitive byte[] to a JDBC VARBINARY
                            </para>
                            <para>
                                Registered under <literal>binary</literal> and <literal>byte[]</literal> in the
                                type registry (see <xref linkend="types-registry"/>).
                            </para>
                        </listitem>
                    </varlistentry>
                    <varlistentry>
                        <term><classname>org.hibernate.type.MaterializedBlobType</classname></term>
                        <listitem>
                            <para>
                                Maps a primitive byte[] to a JDBC BLOB
                            </para>
                            <para>
                                Registered under <literal>materialized_blob</literal> in the type registry (see
                                <xref linkend="types-registry"/>).
                            </para>
                        </listitem>
                    </varlistentry>
                    <varlistentry>
                        <term><classname>org.hibernate.type.ImageType</classname></term>
                        <listitem>
                            <para>
                                Maps a primitive byte[] to a JDBC LONGVARBINARY
                            </para>
                            <para>
                                Registered under <literal>image</literal> in the type registry (see
                                <xref linkend="types-registry"/>).
                            </para>
                        </listitem>
                    </varlistentry>
                </variablelist>
            </section>
            <section xml:id="types-basic-value-wrapperbinary" revision="1">
                <title>Byte[]</title>
                <variablelist>
                    <varlistentry>
                        <term><classname>org.hibernate.type.BinaryType</classname></term>
                        <listitem>
                            <para>
                                Maps a java.lang.Byte[] to a JDBC VARBINARY
                            </para>
                            <para>
                                Registered under <literal>wrapper-binary</literal>, <literal>Byte[]</literal> and
                                <literal>java.lang.Byte[]</literal> in the type registry (see <xref linkend="types-registry"/>).
                            </para>
                        </listitem>
                    </varlistentry>
                </variablelist>
            </section>
            <section xml:id="types-basic-value-chararray">
                <title>char[]</title>
                <variablelist>
                    <varlistentry>
                        <term><classname>org.hibernate.type.CharArrayType</classname></term>
                        <listitem>
                            <para>
                                Maps a char[] to a JDBC VARCHAR
                            </para>
                            <para>
                                Registered under <literal>characters</literal> and <literal>char[]</literal>
                                in the type registry (see <xref linkend="types-registry"/>).
                            </para>
                        </listitem>
                    </varlistentry>
                </variablelist>
            </section>
            <section xml:id="types-basic-value-characterarray" revision="1">
                <title>Character[]</title>
                <variablelist>
                    <varlistentry>
                        <term><classname>org.hibernate.type.CharacterArrayType</classname></term>
                        <listitem>
                            <para>
                                Maps a java.lang.Character[] to a JDBC VARCHAR
                            </para>
                            <para>
                                Registered under <literal>wrapper-characters</literal>, <literal>Character[]</literal>
                                and <literal>java.lang.Character[]</literal> in the type registry (see <xref linkend="types-registry"/>).
                            </para>
                        </listitem>
                    </varlistentry>
                </variablelist>
            </section>
            <section xml:id="types-basic-value-uuid">
                <title><classname>java.util.UUID</classname></title>
                <variablelist>
                    <varlistentry>
                        <term><classname>org.hibernate.type.UUIDBinaryType</classname></term>
                        <listitem>
                            <para>
                                Maps a java.util.UUID to a JDBC BINARY
                            </para>
                            <para>
                                Registered under <literal>uuid-binary</literal> and <literal>java.util.UUID</literal>
                                in the type registry (see <xref linkend="types-registry"/>).
                            </para>
                        </listitem>
                    </varlistentry>
                    <varlistentry>
                        <term><classname>org.hibernate.type.UUIDCharType</classname></term>
                        <listitem>
                            <para>
                                Maps a java.util.UUID to a JDBC CHAR (though VARCHAR is fine too for existing schemas)
                            </para>
                            <para>
                                Registered under <literal>uuid-char</literal> in the type registry (see
                                <xref linkend="types-registry"/>).
                            </para>
                        </listitem>
                    </varlistentry>
                    <varlistentry>
                        <term><classname>org.hibernate.type.PostgresUUIDType</classname></term>
                        <listitem>
                            <para>
                                Maps a java.util.UUID to the PostgreSQL UUID data type (through
                                <literal>Types#OTHER</literal> which is how the PostgreSQL JDBC driver defines it).
                            </para>
                            <para>
                                Registered under <literal>pg-uuid</literal> in the type registry (see
                                <xref linkend="types-registry"/>).
                            </para>
                        </listitem>
                    </varlistentry>
                </variablelist>
            </section>
            <section xml:id="types-basic-value-serializable">
                <title><interfacename>java.io.Serializable</interfacename></title>
                <variablelist>
                    <varlistentry>
                        <term><classname>org.hibernate.type.SerializableType</classname></term>
                        <listitem>
                            <para>
                                Maps implementors of java.lang.Serializable to a JDBC VARBINARY
                            </para>
                            <para>
                                Unlike the other value types, there are multiple instances of this type.  It
                                gets registered once under <interfacename>java.io.Serializable</interfacename>.
                                Additionally it gets registered under the specific
                                <interfacename>java.io.Serializable</interfacename> implementation class names.
                            </para>
                        </listitem>
                    </varlistentry>
                </variablelist>
            </section>
        </section>

        <section xml:id="types-value-composite">
            <title>Composite types</title>
            <note>
                <para>
                    The Java Persistence API calls these embedded types, while Hibernate traditionally called them
                    components.  Just be aware that both terms are used and mean the same thing in the scope of
                    discussing Hibernate.
                </para>
            </note>
            <para>
                Components represent aggregations of values into a single Java type.  For example, you might have
                an Address class that aggregates street, city, state, etc information or a Name class that
                aggregates the parts of a person's Name.  In many ways a component looks exactly like an entity.  They
                are both (generally speaking) classes written specifically for the application.  They both might have
                references to other application-specific classes, as well as to collections and simple JDK types.  As
                discussed before, the only distinguishing factory is the fact that a component does not own its own
                lifecycle nor does it define an identifier.
            </para>
        </section>

        <section xml:id="types-value-collection">
            <title>Collection types</title>
            <important>
                <para>
                    It is critical understand that we mean the collection itself, not its contents.
                    The contents of the collection can in turn be basic, component or entity types (though not
                    collections), but the collection itself is owned.
                </para>
            </important>
            <para>
                Collections are covered in <xref linkend="collections"/>.
            </para>
        </section>

    </section>

    <section xml:id="types-entity">
        <title>Entity types</title>
        <para>
            The definition of entities is covered in detail in <xref linkend="persistent-classes"/>.  For the purpose of
            this discussion, it is enough to say that entities are (generally application-specific) classes which
            correlate to rows in a table.  Specifically they correlate to the row by means of a unique identifier.
            Because of this unique identifier, entities exist independently and define their own lifecycle.  As an example,
            when we delete a <classname>Membership</classname>, both the <classname>User</classname> and
            <classname>Group</classname> entities remain.
            <note>
                <para>
                    This notion of entity independence can be modified by the application developer using the concept of
                    cascades.  Cascades allow certain operations to continue (or "cascade") across an association from
                    one entity to another.  Cascades are covered in detail in <xref linkend="associations"/>.
                </para>
            </note>
        </para>
    </section>

    <section xml:id="types-category-significance">
        <title>Significance of type categories</title>
        <para>
            Why do we spend so much time categorizing the various types of types?  What is the significance of the
            distinction?
        </para>
        <para>
            The main categorization was between entity types and value types.  To review we said that entities, by
            nature of their unique identifier, exist independently of other objects whereas values do not.  An
            application cannot "delete" a Product sku; instead, the sku is removed when the Product itself is
            deleted (obviously you can <emphasis>update</emphasis> the sku of that Product to null to make it
            "go away", but even there the access is done through the Product).
        </para>
        <para>
            Nor can you define an association <emphasis>to</emphasis> that Product sku.  You <emphasis>can</emphasis>
            define an association to Product <emphasis>based on</emphasis> its sku, assuming sku is unique, but that
            is totally different.
        </para>
        <para>
            TBC...
        </para>
    </section>

    <section xml:id="types-custom">
        <title>Custom types</title>
        <para>
            Hibernate makes it relatively easy for developers to create their own <emphasis>value</emphasis> types.  For
            example, you might want to persist properties of type <classname>java.lang.BigInteger</classname> to
            <literal>VARCHAR</literal> columns.  Custom types are not limited to mapping values to a single table
            column.  So, for example, you might want to concatenate together <literal>FIRST_NAME</literal>,
            <literal>INITIAL</literal> and <literal>SURNAME</literal> columns into a <classname>java.lang.String</classname>.
        </para>

        <para>
            There are 3 approaches to developing a custom Hibernate type.  As a means of illustrating the different
            approaches, lets consider a use case where we need to compose a <classname>java.math.BigDecimal</classname>
            and <classname>java.util.Currency</classname> together into a custom <classname>Money</classname> class.
        </para>

        <section xml:id="types-custom-type">
            <title>Custom types using <interfacename>org.hibernate.type.Type</interfacename></title>
            <para>
                The first approach is to directly implement the <interfacename>org.hibernate.type.Type</interfacename>
                interface (or one of its derivatives).  Probably, you will be more interested in the more specific
                <interfacename>org.hibernate.type.BasicType</interfacename> contract which would allow registration of
                the type (see <xref linkend="types-registry"/>).  The benefit of this registration is that whenever
                the metadata for a particular property does not specify the Hibernate type to use, Hibernate will
                consult the registry for the exposed property type.  In our example, the property type would be
                <classname>Money</classname>, which is the key we would use to register our type in the registry:
            </para>

            <example xml:id="types-custom-type-ex-definition">
                <title>Defining and registering the custom Type</title>
                <programlisting role="JAVA"><![CDATA[public class MoneyType implements BasicType {
    public String[] getRegistrationKeys() {
        return new String[] { Money.class.getName() };
    }

	public int[] sqlTypes(Mapping mapping) {
	    // We will simply use delegation to the standard basic types for BigDecimal and Currency for many of the
	    // Type methods...
	    return new int[] {
	             BigDecimalType.INSTANCE.sqlType(),
	             CurrencyType.INSTANCE.sqlType(),
	    };
	    // we could also have honored any registry overrides via...
	    //return new int[] {
	    //         mappings.getTypeResolver().basic( BigDecimal.class.getName() ).sqlTypes( mappings )[0],
	    //         mappings.getTypeResolver().basic( Currency.class.getName() ).sqlTypes( mappings )[0]
	    //};
	}

    public Class getReturnedClass() {
        return Money.class;
    }

    public Object nullSafeGet(ResultSet rs, String[] names, SessionImplementor session, Object owner) throws SQLException {
        assert names.length == 2;
        BigDecimal amount = BigDecimalType.INSTANCE.get( names[0] ); // already handles null check
        Currency currency = CurrencyType.INSTANCE.get( names[1] ); // already handles null check
        return amount == null && currency == null
                ? null
                : new Money( amount, currency );
    }

    public void nullSafeSet(PreparedStatement st, Object value, int index, boolean[] settable, SessionImplementor session)
            throws SQLException {
        if ( value == null ) {
            BigDecimalType.INSTANCE.set( st, null, index );
            CurrencyType.INSTANCE.set( st, null, index+1 );
        }
        else {
            final Money money = (Money) value;
            BigDecimalType.INSTANCE.set( st, money.getAmount(), index );
            CurrencyType.INSTANCE.set( st, money.getCurrency(), index+1 );
        }
    }

    ...
}

Configuration cfg = new Configuration();
cfg.registerTypeOverride( new MoneyType() );
cfg...;
]]></programlisting>
            </example>
            <important>
                <para>
                    It is important that we registered the type <emphasis>before</emphasis> adding mappings.
                </para>
            </important>
        </section>

        <section xml:id="types-custom-ut">
            <title>Custom types using <interfacename>org.hibernate.usertype.UserType</interfacename></title>
            <note>
                <para>
                    Both <interfacename>org.hibernate.usertype.UserType</interfacename> and
                    <interfacename>org.hibernate.usertype.CompositeUserType</interfacename> were originally
                    added to isolate user code from internal changes to the <interfacename>org.hibernate.type.Type</interfacename>
                    interfaces.
                </para>
            </note>
            <para>
                The second approach is the use the <interfacename>org.hibernate.usertype.UserType</interfacename>
                interface, which presents a somewhat simplified view of the <interfacename>org.hibernate.type.Type</interfacename>
                interface.  Using a <interfacename>org.hibernate.usertype.UserType</interfacename>, our
                <classname>Money</classname> custom type would look as follows:
            </para>
            <example xml:id="types-custom-ut-ex-definition">
                <title>Defining the custom UserType</title>
                <programlisting role="JAVA"><![CDATA[public class MoneyType implements UserType {
    public int[] sqlTypes() {
        return new int[] {
                BigDecimalType.INSTANCE.sqlType(),
                CurrencyType.INSTANCE.sqlType(),
        };
    }

    public Class getReturnedClass() {
        return Money.class;
    }

    public Object nullSafeGet(ResultSet rs, String[] names, Object owner) throws SQLException {
        assert names.length == 2;
        BigDecimal amount = BigDecimalType.INSTANCE.get( names[0] ); // already handles null check
        Currency currency = CurrencyType.INSTANCE.get( names[1] ); // already handles null check
        return amount == null && currency == null
                ? null
                : new Money( amount, currency );
    }

    public void nullSafeSet(PreparedStatement st, Object value, int index) throws SQLException {
        if ( value == null ) {
            BigDecimalType.INSTANCE.set( st, null, index );
            CurrencyType.INSTANCE.set( st, null, index+1 );
        }
        else {
            final Money money = (Money) value;
            BigDecimalType.INSTANCE.set( st, money.getAmount(), index );
            CurrencyType.INSTANCE.set( st, money.getCurrency(), index+1 );
        }
    }

    ...
}]]></programlisting>
            </example>
            <para>
                There is not much difference between the <interfacename>org.hibernate.type.Type</interfacename> example
                and the <interfacename>org.hibernate.usertype.UserType</interfacename> example, but that is only because
                of the snippets shown.  If you choose the <interfacename>org.hibernate.type.Type</interfacename> approach
                there are quite a few more methods you would need to implement as compared to the
                <interfacename>org.hibernate.usertype.UserType</interfacename>.
            </para>
        </section>

        <section xml:id="types-custom-cut">
            <title>Custom types using <interfacename>org.hibernate.usertype.CompositeUserType</interfacename></title>
            <para>
                The third and final approach is the use the <interfacename>org.hibernate.usertype.CompositeUserType</interfacename>
                interface, which differs from <interfacename>org.hibernate.usertype.UserType</interfacename> in that it
                gives us the ability to provide Hibernate the information to handle the composition within the
                <classname>Money</classname> class (specifically the 2 attributes).  This would give us the capability,
                for example, to reference the <literal>amount</literal> attribute in an HQL query.  Using a
                <interfacename>org.hibernate.usertype.CompositeUserType</interfacename>, our
                <classname>Money</classname> custom type would look as follows:
            </para>

            <example xml:id="types-custom-cut-ex-definition">
                <title>Defining the custom CompositeUserType</title>
                <programlisting role="JAVA"><![CDATA[public class MoneyType implements CompositeUserType {
    public String[] getPropertyNames() {
        // ORDER IS IMPORTANT!  it must match the order the columns are defined in the property mapping
        return new String[] { "amount", "currency" };
    }

    public Type[] getPropertyTypes() {
        return new Type[] { BigDecimalType.INSTANCE, CurrencyType.INSTANCE };
    }

    public Class getReturnedClass() {
        return Money.class;
    }

    public Object getPropertyValue(Object component, int propertyIndex) {
        if ( component == null ) {
            return null;
        }

        final Money money = (Money) component;
        switch ( propertyIndex ) {
            case 0: {
                return money.getAmount();
            }
            case 1: {
                return money.getCurrency();
            }
            default: {
                throw new HibernateException( "Invalid property index [" + propertyIndex + "]" );
            }
        }
    }

	public void setPropertyValue(Object component, int propertyIndex, Object value) throws HibernateException {
        if ( component == null ) {
            return;
        }

        final Money money = (Money) component;
        switch ( propertyIndex ) {
            case 0: {
                money.setAmount( (BigDecimal) value );
                break;
            }
            case 1: {
                money.setCurrency( (Currency) value );
                break;
            }
            default: {
                throw new HibernateException( "Invalid property index [" + propertyIndex + "]" );
            }
        }
	}

    public Object nullSafeGet(ResultSet rs, String[] names, SessionImplementor session, Object owner) throws SQLException {
        assert names.length == 2;
        BigDecimal amount = BigDecimalType.INSTANCE.get( names[0] ); // already handles null check
        Currency currency = CurrencyType.INSTANCE.get( names[1] ); // already handles null check
        return amount == null && currency == null
                ? null
                : new Money( amount, currency );
    }

    public void nullSafeSet(PreparedStatement st, Object value, int index, SessionImplementor session) throws SQLException {
        if ( value == null ) {
            BigDecimalType.INSTANCE.set( st, null, index );
            CurrencyType.INSTANCE.set( st, null, index+1 );
        }
        else {
            final Money money = (Money) value;
            BigDecimalType.INSTANCE.set( st, money.getAmount(), index );
            CurrencyType.INSTANCE.set( st, money.getCurrency(), index+1 );
        }
    }

    ...
}]]></programlisting>
            </example>
        </section>

    </section>

    <section xml:id="types-registry">
        <title>Type registry</title>
        <para>
            Internally Hibernate uses a registry of basic types (see <xref linkend="types-value-basic"/>) when
            it needs to resolve the specific <interfacename>org.hibernate.type.Type</interfacename> to use in certain
            situations.  It also provides a way for applications to add extra basic type registrations as well as
            override the standard basic type registrations.
        </para>
        <para>
            To register a new type or to override an existing type registration, applications would make use of the
            <methodname>registerTypeOverride</methodname> method of the <classname>org.hibernate.cfg.Configuration</classname>
            class when bootstrapping Hibernate.  For example, lets say you want Hibernate to use your custom
            <classname>SuperDuperStringType</classname>; during bootstrap you would call:
        </para>
        <example xml:id="type-registry-override-ex">
            <title>Overriding the standard <classname>StringType</classname></title>
            <programlisting role="JAVA"><![CDATA[Configuration cfg = ...;
cfg.registerTypeOverride( new SuperDuperStringType() );]]></programlisting>
        </example>
        <para>
            The argument to <methodname>registerTypeOverride</methodname> is a <interfacename>org.hibernate.type.BasicType</interfacename>
            which is a specialization of the <interfacename>org.hibernate.type.Type</interfacename> we saw before.  It
            adds a single method:
        </para>
        <example>
            <title>Snippet from BasicType.java</title>
            <programlisting role="JAVA" >
    /**
	 * Get the names under which this type should be registered in the type registry.
	 *
	 * @return The keys under which to register this type.
	 */
	public String[] getRegistrationKeys();
            </programlisting>
        </example>
        <para>
            One approach is to use inheritance (<classname>SuperDuperStringType</classname> extends 
            <classname>org.hibernate.type.StringType</classname>); another is to use delegation.
        </para>
    </section>

</chapter>
