Repository files navigation

Compile time validation for queries written in HQL, JPQL, andPanache.

This project now requires at least JDK 11, but JDK 15 or aboveis preferred.

Type./gradlew from this project directory.

This produces an artifact with the Maven coordinatesorg.hibernate:query-validator:2.0-SNAPSHOT in your localMaven repository.

It also creates a far jarquery-validator-2.0-SNAPSHOT-all.jarin thebuild/libs directory of this project.

The persistent entity classesmust be annotated with thebasic JPA metadata annotations like@Entity,@ManyToOne,@Embeddable,@MappedSuperclass,@ElementCollection, and@Access. Youmay use XML-based mappings to specify databasemapping information like table and column names if that's whatyou prefer. But entities mappedcompletely in XML will not bediscovered by the query validator.

1. Putquery-validator-2.0-SNAPSHOT-all.jar in thecompile-time classpath of your project. (Or depend onorg.hibernate:query-validator:2.0-SNAPSHOT.)
2. Annotate a package or toplevel class with@CheckHQL.

The validator will check any static string argument of

• thecreateQuery(),createSelectionQuery(), andcreateMutationQuery() methods,
• the@NamedQuery() annotation, or
• the@HQL annotation

which occurs in a package, class, or interface annotated@CheckHQL.

Inside a Panache entity or repository, the following querieswill be checked:

• list(),find(), andstream(),
• count(),
• delete(), and
• update()

The purpose of the query validator is to detect erroneousquery strings and query parameter bindings when the Java codeis compiled, instead of at runtime when the query is executed.

A compile-time error is produced if:

• the query has syntax errors,
• an entity name in the query doesn't reference a persistententity class,
• a member name in the query doesn't reference a mapped fieldor property of the entity, or
• there is some other typing error, for example, incorrectfunction argument types.

Additionally, any JPAQuery instance that is created andimmediately invoked in a single expression will have itsparameter bindings validated. A warning is produced if:

• the query string has a parameter with no argument specifiedusingsetParameter(), or
• an argument is specified usingsetParameter(), but thereis no matching parameter in the query string.

All Panache queries have their parameters validated.

When using a command line compiler,gradle, ormvn, errorsfrom the query validator are displayed in the compiler outputalongside other compilation errors.

Just compile your code withjavac, or even with ECJ(java -jar ecj-4.6.1.jar), with the query validatorjar inthe classpath:

-classpath query-validator-2.0-SNAPSHOT-all.jar

Of course, you'll also need Hibernate core on the classpath.

In principle, it's enough to declare dependencies on Hibernate coreand on the query validator, just like this:

dependencies {    implementation 'org.hibernate.orm:hibernate-core:6.3.0-SNAPSHOT'    annotationProcessor 'org.hibernate:query-validator:2.0-SNAPSHOT'}

Unfortunately, this often results in some quite annoying warningsfromjavac. Get rid of them by also declaring animplementationdependency on the Query validator:

dependencies {    implementation 'org.hibernate:query-validator:2.0-SNAPSHOT'    annotationProcessor 'org.hibernate:query-validator:2.0-SNAPSHOT'    implementation 'org.hibernate:query-validator:2.0-SNAPSHOT'}

Maven handles annotation processors correctly. Just declare thedependency on the query validator:

<dependencies>    <dependency>        <groupId>org.hibernate</groupId>        <artifactId>query-validator</artifactId>        <version>2.0-SNAPSHOT</version>        <optional>true</optional>    </dependency><dependencies>

Both IntelliJ and Eclipse require that annotation processingbe explicitly enabled.

SelectEnable annotation processing in IntelliJ IDEApreferences underBuild, Execution, Deployment > Compiler >AnnotationProcessors.

You do not need to do this if you're using Gradle to buildyour project.

IntelliJ only runs annotation processors during a build (thatis, when youRun your code or explicitlyBuild Project).So you won't see errors in your Java editor as you're typing.

Eclipse IDE doesn't load annotation processors from theproject classpath. So you'll need to add the query validatormanually.

1. InProject > Properties go toJava Compiler >Annotation Processing and selectEnable annotationprocessing.
2. Then go toJava Compiler > Annotation Processing >Factory Path and clickAdd External JARs... andaddbuild/libs/query-validator-2.0-SNAPSHOT-all.jarfrom this project directory.

Your project properties should look like this:

Eclipse runs annotation processors during every incrementalbuild (that is, every time youSave), so you'll see errorsdisplayed inline in your Java editor.

If the query validator doesn't run, please ensure that:

• Eclipse itself is running on a compatible JDK.
• Your project is set up to compile with a compatible Javacompiler, and the compiler compliance level is set to atleast 1.8.

The query validator was developed and tested with:

• JDK 15, JDK 17, JDK 20
• Hibernate 6.3.0
• ECJ 3.33.0
• Eclipse IDE with JDT Core 3.33.0

Other versions ofjavac, ECJ, and Hibernate may or may notwork. The query validator depends on internal compiler APIs injavac and ECJ, and is therefore sensitive to changes in thecompilers.

Please be aware of the following issues.

Queries are interpreted according to Hibernate's flavor of JPQL(i.e. HQL), which is a superset of the query language defined bythe JPA specification. Queries accepted by the query validatormay not execute correctly on other implementations of JPA.

In ECJ, don't use@Entity(name="Whatever"), since, during anincremental build, the processor won't be able to discover theentity namedWhatever. Just let the entity name default tothe name of the class.

Please report ugly, confusing, or badly-formatted error messagesas bugs.