How acoboh/query-filter-jpa works
Based on our analysis of both the file tree and the README, the project is a Java library for dynamic query filtering in JPA (with special support for Spring Boot 2/3) that lets developers define filters via annotations and then auto-generate JPA Specification objects. It is also split into several modules – the core filtering module (e.g., query-filter-jpa and query-filter-jpa-3 for Spring Boot 3), an OpenAPI integration module (e.g., query-filter-jpa-openapi and query-filter-jpa-openapi-3), several example projects (both a basic example and one with Docker support), and a collection of tests and documentation. The goal is to provide an intuitive, annotation-driven way to create dynamic queries without needing to build JPA Specifications manually.
Project Type and Purpose
• The project is a library (with example applications) designed to simplify filtering of JPA queries by allowing users to define filter definitions using custom annotations.
• It integrates with Spring Boot (with distinct modules for Boot 2 and Boot 3), and it includes an OpenAPI module that auto-documents the filter APIs.
Analyzing the File Structure
• The top-level directories include configuration files (such as .github/** for CI/CD), documentation (doc/), examples (with two variants in the examples directory), and multiple modules with dedicated functionality (query-filter-jpa, query-filter-jpa-3, query-filter-jpa-openapi, etc.).
• Inside each module, the package structure is organized under “io/github/acoboh/query/…” which further divides the code into subpackages such as “filter”, “filter/jpa”, “filter/jpa/annotations”, “filter/jpa/processor”, “filter/jpa/exceptions”, etc.
• The extensive file tree for query-filter-jpa and its related modules indicates a clear separation of core processing (converter, processor, definition handling), exception management, and platform-specific contributions (JPA, OpenAPI).
Key Components of the Architecture
A. Client and API Layer
• REST Controllers (as shown in the examples – e.g., PostRestController) that receive HTTP requests containing query parameters for filtering.
• The query parameters can be provided in different syntaxes (RHS colon and LHS bracket formats).
B. Query Filter Library Core
• Annotations: Custom annotations such as @QFDefinitionClass, @QFElement, @QFDate, etc., which define how filtering is applied.
• Filter Definition Classes: Classes that capture the filterable fields (e.g., PostFilterDef) and guide the filter processing.
• Filter Processor: Components (located in the jpa/processor subpackages) that parse input query parameters and construct the corresponding JPA Specification objects.
• Exception Handling: A set of custom exceptions (grouped under query-filter/jpa/exceptions) that help manage errors during filter parsing and execution.
• Converter and Resolutors: Components that convert query parameters into the corresponding model types and resolve the correct operations (in packages like converters and operations/resolutors).
C. Integration with JPA Repositories
• Repositories extending JpaSpecificationExecutor that integrate the query filter output into dynamic JPA queries.
D. OpenAPI Integration Module
• A separate module (query-filter-jpa-openapi[(-3)]) that auto-generates API documentation using the filter definitions.
• This module hooks into Spring Boot’s auto-configuration to include filter details in the Swagger-UI.
E. Example Applications and Supporting Infrastructure
• The examples directory contains sample Spring Boot applications demonstrating the usage of the library.
• Docker-compose and scripts (in the examples/docker and similar directories) show how to run the application in various deployment environments.
Architectural Patterns and Design Principles
• Modular Design: The separation of core filtering functionality, Spring Boot integration, and OpenAPI support into different modules.
• Annotation-driven Configuration: The heavy use of custom annotations to simplify filter definition.
• Separation of Concerns: Controllers handle HTTP and parameter passing; processing components convert filter parameters to Specification objects; repositories execute the queries.
• Extensibility: The design supports custom converters, resolutors, and exception management, which assist in advanced filtering features like arrays, JSON fields, and sorting.
Final Reminder
• Be as detailed as possible – don’t shy away from breaking the system into many components if necessary.
• Capturing the essence: the transformation of filter query parameters (via annotations and filter definitions) into dynamic JPA queries.
Happy diagramming!