5.2.3. Custom value types
It is relatively easy for developers to create their own value types. For example, you might want to persist properties of type
java.lang.BigInteger
to VARCHAR
columns. Hibernate does not provide a built-in type for this. Custom types are not limited to mapping a property, or collection element, to a single table column. So, for example, you might have a Java property getName()
/setName()
of type java.lang.String
that is persisted to the columns FIRST_NAME
, INITIAL
, SURNAME
.
To implement a custom type, implement either
org.hibernate.UserType
or org.hibernate.CompositeUserType
and declare properties using the fully qualified classname of the type. View org.hibernate.test.DoubleStringType
to see the kind of things that are possible.
<property name="twoStrings" type="org.hibernate.test.DoubleStringType"> <column name="first_string"/> <column name="second_string"/> </property>
Notice the use of
<column>
tags to map a property to multiple columns.
The
CompositeUserType
, EnhancedUserType
, UserCollectionType
, and UserVersionType
interfaces provide support for more specialized uses.
You can even supply parameters to a
UserType
in the mapping file. To do this, your UserType
must implement the org.hibernate.usertype.ParameterizedType
interface. To supply parameters to your custom type, you can use the <type>
element in your mapping files.
<property name="priority"> <type name="com.mycompany.usertypes.DefaultValueIntegerType"> <param name="default">0</param> </type> </property>
The
UserType
can now retrieve the value for the parameter named default
from the Properties
object passed to it.
If you regularly use a certain
UserType
, it is useful to define a shorter name for it. You can do this using the <typedef>
element. Typedefs assign a name to a custom type, and can also contain a list of default parameter values if the type is parameterized.
<typedef class="com.mycompany.usertypes.DefaultValueIntegerType" name="default_zero"> <param name="default">0</param> </typedef>
<property name="priority" type="default_zero"/>
It is also possible to override the parameters supplied in a typedef on a case-by-case basis by using type parameters on the property mapping.
Even though Hibernate's rich range of built-in types and support for components means you will rarely need to use a custom type, it is considered good practice to use custom types for non-entity classes that occur frequently in your application. For example, a
MonetaryAmount
class is a good candidate for a CompositeUserType
, even though it could be mapped as a component. One reason for this is abstraction. With a custom type, your mapping documents would be protected against changes to the way monetary values are represented.