Easy JPA Entities

Table of Contents

• 1. Introduction
• 2. What does easy in easy-jpa-entities mean?
• 3. Some more details
• 4. Usage
• 5. Testing
• 6. CI environment
• 7. Test reporting and code coverage
• 8. Reference

1. Introduction

This is a Java library that generates JPA entities.

Purpose

Generated sources can be used as entity (and DTO) clases in an application that uses Spring Data JPA. Generated entities are anemic classes: no behaviour is present.

What you should add yourself

YAML file containing definitions for your entities. And, of course, you must provide the rest of the application as well as a fully configured database with the correct tables.

After usage

You can keep the easy-jpa-entities-processor as a part of your build. If you really must, you can copy and paste the generated code into your sources. In that case the easy-jpa-entities-processor dependency can be erased from your sources.

Benefits

The entity classes

• are generated for you, including the builder, from specifications in YAML format

• are immutable

• are all the same

• are convenient to use. In your code, you’re required to use a builder to create a changed instance. Only some properties can be changed using the builder: not the ID, not the optimistic locking version number, or any other field that is not allowed to change.

• contain a flag that indicates if they were just fetched from the database or were changed but not stored in the database yet (= modified).

Drawbacks

Unless you modify the processor yourself, generated form of the entities is always the same: there is no room for slight differences.

2. What does easy in easy-jpa-entities mean?

You might argue that JPA is created to make the life of Java developers easier. However, there are a lot of options and JPA will do some stuff automatically for you whilst you might not even want to. You might even argue that JPA does not make it easier at all.

JPA entities generated by easy-jpa-entities-processor can not be too complex (that simply is not supported). And you don’t have to think about all the options you have when setting up entities.

So this library is intended to make life easier. You can judge for yourself if that really is the case.

3. Some more details

Easy JPA Entities consists of a jar file that implements a Java Annotation Processor. When included in your project, it will search for an interface that is annotated with @EasyJpaEntities. It well derive the location of the YAML file from that annotation, and use the information in that file to generate JPA entity class files.

Notes:

• Reason this library was created: I think immutability is a very good idea. I am aware of Immutables and Lombok, but, to my humble opinion, these don’t play really well with JPA.

• The ID for the entity is assigned in the Java code. The examples use UUID IDs. You should be able to replace it with anything immutable you like.

• Not implementing setters does not make an entity immutable.

• Using this library can only be used for simple entities that don’t have any entities attached. From what I understand from Effective Aggregate Design you should keep your entities simple anyway. If you want other entities referred to these can be fetched using a separate query. I like the simplicyt for now. However, really storing and retrieving a complete aggregate would be better. This might change in the future.

• The immutable entities generated are immutable in the Java programming space. It is not the same as @Immutable entities in Hibernate.

It should be compatible with JDK 8.

4. Usage

Include the easy-jpa-entities artifact in your build. For example in Maven:

        <dependency>
            <groupId>io.github.gerardpi.easy-jpa-entities</groupId>
            <artifactId>easy-jpa-entities-processor</artifactId>
            <version>enter a version here</version>
            <scope>compile</scope>
        </dependency>

This diagram indicates what is expected as input and what will be produced at build time

Create an interface, and include a YAML file with the same name with the entity definitions.

Example:

• Annotated file: easy-jpa-entities-test/src/main/java/io/github/gerardpi/easy/jpaentities/test1/EasyJpaEntitiesWithAnnotation.java (this is the file to be found by the annotations processor)

• Definitions file: easy-jpa-entities-test/src/main/resources/io/github/gerardpi/easy/jpaentities/test1/EasyJpaEntitiesWithAnnotation.yaml (this file contains the actual definitions)

At compile time, the Java sources are being generated.

Refer to the example code in easy-jpa-entities-test/ for details. Tests are written using jgiven. These tests generate a scenario that looks a lot like Gherkin. Have a look at the builds in the CI environment.

5. Testing

Testing an annotation processor can be difficult: https://dzone.com/articles/the-problem-with-annotation-processors

The result should be a bunch of Java classes with the correct contents. So testing the annotation processor’s output by using it seems to be the simplest way. This implies that test coverage reported by Jacoco reporting in easy-jpa-entities-processor is low.

The test module also contains a test that just compares the expected Java sources with the actual sources to be sure.

6. CI environment

doc/release-notes.adoc

7. Test reporting and code coverage

Reporting:

• Test reporting consists of human-readable scenarios that indicate how the software is tested and which form detailed documentation for the sources.

• Test coverage: what % the source code is actually hit by tests.

Build code like so assuming that you have maven available from your PATH:

1. Clone GIT repository

2. mvn verify -Ptest-reporting

Subsequently, the following reports are available target directory of both modules:

1. Jacoco test coverage reporting (in target/site/jacoco),

2. JGiven test reporting (in target/jgiven-reports) and

3. Test scenarios are generated in asciidoctor format in doc/generated-by-jgiven/. This is also committed to the repository as it is documentation that can be viewed from the repository.

Note	Asciidoctor files can be viewed using a plugin in Intellij IDEA, your favourite browser. It is also converted to HTML when you click the file in Github.

8. Reference

• https://spring.io/projects/spring-boot