v2.0.0

Full Changelog: View Changes

Highlights in v2.0.0

• Full Request Body Support: The library now fully supports parsing filtering and sorting criteria from JSON request bodies alongside HTTP query parameters. This allows for more structured and complex inputs in POST or PUT requests, using DTOs like ListAPIRequest, FilterRequest, and SortRequest. Request body values take precedence over query parameters for overlapping fields, ensuring predictable behavior in hybrid scenarios.

• Nested Field Capabilities: Filtering and sorting on nested entity properties is now possible using a configurable delimiter (default: dot .). For example, createdBy.firstName enables queries across associations without manual join management. The library automatically handles path resolution and supports reuse of existing fetches to avoid duplicate joins, with guidance for custom fetch integration to optimize performance.

• Advanced Extensibility: Introduced custom filter and sort functions via addCustomFilter and addCustomSort in templates, allowing domain-specific predicates. Enum filtering is enhanced with a default EnumFilterFieldImp using Enum.valueOf, and users can override it with custom implementations (e.g., case-insensitive matching) by providing a @Primary bean subclassing AbstractEnumFilterField.

• Optimized Fetch Management: The specification builder now detects and reuses association fetches from prior specifications or custom code, respecting join types like LEFT or RIGHT. This prevents redundant joins in combined specifications. Documentation includes examples for intentional fetch ordering to avoid unexpected reuse, promoting efficient multi-layered query construction.

• Standardized DTOs: New ListAPIRequest DTO encapsulates lists of FilterRequest and SortRequest for controller endpoints, with validation support via Jakarta Bean Validation. Service examples demonstrate seamless integration, standardizing API contracts for filtering (e.g., [{"field": "role", "operator": "eq", "value": "ADMIN"}]) and sorting (e.g., [{"field": "createdAt", "direction": "DESC"}]).

• Comprehensive Operator Expansion: Expanded to 18+ operators, including eq, neq, gt, gte, lt, lte, in, notIn, isNull, isNotNull, contains, icontains, startsWith, istartsWith, endsWith, iendsWith, between, and notBetween. Each operator has a case-insensitive equivalent - prefixed by i, with between and notBetween handling two-value ranges for dates and numerics.

• Enhanced Type Safety and Validation: Built-in type conversion for a wide range of JPA-compatible types: numerics (Byte to BigInteger), booleans, strings, enums (treated as text), UUIDs, and temporal types (Instant, OffsetDateTime, ZonedDateTime, LocalDateTime, LocalDate, LocalTime, YearMonth, Year). Invalid conversions throw InvalidQueryParameterException early, with detailed error messages.

Improvements

• Enhanced Configuration Options: New application properties include query-filter-builder.defaults.field-delimiter for nested paths (e.g., change from _ to .) and query-filter-builder.query-param.defaults.sort-parameter (default: sort). These must align with template definitions for consistency, supporting flexible integration in microservices or legacy systems.

• Robust Error Handling: Dedicated exceptions like InvalidQueryParameterException (for unconvertible values or invalid operators) and QueryBuilderConfigurationException (for template misconfigurations). Includes a base QueryFilterBuilderExceptionHandler for @RestControllerAdvice integration, returning structured error responses (e.g., field-specific details). Undefined fields are silently ignored to maintain API stability.

• Expanded Documentation and Examples: README now features a detailed table of contents, quick start guide, and code samples for injection, template building, context creation, specification application, and edge cases. Sections cover public API references for FilterContext, SortContext, and QueryFilterBuilder, plus integration tests for real-world scenarios like user filtering/sorting.

• Performance Refinements: Registry-based architecture for operators and fields enables fast resolution without reflection overhead. Predicate generation is streamlined for minimal database impact, with support for empty contexts returning neutral specifications (no filtering/sorting). Query parameter sorting uses comma-separated format (e.g., sort=-firstName,lastName) with order preservation.

• Security and Maintainability: Input validation prevents SQL injection via type-safe criteria building. Fluent builder patterns and immutable templates reduce boilerplate. Comprehensive unit tests cover all operators, types, and edge cases (e.g., null checks, invalid paths), ensuring reliability in production Spring Boot 3.1+ environments with Jakarta Persistence 3.1+.

This release marks a significant evolution from v1.0.0, building on core query filter foundations with production-grade extensibility and API ergonomics. For full details, refer to the updated README and Javadoc. Contributions are welcome via the CONTRIBUTING.md guidelines. Licensed under Apache 2.0.

v1.0.0

Full Changelog: View Changes

🔥 Highlights in v1.0.0

• 🚀 Full Feature Set Implementation: Finalized the core functionalities of Query Filter Builder, making it production-ready for building dynamic query filters.
• 🧪 Comprehensive Unit Tests: Added robust test coverage for all critical functionalities to ensure reliability and accuracy.
• 🐛 Bug Fixes: Resolved multiple issues identified during the alpha phase, improving overall performance and stability.

✨ Improvements

• Enhanced filter operator handling for edge cases.
• Improved error messaging for invalid or unsupported query parameters.
• Optimized type compatibility for smoother integration with common JPA data types.