Skip to content
Tutorials Center
My learning

Topics

Lesson 13 of 39 ยท Entity Mapping

Types, Enums and Converters

Map Java types to columns in Hibernate: strings, numbers, java.time dates, enums with @Enumerated, booleans, and custom AttributeConverter classes with runnable stand-ins.

Hibernate maps most Java types to a sensible column type without any annotation: String to varchar, int to integer, LocalDate to date. The interesting cases are enums, dates, large values and your own types. This lesson shows the defaults, the choices you should make explicitly, and how to write a converter for anything else.

Real Hibernate code is read-only here; the runnable programs are plain-Java stand-ins.

Built-in type mapping

Java type Typical column
String varchar(255)
int, long, short integer, bigint, smallint
boolean boolean (or bit)
BigDecimal numeric(38,2); set precision and scale
LocalDate, LocalDateTime, Instant date, timestamp, timestamp
UUID uuid (or binary(16))
byte[] varbinary / blob

Use the java.time types, not java.util.Date. Prefer Instant or OffsetDateTime for points in time, and keep the JDBC time zone fixed (hibernate.jdbc.time_zone=UTC) so servers in different zones agree.

Enums: choose STRING

Java
public enum Status { DRAFT, PUBLISHED, ARCHIVED }

@Enumerated(EnumType.STRING)
private Status status;

The default EnumType.ORDINAL stores the position (0, 1, 2). Inserting a new constant in the middle, or reordering, silently changes the meaning of every existing row. STRING stores the constant name and survives reordering; renaming a constant is then the only breaking change. Always write @Enumerated(EnumType.STRING) explicitly.

Booleans and Y/N columns

Legacy schemas often store booleans as 'Y'/'N' or 0/1. Hibernate has @JdbcTypeCode and converters for that; the general tool is AttributeConverter.

AttributeConverter

A converter turns a Java value into a database value and back:

Java
@Converter(autoApply = false)
public class EmailConverter implements AttributeConverter<Email, String> {

    @Override
    public String convertToDatabaseColumn(Email email) {
        return email == null ? null : email.address();
    }

    @Override
    public Email convertToEntityAttribute(String db) {
        return db == null ? null : new Email(db);
    }
}

@Entity
public class Customer {
    @Id Long id;

    @Convert(converter = EmailConverter.class)
    private Email email;
}
  • autoApply = true applies the converter to every attribute of that Java type; otherwise add @Convert where needed.
  • Both methods must handle null.
  • Converters work on basic attributes. You cannot use them on ids or on association attributes.

Good uses: value objects (Email, Money as a string), encrypting a column, storing a List<String> as comma-separated text, legacy flag columns.

Dates and the Temporal question

With java.time types no @Temporal is needed; Hibernate picks date for LocalDate, timestamp for LocalDateTime, and so on. @Temporal exists only for the old java.util.Date and Calendar. Two helpers fill timestamps for you in Hibernate 6:

Java
@CreationTimestamp
private Instant createdAt;       // set on INSERT

@UpdateTimestamp
private Instant updatedAt;       // set on every UPDATE

JSON and other structured values

Hibernate 6 can map a Java type to a JSON column with @JdbcTypeCode(SqlTypes.JSON), given a JSON library (Jackson or JSON-B) on the classpath. The database must support a JSON type for the best results.

Java
@JdbcTypeCode(SqlTypes.JSON)
private Map<String, String> attributes;

Stand-in: a converter pipeline

Java Stand-in: AttributeConverter for an Email value

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Stand-in: ORDINAL versus STRING

Java Stand-in: why ORDINAL is fragile

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

The PUBLISHED row now reads back as REVIEW with ORDINAL. Nothing failed, the data is simply wrong.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which EnumType should you normally use?

    STRING stores the constant name, so reordering or inserting constants does not corrupt data.
  2. 2. What does AttributeConverter do?

    It maps a basic attribute to a database value in both directions.
  3. 3. What must both converter methods handle?

    Nullable columns pass null in both directions.
  4. 4. Which Java type is recommended for dates without time?

    The java.time types are mapped directly and need no @Temporal.

Summary

  • Most Java types map to sensible columns without annotations; set precision/scale for decimals.
  • Use java.time, not java.util.Date.
  • Always write @Enumerated(EnumType.STRING).
  • AttributeConverter maps your own value types, encrypted columns and legacy flags.
  • Here, real Hibernate code is read-only; the runnable programs are plain-Java stand-ins.

Next: Embeddables and Value Objects