Related Issue(s): #173 querydsl/querydsl , #377 openfeign/querydsl

Problem Description

When using QueryDSL's collection.contains(element) method on a Java Collection-typed entity attribute that is mapped to a basic database type (e.g., String, TEXT) via a JPA @Converter, QueryDSL currently generates a standard JPQL MEMBER OF clause (often via an internal Ops.IN to JPQLOps.MEMBER_OF translation).

Historically, some older Hibernate versions might have been less strict in validating this JPQL against such converted attributes, leading some users (like H-Lo in issue #3618, #377) to believe this pattern "worked." However, as pointed out by contributors like OrangeDog, and in line with JPA principles, an attribute converted to a basic type is not treated as a queryable "plural path" by the persistence provider for standard collection operators like MEMBER OF.

Consequently, modern JPA providers, especially Hibernate 6 and later with its stricter validation, now consistently reject this JPQL, resulting in a runtime org.hibernate.query.SemanticException: Operand of 'member of' operator must be a plural path. This exception, often wrapped, originates глубоко from the ORM layer, making it less obvious to users why their QueryDSL code, which appears type-safe, is failing.

Justification for This Change in QueryDSL

While some users (like H-Lo) might have previously found workarounds or experienced a more lenient behavior from older Hibernate versions, the current stricter validation by Hibernate is aligned with JPA's interpretation of how @Converter to a basic type alters an attribute's nature for querying standard collection operations. The core issue is that QueryDSL currently generates JPQL that is predictably incompatible with how JPA providers handle such converted collections for MEMBER OF operations.

This PR proposes that QueryDSL should proactively address this known incompatibility for the following reasons:

1. Enhanced User Experience & Clearer Diagnostics (Fail-Fast):

   • Instead of allowing users to encounter a potentially cryptic, ORM-specific SemanticException at runtime, QueryDSL can provide an immediate, clear, and QueryDSL-specific QueryException.
   • This exception will precisely explain why the operation is unsupported for that specific attribute mapping (@Converter on a collection to a basic type) and guide the user towards understanding the limitation and considering alternatives (like native queries for DB-specific functions or re-evaluating their mapping if collection querying is crucial).

2. Improved Abstraction and Predictability:

   • QueryDSL serves as an abstraction layer. By detecting this specific pitfall, QueryDSL upholds its role by shielding users from underlying ORM intricacies that lead to predictable failures.
   • It makes QueryDSL's behavior more predictable: if an operation is known to be unsupported by the persistence layer for a given mapping, QueryDSL should ideally signal this at its level.

3. Alignment with Stricter ORM Validations:

   • As ORMs like Hibernate evolve and enforce stricter adherence to specifications or improve their validation, QueryDSL should also adapt to prevent the generation of queries that will no longer be accepted. This change makes QueryDSL a better citizen in the modern JPA ecosystem.

4. Guidance Over Silent Failure or Unexpected Behavior:

   • Even if older Hibernate versions didn't throw an error, it's questionable, as OrangeDog pointed out, whether the MEMBER OF operation on a TEXT column (without database-specific functions) ever produced the semantically correct SQL for a true collection membership check. It might have "not failed" but not worked as truly intended either.
   • Providing a clear error is better than QueryDSL generating a query that either fails cryptically or, in hypothetical lenient scenarios, produces SQL that doesn't match the user's intent for a collection contains check.

This change is not about restoring a "broken" functionality that was once correctly supported, but rather about QueryDSL taking responsibility for generating valid and semantically appropriate queries for the given context, or clearly indicating when it cannot. This PR opts for the latter by providing explicit, early feedback.

Solution Implemented

This PR modifies the JPQLSerializer (specifically the visitAnyInPath method, which is involved when collection.contains() is translated from an Ops.IN operation on a collection path) in the querydsl-jpa module.

The changes are as follows:

1. Detection of Problematic Mapping:

   • A new helper method, isCollectionPathWithConverterToBasicType(Path<?> path, jakarta.persistence.metamodel.Metamodel metamodel), uses the JPA Metamodel to determine if a given QueryDSL Path<?> corresponds to an entity attribute that is a Java Collection but whose PersistentAttributeType is BASIC (indicating a JPA @Converter to a basic database type).

2. Early Exception (Fail-Fast):

   • Within visitAnyInPath, before calling super.visitOperation to generate the MEMBER OF clause, this check is performed.
   • If the problematic mapping is detected, QueryDSL now throws a com.querydsl.core.QueryException with an informative message.

3. Normal Behavior for Valid Cases:

   • If the check determines the mapping is not problematic, the existing logic proceeds, ensuring normally mapped collections are unaffected.

Benefits of the Change

• Improved User Experience: Clear, QueryDSL-specific error message indicating the incompatibility.
• Fail-Fast: Problems identified earlier during JPQL serialization.
• Increased Robustness: QueryDSL handles this specific JPA mapping pattern more gracefully.

How to Test

• A new test case, JPAQueryConverterCollectionContainsTest.java, has been added.
• It defines an entity with a Set<UserRoleInTest> attribute mapped using a custom @Converter (to a comma-delimited String).
• The test method rolesContains_ShouldThrowQueryDSLException_WhenConverterIsUsedOnCollection asserts that a .contains() query on this path now throws the new com.querydsl.core.QueryException with the expected message.

Possible Future Enhancements (Out of Scope for this PR)

While this PR focuses on better diagnostics, future work could explore support for querying such converted collections via database-specific functions, if a generic and maintainable approach within QueryDSL is feasible. This PR provides the immediate benefit of clear error reporting for currently unsupported standard operations.