dev-persistence

Version: 3.0.16 | Java: 17+ | Spring Boot: 3.x

A multi-module framework that eliminates JPA boilerplate through compile-time code generation and runtime dynamic query building.

---

Modules

Module	Description
common-jpa-service	Core runtime engine: dynamic JPQL/SQL query execution, reflection-based filter binding, service abstractions
processor-jpa-service	Compile-time annotation processor that generates QueryJpqlImpl classes from @QueryBuilder
proxy-api-controller	Dynamic REST controller framework: generate API endpoints with annotations, no controller code required
jpa-service-plugin-generator	Maven plugin that scaffolds service, service-impl, and repository classes from JPA entities
project-jpa-persistence	Example Spring Boot application demonstrating the full framework

---

Architecture

┌──────────────────────────────────────────────────────────┐
│                   Your Spring Boot App                   │
│                                                          │
│  ┌───────────────────┐   ┌──────────────────────────┐   │
│  │  REST Controllers │   │   proxy-api-controller   │   │
│  │     (manual)      │   │    (@ApiFindController)  │   │
│  └────────┬──────────┘   └────────────┬─────────────┘   │
│           │                           │                  │
│           └─────────────┬─────────────┘                  │
│                         ▼                                │
│              ┌─────────────────────┐                     │
│              │  JpaService<T, ID>  │  ← common-jpa-service│
│              │   (JpaServiceImpl)  │                     │
│              └─────────┬───────────┘                     │
│                        │                                 │
│        ┌───────────────┴───────────────┐                 │
│        ▼                               ▼                 │
│  ┌──────────────┐            ┌──────────────────┐        │
│  │ JpaRepository│            │  QueryJpqlImpl   │        │
│  │ (Spring Data)│            │ (generated by    │        │
│  └──────────────┘            │  processor)      │        │
│                              └──────────────────┘        │
└──────────────────────────────────────────────────────────┘

Compile time:
  processor-jpa-service   → generates QueryJpqlImpl
  jpa-service-plugin-generator → scaffolds Service/Repository classes

---

How it works

Compile time

1. jpa-service-plugin-generator (Maven plugin, generate-sources phase) scans the configured entity package and generates *Service, *ServiceImpl, and *Repository class skeletons.
2. processor-jpa-service (annotation processor) reads every @QueryBuilder-annotated service interface and generates the corresponding *QueryJpqlImpl class containing pre-built JPQL strings and condition maps.

Runtime

1. Spring autowires the generated services and repositories.
2. A @ApiFindController interface is registered as a Spring @RestController via a Java dynamic proxy.
3. Each HTTP request is handled by FindInterceptor, which builds a QueryParameter from the request, resolves the correct JpaService, and executes the query.
4. JpaServiceImpl delegates query execution to BaseJpaService, which assembles the WHERE clause, JOIN FETCH clauses, ORDER BY, and pagination dynamically.
5. Results are mapped to DTOs via @ApiMapper and returned.

---

Quick Start

Add the three runtime dependencies and the annotation processor to your project:

<dependencies>
    <dependency>
        <groupId>com.bld.commons</groupId>
        <artifactId>common-jpa-service</artifactId>
        <version>3.0.16</version>
    </dependency>
    <dependency>
        <groupId>com.bld.commons</groupId>
        <artifactId>proxy-api-controller</artifactId>
        <version>3.0.16</version>
    </dependency>
</dependencies>

<build>
    <plugins>
        <!-- Scaffold generator (run once to create service/repository skeletons) -->
        <plugin>
            <groupId>com.bld.commons</groupId>
            <artifactId>jpa-service-plugin-generator</artifactId>
            <version>3.0.16</version>
            <configuration>
                <persistencePackage>com.example.domain</persistencePackage>
                <servicePackage>com.example.service</servicePackage>
                <basePackage>com.example</basePackage>
            </configuration>
        </plugin>

        <!-- Annotation processor (generates QueryJpqlImpl at compile time) -->
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-compiler-plugin</artifactId>
            <configuration>
                <annotationProcessorPaths>
                    <path>
                        <groupId>com.bld.commons</groupId>
                        <artifactId>processor-jpa-service</artifactId>
                        <version>3.0.16</version>
                    </path>
                </annotationProcessorPaths>
            </configuration>
        </plugin>
    </plugins>
</build>

See project-jpa-persistence for a complete working example.

---

Full documentation

Detailed documentation for each module is in its own README (links in the table above). The docs/ directory contains an extended reference covering the complete API.