To shade or not to shade?

Development
1

I’m struggling a bit about the shading of module artifacts. The shade plugin is currently in use for

  • commons/typed-values
  • connect/connectors-all
  • engine
  • spin/dataformat-all

I was stumbling now (again) over it with the failing Tomcat integration tests. The shaded artifacts bundle javax/jakarta APIs and dependents into the uberjar. Some rules for the shading are outdated now with the migration to jakarta and have to be reworked.

It made me think about what needs to be shaded and what not, or why at all. Especially I am concerned about shading of the JavaEE/JakartaEE APIs.

I see the following reasons for the shading

  • Have a single dependency that is self-contained
  • Be independent from the exact EE API version and subtle differences
  • Provide EE APIs for non-EE containers (=> Tomcat)

But it also raises the complexity significantly.

Questions:

  1. Shall we include and relocate JakartaEE APIs in these artifacts?
  2. Or: Shall we exclude JakartaEE APIs from the shaded jar and make sure (for Tomcat) that they are part of the /lib folder?
  3. Shall we get rid off shading at all?

WDYT?

2

In my experience, shading is frequently a source of problems. Sometimes, as a user of a library, you want to override versions, exclude dependencies, or otherwise manipulate dependencies. Shading reduces the flexibility for developers. I would prefer getting rid of shading in general.

1 Like
3

I’d like to unerstand the reasons why this shading was done in the first place. It fits my experience that shading makes things more complicated, but I’d assume when it was introduced, somebody had a good reason. Unfortunately, the commits I checked did not explain that reason.

Maybe it’s not a black or white “we do shading or we don’t” decision, but each instance should be evaluated. Shading of javax / jakarta dependencies might have been done to support different Java EE / Jakarta EE versions, Spring uses this API, too. Shading of Jackson and GSON is often done, because other frameworks pull them in, too, and then you run into compatibillity issues.

It would be a catastrophe if at one point Operaton would work with Spring but not with Quarkus, because one of them upgraded to a newer Jackson/GSON version with a breaking API change.