HSEARCH-3319 Type-safe field references / HSEARCH-5300 Annotation processor for the Search static metamodel

[marko-bekhta]

https://hibernate.atlassian.net/browse/HSEARCH-3319
https://hibernate.atlassian.net/browse/HSEARCH-5300

---

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license
and can be relicensed under the terms of the LGPL v2.1 license in the future at the maintainers' discretion.
For more information on licensing, please check here.

---

[sonarqubecloud]

Quality Gate failed

Failed conditions
78.2% Coverage on New Code (required ≥ 80%)

See analysis details on SonarCloud

[marko-bekhta]

Hey @yrodiere 😃 the approach we discussed last Friday seems to work well so far. (see the new inline comments or just take a look at the FieldReferenceIT )

One thing I'm not sure how to deal with is named predicates. They are defined in binders, where there's no notion of search scope. Since binders would define the index structure, does it make sense to use the generated metamodel in them? as its generation depends on the binder ... 🤔 🙈

[marko-bekhta]

So, in the new commit, I've tried adding a Maven plugin that would generate things. The approach I've taken here is to have model+ search config classes in their own jar that is passed as a dependency to the Maven plugin. The plugin then starts the Search. I've used some of our test helpers to start things since, well, it's just to test how it'll work.

It generates something like:

package org.hibernate.search.metamodel.generator.model;

class MyEntity__ {

	public String text;	
}

package org.hibernate.search.metamodel.generator.model;

class MyProgrammaticEntity__ {

	public String number;
	public String text;	
}

And since it happens on the generate sources phase, these are getting compiled automatically by Maven itself.

As for the plugin configuration:

<configuration>
    <annotatedTypes>
        <type>org.hibernate.search.metamodel.generator.model.MyEntity</type>
        <type>org.hibernate.search.metamodel.generator.model.MyProgrammaticEntity</type>
    </annotatedTypes>
    <properties>
        <hibernate.search.mapping.configurer>org.hibernate.search.metamodel.generator.model.MyConfigurer</hibernate.search.mapping.configurer>
    </properties>
</configuration>

There's a way to pass any properties that should be "forwarded" to the Search through properties. In this case, I've tried passing a configurer to apply some programmatic mapping 🙈.

now.... next thing I'd want to try is to run the plugin in the same module that the model is. From what I've seen so far, it is easy to get the source root, and the dependencies (things that were missing in the AP approach).

[hibernate-github-bot]

Thanks for your pull request!

This pull request appears to follow the contribution rules.

› This message was automatically generated.

[sonarqubecloud]

Quality Gate failed

Failed conditions
72.8% Coverage on New Code (required ≥ 80%)

See analysis details on SonarQube Cloud

[marko-bekhta]

Hey @yrodiere,
I've added the AP experiments to this branch as in the end we'd want to use the interfaces introduced here to generate that model.... as if the PR wasn't big enough already 😄, but the experiments are all in a single commit, and I've added comments to the places I think are of interest. There's a lot of boring code similar to the one we have in the annotation processors, as these just work with a different model.

the next steps, as I see it, are:

• keep adding the missing bits (e.g. type level binders etc.). As I encounter some new code example from the docs, or just when I remember some missing part, I add it to the test and then see what has to be added to the processor to get it working.
• write a simple class from the model.
• take care of "various backends". I think that we'd just add all backends (lucene,elasticsearch) and have a config property for the annotation processor to let the user specify the backend to use (or even both).
• deal with the ORM mapper. I don't think that it would be feasible to make ORM somehow generate the model from javax.lang.model.element types. Hence, my thinking here is to add a specific processor that reads the ORM's @Id and treats them as @DocumentId; ignore the access type for now 🙈

[yrodiere]

Hey. I'm finally having a look, but first some answers

take care of "various backends". I think that we'd just add all backends (lucene,elasticsearch) and have a config property for the annotation processor to let the user specify the backend to use (or even both).

Backends should be in the user classpath already, no? If you rely on that, you can make the annotation processor work without any configuration for the most common case (only one backend type in the classpath).

the next steps, as I see it, are: [...]

Makes sense.

Except...

deal with the ORM mapper. I don't think that it would be feasible to make ORM somehow generate the model from javax.lang.model.element types

As stated, I agree. But:

1. We don't need the whole ORM metamodel. Most of the things we do around the Hibernate ORM metamodel in Search are related to dependency resolution, which is pointless when generating Search's static metamodel. We would only need to infer access type, somehow, and that could reasonably be done by getting rid of our current way of doing it and directly applying the JPA spec ourselves instead.
2. We don't need ORM to do it, we can do it ourselves. It's annoying, but possible.
3. Perhaps Hibernate Models could help someday.

Critically, this task can even be extracted to a separate issue, and we can ask someone who knows this AccessType stuff to help with a first solution that just implements this stuff directly in Hibernate Search :)

Hence, my thinking here is to add a specific processor that reads the ORM's @id and treats them as @documentid; ignore the access type for now 🙈

That's a very reasonable temporary solution.

[yrodiere]

No complaints, everything seems very reasonable :)

Maybe now would be the time to start merging things? It looks like we're going to go ahead with this solution, so it's not like we're going to revert it entirely. You'll just keep adding/updating code from now on, I believe?

[yrodiere]

Shouldn't this be...

Suggested change

	SearchPredicateFactory<SR> withRoot(String objectFieldPath);
	SearchPredicateFactory<?> withRoot(String objectFieldPath);

[yrodiere]

Uh, this one had been pending on your PR for quite some time. Sorry about that.

[marko-bekhta]

@yrodiere this commit (24465fa) adds the docs 😃. only pinging you here so it'll be easier to find this change 😃 🙈

[yrodiere]

I couldn't review it all unfortunately, but here are a few comments on the documentation.
Great stuff :)

[yrodiere]

Maybe this introduction should be a bit more extensive?

E.g.:

Suggested change

	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.

[yrodiere]

Suggested change

	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.

[yrodiere]

Suggested change

	subset of search traits interfaces defined in `org.hibernate.search.engine.search.reference.pass:[*]`, which in turn allows
	subset of search "trait" interfaces defined in `org.hibernate.search.engine.search.reference.pass:[*]`, which in turn allows

[yrodiere]

Maybe also link to whatever section of the documentation talks about "traits"? It's quite a specific term.

[yrodiere]

Suggested change

	<1> If the title field is projectable then this compiles works fine,
	<1> If the title field is projectable then this compiles fine,

[yrodiere]

Suggested change

	<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 )`

[yrodiere]

Suggested change

	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 <<TODO LINK,indexed-embedded properties>>). These classes contain <<static-metamodel-processor-field-reference-types,field references>>

[yrodiere]

Can't you run the annotation processor on a subset of the sources?

I'm pretty sure you can add a separate execution of the maven-compiler-plugin that only performs annotation processing, in which case you could possibly filter the sources to include only this package.

[yrodiere]

Awesome ❤️

[yrodiere]

I'm afraid linking to #field-paths won't be very helpful here.
Wouldn't it be better to add a section there about "static metamodel field references", with some generic info about what the static metamodel is and a recommendation to check it out in the reference documentation?

[yrodiere]

Or... Better option, use var? That's what people should do when using DSL classes anyway.

[sonarqubecloud]

Quality Gate passed

Issues
83 New issues
0 Accepted issues

Measures
0 Security Hotspots
80.9% Coverage on New Code
0.4% Duplication on New Code

See analysis details on SonarQube Cloud