Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/wimdeblauwe/jpearl

JPA Early Primary Key Library
https://github.com/wimdeblauwe/jpearl

hibernate jpa spring-boot

Last synced: about 1 month ago
JSON representation

JPA Early Primary Key Library

Awesome Lists containing this project

README 

        
= 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]

----



    io.github.wimdeblauwe

    jpearl-core

    LATEST_VERSION_HERE



----



== 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]

----



    

        io.github.wimdeblauwe

    



----



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]

----



    

        

            

                

                    io.github.wimdeblauwe

                    jpearl-maven-plugin

                    ${jpearl.version}

                    

                        com.company.app

                    

                

            

        

    



----



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 {

    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 { //<.>

    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 { //<.>

}

----

<.> 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, 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 generator;



    public UserRepositoryImpl(UniqueIdGenerator 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)`

====