Weld 5.0.0.Beta1

2022-1-24   release   Matej Novotny

Some of you might have noticed that Weld already had some version 5 releases, namely two Alphas. Those were a work-in-progress implementations so I didn’t post any actual release notes as the specification was still undergoing changes. CDI 4 is now in very much ready-to-fly state as its first CR release has recently landed in Maven Central. Therefore, here we are with a proper release of Weld API 5.0.Beta5 and Weld Core 5.0.0.Beta1 which implements all the bits and pieces of CDI 4.0 plus brings a few more changes and deprecation removals.

This post will try to cover Weld-side of things meaning anything that changed and is Weld specific or influences integrators in any way. If you want to learn what’s new in CDI 4.0, I suggest taking a look at this detailed article I wrote some time ago. It provides a good overview of all major changes, all of which are implemented in this Weld release. In case you want to check out the list of JIRA issues for Weld releases, the last chapter will provide links for both Alpha releases as well as this Beta release. Last but not least, you can also reach out to us via Gitter channel or weld-dev@lists.jboss.org mailing list.

Without further ado, let’s dive into it!

Target JDK version for Weld 5 (and for CDI 4) is now 11

Therefore, JDK 11 is now the minimal version required to run Weld. This is basically a requirement for all Jakarta EE 10 specifications. On the other hand, Weld 5 is also tested against and supports JDK 17 as well.

Weld 5 is no longer a multi-release (MR) JARs

As you might know, Weld 3 and 4 are running some different class defining strategies for JDK 8 or 11+ resulting in an MR JAR solution. Since JDK 11 is the basis, this is no longer needed and similar workarounds were removed from code.

Deprecations and removals

Here is a list of all changes of this nature within Weld APIs:

  • Multiple methods from org.jboss.weld.serialization.spi.ProxyServices were removed.

    • If you are an integrator, you probably implemented this interface at some point in time; these methods weren’t used by Weld anyway, so they are now gone for good.

    • Here is a link to the issue removing it.

  • Any integrators basing their implementations of Jandex likely implemented ClassFileInfo; its isTopLevelClass() has been removed.

    • Note that this method was redundant and can be replaced by getClassNestingType().

    • This was removed as part of the above mentioned issue.

  • WeldInstance.Handler class is now deprecated and so are multiple methods returning this type from WeldInstance

CDI has had a similar cleanup and some long deprecated API methods were removed; glance at this GitHub issue if you want to learn more about that.

Empty `beans.xml interpretation

There is one breaking change in CDI 4.0 that should be mentioned here - change of default interpretation of empty beans.xml descriptor. Up until CDI 3.0, leaving this file empty meant discovery mode all whereas starting with CDI 4 it now defaults to annotated discovery mode. As per specification, in all discovery mode, all classes in bean archive are scanned and if fitting, turned into beans. However, annotated discovery mode only scans classes with bean defining annotations. Therefore, this change can be breaking for lots of applications using empty beans.xml and relying on CDI to discover classes without annotations. In order to ease the transition to this new default, CDI 4 specification says the following:

For compatibility with CDI versions prior to 4.0, CDI Full products must contain an option that causes an archive with empty beans.xml to be considered an explicit bean archive.

This option is vendor-dependent and integrators needs to define how to achieve it in their frameworks/platforms. That being said, Weld has been updated to allow for this. If you are using Weld tooling to parse beans.xml, chances are, you’re doing one of these:

  • Directly invoking parser via org.jboss.weld.xml.BeansXmlStreamParser.

    • BeansXmlStreamParser now has new constructor methods which allow passing BeanDiscoveryMode parameter telling Weld how to interpret empty beans.xml.

    • All former constructors were retained and default to BeanDiscoveryMode.ANNOTATED.

  • Indirectly invoking it via an implementation of org.jboss.weld.bootstrap.api.Bootstrap and its parse methods.

    • New variantions of the parse methods were added and accept BeanDiscoveryMode parameter telling Weld how to interpret empty beans.xml.

    • All former variantion of parse methods were retained and default to BeanDiscoveryMode.ANNOTATED.

This should give integrators enough leeway to implement the backward compatibility switch.

Weld versus CDI Lite versus CDI Full

By far the biggest change in CDI 4.0 is the introduction of CDI Lite. At this point I should reiterate that I highly recommend looking this article if you don’t know what CDI Lite is. In short, CDI Lite is a feature subset of CDI Full that broadens the amount of environments in which CDI can execute; more presicely, it enables CDI in build time oriented frameworks such as Micronaut or Quarkus. What does that means for Weld users? Nothing much, Weld is and will be a runtime oriented implementation and you can keep using CDI as you did up until now. More precisely, Weld is so called CDI Full implementation meaning it provides each and every CDI feature and while there were some deprecations and removals, the rest stays the same.

Build Compatible Extensions

One of the notable additions to CDI Lite (and therefore into CDI Full as well) were Build Compatible Extensions (BCE). These are akin to Portable Extensions but tuned in a way so that they can be used in build time oriented environments as well. Along with it comes a different language model because AnnotatedType and friends are reflection-heavy and not a good fit for that API. If you want to learns more, here is an excellent article by Ladislav Thon that covers how they work.

From Weld perspective, you can use BCE as much as you like although they are also executed at runtime, just as Portable Extensions are. It is still recommended to use Portable Extensions if possible because BCE are (in Weld) implemented via Portable Extensions. That being said, if you have some portability demands between Lite and Full, you should be able to use BCE as much as you like.

Integrators - how to make Weld understand Build Compatible Extensions?

This part focuses mainly on integrators and describes how Weld implements Build Compatible Extensions and what needs to be done by integrators in order to fully support CDI Lite.

weld-lite-extension-translator module

Weld 5 has a new module that enables Build Compatible Extensions (BCE) and the new language model that goes along with it - weld-lite-extension-translator. GAV of this new artifact is org.jboss.weld:weld-lite-extension-translator:5.0.0.Beta1. As I mentioned in previous point, BCE are executed via a Portable extension. More precisely, the key class is WeldLiteExtensionTranslator.

Just like any Portable extension, it needs an entry in META-INF or an instance of this extensions has to be added programmaticaly during Weld bootstrap. This is where it gets tricky; it doesn’t work out of the box in all environments!

  • Weld SE - works out of the box, the extension is automagically added

  • Weld Servlet - works out of the box, the extensions is automagically added

  • EE - doesn’t work without integrator registering the extension

  • Any other custom integration - doesn’t work without integrator registering the extension

There is of course a reason for it - complex structured deployments (such as EAR or WAR) and the fact that Weld alone cannot know the deployment well enough to make sure this extension wouldn’t be registered multiple times. On top of that, you might also want to avoid registering this extension if there are no BCE found inside the deployment which can also be dependent on how the given platform performs such discovery. Therefore, Weld leaves it up to the integrator (WildFly, GF, Liberty,…​) to identify where and when to register this extension for each deployment.

Registering LiteExtensionTranslator

Registering the LiteExtensionTranslator can be as easy as adding a META-INF entry with it into some archive in the deployment. An example of this would be arquillian-container-weld, a test container for Weld applications. As you can see from this pull request, it basically adds a META-INF entry which is sufficient to support new extension model. Since it a test tool, the extension is always registered without any attempt to optimize it.

The above solution is nice and clean, but won’t cut it for any EE integrators. Instead, you will want to register this extension very similarly to how you currently register ProbeExtension - add it programmatically as part of the CDI deployment. As mentioned above, this extension should to be registered at most once per deployment, so I’d recommend welding (pun intended) this directly into your org.jboss.weld.bootstrap.spi.CDI11Deployment implementation. Because WildFly does not yet have a public branch with this, I can at least point to how it registers ProbeExtension. With a little bit of digging, it boils down to creating CDI11Deployment impl with list of extensions already containing this one.

Which brings us to the second point - I’d recommend integrators to optimize this process and only register/include LiteExtensionTranslator when there is at least one BCE present in any given deployment. The reason being that this extension has to monitor a very wide range of events including ProcessAnnotatedType<?> for all types in order to properly implement BCE. Many integrators can perform BCE detection in their own ways (such as Jandex in WildFly) but for those that want a generic solution, take a look at org.jboss.weld.lite.extension.translator.BuildCompatibleExtensionLoader which is a utility class alowing to perform a standard service discovery process with given ClassLoader and returns the set of discovered BCE classes. You can then instantiate LiteExtensionTranslator via a constructor that takes this set as an input; or skip registering it if you haven’t found any BCE at all.

TCK structural changes and lang model TCKs

Few paragraphs above I mentioned new language model used by Build Compatible Extensions. Obviously, this needed some testing and so CDI TCK has a separate module for it; see lang-model module and its README. Weld tests and passes these TCKs via lang-model-tck module.

Next change was a separation of tests between pure CDI tests and tests requiring other Jakarta EE technologies such as JSF, EL and other. Many of these are candidates for move into their respective specifications but are for now still hosted in CDI TCK. All of these tests now reside under a separate module with GAV jakarta.enterprise:cdi-tck-web-impl.

Lastly, due to the split between CDI Lite and Full and the ability to have CDI implementations only for Lite, all TCKs had to be reviewed and a new test category was added - cdi-full. It is easy to guess that this category was assigned to tests that are supposed to only execute in CDI Full implementations; i.e. tests containing features that aren’t present in CDI Lite. Weld, as noted before, is a CDI Full implementation and as such passes all TCKs. The current setup used for TCK execution can be read from this POM file.

More in-depth overview of resolved issues in Weld 5

Finally, for those who would like to inspect a more detailed list of changes, here are links to release notes of all version 5 releases up to and including Beta1:

[ Download ] [ Documentation ] [ Release notes ]