SLFJ4-579: Export client packages of slf4j-api in version 1

[HannesWell]

Fixes https://jira.qos.ch/browse/SLF4J-579

This allows to use the slf4j-api version 2 artifact as drop-in replacement for slf4j-api version 1 in OSGi environments as well.
slf4j-api can now be wired to bundles that require packages of slf4j-api in version 1 or 2.

At the moment the first commit of this PR is actually handled in #330, but since it would otherwise conflict I included that as well. Once #330 is resolved, this only consists of a single, small commit (which is the second one a.t.m.).

@ceki can you please state if besides org.slf4j the packages org.slf4j.event and org.slf4j.helpers were considered part of the API in slf4j-1? You already told that some classes in org.slf4j.event were considered internal, but did that also apply for the package as a whole or where clients supposed to access some classes?

[HannesWell]

@ceki can you please have a look at this after #330?

@bjhargrave @timothyjward @stbischof do you want to share your opinion about the second commit (first one is in #330) from an OSGi point of view?

[mikerumpf]

Thank you for the work, Hannes! Would be cool if this could be merged and released soon as it solves a lot of dependency issues.

[ceki]

@HannesWell Regarding compatibility, classes/interfaces that a user can be reasonable expected to use is guaranteed to be backward-binary-compatible. On the other hand, classes/interfaces which are used by logging back-ends implementing the SLF4J API, are not offered this guarantee but the changes are usually have quite a minimal impact.

Having said this, at the scale of SLF4J distribution, no change has minimal impact.

To answer your question, "org.slf4j" package is for public consumption wheras its sub-packages are considered "internal".

[ceki]

@HannesWell The jira.qos.ch server crashed and had to be rebuilt from backups. This led to some data loss. If you would like to
follow issues on the Jira, please register with jira.qos.ch a second time. My apologies for the inconvenience.

[HannesWell]

@HannesWell Regarding compatibility, classes/interfaces that a user can be reasonable expected to use is guaranteed to be backward-binary-compatible. On the other hand, classes/interfaces which are used by logging back-ends implementing the SLF4J API, are not offered this guarantee but the changes are usually have quite a minimal impact.

Having said this, at the scale of SLF4J distribution, no change has minimal impact.

Yes, I understand and agree.
But the purpose of this change is to allow that one can use slf4j 2 with a logging back-end for slf4j-2 in conjunction with a consumer of the slf4j-1 API. For example there are libraries that use the slf4j-api for logging but only import the package org.slf4j with a version range of (1.7,2] MANIFEST.MF and therefore in OSGi you cannot use them with slf4j-2.

The purpose is not to let a logging backend targeted for slf4j-1 be used with the slf4j-2 api artifact.
That's the reasons why the org.slf4j.spi package is not exported in version 1.x so that a backend for slf4j-1 does not accidentally get wired to slf4j-api version 2.

[ceki]

@HannesWell What is the goal that we are trying to achieve?

If the goal is to ensure backward compatibility for regular clients, then exporting "org.slf4j;version=1.7.36" makes sense.

I don't think a logging back-end can be implemented without importing org.slf4j.spi. Moreover, given that there are very few such implementations, at least comparatively, it is reasonable to ask of them to upgrade to slf4j 2.0.x.

Thus, I think it would make sense to export org.slf4j.spi, org.slf4j.helpers, org.slf4j.event version 2.0.7 for the sake of logging back-ends.

[HannesWell]

@HannesWell What is the goal that we are trying to achieve?

If the goal is to ensure backward compatibility for regular clients, then exporting "org.slf4j;version=1.7.36" makes sense.

Yes, the goal is only to support clients that are programmed against slf4j-1 and only import org.slf4j with range [1.x,2) even with slf4j version two.

I don't think a logging back-end can be implemented without importing org.slf4j.spi. Moreover, given that there are very few such implementations, at least comparatively, it is reasonable to ask of them to upgrade to slf4j 2.0.x.

Thus, I think it would make sense to export org.slf4j.spi, org.slf4j.helpers, org.slf4j.event version 2.0.7 for the sake of logging back-ends.

Yes. Sorry I think my previous comments were misleading. This change only adds new exports with version 1.7.36. All previously existing exports of packages in version 2.0.7 are not changed so that the slf4j-api module exports the user/client facing packages in version 1.7.36 and 2.0.7 and the back-end facing packages are only exported in version 2.0.7.

So before this change the Export-Package entry was:

Export-Package:
 org.slf4j;uses:="org.slf4j.event,org.slf4j.helpers,org.slf4j.spi";version="2.0.7",
 org.slf4j.event;uses:="org.slf4j,org.slf4j.helpers";version="2.0.7",
 org.slf4j.helpers;uses:="org.slf4j,org.slf4j.event,org.slf4j.spi";version="2.0.7",
 org.slf4j.spi;uses:="org.slf4j,org.slf4j.event,org.slf4j.helpers";version="2.0.7"

with the current state of the change it is

Export-Package:
 org.slf4j;uses:="org.slf4j.event,org.slf4j.helpers,org.slf4j.spi";version="2.0.7",
 org.slf4j.event;uses:="org.slf4j,org.slf4j.helpers";version="2.0.7",
 org.slf4j.helpers;uses:="org.slf4j,org.slf4j.event,org.slf4j.spi";version="2.0.7",
 org.slf4j.spi;uses:="org.slf4j,org.slf4j.event,org.slf4j.helpers";version="2.0.7",
 org.slf4j;version="1.7.36";uses:="org.slf4j.event,org.slf4j.helpers,org.slf4j.spi",
 org.slf4j.event;version="1.7.36";uses:="org.slf4j,org.slf4j.helpers",
 org.slf4j.helpers;version="1.7.36";uses:="org.slf4j,org.slf4j.event,org.slf4j.spi"

So the only difference is that the packages org.slf4j org.slf4j.event and org.slf4j.helpers are additionally exported in version 1.7.36.

I don't think a logging back-end can be implemented without importing org.slf4j.spi. Moreover, given that there are very few such implementations, at least comparatively, it is reasonable to ask of them to upgrade to slf4j 2.0.x.

Yes, that makes sense. I'm update to update this PR to only export the package org.slf4j in version 2.0.7 and 1.7.36 and export the other packages in the module only with version 2.0.7.
If some artifact requires a sub-package of org.slf4j it should be encoded in that artifact's OSGi metadata with which versions of slf4j it is compatible.

[ceki]

Good. Thank you.

You mentioned previously that the PR could optimize for "minimal diff" or for "simplicity of understanding/maintenance". In principle, I think the latter is a better choice.

[HannesWell]

Done.
Now the exports are:

Export-Package:
 org.slf4j;uses:="org.slf4j.event,org.slf4j.helpers,org.slf4j.spi";version="2.0.7",
 org.slf4j.event;uses:="org.slf4j,org.slf4j.helpers";version="2.0.7",
 org.slf4j.helpers;uses:="org.slf4j,org.slf4j.event,org.slf4j.spi";version="2.0.7",
 org.slf4j.spi;uses:="org.slf4j,org.slf4j.event,org.slf4j.helpers";version="2.0.7",
 org.slf4j;uses:="org.slf4j.event,org.slf4j.helpers,org.slf4j.spi";version="1.7.36"

[HannesWell]

You mentioned previously that the PR could optimize for "minimal diff" or for "simplicity of understanding/maintenance". In principle, I think the latter is a better choice.

Do you mean regarding the use of the maven-bundle-plugin vs. the bnd-maven-plugin and the use of Manifest.MF files committed into this git repo?

[ceki]

@HannesWell Whatever is easier to maintain on the long run. I'll have a look at your earlier commits and attempt to make a more enlightened comment.

[HannesWell]

@HannesWell Whatever is easier to maintain on the long run.

The maven-bundle-plugin uses the bnd-maven-plugin under the hood, consequently the latter receives updates earlier.
Besides that I think on the long run it is easier to have only one and the same source for OSGi metadata for all slf4j modules. Yes therefore I think it would be good to move all configuration into the bundle/bnd-plugin and get rid of the MANIFEST.MF files.

But I think this should be done in follow up PRs, so that this can land earlier. I can create corresponding small PRs for the migration if you agree. :)

[HannesWell]

Thanks a lot @ceki for your review, merge and immediate release of slf4j 2.0.7.
This will allow immediate adoption of slf4j-2 in the OSGi world. Already prepared the changes to update the Eclipse Platform to the new release.