Jandex 2.4.3 and the path to 3.0

[Ladislav Thon]

Hi,

last week, I've released Jandex 3.0.0-RC1, and yesterday, I've released Jandex 2.4.3.Final. (A corresponding release of the Jandex Maven plugin is on its way to Central as we speak.)

There's a few breaking changes in Jandex 3.0 and the 2.4.3 release is supposed to make migration easier (or at least require less coordination).

Specifically, Jandex 2.4.3 deprecates these 2 methods because they have a different return type in 3.0:

- ClassInfo.annotations()
- MethodInfo.parameters()

Replacements are, respectively:

- ClassInfo.annotationsMap()
- MethodInfo.parameterTypes()

These 2 replacement methods are present both in Jandex 2.4.3 and 3.0.0[-RC1].

Additionally, certain usages of MethodInfo.parameters() can be simplified using MethodInfo.parametersCount() and parameterType(int). These 2 methods are also present both in 2.4.3 and 3.0.0[-RC1].

Updating to Jandex 2.4.3 is safe, because it's fully compatible with previous releases. A project that uses Jandex 2.4.3 and avoids deprecated methods is almost fully _binary_ compatible with Jandex 3.0 (almost because of the return type change in Indexer.index(), but that should only affect a very small number of existing code paths).

I went through the projects that I know use Jandex and made the necessary changes myself and will submit PRs in the coming days. These projects are:

- Quarkus, including ArC and RESTEasy Reactive
- Gizmo
- Weld
- SmallRye OpenAPI
- SmallRye Async API -- no changes required
- SmallRye GraphQL
- WildFly Core -- no changes required, just updating Jandex
- WildFly Full
- RESTEasy (classic) -- no changes required

If you maintain (or know about) some other project that uses Jandex, feel free to ping me, I'll be happy to help.

Note that there are more changes in Jandex 3.0. All the details can be found in the issue tracker: https://github.com/smallrye/jandex/milestone/3 For your convenience, here's a summary of what's coming in Jandex 3.0 and is technically a breaking change, even though most of them won't likely affect anyone:

- moved Jandex to SmallRye
- bumped minimum Java version to 8
- regularized access to annotations from AnnotationTarget
  - this is why ClassInfo.annotations() needs to change the return type
  - there are methods to access annotations without considering nested annotation targets, too!
- regularized access to method parameters from MethodInfo
  - this is why MethodInfo.parameters() needs to change the return type
  - common parameter-accessing methods on MethodInfo ignore mandated/synthetic parameters
  - special methods exist to access all parameters, including mandated/synthetic
- added a new kind of types, TypeVariableReference, to faithfully represent recursive type variables
- changed Indexer.index() to return void (instead of ClassInfo)
  - required to be able to post-process an index during Indexer.complete()
- added indexing of class-retained annotations
  - Jandex 2 only indexes runtime-retained annotations
  - AnnotationInstance.runtimeVisible() can be used to distinguish
- added a few methods to IndexView
  - navigation for interfaces: getKnownDirectSubinterfaces(), getAllKnownSubinterfaces()
  - navigation for packages: getClassesInPackage(), getSubpackages()
  - breaks projects that implement this interface on their own (which I know at least WildFly and Quarkus do)
- removed IndexReader.getDataVersion()
  - it's been incorrect anyway, and I couldn't find anyone using it

When Jandex 3.0 goes final, which I hope happens in a few weeks, I will publish an announcement with all details on the SmallRye blog. In the meantime, I'll use the previously mentioned projects (and their test suites) to verify that Jandex 3.0 doesn't contain any hidden surprises.

Any questions? Ideas? My inbox and the Jandex issue tracker are always open :-)

Thanks,

LT

[Martin Kouba]

FYI qute-generator [1] is also using jandex heavily...

[1]
https://github.com/quarkusio/quarkus/tree/main/independent-projects/qute/generator

This is really a nice-to-have ;-)

>   - breaks projects that implement this interface on their own (which I
> know at least WildFly and Quarkus do)
> - removed IndexReader.getDataVersion()
>   - it's been incorrect anyway, and I couldn't find anyone using it
>
> When Jandex 3.0 goes final, which I hope happens in a few weeks, I will
> publish an announcement with all details on the SmallRye blog. In the
> meantime, I'll use the previously mentioned projects (and their test
> suites) to verify that Jandex 3.0 doesn't contain any hidden surprises.
>
> Any questions? Ideas? My inbox and the Jandex issue tracker are always
> open :-)

Wouldn't it make sense to add the @since javadoc tag to the new methods
introduced in 3.0?

>
> Thanks,
>
> LT
>
> --
> You received this message because you are subscribed to the Google
> Groups "Quarkus Development mailing list" group.
> To unsubscribe from this group and stop receiving emails from it, send
> an email to quarkus-dev...@googlegroups.com
> <mailto:quarkus-dev...@googlegroups.com>.
> To view this discussion on the web visit
> https://groups.google.com/d/msgid/quarkus-dev/CALbocO%3DjQ9mwDC_MkZzeLRyh7%2Bj-3Xb%2BqR62bMc1N-V-QXV8yg%40mail.gmail.com
> <https://groups.google.com/d/msgid/quarkus-dev/CALbocO%3DjQ9mwDC_MkZzeLRyh7%2Bj-3Xb%2BqR62bMc1N-V-QXV8yg%40mail.gmail.com?utm_medium=email&utm_source=footer>.

--
Martin Kouba
Software Engineer
Red Hat, Czech Republic

[Ladislav Thon]

st 29. 6. 2022 v 16:02 odesílatel Martin Kouba <mko...@redhat.com> napsal:

On 28. 06. 22 11:16, Ladislav Thon wrote:
> I went through the projects that I know use Jandex and made the
> necessary changes myself and will submit PRs in the coming days. These
> projects are:
>
> - Quarkus, including ArC and RESTEasy Reactive

FYI qute-generator [1] is also using jandex heavily...

[1]
https://github.com/quarkusio/quarkus/tree/main/independent-projects/qute/generator

Yea I noticed that later, because the Qute parent POM doesn't reference Jandex directly, it assumes it's just there (transitively, probably through Gizmo). I fixed that in this PR: https://github.com/quarkusio/quarkus/pull/26442

 

> Any questions? Ideas? My inbox and the Jandex issue tracker are always
> open :-)

Wouldn't it make sense to add the @since javadoc tag to the new methods
introduced in 3.0?

I did that for a lot of the methods added in 3.0, but I can see that I missed some. I'll try to fix that, thanks for noticing!

(It won't make sense to add `@since 3.0` to the methods I just backported to 2.4.3 though :-) )

LT

[Martin Kouba]

On 29. 06. 22 16:43, Ladislav Thon wrote:
> st 29. 6. 2022 v 16:02 odesílatel Martin Kouba <mko...@redhat.com

> <mailto:mko...@redhat.com>> napsal:

>
> On 28. 06. 22 11:16, Ladislav Thon wrote:
> > I went through the projects that I know use Jandex and made the
> > necessary changes myself and will submit PRs in the coming days.
> These
> > projects are:
> >
> > - Quarkus, including ArC and RESTEasy Reactive
>
> FYI qute-generator [1] is also using jandex heavily...
>
> [1]
> https://github.com/quarkusio/quarkus/tree/main/independent-projects/qute/generator
> <https://github.com/quarkusio/quarkus/tree/main/independent-projects/qute/generator>
>
>
> Yea I noticed that later, because the Qute parent POM doesn't reference
> Jandex directly, it assumes it's just there (transitively, probably
> through Gizmo). I fixed that in this PR:

Well, yes it's a transitive dependency of gizmo... which is IMO
perfectly fine, i.e. an explicit dependency is not needed but I get your
point.

> https://github.com/quarkusio/quarkus/pull/26442

> <https://github.com/quarkusio/quarkus/pull/26442>
>
> > Any questions? Ideas? My inbox and the Jandex issue tracker are
> always
> > open :-)
>
> Wouldn't it make sense to add the @since javadoc tag to the new methods
> introduced in 3.0?
>
>
> I did that for a lot of the methods added in 3.0, but I can see that I
> missed some. I'll try to fix that, thanks for noticing!
>
> (It won't make sense to add `@since 3.0` to the methods I just
> backported to 2.4.3 though :-) )
>
> LT