= JPearl - JPA Early Primary Key Library :toc: macro

image:https://travis-ci.org/wimdeblauwe/jpearl.svg?branch=master["Build Status",link="https://travis-ci.org/wimdeblauwe/jpearl"]

image:https://maven-badges.herokuapp.com/maven-central/io.github.wimdeblauwe/jpearl-core/badge.svg["Maven Central",link="https://search.maven.org/search?q=a:jpearl-core"]

toc::[]

== Goal

The goal of the project is to provide some convenient classes and interface to use JPA with early primary key generation.

It also encourages to use value objects as primary keys.

== Dependency coordinates

Maven coordinates to add the dependency to your project:

[source,xml]

== Spring Boot compatibility

|=== |jpearl |Spring Boot|Minimum Java version

|https://github.com/wimdeblauwe/jpearl/releases/tag/2.0.1[2.0.1] |3.x |17

|https://github.com/wimdeblauwe/jpearl/releases/tag/2.0.0[2.0.0] |3.x |17

|https://github.com/wimdeblauwe/jpearl/releases/tag/1.2.0[1.2.0] |2.x |8 |=== == Maven plugin

To generate the entity and related classes, use the following direct invocation of the jpearl-maven-plugin:

[source]

mvn io.github.wimdeblauwe:jpearl-maven-plugin:VERSION_HERE:generate -DbasePackage=com.company.app -Dentity=MyEntity

This will generate the following classes/interfaces:

• com.company.app.myentity.MyEntity
• com.company.app.myentity.MyEntityId
• com.company.app.myentity.MyEntityRepository
• com.company.app.myentity.MyEntityRepositoryCustom
• com.company.app.myentity.MyEntityRepositoryImpl

And the following tests:

• com.company.app.myentity.MyEntityRepositoryTest

If you want to shorten the command line typing, add the following to your ~/.m2/settings.xml file: [source,xml]

You can now run: [source]

mvn jpearl:generate -DbasePackage=com.company.app -Dentity=MyEntity

To avoid having to specify the base package each time, configure the plugin in your project:

[source,xml]

The maven command now becomes as simple as: [source]

mvn jpearl:generate -Dentity=MyEntity

== Usage

. Create a primary value object. For example: UserId: + [source,java]

import io.github.wimdeblauwe.jpearl.AbstractEntityId;

import java.util.UUID;

public class UserId extends AbstractEntityId<UUID> { protected UserId() { //<.> }

public UserId(UUID id) { //<.>
    super(id);
}

}

<.> A protected default constructor is required by JPA/Hibernate. <.> A public constructor that will be used by the application itself. . Create the entity. For example: User + [source,java]

import io.github.wimdeblauwe.jpearl.AbstractEntity;

import jakarta.persistence.Entity;

@Entity //<.> public class User extends AbstractEntity<UserId> { //<.> private String name;

protected User() { //<.>
}

public User(UserId id, String name) { //<.>
    super(id);
    this.name = name;
}

public String getName() {
    return name;
}

}

<.> Annotate the class with @Entity so JPA will discover it. <.> Extend from AbstractEntity and configure the used id class via generics. <.> A protected default constructor is required by JPA/Hibernate. <.> A public constructor that will be used by the application itself. . Create a repository interface. For example: UserRepository + [source,java]

import org.springframework.data.repository.CrudRepository; import org.springframework.transaction.annotation.Transactional;

@Transactional(readOnly = true) // <.> public interface UserRepository extends CrudRepository<User, UserId> { //<.> }

<.> Mark transactions on the repo interface as read-only by default. If you later add finder methods to this UserRepository interface, then the transactions of each method will be read-only which is best for finders. If there is a modifying query, be sure to individually annotate that method with @Transactional (without the readOnly). <.> Use CrudRepository or PagingAndSortingRepository according to your needs. Use the entity and the entity id classes in the generics.

. Create a custom interface to extend the UserRepository interface with custom code. Example: UserRepositoryCustom: + [source,java]

public interface UserRepositoryCustom { //<.> UserId nextId(); //<.> }

<.> Make sure the name of the interface is the repository name, with Custom suffix. <.> Add a method that returns the id type. Usually, this method is called nextId(). . Have the repository extend from the custom repository interface: + [source,java]

@Transactional(readOnly = true) public interface UserRepository extends CrudRepository<User, UserId>, UserRepositoryCustom { }

. Create a class to implement the custom interface. Example: UserRepositoryImpl: + [source,java]

import io.github.wimdeblauwe.jpearl.UniqueIdGenerator;

import java.util.UUID;

public class UserRepositoryImpl implements UserRepositoryCustom { //<.> private final UniqueIdGenerator<UUID> generator;

public UserRepositoryImpl(UniqueIdGenerator<UUID> generator) { // <.>
    this.generator = generator;
}

@Override
public UserId nextId() {
    return new UserId(generator.getNextUniqueId()); // <.>
}

}

<.> Be sure to name the class the repository name with Impl suffix <.> Inject the unique id generator <.> Generate a new unique id for each call to nextId() + [TIP]

You usually have a repository per aggregate root. Entities within that root will not have their own repository, but there will be an extra method on the custom interface to generate primary keys. E.g.: [source,java]

public interface PostRepositoryCustom { PostId nextId();

PostCommentId nextCommentId();

}

====

== Release

Release is done via the Maven Release Plugin:

mvn release:prepare

and

mvn release:perform

Finally, push the local commits and the tag to remote.

[NOTE]

Before releasing, run export GPG_TTY=$(tty)