Spring Middleware provides a small framework for building parameterized JPQL queries from typed search DTOs. It keeps repository code declarative by translating annotated search objects into joins, conditions, ordering, and pagination at runtime.
The JPA module builds safe, parameterized JPQL from POJO search objects. Instead of manually composing query strings in each repository, services define focused search DTOs and let the framework generate the query structure at runtime.
The module uses a set of small buffers and builders to generate a JPQL query string, parameterize it safely, and execute it through JPA.
Annotate a search class with @SearchForClass and annotate fields with search metadata.
QueryBuffer, WhereBuffer, and JoinBuffer generate SELECT, FROM, JOIN, and WHERE fragments.
QueryParameterizer binds values safely and SearchRepositoryImpl executes the query with EntityManager.
SearchRepositoryImpl creates QueryBufferParameters,
delegates query construction to QueryBuffer, then parameterizes and executes the result.
Condition builders transform annotation semantics into query fragments. This keeps JPQL generation testable and extensible instead of hiding logic in one large query utility.
Search DTOs stay declarative because most of the query semantics live in annotations rather than in handwritten repository code.
Defines the entity class used in the SELECT and FROM clauses,
and whether DISTINCT should be applied.
The main field-level annotation for LIKE, comparisons, inclusion operators, joins, concatenation, null checks, and pre-conditions.
Nested search objects, collection existence checks, and grouped property definitions allow richer WHERE fragments without manual JPQL composition.
Search DTOs describe query intent. The framework reads the annotations and turns them into joins, parameterized predicates, and optional DISTINCT selection.
@SearchForClass(value = Catalog.class, distinct = true)
public class CatalogSearch implements Search {
@SearchProperty(
value = "name",
isLike = true,
concat = @Concat({"name", "description"})
)
private String q;
@SearchProperty(
value = "products",
isLike = false,
join = @Join(value = "c.products p", left = true, fetch = true)
)
private List<UUID> productIds;
// getters / setters
}@SearchForClass(value = Product.class)
public class ProductSearch implements Search {
@SearchProperty(value = "name", isLike = true)
private String name;
@SearchProperty(value = "catalog.id", isLike = false)
private UUID catalogId;
// getters / setters
}Services extend the repository contract and use high-level search methods instead of composing JPQL manually in each repository.
public interface CatalogSearchRepository
extends SearchRepository<Catalog, CatalogSearch> {
}// then in service:
List<Catalog> result =
catalogSearchRepository.findBySearch(searchDto, pagination);Query generation is deterministic and can be unit-tested directly. A search DTO with a non-null text query and product ids can produce JPQL like the following.
SELECT DISTINCT c FROM Catalog c LEFT JOIN FETCH c.products p
WHERE (UPPER(CONCAT(c.name,' ',c.description)) LIKE :param0)
AND (c.products IN :param1)
ORDER BY c.nameDISTINCT from @SearchForClassThe module supports richer query construction than simple equality checks. Joins, grouped properties, pre-conditions, and nested search fragments can all participate in the final WHERE clause.
JoinBuffer collects and normalizes joins, preventing duplicate JOIN clauses
when multiple search properties reference the same path.
@SubSearch allows a nested search object to generate its own WHERE fragment
and be embedded into the parent search.
Raw JPQL fragments and grouped @SearchProperties definitions make it possible
to combine generated predicates with more specific query rules.
Query generation is not limited to WHERE clauses. The repository implementation also coordinates ordering, pagination, and optional in-memory post-filtering when required.
OrderBy is wired into QueryBufferParameters so
QueryBuffer can append an ORDER BY clause.
Pagination is applied through setFirstResult and setMaxResults
when post-filtering is not required.
When a custom QueryFilter is involved, pagination may be applied after
the database fetch using PaginableResultDB.
The module is extensible through small, annotation-driven builders. This makes it possible to introduce project-specific query semantics without rewriting the base infrastructure.
The framework resolves a field annotation to a builder through
@ConditionBufferBuilderClass, then asks the Spring-based factory
for the concrete ConditionBufferBuilder.
You can add new domain-specific annotations and small builder implementations when the default builders do not cover a project-specific use case.
Because query generation is deterministic, it is straightforward to unit-test the produced JPQL and verify join, concat, and placeholder behavior.
@Test
public void buildsCatalogQuery_joinAndConcat_present() {
CatalogSearch s = new CatalogSearch();
s.setQ("summer");
s.setProductIds(Collections.singletonList(UUID.randomUUID()));
QueryBufferParameters<Catalog, Search> params =
new QueryBufferParameters<>(s, Catalog.class, new OrderBy(), false);
QueryBuffer<Catalog, Search> qb = new QueryBuffer<>(params);
String query = qb.toString();
Assertions.assertTrue(query.contains("LEFT JOIN") || query.contains("JOIN"));
Assertions.assertTrue(query.toUpperCase().contains("UPPER(CONCAT"));
}QueryBuffer directlyApplicationContext when testing builder factoriesDynamic JPQL generation should stay focused, explicit, and bounded.
Every exposed field can add more complexity to the generated JPQL, so keep search objects focused.
Prefer pagination whenever a search may return many rows.
Use @Join to control LEFT, RIGHT, or FETCH joins and to avoid N+1 issues when appropriate.
The JPA module is centered around repository execution, buffers, and concrete condition builders.
.../jpa/repository/SearchRepositoryImpl.java
.../jpa/buffer/QueryBuffer.java
.../jpa/buffer/JoinBuffer.java
.../jpa/buffer/builder/*