Взгляд изнутри на спящие типы

Типы гибернации являются представлением типов SQL баз данных, обеспечивают абстракцию базовых типов баз данных и предотвращают взаимодействие приложения с фактическими типами столбцов базы данных. Они позволяют нам разрабатывать приложение, не беспокоясь о целевой базе данных и типах столбцов, которые поддерживает база данных. Вместо этого мы включаем отображение типов Java в типы Hibernate. Диалект базы данных, как часть Hibernate, отвечает за преобразование типов Java в типы SQL на основе целевой базы данных. Это дает нам возможность изменить базу данных на базу данных, которая может поддерживать различные типы столбцов или SQL без изменения кода приложения.

Встроенные типы

Hibernate includes a rich and powerful range of built-in types. These types satisfy most needs of a typical application, providing a bridge between basic Java types and common SQL types. Java types mapped with these types range from basic, simple types, such as long and int, to large and complex types, such as Blob and Clob. The following table categorizes Hibernate built-in types with corresponding Java and SQL types:

Although the SQL types specified in the table above are standard SQL types, your database may support somewhat different SQL types. Refer to your database documentation to find out which types you may use instead of the standard SQL types shown in the table above.

Don’t worry about the SQL types that your database supports. The SQL dialect and JDBC driver are always responsible for transforming the Java type values to appropriate SQL type representations.

The type attribute specifies Hibernate types in mapping definitions. This helps Hibernate to create an appropriate SQL statement when the class property is stored, updated, or retrieved from its respective column.

The type attribute may appear in different places in a mapping file. You may use it with the <id>, <property>, <discriminator>, <index>, and <element> elements. Here is a sample mapping file with some type attributes in different locations:

<hibernate-mapping>
 <class name="Person" table="PERSON" discriminator-value="PE">

 <id name="id" column="ID" type="long">
 <generator class="native"/>
 </id>

 <discriminator column="PERSON_TYPE" type="string"/>

 <property name="birthdate" column="BIRTHDATE" type="date"/>

 <list name="papers" table="STUDENT_PAPER">
 <key column="STUDENT_ID"/>
 <list-index column="POSITION"/>
 <element column="PAPER_PATH" type="string"/>
 </list>

 <!-- mapping of other fields -->
 </class>
</hibernate-mapping>

If a property is mapped without the type attribute, Hibernate uses the reflection API to find the actual type of that property and uses the corresponding Hibernate type for it. However, you should specify the type attribute if that property can be mapped with more than one Hibernate type. For example, if a property is of type java.lang.String, and its mapping definition does not include the type attribute, Hibernate will use the reflection API and select the type string for it. This means you need to explicitly define the Hibernate type for a Java String if you want to map the String with a character or text Hibernate type.

Custom types

For most mappings, Hibernate’s built-in types are enough. However, in some situations, you may need to define a custom type. These situations generally happen when we want Hibernate to treat basic Java types or persistent classes differently than it normally would. Here are some situations where you may need to define and use a custom type:

• Storing a particular Java type in a column with a different SQL type than Hibernate normally uses: For example, you might want to store a java.util.Date object in a column of type VARCHAR, or a String object in a DATE column.
• Mapping a value type: Value types, the dependent persistent classes that do not have their own identifiers, can be mapped with custom types. This means you can treat value types similarly to primitive types and map them with the <property> element, instead of <component>.
• Splitting up a single property value and storing the result in more than one database column: For example, assume that any phone number is split-up into four components—representing country code, area code, exchange, and line number, stored in four columns of the database. We may take this approach to provide a search facility for countries, areas, exchanges, and line numbers. If the phone numbers are represented as long numbers populated from four columns, we need to define a custom type and tell Hibernate how to assemble the number.
• Storing more than one property in a single column: For example, if a papersproperty of a Student class is represented as an object of java.util.List and holds the file paths of all of the papers the student has written. You can define a custom type to persist all of the papers file paths as a semicolon-separated string in a single column.
• Using an application-specific class as an identifier for the persistent class: For example, suppose you want to use the application-specific class CustomIdentifier, instead of the int, long, String, and so on, for persistent class identifiers. In this case, you also need to implement an IdentifierGenerator to tell Hibernate how to create new identifier values for non-persisted objects.

In practice, other use cases also need custom types for implementation and use. In all of these situations, you must tell Hibernate how to map a particular Java type to a database representation. You do this by implementing one of the interfaces which Hibernate provides for this purpose. The basic and most commonly used of these interfaces include org.hibernate.usertype.UserType and org.hibernate. usertype.CompositeUserType. Let’s look at these in detail, discussing their differences, and how to use them.

UserType

UserType is the most commonly used Hibernate extension type. This interface exposes basic methods for defining a custom type. Here, we introduce a simple case and show how a custom type can provide a convenient mapping definition for it.

Suppose that the history of any school is represented by an individual class, History. Obviously, the History class is a value type, because no other persistent class uses the History class for its own use. This means that all History objects depend on School objects. Moreover, each school has its own history, and history is never shared between schools. Here is the School class:

package com.packtpub.springhibernate.ch07;

import java.io.Serializable;

public class School implements Serializable {

 private long id;
 private History history ;
 //other fields

 //setter and getter methods
 public long getId() {
 return id;
 }

 public void setId(long id) {
 this.id = id;
 }

 public History getHistory() {
 return history;
 }

 public void setHistory(History history) {
 this.history = history;
 }
 
 //other setters and getters
}

And this is the History class:

package com.packtpub.springhibernate.ch07;

import java.io.Serializable;
import java.util.Date;

public class History implements Serializable {
 long initialCapacity;
 Date establishmentDate;

 public long getInitialCapacity() {
 return initialCapacity;
 }

 public void setInitialCapacity(long initialCapacity) {
 this.initialCapacity = initialCapacity;
 }

 public Date getEstablishmentDate() {
 return establishmentDate;
 }

 public void setEstablishmentDate(Date establishmentDate) {
 this.establishmentDate = establishmentDate;
 }
}

Note that I have intentionally omitted all irrelevant fields of the two classes to keep the example simple.

Our strategy in mapping a value type so far is to use one table for persisting both the persistent class and its associated value types. Based on this strategy, we need to use a SCHOOL table, which stores all of the School and History properties, and then map both School and its History class into that table through the <component> element in the mapping file. The mapping definition for School and its associated History class is as follows:

<hibernate-mapping>
 <class name="com.packtpub.springhibernate.ch07.School" 
table="SCHOOL">
 <id name="id" type="long" column="id">
 <generator class="increment"/>
 </id>
 <component name="history" 
 class="com.packtpub.springhibernate.ch07.History">
 <property name="initialCapacity" column="INITIAL_CAPACITY"
 type="long"/>
 <property name="establishmentDate" column="ESTABLISHMENT_DATE"
 type="date"/> 
 </component>

 <!-- mapping of other fields -->
 </class>
</hibernate-mapping>

As an alternative approach, you can map the History class with a custom type. You do this by implementing a custom type, HistoryType, which defines how to map History objects to the target table. Actually, Hibernate does not persist a custom type. Instead, the custom type gives Hibernate information about how to persist a value type in the database. Let’s implement a basic custom type by implementing the UserType interface. In the next section of this article, we’ll discuss how to map History with an implementation of another Hibernate custom type interface, CompositeUserType.

The following code shows the HistoryType class that implements the UserType interface, providing a custom type for the History class:

package com.packtpub.springhibernate.ch07;

import java.sql.PreparedStatement;
import java.sql.ResultSet;
import java.sql.SQLException;
import java.sql.Types;
import java.io.Serializable;
import java.util.Date;

import org.hibernate.Hibernate;
import org.hibernate.HibernateException;
import org.hibernate.usertype.UserType;

public class HistoryType implements UserType {

 private int[] types = { Types.BIGINT, Types.DATE};

 public int[] sqlTypes() {
 return types;
 }

 public Class returnedClass() {
 return History.class;
 }

 public boolean equals(Object a, Object b) throws HibernateException {
 return (a == b) ||
 ((a != null) && (b != null) && (a.equals(b)));
 }

 public int hashCode(Object o) throws HibernateException {
 return o.hashCode();
 }

 public Object nullSafeGet(ResultSet rs, String[] names, Object owner)
 throws HibernateException, SQLException {
 Long initialCapacity = rs.getLong(names[0]);
 // check if the last column read is null
 if (rs.wasNull()) return null;
 Date establishmentDate = rs.getDate(names[1]);
 History history = new History() ;
 history.setInitialCapacity(initialCapacity.longValue());
 history.setEstablishmentDate(establishmentDate);
 return history;
 }

 public void nullSafeSet(PreparedStatement ps, Object value, int index)
 throws HibernateException, SQLException {
 
 if(value==null){
 ps.setNull(index, Hibernate.LONG.sqlType());
 ps.setNull(index+1, Hibernate.DATE.sqlType());
 }else{
 History history = (History) value;
 long initialCapacity = history.getInitialCapacity();
 Date establishmentDate = history.getEstablishmentDate();
 Hibernate.LONG.nullSafeSet(ps, new Long(initialCapacity), index);
 Hibernate.DATE.nullSafeSet(ps, establishmentDate, index + 1);
 }
 }

 public Object deepCopy(Object o) throws HibernateException {
 if (o == null) return null;
 History origHistory = (History) o;
 History newHistory = new History();

 newHistory.setInitialCapacity(origHistory.getInitialCapacity());
 newHistory.setEstablishmentDate(origHistory.getEstablishmentDate());
 return newHistory;
 }

 public boolean isMutable() {
 return true;
 }

 public Serializable disassemble(Object value) throws 
 HibernateException {
 return (Serializable) value;
 }

 public Object assemble(Serializable cached, Object owner) 
 throws HibernateException {
 return cached;
 }

 public Object replace(Object original, Object target, Object owner) 
 throws HibernateException {
 return original;
 }
}

The following table provides a short description for the methods in the UserType interface:

In some of the methods shown in the table above, the owner object is passed as an argument to the method. You can use this object if you need the other properties of the value-type instance. For example, you can access a property of the owner if you need it to calculate the value for a value-type property.

Serializing and caching issue
If the value type, in our case History, does not implement the java.io.Serializable interface, then its respective custom type is responsible for properly serializing or deserializing the value type. Otherwise, the value-type instances cannot be cached by the Hibernate second-level cache service.

To use the defined custom type, you need to edit the mapping file as shown below:

<hibernate-mapping>
 <class name="com.packtpub.springhibernate.ch07.School" table="SCHOOL">
 <id name="id" type="long" column="id">
 <generator class="increment"/>
 </id>
 <property name="history" 
 type="com.packtpub.springhibernate.ch07.HistoryType">
 <column="INITIAL_CAPACITY" type="long"/>
 <column="ESTABLISHMENT_DATE" type="date"/> 
 </property>

 <!-- mapping of other fields -->
 </class>
</hibernate-mapping>

Note that you should specify the columns in order, corresponding to the order of types returned by the getTypes() method and the index of the values the nullSafeGet() and nullSafeSet() handle.

So far, all we have done is implemented a custom type in the simplest form. The implemented custom type only transforms the value-type instances to the database columns and vice versa. A custom type may be more complicated than we have seen so far, and can do much more sophisticated things. The advantage of this implemented custom type is obvious: we can define our own strategy for mapping value types. For instance, a property of the value type can be stored in more than one column, or more than one property can be stored in a single column.

The main shortcoming of this approach is that, we have hidden the value-type properties from Hibernate. Therefore, Hibernate does not know anything about the properties inside the value type, or how to query persistent objects based on their associated value types as problem constraints are involved. Let’s look at CompositeUserType and how it can solve this problem.

CompositeUserType

Another way to define a custom type is to use the CompositeUserType interface. This type is similar to UserType, but with more methods to expose the internals of your value-type class to Hibernate. CompositeUserType is useful when application query expressions include constraints on value-type properties. If you want to query the persistent objects with constraints on their associated value types, map the associated value types with CompositeUserType. The following code shows the CompositeHistoryType implementation for History:

package com.packtpub.springhibernate.ch07;

import org.hibernate.usertype.CompositeUserType;
import org.hibernate.type.Type;
import org.hibernate.HibernateException;
import org.hibernate.Hibernate;
import org.hibernate.engine.SessionImplementor;

import java.sql.ResultSet;
import java.sql.SQLException;
import java.sql.PreparedStatement;
import java.io.Serializable;
import java.util.Date;

public class CompositeHistoryType implements CompositeUserType {

 private String[] propertyNames = {"initialCapacity", "establishmentDate"};

 private Type[] propertyTypes = {Hibernate.LONG, Hibernate.DATE};

 public String[] getPropertyNames() {
 return propertyNames;
 }

 public Type[] getPropertyTypes() {
 return propertyTypes;
 }

 public Object getPropertyValue(Object component, int property) {
 History history = (History) component;
 switch (property) {
 case 0:
 return new Long(history.getInitialCapacity());
 case 1:
 return history.getEstablishmentDate();
 }
 throw new IllegalArgumentException(property +
 " is an invalid property index for class type " +
 component.getClass().getName());
 }

 public void setPropertyValue(Object component, int property,
 Object value) {
 History history = (History) component;
 switch (property) {
 case 0:
 history.setInitialCapacity(((Long) value).longValue());
 case 1:
 history.setEstablishmentDate((Date) value);
 default:
 throw new IllegalArgumentException(property +
 " is an invalid property index for class type " +
 component.getClass().getName());
 }
 
 }

 public Class returnedClass() {
 return History.class;
 }

 public boolean equals(Object o1, Object o2) throws HibernateException {
 if (o1 == o2) return true;
 if (o1 == null || o2 == null) return false;
 return o1.equals(o2);
 }

 public int hashCode(Object o) throws HibernateException {
 return o.hashCode();
 }

 public Object assemble(Serializable cached,
 SessionImplementor session, Object owner)
 throws HibernateException {
 return deepCopy(cached);
 }

 public Object replace(Object original, Object target, 
 SessionImplementor sessionImplementor, Object owner) 
 throws HibernateException {
 return original;
 }

 public Serializable disassemble(Object value,
 SessionImplementor session)
 throws HibernateException {
 return (Serializable) deepCopy(value);
 }

 public Object nullSafeGet(ResultSet rs, String[] names,
 SessionImplementor session, Object o)
 throws HibernateException, SQLException {
 long initialCapacity = rs.getLong(names[0]);
 java.util.Date establishmentDate = rs.getDate(names[1]);
 return new History(initialCapacity, establishmentDate);
 }

 public void nullSafeSet(PreparedStatement ps,
 Object value, int index, SessionImplementor session)
 throws HibernateException, SQLException {
 if (value == null) {
 ps.setNull(index, Hibernate.LONG.sqlType());
 ps.setNull(index + 1, Hibernate.DATE.sqlType());
 } else {
 History history = (History) value;
 long l = history.getEstablishmentDate().getTime();
 ps.setLong(index, history.getInitialCapacity());
 ps.setDate(index + 1, new java.sql.Date(l));
 }
 }

 public Object deepCopy(Object value) throws HibernateException {
 if (value == null) return null;
 History origHistory = (History) value;
 History newHistory = new History();

 newHistory.setInitialCapacity(origHistory.getInitialCapacity());
 newHistory.setEstablishmentDate(origHistory.getEstablishmentDate());
 return newHistory;
 }

 public boolean isMutable() {
 return true;
 }
}

As you can see, this interface exposes some extra methods not seen in UserType. The following table shows the functionality of these methods:

Using this custom type is same as using UserType, except that you need to specify the CompositeHistoryType instead of HistoryType as follows:

<property name="history" 
 type="com.packtpub.springhibernate.ch07.CompositeHistoryType">
 <column="INITIAL_CAPACITY" type="long"/>
 <column="ESTABLISHMENT_DATE" type="date"/> 
</property>

As mentioned earlier, this custom type provides an ability to query on properties of the History type. HQL is one approach provided by Hibernate to query the persistent object. For instance, suppose we are interested in schools established before 1980. The following code shows querying these objects with HQL, a Hibernate-specific query language that works with objects:

Calendar c = Calendar.getInstance();
c.set(Calendar.YEAR, 1980);
Query q = session.createQuery(
"select s from School s where s.history.establishmentDate < :edate"
).setParameter("edate", new Date(c.getTimeInMillis()));

All we have done in this snippet is created a Query object with an HQL expression indicating all School objects with establishment date before 1980. Note that HistoryCompositeType provides the ability to query the School object with criteria applied to History objects.

The only advantage of CompositeUserType over UserType is that CompositeUserType exposes the value-type properties for Hibernate. Therefore, it lets you query persistent instances based on values of their associated value-type instances.

Summary

In this article, we discussed Hibernate types, which define the mapping of each Java type to an SQL type. It is the responsibility of the Hibernate dialect and the JDBC driver to convert the Java types to the actual target SQL types. This means a Java type may be transformed to different SQL types when different databases are used.

Although Hibernate provides a rich set of data types, called built-in types, some situations require the definition of a new type. One such situation occurs when you want to change Hibernate’s default behavior for mapping a Java type to an SQL type. Another situation is when you want to split up a class property to a set of table columns, or merge a set of properties to a table column.

Built-in types include primitive, string, byte array, time, localization, serializable, and JDBC large types.

Hibernate provides several interfaces for implementation by custom types. The most commonly used interfaces are org.hibernate.usertype.UserType and org.hibernate.usertype.CompositeUserType. The basic extension point is UserType. It allows us to map a value-type, but hides the value-type properties from Hibernate, so it does not provide the application with the ability to query value types. In contrast, CompositeUserType exposes the value-type properties to Hibernate, and allows Hibernate to query the value-types.