Using Hibernate Annotations in JPA Projects on WildFly

Hibernate annotations play a key role in mapping Java objects to database tables in JPA projects running on WildFly. However, integrating these annotations seamlessly requires proper dependencies and configurations to avoid runtime errors.

The Issue with Using Hibernate Annotations in WildFly

Hibernate annotations are available in Hibernate core project. Therefore, in order to compile your project, you will need the following dependency in your pom.xml:

<dependency>
    <groupId>org.hibernate</groupId>
    <artifactId>hibernate-core</artifactId>
    <version>6.4.1.Final</version>
    <scope>provided</scope>
</dependency>

However, when running on WildFly, Hibernate annotations will not be available as default module. Therefore, if you try to deploy a project with Hibernate annotations you will have the following error:

Caused by: java.lang.NoClassDefFoundError: org/hibernate/annotations/common/reflection/XProperty

The Solution

To resolve this issue, you have two options:

The first option is to add a dependencies entry to the MANIFEST.MF file with a comma-separated list of dependency module names:

Dependencies: org.hibernate.commons-annotations

Please note that you can also add the following configuration to the packaging plug-in configuration in the project’s pom.xml file.

<configuration>
   <archive>
      <manifestEntries>
         <Dependencies>org.hibernate.commons-annotations</Dependencies>
      </manifestEntries>
   </archive>
</configuration>

The second option is to include in the file jboss-deployment-structure.xml the following dependency:

<jboss-deployment-structure>
    <deployment>
        <dependencies>
            <module name="org.hibernate.commons-annotations"/>
        </dependencies>
    </deployment>
</jboss-deployment-structure>

These configurations ensure that the required Hibernate annotations are available within the WildFly environment, preventing class loading issues during runtime.

Example: Using Hibernate Annotations in a JPA Entity

Let’s consider a simple example demonstrating the use of Hibernate annotations in a JPA entity:

import javax.persistence.*;
import org.hibernate.annotations.Type;

@Entity
@Table(name = "employees")
public class Employee {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @Column(name = "full_name")
    private String fullName;

    @Column(name = "salary")
    private double salary;

    @Type(type = "text")
    @Column(name = "details")
    private String details;

    // Getters and setters omitted for brevity
}

In this example:

• @Entity marks the class as a JPA entity.
• @Table specifies the table name for mapping.
• @Id and @GeneratedValue define the primary key and its generation strategy.
• @Column maps entity fields to table columns, specifying column names.
• @Type from Hibernate annotations allows custom types, here used to define a field as text type.

Ensure the Hibernate annotations, especially @Type, are accessible by applying the proper dependency configurations in your WildFly deployment descriptor.

By employing these annotations, JPA entities can be precisely mapped to database tables, leveraging the full potential of Hibernate in your WildFly-based JPA projects.

Finally, for a full example, about using JSON Type in JPA Projects, check this article: How to store JSON Data with JPA and Hibernate