split + rewrite query language chapter to new HQL guide document

This commit is contained in:
Gavin 2023-05-26 10:56:04 +02:00 committed by Christian Beikov
parent e99ae7995a
commit 790c2aa944
34 changed files with 3442 additions and 32 deletions

View File

@ -194,6 +194,57 @@ tasks.register('renderIntroduction', AsciidoctorTask) {task->
}
}
tasks.register('renderQLPdf', AsciidoctorPdfTask) {task->
group = "Documentation"
description = 'Renders the Query Language document in PDF format using Asciidoctor.'
tasks.buildDocs.dependsOn task
tasks.buildDocsForPublishing.dependsOn task
inputs.property "hibernate-version", project.ormVersion
sourceDir = file( 'src/main/asciidoc/querylanguage' )
baseDir = file( 'src/main/asciidoc/querylanguage' )
sources {
include 'Hibernate_Query_Language.adoc'
}
outputDir = "$buildDir/asciidoc/querylanguage/pdf"
attributes jpaJavadocUrlPrefix: "https://javaee.github.io/javaee-spec/javadocs/javax/persistence/"
}
tasks.register('renderQL', AsciidoctorTask) {task->
group = "Documentation"
description = 'Renders the Query Language document in HTML format using Asciidoctor.'
tasks.buildDocs.dependsOn task
tasks.buildDocsForPublishing.dependsOn task
inputs.property "hibernate-version", project.ormVersion
sourceDir = file( 'src/main/asciidoc/querylanguage' )
sources {
include 'Hibernate_Query_Language.adoc'
}
outputDir = "$buildDir/asciidoc/querylanguage/html_single"
attributes linkcss: true,
stylesheet: "css/hibernate.css",
docinfo: 'private',
jpaJavadocUrlPrefix: "https://javaee.github.io/javaee-spec/javadocs/javax/persistence/"
resources {
from('src/main/asciidoc/querylanguage/') {
include 'images/**'
}
from('src/main/style/asciidoctor') {
include 'images/**'
}
from('src/main/style/asciidoctor') {
include 'css/**'
}
from('src/main/style/asciidoctor') {
include 'js/**'
}
}
}
// User Guide ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
tasks.register('renderUserGuide', AsciidoctorTask) { task ->

View File

@ -1425,10 +1425,10 @@ Let's pause to remember the annotations we've met so far.
|===
| Annotation | Purpose | JPA-standard
| `@Entity` | Declare an entity class | ✓
| `@MappedSuperclass` | Declare a non-entity class with mapped attributes inherited by an entity | ✓
| `@Embeddable` | Declare an embeddable type | ✓
| `@IdClass` | declare the identifier class for an entity with multiple `@Id` attributes | ✓
| `@Entity` | Declare an entity class | ✔
| `@MappedSuperclass` | Declare a non-entity class with mapped attributes inherited by an entity | ✔
| `@Embeddable` | Declare an embeddable type | ✔
| `@IdClass` | declare the identifier class for an entity with multiple `@Id` attributes | ✔
|===
.Declaring basic attributes
@ -1436,14 +1436,14 @@ Let's pause to remember the annotations we've met so far.
|===
| Annotation | Purpose | | JPA-standard
| `@Id` | Declare a basic-typed identifier attribute | | ✓
| `@Version` | Declare a version attribute | | ✓
| `@Basic` | Declare a basic attribute | Default | ✓
| `@EmbeddedId` | Declare an embeddable-typed identifier attribute | | ✓
| `@Embedded` | Declare an embeddable-typed attribute | Inferred | ✓
| `@Enumerated` | Declare an `enum`-typed attribute and specify how it is encoded | Inferred | ✓
| `@Array` | Declare that an attribute maps to a SQL `ARRAY`, and specify the length | Inferred | ✗
| `@ElementCollection` | Declare that a collection is mapped to a dedicated table | | ✓
| `@Id` | Declare a basic-typed identifier attribute | | ✔
| `@Version` | Declare a version attribute | | ✔
| `@Basic` | Declare a basic attribute | Default | ✔
| `@EmbeddedId` | Declare an embeddable-typed identifier attribute | | ✔
| `@Embedded` | Declare an embeddable-typed attribute | Inferred | ✔
| `@Enumerated` | Declare an `enum`-typed attribute and specify how it is encoded | Inferred | ✔
| `@Array` | Declare that an attribute maps to a SQL `ARRAY`, and specify the length | Inferred | ✖
| `@ElementCollection` | Declare that a collection is mapped to a dedicated table | | ✔
|===
.Converters and compositional basic types
@ -1451,13 +1451,13 @@ Let's pause to remember the annotations we've met so far.
|===
| Annotation | Purpose | JPA-standard
| `@Converter` | Register an `AttributeConverter` | ✓
| `@Convert` | Apply a converter to an attribute | ✓
| `@JavaType` | Explicitly specify an implementation of `JavaType` for a basic attribute | ✗
| `@JdbcType` | Explicitly specify an implementation of `JdbcType` for a basic attribute | ✗
| `@JdbcTypeCode` | Explicitly specify a JDBC type code used to determine the `JdbcType` for a basic attribute | ✗
| `@JavaTypeRegistration` | Register a `JavaType` for a given Java type | ✗
| `@JdbcTypeRegistration` | Register a `JdbcType` for a given JDBC type code | ✗
| `@Converter` | Register an `AttributeConverter` | ✔
| `@Convert` | Apply a converter to an attribute | ✔
| `@JavaType` | Explicitly specify an implementation of `JavaType` for a basic attribute | ✖
| `@JdbcType` | Explicitly specify an implementation of `JdbcType` for a basic attribute | ✖
| `@JdbcTypeCode` | Explicitly specify a JDBC type code used to determine the `JdbcType` for a basic attribute | ✖
| `@JavaTypeRegistration` | Register a `JavaType` for a given Java type | ✖
| `@JdbcTypeRegistration` | Register a `JdbcType` for a given JDBC type code | ✖
|===
.System-generated identifiers
@ -1465,11 +1465,11 @@ Let's pause to remember the annotations we've met so far.
|===
| Annotation | Purpose | JPA-standard
| `@GeneratedValue` | Specify that an identifier is system-generated | ✓
| `@SequenceGenerator` | Define an id generated backed by on a database sequence | ✓
| `@TableGenerator` | Define an id generated backed by a database table | ✓
| `@IdGeneratorType` | Declare an annotation that associates a custom `Generator` with each `@Id` attribute it annotates | ✗
| `@ValueGenerationType` | Declare an annotation that associates a custom `Generator` with each `@Basic` attribute it annotates | ✗
| `@GeneratedValue` | Specify that an identifier is system-generated | ✔
| `@SequenceGenerator` | Define an id generated backed by on a database sequence | ✔
| `@TableGenerator` | Define an id generated backed by a database table | ✔
| `@IdGeneratorType` | Declare an annotation that associates a custom `Generator` with each `@Id` attribute it annotates | ✖
| `@ValueGenerationType` | Declare an annotation that associates a custom `Generator` with each `@Basic` attribute it annotates | ✖
|===
.Declaring entity associations
@ -1477,11 +1477,11 @@ Let's pause to remember the annotations we've met so far.
|===
| Annotation | Purpose | JPA-standard
| `@ManyToOne` | Declare the single-valued side of a many-to-one association (the owning side) | ✓
| `@OneToMany` | Declare the many-valued side of a many-to-one association (the unowned side) | ✓
| `@ManyToMany` | Declare either side of a one-to-one association | ✓
| `@OneToOne` | Declare either side of a one-to-one association | ✓
| `@MapsId` | Declare that the owning side of a `@OneToOne` association maps the primary key column | ✓
| `@ManyToOne` | Declare the single-valued side of a many-to-one association (the owning side) | ✔
| `@OneToMany` | Declare the many-valued side of a many-to-one association (the unowned side) | ✔
| `@ManyToMany` | Declare either side of a one-to-one association | ✔
| `@OneToOne` | Declare either side of a one-to-one association | ✔
| `@MapsId` | Declare that the owning side of a `@OneToOne` association maps the primary key column | ✔
|===
Phew!

View File

@ -1,8 +1,8 @@
:pdf-theme: theme.yml
:pdf-theme: ../pdf/theme.yml
:source-highlighter: rouge
:icons: font
:doctype: book
:pdf-fontsdir: fonts
:pdf-fontsdir: ../pdf/fonts
:docsBase: https://docs.jboss.org/hibernate/orm
:versionDocBase: {docsBase}/6.3
:userGuideBase: {versionDocBase}/userguide/html_single/Hibernate_User_Guide.html
@ -39,7 +39,7 @@ include::Mapping.adoc[]
include::Interacting.adoc[]
// include::../userguide/chapters/query/hql/QueryLanguage.adoc[]
// include::../userguide/chapters/query/hql/Hibernate_Query_Language.adoc[]
<<<

File diff suppressed because it is too large Load Diff

View File

@ -0,0 +1 @@
identifier | INTEGER_LITERAL | expression

View File

@ -0,0 +1,4 @@
select distinct
p.last_name
from
person p

View File

@ -0,0 +1,12 @@
select
c.id,
c.duration,
c.phone_id,
c.call_timestamp
from
phone_call c
join
Phone p
on p.id=c.phone_id
where
p.phone_number='123-456-7890'

View File

@ -0,0 +1,11 @@
limitClause
: "LIMIT" parameterOrIntegerLiteral
offsetClause
: "OFFSET" parameterOrIntegerLiteral ("ROW" | "ROWS")?
fetchClause
: "FETCH" ("FIRST" | "NEXT")
(parameterOrIntegerLiteral | parameterOrNumberLiteral "%")
("ROW" | "ROWS")
("ONLY" | "WITH" "TIES")

View File

@ -0,0 +1,10 @@
sortExpression sortDirection? nullsPrecedence?
sortExpression
: identifier | INTEGER_LITERAL | expression
sortDirection
: "ASC" | "DESC"
nullsPrecedence
: "NULLS" ("FIRST" | "LAST")

View File

@ -0,0 +1,7 @@
expression "NOT"? "IN" inList
inList
: ("ELEMENTS"|"INDICES") "(" simplePath ")"
| "(" (expression ("," expression)*)? ")"
| "(" subquery ")"
| parameter

View File

@ -0,0 +1 @@
expression "NOT"? ("LIKE" | "ILIKE") expression ("ESCAPE" character)?

View File

@ -0,0 +1 @@
"CASE" ("WHEN" predicate "THEN" expression)+ ("ELSE" expression)? "END"

View File

@ -0,0 +1,7 @@
(expression | instantiation) alias?
instantiation
: "NEW" instantiationTarget "(" instantiationArguments ")"
alias
: "AS"? IDENTIFIER

View File

@ -0,0 +1 @@
"CASE" expression ("WHEN" expression "THEN" expression)+ ("ELSE" expression)? "END"

View File

@ -0,0 +1,2 @@
deleteStatement
: "DELETE" "FROM"? targetEntity whereClause?

View File

@ -0,0 +1,14 @@
insertStatement
: "INSERT" "INTO"? targetEntity targetFields (queryExpression | valuesList)
targetEntity
: entityName variable?
targetFields
: "(" simplePath ("," simplePath)* ")"
valuesList
: "VALUES" values ("," values)*
values
: "(" expression ("," expression)* ")"

View File

@ -0,0 +1,36 @@
selectStatement
: queryExpression
queryExpression
: withClause? orderedQuery (setOperator orderedQuery)*
orderedQuery
: (query | "(" queryExpression ")") queryOrder?
query
: selectClause fromClause? whereClause? (groupByClause havingClause?)?
| fromClause whereClause? (groupByClause havingClause?)? selectClause?
queryOrder
: orderByClause limitClause? offsetClause? fetchClause?
fromClause
: "FROM" entityWithJoins ("," entityWithJoins)*
entityWithJoins
: fromRoot (join | crossJoin | jpaCollectionJoin)*
fromRoot
: entityName variable?
| "LATERAL"? "(" subquery ")" variable?
join
: joinType "JOIN" "FETCH"? joinTarget joinRestriction?
joinTarget
: path variable?
| "LATERAL"? "(" subquery ")" variable?
withClause
: "WITH" cte ("," cte)*
;

View File

@ -0,0 +1,11 @@
updateStatement
: "UPDATE" "VERSIONED"? targetEntity setClause whereClause?
targetEntity
: entityName variable?
setClause
: "SET" assignment ("," assignment)*
assignment
: simplePath "=" expression