alvinalexander.com | career | drupal | java | mac | mysql | perl | scala | uml | unix  

Hibernate example source code file (type.xml)

This example Hibernate source code file (type.xml) is included in the DevDaily.com "Java Source Code Warehouse" project. The intent of this project is to help you "Learn Java by Example" TM.

Java - Hibernate tags/keywords

hibernate, hibernate, java, jdbc, jdbc, maps, maps, money, object, registered, registered, string, the, varchar

The Hibernate type.xml source code

<!--
  ~ Hibernate, Relational Persistence for Idiomatic Java
  ~
  ~ Copyright (c) 2010, Red Hat Inc. or third-party contributors as
  ~ indicated by the @author tags or express copyright attribution
  ~ statements applied by the authors.  All third-party contributions are
  ~ distributed under license by Red Hat Inc.
  ~
  ~ This copyrighted material is made available to anyone wishing to use, modify,
  ~ copy, or redistribute it subject to the terms and conditions of the GNU
  ~ Lesser General Public License, as published by the Free Software Foundation.
  ~
  ~ This program is distributed in the hope that it will be useful,
  ~ but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  ~ or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License
  ~ for more details.
  ~
  ~ You should have received a copy of the GNU Lesser General Public License
  ~ along with this distribution; if not, write to:
  ~ Free Software Foundation, Inc.
  ~ 51 Franklin Street, Fifth Floor
  ~ Boston, MA  02110-1301  USA
  -->
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
        
<chapter id="types">
    <title>Types

    <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
        object with a number of attributes such as a <literal>sku, name, 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, which is an implementation of the
        <interfacename>org.hibernate.type.Type interface.  In addition, a
        <emphasis>Hibernate type 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 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 id="types-value">
        <title>Value types

        <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 )
            amd collection types (see <xref linkend="types-value-collection"/>).
        </para>

        <section id="types-value-basic">
            <title>Basic value types
            <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 id="types-value-basic-string">
                <title>java.lang.String
                <variablelist>
                    <varlistentry>
                        <term>org.hibernate.type.StringType
                        <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 and java.lang.String
                                in the type registry (see <xref linkend="types-registry"/>).
                            </para>
                        </listitem>
                    </varlistentry>
                    <varlistentry>
                        <term>org.hibernate.type.MaterializedClob
                        <listitem>
                            <para>
                                Maps a string to a JDBC CLOB type
                            </para>
                            <para>
                                Registered under <literal>materialized_clob in the type registry (see
                                <xref linkend="types-registry"/>).
                            </para>
                        </listitem>
                    </varlistentry>
                    <varlistentry>
                        <term>org.hibernate.type.TextType
                        <listitem>
                            <para>
                                Maps a string to a JDBC LONGVARCHAR type
                            </para>
                            <para>
                                Registered under <literal>text in the type registry (see
                                <xref linkend="types-registry"/>).
                            </para>
                        </listitem>
                    </varlistentry>
                </variablelist>
            </section>
            <section id="types-basic-value-character">
                <title>java.lang.Character (or char primitive)
                <variablelist>
                    <varlistentry>
                        <term>org.hibernate.type.CharacterType
                        <listitem>
                            <para>
                                Maps a char or <classname>java.lang.Character to a JDBC CHAR
                            </para>
                            <para>
                                Registered under <literal>char and java.lang.Character in the
                                type registry (see <xref linkend="types-registry"/>).
                            </para>
                        </listitem>
                    </varlistentry>
                </variablelist>
            </section>
            <section id="types-value-basic-boolean">
                <title>java.lang.Boolean (or boolean primitive)
                <variablelist>
                    <varlistentry>
                        <term>org.hibernate.type.BooleanType
                        <listitem>
                            <para>
                                Maps a boolean to a JDBC BIT type
                            </para>
                            <para>
                                Registered under <literal>boolean and java.lang.Boolean in
                                the type registry (see <xref linkend="types-registry"/>).
                            </para>
                        </listitem>
                    </varlistentry>
                    <varlistentry>
                        <term>org.hibernate.type.NumericBooleanType
                        <listitem>
                            <para>
                                Maps a boolean to a JDBC INTEGER type as 0 = false, 1 = true
                            </para>
                            <para>
                                Registered under <literal>numeric_boolean in the type registry (see
                                <xref linkend="types-registry"/>).
                            </para>
                        </listitem>
                    </varlistentry>
                    <varlistentry>
                        <term>org.hibernate.type.YesNoType
                        <listitem>
                            <para>
                                Maps a boolean to a JDBC CHAR type as ('N' | 'n') = false, ( 'Y' | 'y' ) = true
                            </para>
                            <para>
                                Registered under <literal>yes_no in the type registry (see
                                <xref linkend="types-registry"/>).
                            </para>
                        </listitem>
                    </varlistentry>
                    <varlistentry>
                        <term>org.hibernate.type.TrueFalseType
                        <listitem>
                            <para>
                                Maps a boolean to a JDBC CHAR type as ('F' | 'f') = false, ( 'T' | 't' ) = true
                            </para>
                            <para>
                                Registered under <literal>true_false in the type registry (see
                                <xref linkend="types-registry"/>).
                            </para>
                        </listitem>
                    </varlistentry>
                </variablelist>
            </section>
            <section id="types-basic-value-byte">
                <title>java.lang.Byte (or byte primitive)
                <variablelist>
                    <varlistentry>
                        <term>org.hibernate.type.ByteType
                        <listitem>
                            <para>
                                Maps a byte or <classname>java.lang.Byte to a JDBC TINYINT
                            </para>
                            <para>
                                Registered under <literal>byte and java.lang.Byte in the
                                type registry (see <xref linkend="types-registry"/>).
                            </para>
                        </listitem>
                    </varlistentry>
                </variablelist>
            </section>
            <section id="types-basic-value-short">
                <title>java.lang.Short (or short primitive)
                <variablelist>
                    <varlistentry>
                        <term>org.hibernate.type.ShortType
                        <listitem>
                            <para>
                                Maps a short or <classname>java.lang.Short to a JDBC SMALLINT
                            </para>
                            <para>
                                Registered under <literal>short and java.lang.Short in the
                                type registry (see <xref linkend="types-registry"/>).
                            </para>
                        </listitem>
                    </varlistentry>
                </variablelist>
            </section>
            <section id="types-basic-value-int">
                <title>java.lang.Integer (or int primitive)
                <variablelist>
                    <varlistentry>
                        <term>org.hibernate.type.IntegerTypes
                        <listitem>
                            <para>
                                Maps an int or <classname>java.lang.Integer to a JDBC INTEGER
                            </para>
                            <para>
                                Registered under <literal>int and java.lang.Integerin the
                                type registry (see <xref linkend="types-registry"/>).
                            </para>
                        </listitem>
                    </varlistentry>
                </variablelist>
            </section>
            <section id="types-basic-value-long">
                <title>java.lang.Long (or long primitive)
                <variablelist>
                    <varlistentry>
                        <term>org.hibernate.type.LongType
                        <listitem>
                            <para>
                                Maps a long or <classname>java.lang.Long to a JDBC BIGINT
                            </para>
                            <para>
                                Registered under <literal>long and java.lang.Long in the
                                type registry (see <xref linkend="types-registry"/>).
                            </para>
                        </listitem>
                    </varlistentry>
                </variablelist>
            </section>
            <section id="types-basic-value-float">
                <title>java.lang.Float (or float primitive)
                <variablelist>
                    <varlistentry>
                        <term>org.hibernate.type.FloatType
                        <listitem>
                            <para>
                                Maps a float or <classname>java.lang.Float to a JDBC FLOAT
                            </para>
                            <para>
                                Registered under <literal>float and java.lang.Float in the
                                type registry (see <xref linkend="types-registry"/>).
                            </para>
                        </listitem>
                    </varlistentry>
                </variablelist>
            </section>
            <section id="types-basic-value-double">
                <title>java.lang.Double (or double primitive)
                <variablelist>
                    <varlistentry>
                        <term>org.hibernate.type.DoubleType
                        <listitem>
                            <para>
                                Maps a double or <classname>java.lang.Double to a JDBC DOUBLE
                            </para>
                            <para>
                                Registered under <literal>double and java.lang.Double in the
                                type registry (see <xref linkend="types-registry"/>).
                            </para>
                        </listitem>
                    </varlistentry>
                </variablelist>
            </section>
            <section id="types-basic-value-biginteger">
                <title>java.math.BigInteger
                <variablelist>
                    <varlistentry>
                        <term>org.hibernate.type.BigIntegerType
                        <listitem>
                            <para>
                                Maps a <classname>java.math.BigInteger to a JDBC NUMERIC
                            </para>
                            <para>
                                Registered under <literal>big_integer and java.math.BigInteger in the
                                type registry (see <xref linkend="types-registry"/>).
                            </para>
                        </listitem>
                    </varlistentry>
                </variablelist>
            </section>
            <section id="types-basic-value-bigdecimal">
                <title>java.math.BigDecimal
                <variablelist>
                    <varlistentry>
                        <term>org.hibernate.type.BigDecimalType
                        <listitem>
                            <para>
                                Maps a <classname>java.math.BigDecimal to a JDBC NUMERIC
                            </para>
                            <para>
                                Registered under <literal>big_decimal and java.math.BigDecimal in the
                                type registry (see <xref linkend="types-registry"/>).
                            </para>
                        </listitem>
                    </varlistentry>
                </variablelist>
            </section>
            <section id="types-basic-value-timestamp">
                <title>java.util.Date or java.sql.Timestamp
                <variablelist>
                    <varlistentry>
                        <term>org.hibernate.type.TimestampType
                        <listitem>
                            <para>
                                Maps a <classname>java.sql.Timestamp to a JDBC TIMESTAMP
                            </para>
                            <para>
                                Registered under <literal>timestamp, java.sql.Timestamp and
                                <literal>java.util.Date in the type registry (see ).
                            </para>
                        </listitem>
                    </varlistentry>
                </variablelist>
            </section>
            <section id="types-basic-value-time">
                <title>java.sql.Time
                <variablelist>
                    <varlistentry>
                        <term>org.hibernate.type.TimeType
                        <listitem>
                            <para>
                                Maps a <classname>java.sql.Time to a JDBC TIME
                            </para>
                            <para>
                                Registered under <literal>time and java.sql.Time in the
                                type registry (see <xref linkend="types-registry"/>).
                            </para>
                        </listitem>
                    </varlistentry>
                </variablelist>
            </section>
            <section id="types-basic-value-date">
                <title>java.sql.Date
                <variablelist>
                    <varlistentry>
                        <term>org.hibernate.type.DateType
                        <listitem>
                            <para>
                                Maps a <classname>java.sql.Date to a JDBC DATE
                            </para>
                            <para>
                                Registered under <literal>date and java.sql.Date in the
                                type registry (see <xref linkend="types-registry"/>).
                            </para>
                        </listitem>
                    </varlistentry>
                </variablelist>
            </section>
            <section id="types-basic-value-calendar">
                <title>java.util.Calendar
                <variablelist>
                    <varlistentry>
                        <term>org.hibernate.type.CalendarType
                        <listitem>
                            <para>
                                Maps a <classname>java.util.Calendar to a JDBC TIMESTAMP
                            </para>
                            <para>
                                Registered under <literal>calendar, java.util.Calendar and
                                <literal>java.util.GregorianCalendar in the type registry (see
                                <xref linkend="types-registry"/>).
                            </para>
                        </listitem>
                    </varlistentry>
                    <varlistentry>
                        <term>org.hibernate.type.CalendarDateType
                        <listitem>
                            <para>
                                Maps a <classname>java.util.Calendar to a JDBC DATE
                            </para>
                            <para>
                                Registered under <literal>calendar_date in the type registry (see
                                <xref linkend="types-registry"/>).
                            </para>
                        </listitem>
                    </varlistentry>
                </variablelist>
            </section>
            <section id="types-basic-value-currency">
                <title>java.util.Currency
                <variablelist>
                    <varlistentry>
                        <term>org.hibernate.type.CurrencyType
                        <listitem>
                            <para>
                                Maps a <classname>java.util.Currency to a JDBC VARCHAR (using the Currency code)
                            </para>
                            <para>
                                Registered under <literal>currency and java.util.Currency in the
                                type registry (see <xref linkend="types-registry"/>).
                            </para>
                        </listitem>
                    </varlistentry>
                </variablelist>
            </section>
            <section id="types-basic-value-locale">
                <title>java.util.Locale
                <variablelist>
                    <varlistentry>
                        <term>org.hibernate.type.LocaleType
                        <listitem>
                            <para>
                                Maps a <classname>java.util.Locale to a JDBC VARCHAR (using the Locale code)
                            </para>
                            <para>
                                Registered under <literal>locale and java.util.Locale in the
                                type registry (see <xref linkend="types-registry"/>).
                            </para>
                        </listitem>
                    </varlistentry>
                </variablelist>
            </section>
            <section id="types-basic-value-timezone">
                <title>java.util.TimeZone
                <variablelist>
                    <varlistentry>
                        <term>org.hibernate.type.TimeZoneType
                        <listitem>
                            <para>
                                Maps a <classname>java.util.TimeZone to a JDBC VARCHAR (using the TimeZone ID)
                            </para>
                            <para>
                                Registered under <literal>timezone and java.util.TimeZone in the
                                type registry (see <xref linkend="types-registry"/>).
                            </para>
                        </listitem>
                    </varlistentry>
                </variablelist>
            </section>
            <section id="types-basic-value-url">
                <title>java.net.URL
                <variablelist>
                    <varlistentry>
                        <term>org.hibernate.type.UrlType
                        <listitem>
                            <para>
                                Maps a <classname>java.net.URL to a JDBC VARCHAR (using the external form)
                            </para>
                            <para>
                                Registered under <literal>url and java.net.URL in the
                                type registry (see <xref linkend="types-registry"/>).
                            </para>
                        </listitem>
                    </varlistentry>
                </variablelist>
            </section>
            <section id="types-basic-value-class">
                <title>java.lang.Class
                <variablelist>
                    <varlistentry>
                        <term>org.hibernate.type.ClassType
                        <listitem>
                            <para>
                                Maps a <classname>java.lang.Class to a JDBC VARCHAR (using the Class name)
                            </para>
                            <para>
                                Registered under <literal>class and java.lang.Class in the
                                type registry (see <xref linkend="types-registry"/>).
                            </para>
                        </listitem>
                    </varlistentry>
                </variablelist>
            </section>
            <section id="types-basic-value-blob">
                <title>java.sql.Blob
                <variablelist>
                    <varlistentry>
                        <term>org.hibernate.type.BlobType
                        <listitem>
                            <para>
                                Maps a <classname>java.sql.Blob to a JDBC BLOB
                            </para>
                            <para>
                                Registered under <literal>blob and java.sql.Blob in the
                                type registry (see <xref linkend="types-registry"/>).
                            </para>
                        </listitem>
                    </varlistentry>
                </variablelist>
            </section>
            <section id="types-basic-value-clob">
                <title>java.sql.Clob
                <variablelist>
                    <varlistentry>
                        <term>org.hibernate.type.ClobType
                        <listitem>
                            <para>
                                Maps a <classname>java.sql.Clob to a JDBC CLOB
                            </para>
                            <para>
                                Registered under <literal>clob and java.sql.Clob in the
                                type registry (see <xref linkend="types-registry"/>).
                            </para>
                        </listitem>
                    </varlistentry>
                </variablelist>
            </section>
            <section id="types-basic-value-binary" revision="1">
                <title>byte[]
                <variablelist>
                    <varlistentry>
                        <term>org.hibernate.type.BinaryType
                        <listitem>
                            <para>
                                Maps a primitive byte[] to a JDBC VARBINARY
                            </para>
                            <para>
                                Registered under <literal>binary and byte[] in the
                                type registry (see <xref linkend="types-registry"/>).
                            </para>
                        </listitem>
                    </varlistentry>
                    <varlistentry>
                        <term>org.hibernate.type.MaterializedBlobType
                        <listitem>
                            <para>
                                Maps a primitive byte[] to a JDBC BLOB
                            </para>
                            <para>
                                Registered under <literal>materialized_blob in the type registry (see
                                <xref linkend="types-registry"/>).
                            </para>
                        </listitem>
                    </varlistentry>
                    <varlistentry>
                        <term>org.hibernate.type.ImageType
                        <listitem>
                            <para>
                                Maps a primitive byte[] to a JDBC LONGVARBINARY
                            </para>
                            <para>
                                Registered under <literal>image in the type registry (see
                                <xref linkend="types-registry"/>).
                            </para>
                        </listitem>
                    </varlistentry>
                </variablelist>
            </section>
            <section id="types-basic-value-wrapperbinary" revision="1">
                <title>Byte[]
                <variablelist>
                    <varlistentry>
                        <term>org.hibernate.type.BinaryType
                        <listitem>
                            <para>
                                Maps a java.lang.Byte[] to a JDBC VARBINARY
                            </para>
                            <para>
                                Registered under <literal>wrapper-binary, Byte[] and
                                <literal>java.lang.Byte[] in the type registry (see ).
                            </para>
                        </listitem>
                    </varlistentry>
                </variablelist>
            </section>
            <section id="types-basic-value-chararray">
                <title>char[]
                <variablelist>
                    <varlistentry>
                        <term>org.hibernate.type.CharArrayType
                        <listitem>
                            <para>
                                Maps a char[] to a JDBC VARCHAR
                            </para>
                            <para>
                                Registered under <literal>characters and char[]
                                in the type registry (see <xref linkend="types-registry"/>).
                            </para>
                        </listitem>
                    </varlistentry>
                </variablelist>
            </section>
            <section id="types-basic-value-characterarray" revision="1">
                <title>Character[]
                <variablelist>
                    <varlistentry>
                        <term>org.hibernate.type.CharacterArrayType
                        <listitem>
                            <para>
                                Maps a java.lang.Character[] to a JDBC VARCHAR
                            </para>
                            <para>
                                Registered under <literal>wrapper-characters, Character[]
                                and <literal>java.lang.Character[] in the type registry (see ).
                            </para>
                        </listitem>
                    </varlistentry>
                </variablelist>
            </section>
            <section id="types-basic-value-uuid">
                <title>java.util.UUID
                <variablelist>
                    <varlistentry>
                        <term>org.hibernate.type.UUIDBinaryType
                        <listitem>
                            <para>
                                Maps a java.util.UUID to a JDBC BINARY
                            </para>
                            <para>
                                Registered under <literal>uuid-binary and java.util.UUID
                                in the type registry (see <xref linkend="types-registry"/>).
                            </para>
                        </listitem>
                    </varlistentry>
                    <varlistentry>
                        <term>org.hibernate.type.UUIDCharType
                        <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 in the type registry (see
                                <xref linkend="types-registry"/>).
                            </para>
                        </listitem>
                    </varlistentry>
                    <varlistentry>
                        <term>org.hibernate.type.PostgresUUIDType
                        <listitem>
                            <para>
                                Maps a java.util.UUID to the PostgreSQL UUID data type (through
                                <literal>Types#OTHER which is how the PostgreSQL JDBC driver defines it).
                            </para>
                            <para>
                                Registered under <literal>pg-uuid in the type registry (see
                                <xref linkend="types-registry"/>).
                            </para>
                        </listitem>
                    </varlistentry>
                </variablelist>
            </section>
            <section id="types-basic-value-serializable">
                <title>java.io.Serializable
                <variablelist>
                    <varlistentry>
                        <term>org.hibernate.type.SerializableType
                        <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.
                                Additionally it gets registered under the specific
                                <interfacename>java.io.Serializable implementation class names.
                            </para>
                        </listitem>
                    </varlistentry>
                </variablelist>
            </section>
        </section>

        <section id="types-value-composite">
            <title>Composite types
            <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 id="types-value-collection">
            <title>Collection types
            <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 id="types-entity">
        <title>Entity types
        <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, both the User and
            <classname>Group 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 id="types-category-significance">
        <title>Significance of type categories
        <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 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 that Product sku.  You can
            define an association to Product <emphasis>based on its sku, assuming sku is unique, but that
            is totally different.
        </para>
        <para>
            TBC...
        </para>
    </section>

    <section id="types-custom">
        <title>Custom types
        <para>
            Hibernate makes it relatively easy for developers to create their own <emphasis>value types.  For
            example, you might want to persist properties of type <classname>java.lang.BigInteger to
            <literal>VARCHAR 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>INITIAL and SURNAME columns into a java.lang.String.
        </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
            and <classname>java.util.Currency together into a custom Money class.
        </para>

        <section id="types-custom-type">
            <title>Custom types using org.hibernate.type.Type
            <para>
                The first approach is to directly implement the <interfacename>org.hibernate.type.Type
                interface (or one of its derivatives).  Probably, you will be more interested in the more specific
                <interfacename>org.hibernate.type.BasicType 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, which is the key we would use to register our type in the registry:
            </para>

            <example id="types-custom-type-ex-definition">
                <title>Defining and registering the custom Type
                <programlisting role="JAVA">
            </example>
            <important>
                <para>
                    It is important that we registered the type <emphasis>before adding mappings.
                </para>
            </important>
        </section>

        <section id="types-custom-ut">
            <title>Custom types using org.hibernate.usertype.UserType
            <note>
                <para>
                    Both <interfacename>org.hibernate.usertype.UserType and
                    <interfacename>org.hibernate.usertype.CompositeUserType were originally
                    added to isolate user code from internal changes to the <interfacename>org.hibernate.type.Type
                    interfaces.
                </para>
            </note>
            <para>
                The second approach is the use the <interfacename>org.hibernate.usertype.UserType
                interface, which presents a somewhat simplified view of the <interfacename>org.hibernate.type.Type
                interface.  Using a <interfacename>org.hibernate.usertype.UserType, our
                <classname>Money custom type would look as follows:
            </para>
            <example id="types-custom-ut-ex-definition">
                <title>Defining the custom UserType
                <programlisting role="JAVA">
            </example>
            <para>
                There is not much difference between the <interfacename>org.hibernate.type.Type example
                and the <interfacename>org.hibernate.usertype.UserType example, but that is only because
                of the snippets shown.  If you choose the <interfacename>org.hibernate.type.Type approach
                there are quite a few more methods you would need to implement as compared to the
                <interfacename>org.hibernate.usertype.UserType.
            </para>
        </section>

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

            <example id="types-custom-cut-ex-definition">
                <title>Defining the custom CompositeUserType
                <programlisting role="JAVA">
            </example>
        </section>

    </section>

    <section id="types-registry">
        <title>Type registry
        <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 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 method of the org.hibernate.cfg.Configuration
            class when bootstrapping Hibernate.  For example, lets say you want Hibernate to use your custom
            <classname>SuperDuperStringType; during bootstrap you would call:
        </para>
        <example id="type-registry-override-ex">
            <title>Overriding the standard StringType
            <programlisting role="JAVA">
        </example>
        <para>
            The argument to <methodname>registerTypeOverride is a org.hibernate.type.BasicType
            which is a specialization of the <interfacename>org.hibernate.type.Type we saw before.  It
            adds a single method:
        </para>
        <example>
            <title>Snippet from BasicType.java
            <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 extends 
            <classname>org.hibernate.type.StringType); another is to use delegation.
        </para>
    </section>

</chapter>

Other Hibernate examples (source code examples)

Here is a short list of links related to this Hibernate type.xml source code file:

... this post is sponsored by my books ...

#1 New Release!

FP Best Seller

 

new blog posts

 

Copyright 1998-2021 Alvin Alexander, alvinalexander.com
All Rights Reserved.

A percentage of advertising revenue from
pages under the /java/jwarehouse URI on this website is
paid back to open source projects.