git-svn-id: https://svn.jboss.org/repos/hibernate/core/trunk@19607 1b8cb986-b30d-0410-93ca-fae66ebed9b2
This commit is contained in:
Steve Ebersole
parent
30ea7142e8
commit
a05dc9066a
|
|
@ -0,0 +1,990 @@
|
||||||
|
<!--
|
||||||
|
~ 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</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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 id="types.basic.value.binary">
|
||||||
|
<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>
|
||||||
|
</variablelist>
|
||||||
|
</section>
|
||||||
|
<section id="types.basic.value.wrapperbinary">
|
||||||
|
<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 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 id="types.basic.value.characterarray">
|
||||||
|
<title>char[]</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 id="types.basic.value.serializable">
|
||||||
|
<title>java.io.Serializable</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 <literal>java.io.Serializable</literal>. Additionally it
|
||||||
|
gets registered under the specific <interfacename>java.io.Serializable</interfacename>
|
||||||
|
implementation class names.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
</variablelist>
|
||||||
|
</section>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section 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.
|
||||||
|
</para>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section 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 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 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 maker 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.
|
||||||
|
|
||||||
|
|
||||||
|
entity types define
|
||||||
|
data that maintains its own lifecycle, while value types define data that only exists dependently. Essentially it defines it own unique identifier. In turn that means
|
||||||
|
that it can be used to share references to that data from other entities (or components or collections).
|
||||||
|
This dependence/independence has a few important ramifications:
|
||||||
|
<itemizedlist>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
First, entities can be looked up and referenced (as in foreign keys). The same is not true of
|
||||||
|
a value type. For example, a <classname>Product</classname> entity can be looked up by its
|
||||||
|
unique identifier. The sku of that Product
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</itemizedlist>
|
||||||
|
</para>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section 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> columsn 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 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:
|
||||||
|
<example 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 );
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
...
|
||||||
|
}]]></programlisting>
|
||||||
|
<programlisting role="JAVA">
|
||||||
|
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>
|
||||||
|
</para>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section 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 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 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.UserType</interfacename>, our <classname>Money</classname> custom
|
||||||
|
type would look as follows:
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<example 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 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:
|
||||||
|
<example 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>
|
||||||
|
<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:
|
||||||
|
<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>
|
||||||
|
One approach is to use inheritance (<classname>SuperDuperStringType</classname> extends
|
||||||
|
<classname>org.hibernate.typeStringType</classname>). Another approach is to use delegation.
|
||||||
|
</para>
|
||||||
|
<important>
|
||||||
|
<para>
|
||||||
|
Currently UserType and CompositeUserType cannot be registered with the registry. See
|
||||||
|
<ulink url="http://opensource.atlassian.com/projects/hibernate/browse/HHH-5262"/> for details.
|
||||||
|
</para>
|
||||||
|
</important>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
</chapter>
|
||||||
Loading…
Reference in New Issue