HSEARCH-5300 Add documentation for static metamodel

Author: marko-bekhta

documentation/src/main/asciidoc/public/reference/_static-metamodel-overview.adoc

@@ -0,0 +1,68 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright Red Hat Inc. and Hibernate Authors
+[[static-metamodel-overview]]
+= Overview of the static metamodel
+
+include::../components/_incubating-warning.adoc[]
+
+The static metamodel class describes the index structure. Each indexed entity (index) is represented by a single class
+that may contain inner classes describing the embeddables (i.e. nested/flattened objects). These classes contain <<static-metamodel-processor-field-reference-types,field references>>
+representing index fields and their search capabilities.
+
+The name of this root class is constructed from the indexed entity name by adding `pass:[__]` (two underscores) suffix, e.g. `MySearchEntitypass:[__]`.
+If the indexed entity is a (static) inner class, then all the owning classes will be part of the name delimited with a `pass:[_]` (single underscore),
+e.g. `MyOuterClasspass:[_]MySearchEntitypass:[__]`.
+These classes are created in the same package where the search entity they represent is located.
+
+The root metamodel class that describes the indexed entity has a static field `INDEX` that users can use to interact with the metamodel.
+It serves two primary purposes:
+
+* It simplifies creating the search scope and building search queries for such scope.
+* It provides a way to reference index fields when constructing queries.
+
+NOTE: While the default naming convention was described in this section,
+there are plans to provide more flexibility in this area to the users (see https://hibernate.atlassian.net/browse/HSEARCH-5366[HSEARCH-5366]) .
+
+====
+[source, JAVA, indent=0, subs="+callouts"]
+----
+include::{sourcedir}/org/hibernate/search/documentation/search/metamodel/MetamodelIT.java[tags=entryPoint]
+----
+<1> Obtain the search session.
+<2> Create the search scope over the book index. Using such scope in the <<search-dsl,Search DSL>> will automatically
+limit acceptable field references to the ones obtained from the `Book__.INDEX`
+<3> Use the metamodel to reference the fields when creating the queries.
+====
+
+[[static-metamodel-processor-field-reference-types]]
+== Field reference types
+
+A field reference type describes the set of search capabilities a particular index field has, in particular,
+what kind of projections/aggregations/predicates/sorts are allowed, if any. It does so by implementing a
+subset of search traits interfaces defined in `org.hibernate.search.engine.search.reference.pass:[*]`, which in turn allows
+performing compile-time checks when building <<search-dsl,search queries>>.
+
+====
+[source, JAVA, indent=0, subs="+callouts"]
+----
+include::{sourcedir}/org/hibernate/search/documentation/search/metamodel/MetamodelIT.java[tags=compileCheck-pass]
+----
+<1> If the title field is projectable then this compiles works fine,
+otherwise compilation fails with an error similar to:
++
+----
+error: no suitable method found for field(ValueFieldReferenceP0P13P14P2P4P5P6P7P8P9<Book__,String,String,String,String>)
+----
++
+as such field reference (for a filed with `Projectable.NO`) will not implement the required `FieldProjectionFieldReference` interface.
+====
+
+The field reference also provides a way to quickly switch between <<search-dsl-argument-type,different value models>> when necessary.
+
+====
+[source, JAVA, indent=0, subs="+callouts"]
+----
+include::{sourcedir}/org/hibernate/search/documentation/search/metamodel/MetamodelIT.java[tags=valueModel]
+----
+<1> Calling `string()` on a field reference is an eqivalent to `.field( "genre"  ).matching( <search value>, ValueModel.STRING )`
+====

documentation/src/main/asciidoc/public/reference/_static-metamodel-processor.adoc

@@ -0,0 +1,116 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright Red Hat Inc. and Hibernate Authors
+[[static-metamodel-processor]]
+= Annotation processor
+
+include::../components/_incubating-warning.adoc[]
+
+[[static-metamodel-processor-enabling]]
+== Enabling the annotation processor
+
+Hibernate Search provides a dedicated annotation processor to generate the static metamodel classes.
+This annotation processor is located in the `org.hibernate.search:hibernate-search-metamodel-processor`.
+
+The annotation processor has to be added to the build, e.g. for Maven:
+
+====
+[source,XML,subs="+attributes"]
+----
+<plugin>
+    <artifactId>maven-compiler-plugin</artifactId>
+    <executions>
+        <execution>
+            <id>default-compile</id>
+            <configuration>
+                <annotationProcessors>
+                    <annotationProcessor>org.hibernate.search.metamodel.processor.HibernateSearchMetamodelProcessor</annotationProcessor> <1>
+                </annotationProcessors>
+                <annotationProcessorPaths>
+                    <path>
+                        <groupId>org.hibernate.search</groupId>
+                        <artifactId>hibernate-search-metamodel-processor</artifactId> <2>
+                    </path>
+                    <path>
+                        <groupId>org.hibernate.search</groupId>
+                        <artifactId>hibernate-search-backend-lucene</artifactId> <3>
+                    </path>
+                </annotationProcessorPaths>
+            </configuration>
+        </execution>
+    </executions>
+</plugin>
+----
+
+<1> Provide the fully qualified class name of the annotation processor that generates the metamodel.
+<2> Add the `org.hibernate.search:hibernate-search-metamodel-processor` dependency as an annotation processor path for the Maven compiler plugin to be able to actually find the processor.
+<3> Add the backend dependency, in this example, the <<backend-lucene,Lucene backend>>, as an annotation processor path.
+It is important to include the same backend that the application is using to make sure that the generated metamodel classes reflect all the backend specifics.
+For example, backends might have different defaults, resulting in a different set of field traits depending on the backend.
+
+NOTE: The version of both annotation processor and backend dependencies are skipped in the definition of the annotation paths, as in case the Hibernate Search BOM is imported via dependency management, the compiler plugin will use the managed versions.
+This way the generated metamodel classes will be based on the same backend that the application uses.
+====
+
+[[static-metamodel-processor-configuration]]
+== Configuration
+
+The annotation processor options are passed as the compiler arguments with the `-A` key:
+
+====
+[source,XML,subs="+attributes"]
+----
+<plugin>
+    <artifactId>maven-compiler-plugin</artifactId>
+    <executions>
+        <execution>
+            <id>default-compile</id>
+            <configuration>
+                <compilerArgs>
+                    <arg>-Aorg.hibernate.search.metamodel.processor.generated_annotation.timestamp=false</arg> <1>
+                    <arg><!-- ... --></arg> <2>
+                </compilerArgs>
+                <!-- ... --> <3>
+            </configuration>
+        </execution>
+    </executions>
+</plugin>
+----
+
+<1> Pass the annotation processor parameters using the `-A` key.
+<2> Pass any other compiler arguments required by the build.
+<3> Further compiler plugin configuration.
+====
+
+The following annotation processor configuration properties are available:
+
+[[static-metamodel-processor-configuration-generated_annotation-add]]`org.hibernate.search.metamodel.processor.generated_annotation.add`::
+Description:::
+Whether to add the `@Generated` annotation to the generated static metamodel classes.
+Default value:::
+`true`
+
+[[static-metamodel-processor-configuration-generated_annotation-timestamp]]`org.hibernate.search.metamodel.processor.generated_annotation.timestamp`::
+Description:::
+Defines whether the `@Generated` annotation includes the `date` attribute.
+Having the date attribute will result in non-reproducible builds, as the timestamp will be different for each compilation.
+Hence, it is disabled by default.
+Default value:::
+`false`
+
+[[static-metamodel-processor-configuration-add_generated_annotation]]`org.hibernate.search.metamodel.processor.backend.version`::
+Description:::
+Explicitly define the backend version. By default, the processor will use the latest compatible version of the backend.
+This option can be used if the static metamodel is required for an older backend version.
+Default value:::
+`<latest>`
+
+[[static-metamodel-processor-limitations]]
+== Current annotation processor limitations
+
+While the annotation processor is in its early stages of development, it has a few limitations:
+
+* Any use of <<binding-valuebridge-valuebinder,custom binders>> will be ignored and should produce a compiler warning.
+This means that if the search entities rely on custom binders, fields that those binders produce will be missing from the generated metamodel.
+* <<mapper-orm-custom-annotations,Custom mapping annotations>> are not supported.
+* <<mapping-programmatic,Programmatic mapping>> is also unsupported by the annotation processor.
+As the annotation processor cannot easily read programmatic mapping definitions, this limitation is here to stay.

documentation/src/main/asciidoc/public/reference/_static-metamodel.adoc

@@ -0,0 +1,17 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright Red Hat Inc. and Hibernate Authors
+[[static-metamodel]]
+= Static metamodel
+
+include::../components/_incubating-warning.adoc[]
+
+Hibernate Search static metamodel represents the index structure
+that provides a type-safe way of creating search queries through the <<search-dsl,Search DSL>>.
+
+:leveloffset: +1
+
+include::_static-metamodel-overview.adoc[]
+
+include::_static-metamodel-processor.adoc[]
+
+:leveloffset: -1

documentation/src/main/asciidoc/public/reference/index.adoc

@@ -63,6 +63,8 @@ include::_backend-elasticsearch.adoc[]
 
 include::_coordination.adoc[]
 
+include::_static-metamodel.adoc[]
+
 include::_integrations.adoc[]
 
 include::_limitations.adoc[]

documentation/src/test/java/org/hibernate/search/documentation/search/metamodel/Author.java

@@ -0,0 +1,67 @@
+/*
+ * SPDX-License-Identifier: Apache-2.0
+ * Copyright Red Hat Inc. and Hibernate Authors
+ */
+package org.hibernate.search.documentation.search.metamodel;
+
+import java.util.ArrayList;
+import java.util.List;
+
+import jakarta.persistence.Entity;
+import jakarta.persistence.Id;
+import jakarta.persistence.ManyToMany;
+
+import org.hibernate.search.mapper.pojo.mapping.definition.annotation.FullTextField;
+import org.hibernate.search.mapper.pojo.mapping.definition.annotation.Indexed;
+
+@Entity
+@Indexed
+public class Author {
+
+	@Id
+	private Integer id;
+
+	@FullTextField(analyzer = "name")
+	private String firstName;
+
+	@FullTextField(analyzer = "name")
+	private String lastName;
+
+	@ManyToMany(mappedBy = "authors")
+	private List<Book> books = new ArrayList<>();
+
+	public Author() {
+	}
+
+	public Integer getId() {
+		return id;
+	}
+
+	public void setId(Integer id) {
+		this.id = id;
+	}
+
+	public String getFirstName() {
+		return firstName;
+	}
+
+	public void setFirstName(String firstName) {
+		this.firstName = firstName;
+	}
+
+	public String getLastName() {
+		return lastName;
+	}
+
+	public void setLastName(String lastName) {
+		this.lastName = lastName;
+	}
+
+	public List<Book> getBooks() {
+		return books;
+	}
+
+	public void setBooks(List<Book> books) {
+		this.books = books;
+	}
+}