Package org.hibernate.annotations.processing

Annotation Interface CheckHQL

@Target({PACKAGE,TYPE})
@Retention(CLASS)
@Incubating
public @interface CheckHQL

Indicates that a package or top-level type contains HQL or JPQL queries encoded as static strings that should be validated at compile time by the Metamodel Generator or Query Validator. Errors in queries are reported by the Java compiler.

The Metamodel Generator or Query Validator must be enabled as an annotation processor in the project build. Otherwise, if neither is enabled, this annotation has no effect.

If only the Metamodel Generator is enabled, only arguments to the following annotations are validated:

• NamedQuery.query(),
• NamedQuery.query().

Otherwise, if the Query validator is enabled, then, within the scope annotated @CheckHQL, any static string argument to any one of the following methods is interpreted as HQL/JPQL and validated:

• EntityManager.createQuery(String,Class),
• EntityManager.createQuery(String),
• QueryProducer.createSelectionQuery(String,Class), or
• QueryProducer.createMutationQuery(String)

The entity classes referred to by the queries must be annotated with basic JPA metadata annotations like @Entity, @ManyToOne, @Embeddable, @MappedSuperclass, @ElementCollection, and @Access. Metadata specified in XML mapping documents is ignored by the query validator.

Syntax errors, unknown entity names and unknown entity member names, and typing errors all result in compile-time errors.

Since:

6.3

See Also:

• NamedQuery.query()
• EntityManager.createQuery(String,Class)
• QueryProducer.createSelectionQuery(String,Class)

Implementation Note:

The static HQL type checker is not aware of metadata defined purely in XML, nor of JPA converters, and therefore sometimes reports false positives. That is, it rejects queries at compile time that would be accepted at runtime.

Therefore, by default, HQL specified in NamedQuery annotations is always validated for both syntax and semantics, but only illegal syntax is reported with severity Diagnostic.Kind.ERROR. Problems with the semantics of HQL named queries (typing problem) are reported to the Java compiler by the Metamodel Generator with severity Diagnostic.Kind.WARNING.

So, actually, the effect of CheckHQL is only to change the severity of reported problem.

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element	Description
Class<? extends Dialect>	dialect	A Hibernate dialect to use.

Element Details

dialect

Class<? extends Dialect> dialect

A Hibernate dialect to use.

See Also:

• Dialect

Default:

org.hibernate.annotations.processing.GenericDialect.class