Skip to main content

Simple Mapping

@Entity​

The @Entity annotation is used to decorate immutable interfaces to represent ORM entities.

Book.java
@Entity
public interface Book {
    ...Omit other code...
}
info

Why are entity types interfaces instead of classes?

Jimmer entities have

and , which are not simple POJOs with intricate internal workings that cannot be accomplished manually or with lombok assistance.

So Jimmer lets developers write interfaces that are implemented at compile time by preprocessors (AnnotationProcessor for Java, KSP for Kotlin).

@Table​

The @Table annotation specifies the table name for the entity. If @Table annotation is not used, e.g.

BookStore.java
@Entity
public interface BookStore {
    ...Omit other code... 
}

Jimmer will deduce the table name corresponding to the BookStore interface based on the naming strategy.

If the default naming strategy is not overridden by the user, the table name for interface BookStore is BOOK_STORE. So the previous code is equivalent to:

BookStore.java
@Entity
@Table(name = "BOOK_STORE")
public interface BookStore {
    ...Omit other code...
}

@Column​

The @Column annotation specifies the database column for ordinary non-associative properties. If @Column annotation is not used, e.g.

Author.java
@Entity 
public interface BookStore {

    String firstName();

    ...Omit other code...
}

Jimmer will deduce the column name corresponding to the firstName property based on the naming strategy.

If the default naming strategy is not overridden by the user, the column name for property firstName is FIRST_NAME. So the previous code is equivalent to:

Author.java
@Entity
public interface BookStore {

    @Column(name = "FIRST_NAME") 
    String firstName();

    ...Omit other code...
}
caution

@Column is only used to explicitly specify column names for non-associative properties. For foreign key column names of many-to-one or one-to-one association properties, they must be specified through @JoinColumn. See Association Mapping for more.

@Id​

Declare a property as the id property, as follows

Book.java
@Entity
public interface Book {

    @Id  
    long id();
}
caution

The id field must be non-null (for Java, long is used here instead of Long)

Unlike JPA, which encourages declaring the id as a nullable type, Jimmer does not use this method to express not specifying the id during data insertion. The dynamism of Jimmer objects themselves can easily express this problem.

See Nullity for details.

@GeneratedValue​

In the previous example, the primary key property decorated with @Id is a business field that must be specified when inserting data.

However, more often, we expect that the primary key property itself has no business meaning, so that it can be unspecified when inserting data and automatically generated instead. The automatic id generation strategies are:

  • Database autoincrement
  • Database sequence
  • UUID
  • Snowflake ID

@GeneratedValue works with @Id to specify auto growth strategy for Id.

Database autoincrement​

Book.java
@Entity
public interface Book {

    @Id  
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    long id();
}

Database sequence​

Book.java
@Entity
public interface Book {

    @Id
    @GeneratedValue(strategy = GenerationType.SEQUENCE)  
    long id();
}

Here, the sequence name in the database is not specified through the sequenceName of @GeneratorValue. Jimmer will deduce the sequence name based on the naming strategy.

If the default naming strategy is not overridden by the user, the sequence name here is BOOK_ID_SEQ. So the previous code is equivalent to:

Book.java
@Entity
public interface Book {

    @Id
    @GeneratedValue(
        strategy = GenerationType.SEQUENCE,
        sequenceName = "BOOK_ID_SEQ" 
    )
    long id();
}

UUID​

Setting the generatorType property of @GeneratedValue to org.babyfish.jimmer.sql.meta.UUIDIdGenerator can be used to randomly generate UUIDs

Book.java
@Entity
public interface Book {

    @Id
    @GeneratedValue(generatorType = UUIDIdGenerator.class) 
    UUID id();
}

Custom IdGenerator​

When the above Id growth strategies cannot meet the requirements, a custom Id generation strategy can be defined.

Jimmer provides an UserIdGenerator<T> interface

UserIdGenerator.java
package org.babyfish.jimmer.sql.meta;

public interface UserIdGenerator<T> extends IdGenerator {

    T generate(Class<?> entityType); 
}

Users can implement this interface to implement any Id generation algorithm, including snowflake ID.

MyGenerator.java
package com.mycompany.myproject.common;

public class MyIdGenerator implements UserIdGenerator<Long> {

    @Override
    public Long generate(Class<?> entityType) {
        return ...Omit custom id generation logic...
    }
}
Book.java
@Entity
public interface Book {

    @Id
    @GeneratedValue(generateType = MyIdGenerator.class)
    Long id();
}
caution

The user-implemented Id generation class MyIdGenerator itself does not have generic parameters, but generic parameters must be specified for the super interface UserIdGenerator.

The type of the decorated Id property must be consistent with this generic parameter, otherwise an exception will be thrown.