HSEARCH-5300 Rename package/processor and clean up the docs

Author: marko-bekhta

Jenkinsfile

@@ -498,7 +498,7 @@ stage('Non-default environments') {
 					// we'd better recompile everything with the same compiler rather than get some strange errors
 					mavenNonDefaultBuild buildEnv, """ \
 							-DskipTests -DskipITs \
-							-P${buildEnv.mavenProfile},!javaModuleITs,!metamodelITs -pl '!:hibernate-search-documentation,!:hibernate-search-reports' \
+							-P${buildEnv.mavenProfile},!javaModuleITs,!metamodelITs -pl '!:hibernate-search-documentation,!:hibernate-search-documentation-lucene-next,!:hibernate-search-reports' \
 							-Dgib.buildAll=true \
 					"""
 				}

bom/public/pom.xml

@@ -94,7 +94,7 @@
             </dependency>
             <dependency>
                 <groupId>org.hibernate.search</groupId>
-                <artifactId>hibernate-search-metamodel-processor</artifactId>
+                <artifactId>hibernate-search-processor</artifactId>
                 <version>${project.version}</version>
             </dependency>
             <!-- Relocation artifacts: -->

build/jqassistant/rules/rules.xml

@@ -281,7 +281,7 @@
                         WHEN 'hibernate-search-mapper-orm' THEN 'HibernateOrm'
                         WHEN 'hibernate-search-mapper-orm-outbox-polling' THEN 'OutboxPolling'
                         WHEN 'hibernate-search-mapper-orm-jakarta-batch-jberet' THEN 'JBeret'
-                        WHEN 'hibernate-search-metamodel-processor' THEN 'Processor'
+                        WHEN 'hibernate-search-processor' THEN 'Processor'
                         ELSE 'UNKNOWN-MODULE-SPECIFIC-KEYWORD-PLEASE-UPDATE-JQASSISTANT-RULES'
                     END
             RETURN

build/parents/build/pom.xml

@@ -371,7 +371,7 @@
             </dependency>
             <dependency>
                 <groupId>org.hibernate.search</groupId>
-                <artifactId>hibernate-search-metamodel-processor</artifactId>
+                <artifactId>hibernate-search-processor</artifactId>
                 <version>${project.version}</version>
             </dependency>
 

build/reports/pom.xml

@@ -76,7 +76,7 @@
         </dependency>
         <dependency>
             <groupId>org.hibernate.search</groupId>
-            <artifactId>hibernate-search-metamodel-processor</artifactId>
+            <artifactId>hibernate-search-processor</artifactId>
         </dependency>
         <dependency>
             <groupId>org.hibernate.search</groupId>

documentation/pom.xml

@@ -64,7 +64,7 @@
         </dependency>
         <dependency>
             <groupId>${project.groupId}</groupId>
-            <artifactId>hibernate-search-metamodel-processor</artifactId>
+            <artifactId>hibernate-search-processor</artifactId>
             <scope>test</scope>
         </dependency>
         <dependency>
@@ -121,7 +121,42 @@
                          even though we don't explicitly use it.
                          This is probably a compiler bug, so here we need to work around it. -->
                     <showDeprecation>false</showDeprecation>
+                    <testExcludes>
+                        <exclude>org/hibernate/search/documentation/search/metamodel/**</exclude>
+                    </testExcludes>
                 </configuration>
+                <executions>
+                    <execution>
+                        <id>generate-metamodel</id>
+                        <phase>test-compile</phase>
+                        <goals>
+                            <goal>testCompile</goal>
+                        </goals>
+                        <configuration>
+                            <proc>full</proc>
+                            <testIncludes>
+                                <include>org/hibernate/search/documentation/search/metamodel/**</include>
+                            </testIncludes>
+                            <testExcludes combine.self="override" combine.children="override"></testExcludes>
+                            <showWarnings>false</showWarnings>
+                            <annotationProcessors>
+                                <annotationProcessor>org.hibernate.search.processor.HibernateSearchProcessor</annotationProcessor>
+                            </annotationProcessors>
+                            <annotationProcessorPaths>
+                                <path>
+                                    <groupId>org.hibernate.search</groupId>
+                                    <artifactId>hibernate-search-processor</artifactId>
+                                    <version>${project.version}</version>
+                                </path>
+                                <path>
+                                    <groupId>org.hibernate.search</groupId>
+                                    <artifactId>hibernate-search-backend-elasticsearch</artifactId>
+                                    <version>${project.version}</version>
+                                </path>
+                            </annotationProcessorPaths>
+                        </configuration>
+                    </execution>
+                </executions>
             </plugin>
             <plugin>
                 <groupId>org.apache.maven.plugins</groupId>

documentation/src/main/asciidoc/public/reference/_mapping-inspect.adoc

@@ -50,9 +50,7 @@ is it searchable, sortable, projectable,
 what is the expected java class for arguments to the <<search-dsl,Search DSL>>,
 what are the analyzers/normalizer set on this field,
 ...
-<9> Inspect the "traits" of a field type:
-each trait represents a predicate/sort/projection/aggregation
-that can be used on fields of that type.
+<9> Inspect the <<mapping-inspect-traits,"traits">> of a field type.
 <10> Object fields can also be inspected.
 <11> A collection of all configured analyzers
 available for the index represented by the descriptor can also be inspected.
@@ -64,6 +62,14 @@ available for the index represented by the descriptor can also be inspected.
 to see if a particular normalizer is available within the index context.
 ====
 
+[[mapping-inspect-traits]]
+[TIP]
+====
+Traits define the set of search capabilities available for the field,
+in particular, each trait represents a predicate/sort/projection/aggregation
+that can be used on that field.
+====
+
 [TIP]
 ====
 The `Backend` and `IndexManager` can also be used to

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

@@ -6,15 +6,15 @@
 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>>
+that may contain inner classes describing object fields (e.g. from <<mapping-indexedembedded,indexed-embedded properties>>). 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.
+The root metamodel class that describes the indexed entity has a static field `INDEX` that you 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.
@@ -39,15 +39,15 @@ limit acceptable field references to the ones obtained from the `Book__.INDEX`
 
 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
+subset of <<mapping-inspect-traits,search "trait">> 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,
+<1> If the title field is projectable then this compiles fine,
 otherwise compilation fails with an error similar to:
 +
 ----
@@ -64,5 +64,5 @@ The field reference also provides a way to quickly switch between <<search-dsl-a
 ----
 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 )`
+<1> Calling `string()` on a field reference is an equivalent to `.field( "genre"  ).matching( <search value>, ValueModel.STRING )`
 ====

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

@@ -9,7 +9,7 @@ include::../components/_incubating-warning.adoc[]
 == 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`.
+This annotation processor is located in the `org.hibernate.search:hibernate-search-processor`.
 
 The annotation processor has to be added to the build, e.g. for Maven:
 
@@ -23,12 +23,12 @@ The annotation processor has to be added to the build, e.g. for Maven:
             <id>default-compile</id>
             <configuration>
                 <annotationProcessors>
-                    <annotationProcessor>org.hibernate.search.metamodel.processor.HibernateSearchMetamodelProcessor</annotationProcessor> <1>
+                    <annotationProcessor>org.hibernate.search.processor.HibernateSearchProcessor</annotationProcessor> <1>
                 </annotationProcessors>
                 <annotationProcessorPaths>
                     <path>
                         <groupId>org.hibernate.search</groupId>
-                        <artifactId>hibernate-search-metamodel-processor</artifactId> <2>
+                        <artifactId>hibernate-search-processor</artifactId> <2>
                     </path>
                     <path>
                         <groupId>org.hibernate.search</groupId>
@@ -42,12 +42,13 @@ The annotation processor has to be added to the build, e.g. for Maven:
 ----
 
 <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.
+<2> Add the `org.hibernate.search:hibernate-search-processor` dependency to the annotation processor path (a superset of the compile path), so the Java compiler can find the processor.
+<3> Add the backend dependency, in this example, the <<backend-lucene,Lucene backend>>, to the 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.
+For example, backends might have different defaults, resulting in a different set of <<mapping-inspect-traits,search traits>> per specific field, 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.
+NOTE: The version of both annotation processor and backend dependencies can be ommitted in the definition of the annotation paths,
+because they are defined in the Hibernate Search BOM, which we recommend you import via dependency management.
 This way the generated metamodel classes will be based on the same backend that the application uses.
 ====
 
@@ -66,7 +67,7 @@ The annotation processor options are passed as the compiler arguments with the `
             <id>default-compile</id>
             <configuration>
                 <compilerArgs>
-                    <arg>-Aorg.hibernate.search.metamodel.processor.generated_annotation.timestamp=false</arg> <1>
+                    <arg>-Aorg.hibernate.search.processor.generated_annotation.timestamp=false</arg> <1>
                     <arg><!-- ... --></arg> <2>
                 </compilerArgs>
                 <!-- ... --> <3>
@@ -83,34 +84,39 @@ The annotation processor options are passed as the compiler arguments with the `
 
 The following annotation processor configuration properties are available:
 
-[[static-metamodel-processor-configuration-generated_annotation-add]]`org.hibernate.search.metamodel.processor.generated_annotation.add`::
+[[static-metamodel-processor-configuration-generated_annotation-add]]`org.hibernate.search.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`::
+[[static-metamodel-processor-configuration-generated_annotation-timestamp]]`org.hibernate.search.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`::
+[[static-metamodel-processor-configuration-add_generated_annotation]]`org.hibernate.search.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.
+While this option is mostly for the Elasticsearch backend,
+where it translates into <<configuration-properties-aggregated-hibernate-search-backend-elasticsearchhibernate.search.backend.version,`hibernate.search.backend.version`>>,
+it will also translate into <<configuration-properties-aggregated-hibernate-search-backend-lucenehibernate.search.backend.lucene_version,`hibernate.search.backend.lucene_version`>> if the Lucene backend is used.
 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:
+While the annotation processor is very much functional and we encourage you to try it,
+it is still in the early stages of development, and thus 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.
+* <<mapper-orm-custom-annotations,Custom mapping annotations>> are ignored without warning.
 * <<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.
+As the annotation processor cannot possibly execute programmatic mapping defined in the code that is being compiled,
+this limitation is here to stay.

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

@@ -5,8 +5,11 @@
 
 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>>.
+Hibernate Search's static metamodel is a set of generated classes that represents the structure of each entity's index,
+thereby allowing to reference index fields in a type-safe way to create search queries through the <<search-dsl,Search DSL>>.
+
+The basic principles are very similar to the link:{hibernateDocUrl}#tooling-modelgen[JPA static metamodel available in Hibernate ORM],
+but in the case of Search the metamodel is about indexes rather than entities.
 
 :leveloffset: +1
 

documentation/src/test/java/org/hibernate/search/documentation/search/converter/ProjectionConverterIT.java

@@ -165,7 +165,7 @@ public void setStatus(OrderStatus status) {
 		}
 	}
 
-	private enum OrderStatus {
+	enum OrderStatus {
 		ACKNOWLEDGED,
 		IN_PROGRESS,
 		DELIVERED

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

@@ -30,9 +30,6 @@ public class Author {
 	@ManyToMany(mappedBy = "authors")
 	private List<Book> books = new ArrayList<>();
 
-	public Author() {
-	}
-
 	public Integer getId() {
 		return id;
 	}