Boolean Converters in Hibernate 6

1. Overview

In this tutorial, we’ll learn how to use boolean converters added in Hibernate 6 to map boolean properties in our domain model. Hibernate 6 revamped the type system. Consequently, the update removed a few existing classes used for representing booleans.

2. Models

To illustrate how to use boolean converters in Hibernate 6, we’ll be using the H2 database in the tests. First, we’ll create a database table with a SQL script:

CREATE TABLE Question (
    id UUID,
    content VARCHAR,
    correctAnswer CHAR,
    shouldBeAsked CHAR,
    isEasy TINYINT,
    wasAskedBefore CHAR,
    PRIMARY KEY (id)
)

Then, in Java, we’ll map this table to the Question entity class:

@Entity
public class Question {
    @Id
    private UUID id;
    private String content;
    private Boolean correctAnswer;
    private Boolean shouldBeAsked;
    private Boolean isEasy;
    private Boolean wasAskedBefore;

    public Question() {
    }

    // standard setters and getters
}

3. Mapping Y and N With YesNoConverter

In general, the uppercase letters Y and N are used to convey a true or false value, respectively. Previously, we could map these by annotating a field with @Type and specifying YesNoBooleanType:

// the old way
@Type(type = "org.hibernate.type.YesNoBooleanType")
private Boolean someBoolean;

Hibernate 6 replaced YesNoBooleanType with YesNoConverter. Because it’s a converter, we have to use it with @Convert instead of @Type.

Let’s apply this new converter to correctAnswer in Question:

@Convert(converter = YesNoConverter.class)
private Boolean correctAnswer;

Now, let’s verify Y and N are mapped correctly:

@Test
void whenFieldAnnotatedWithYesNoConverter_ThenConversionWorks() {
    session.beginTransaction();
    UUID likeJavaQuestionId = UUID.randomUUID();
    UUID sydneyCapitalOfAustraliaQuestionId = UUID.randomUUID();
    session.persist(new QuestionBuilder().id(likeJavaQuestionId)
      .content("Do you like Java?")
      .correctAnswer(true)
      .build());
    session.persist(new QuestionBuilder().id(sydneyCapitalOfAustraliaQuestionId)
      .content("Is Sydney the capital of Australia?")
      .correctAnswer(false)
      .build());
    session.flush();

    char likeJavaQuestionCorrectAnswerDbValue = session.createNativeQuery(format("SELECT correctAnswer FROM Question WHERE id='%s'", likeJavaQuestionId), Character.class)
      .getSingleResult();
    char sydneyCapitalOfAustraliaQuestionCorrectAnswerDbValue = session.createNativeQuery(format("SELECT correctAnswer FROM Question WHERE id='%s'", sydneyCapitalOfAustraliaQuestionId), Character.class)
      .getSingleResult();
    session.close();

    assertEquals('Y', likeJavaQuestionCorrectAnswerDbValue);
    assertEquals('N', sydneyCapitalOfAustraliaQuestionCorrectAnswerDbValue);
}

4. Mapping T and F With TrueFalseConverter

Similarly, we can use the uppercase letters T and F to represent a boolean. Hibernate 6 removed TrueFalseBooleanType:

// old way
@Type(type = "org.hibernate.type.TrueFalseBooleanType")
private Boolean someBoolean;

As a replacement, we’ll use TrueFalseConverter to specify this mapping. Let’s register it for shouldBeAsked:

@Convert(converter = TrueFalseConverter.class)
private Boolean shouldBeAsked;

Let’s test the conversion:

@Test
void whenFieldAnnotatedWithTrueFalseConverter_ThenConversionWorks() {
    session.beginTransaction();
    UUID codeTestedQuestionId = UUID.randomUUID();
    UUID earningsQuestionId = UUID.randomUUID();
    session.persist(new QuestionBuilder().id(codeTestedQuestionId)
      .content("Is this code tested?")
      .shouldBeAsked(true)
      .build());
    session.persist(new QuestionBuilder().id(earningsQuestionId)
      .content("How much do you earn?")
      .shouldBeAsked(false)
      .build());
    session.flush();

    char codeTestedQuestionShouldBeAskedDbValue = session.createNativeQuery(format("SELECT shouldBeAsked FROM Question WHERE id='%s'", codeTestedQuestionId), Character.class)
      .getSingleResult();
    char earningsQuestionsShouldBeAskedDbValue = session.createNativeQuery(format("SELECT shouldBeAsked FROM Question WHERE id='%s'", earningsQuestionId), Character.class)
      .getSingleResult();
    session.close();

    assertEquals('T', codeTestedQuestionShouldBeAskedDbValue);
    assertEquals('F', earningsQuestionsShouldBeAskedDbValue);
}

5. Mapping 0 and 1 With NumericBooleanConverter

Lastly, letters aren’t the only way to represent a boolean. People commonly use the integers 0 and 1 for this purpose as well. In the past, we’d use NumericBooleanType for this representation:

// old way
@Type(type = "org.hibernate.type.NumericBooleanType")
private Boolean someBoolean;

Let’s instead use the new NumericBooleanConverter. We’ll map zero or one values to isEasy:

@Convert(converter = NumericBooleanConverter.class)
private Boolean isEasy;

As usual, let’s check if it’s working as expected:

@Test
void whenFieldAnnotatedWithNumericBooleanConverter_ThenConversionWorks() {
    session.beginTransaction();
    UUID earthFlatQuestionId = UUID.randomUUID();
    UUID shouldLearnProgrammingQuestionId = UUID.randomUUID();
    session.persist(new QuestionBuilder().id(earthFlatQuestionId)
      .content("Is the Earth flat?")
      .isEasy(true)
      .build());
    session.persist(new QuestionBuilder().id(shouldLearnProgrammingQuestionId)
      .content("Should one learn programming")
      .isEasy(false)
      .build());
    session.flush();

    int earthFlatQuestionIsEasyDbValue = session.createNativeQuery(format("SELECT isEasy FROM Question WHERE id='%s'", earthFlatQuestionId), Integer.class)
      .getSingleResult();
    int shouldLearnProgrammingQuestionIsEasyDbValue = session.createNativeQuery(format("SELECT isEasy FROM Question WHERE id='%s'", shouldLearnProgrammingQuestionId), Integer.class)
      .getSingleResult();
    session.close();

    assertEquals(1, earthFlatQuestionIsEasyDbValue);
    assertEquals(0, shouldLearnProgrammingQuestionIsEasyDbValue);
}

6. Specifying a Default Converter With @ConverterRegistration

Annotating every boolean field with a converter is tedious and error-prone. More often than not, we represent a boolean in only one way in our database.

Unsurprisingly, the boolean converters provided by Hibernate are not set to auto-apply by default. However, Hibernate 6.1 introduced @ConverterRegistration, which we can use to auto-apply existing converters.

To do this, let’s add a package-info.java file with this annotation in the package where our Question class resides and make YesNoConverter apply by default:

@ConverterRegistration(converter = YesNoConverter.class)
package com.baeldung.hibernate.booleanconverters.model;

import org.hibernate.annotations.ConverterRegistration;
import org.hibernate.type.YesNoConverter;

We didn’t set autoApply in @ConverterRegistration because it’s set to true by default. The Question entity contains the boolean field wasAskedBefore, and since we didn’t annotate it with any converter, Hibernate uses YesNoConverter to map it:

@Test
void givenConverterRegisteredToAutoApply_whenFieldIsNotAnnotated_ThenConversionWorks() {
    session.beginTransaction();
    UUID likeJavaQuestionId = UUID.randomUUID();
    UUID likeKotlinQuestionId = UUID.randomUUID();
    session.persist(new QuestionBuilder().id(likeJavaQuestionId)
      .content("Do you like Java?")
      .wasAskedBefore(true)
      .build());
    session.persist(new QuestionBuilder().id(likeKotlinQuestionId)
      .content("Do you like Kotlin?")
      .wasAskedBefore(false)
      .build());
    session.flush();

    char likeJavaQuestionWasAskedBeforeDbValue = session.createNativeQuery(format("SELECT wasAskedBefore FROM Question WHERE id='%s'", likeJavaQuestionId), Character.class)
      .getSingleResult();
    char likeKotlinQuestionWasAskedBeforeDbValue = session.createNativeQuery(format("SELECT wasAskedBefore FROM Question WHERE id='%s'", likeKotlinQuestionId), Character.class)
      .getSingleResult();
    session.close();

    assertEquals('Y', likeJavaQuestionWasAskedBeforeDbValue);
    assertEquals('N', likeKotlinQuestionWasAskedBeforeDbValue);
}

7. Caveats

We might start using these new converters and find out that Hibernate doesn’t populate our boolean fields correctly. That’s probably because YesNoConverter and TrueFalseConverter only work for uppercase characters. Lowercase letters will be silently mapped to null:

@Test
void givenFieldAnnotatedWithYesNoConverter_WhenDbValueIsLowercase_ThenDomainModelValueNull() {
    session.beginTransaction();
    UUID mappedToNullQuestionId = UUID.randomUUID();
    UUID behaviorIntuitiveQuestionId = UUID.randomUUID();
    session.createNativeMutationQuery(format("INSERT INTO Question (id, content, correctAnswer) VALUES ('%s', 'Will correctAnswer be mapped to null?', 'y')", mappedToNullQuestionId))
      .executeUpdate();
    session.createNativeMutationQuery(format("INSERT INTO Question (id, content, correctAnswer) VALUES ('%s', 'Is this behavior intuitive?', 'n')", behaviorIntuitiveQuestionId))
      .executeUpdate();

    Question behaviorIntuitiveQuestion = session.get(Question.class, behaviorIntuitiveQuestionId);
    Question mappedToNullQuestion = session.get(Question.class, mappedToNullQuestionId);
    session.close();

    assertNull(behaviorIntuitiveQuestion.getCorrectAnswer());
    assertNull(mappedToNullQuestion.getCorrectAnswer());
}

8. Mapping Different Representations With JPA AttributeConverter

We can encounter all sorts of boolean representations in databases. If none of the default Hibernate converters meet our requirements, we have to define mapping logic ourselves. We can easily do this by creating a JPA Attribute Converter.

9. Conclusion

In this article, we learned how to map booleans with Hibernate 6.

Standard boolean types were replaced by converters. As a result, we need to use @Convert instead of @Type.

Additionally, we have to keep in mind that YesNoConverter and TrueFalseConverter don’t work with lowercase letters. And, in order to reduce boilerplate code, we should use @ConverterRegistration for auto-applying converters.

The Hibernate converters we saw are all implementations of JPA AttributeConverter. If none of them suit our needs, we can write our own implementation and use it in the same way.