Source compatibility with version 4.3 and more recent versions of the OSGi core API

[nicoroeser]

In its subproject Apache Felix OSGi Core, Felix repackages OSGi core as a Maven module. The latest release from Felix is artifact org.osgi.core in version 1.4.0. This corresponds to the OSGi core API sources in version 4.2.0. The sources from OSGi and from Felix carry the date 2009-09-01 each.

(Side note: it seems that osgi.core-4.2.1 sources from OSGi have been made available at some point in time but I cannot find an official download for them.)

Woodstox currently depends on the Felix OSGi release (version 1.4.0 of it). OSGi has released version 7 of the OSGi core API in 2018.

Version 4.3 of the upstream OSGi sources introduces changes which are still binary compatible but in some parts not source compatible with earlier versions. This is due to the introduction of Java generics in version 4.3 of the OSGi core API. The OSGi Service Platform Core Specification, Release 4, Version 4.3 (via OSGi Specifications page) explains this in detail in section 1.4 (“Migration to Generics”) on pages 7 and 8.

The current woodstox code fails to compile with OSGi core API versions 4.3 or later due to these source incompatibilities:

woodstox/src/main/java/com/ctc/wstx/osgi/WstxBundleActivator.java

Lines 30 to 36 in 5f384b8

	ctxt.registerService(Stax2InputFactoryProvider.class.getName(), inputP, inputP.getProperties());
	OutputFactoryProviderImpl outputP = new OutputFactoryProviderImpl();
	ctxt.registerService(Stax2OutputFactoryProvider.class.getName(), outputP, outputP.getProperties());
	ValidationSchemaFactoryProviderImpl[] impls = ValidationSchemaFactoryProviderImpl.createAll();
	for (int i = 0, len = impls.length; i < len; ++i) {
	ValidationSchemaFactoryProviderImpl impl = impls[i];
	ctxt.registerService(Stax2ValidationSchemaFactoryProvider.class.getName(), impl, impl.getProperties());

These lines pass java.util.Properties (without generics) where a java.util.Dictionary<String,?> is expected.

I’d like to suggest to update the Woodstox code so that it will also be compatible with more recent OSGi core API releases/versions. Even when they have not yet been made available as Maven modules through Felix.

[cowtowncoder]

@nicoroeser Sounds like a good idea. Just couple of questions, since I don't have much practical experience with OSGi: most code dealing with it, including wrt maven build, has been user contribution.

First: just to confirm, suggestion is to change from Felix dependency to

https://mvnrepository.com/artifact/org.osgi/org.osgi.core

instead? If so, which version (considering that Woodstox 6 still only requires Java 6)?

Second: how much user impact would this change have?
Woodstox version is currently 6.2.x, and I am guessing it should at least go to next minor version (6.3).

[nicoroeser]

@cowtowncoder, I am sorry but I am not an expert on OSGi or Maven as well. I just noticed the issue because I prepared ebuilds (=package building recipes) on a Gentoo system, and Woodstox is an indirect dependency of the package I like to build. This is why I built it from sources; and as I did not use Maven for building, I noticed the dependency on osgi-core below version 4.3 (I had 7.0.0 installed, and saw a failure – then started debugging).

I had not wanted to suggest to drop Felix. This is because I had not known about the org.osgi.core Maven module from org.osgi.core. But as I now know that it exists (thanks!), it might be possible, yes. I cannot comment on which way is better. We might as well ask the Apache Felix developers to release a new version of their Maven module, or ask them whether they could comment on a recommendation. The source code between the two modules is identical (I diffed them) for OSGi core API version 4.2.0.

Regarding the version: I have been able to build OSGi core 7.0.0 with javac from OpenJDK 1.8.0_252 (IcedTea 3.16.0) with -source 1.6 -target 1.6. But I recommend that you check with javac from JDK 6 just to make sure. If compilation succeeds, API compatibility should still be verified in the next step. It seems that the OSGi specifications include compatibility notes like the one referred to in my previous commit. The documents for all versions in between should be checked in order to avoid surprises when switching the implementation.

While I normally recommend to use the latest versions available (due to included bugfixes and so on), this might have implications for users on different systems. According to section “Dependency Version Ranges” in the Maven reference manual, a version in a dependency in pom.xml means “any version, with this one preferred” for Maven. So the version which is currently stated can be kept – but code changes should be made anyway:

What I do recommend (in any case) is to make adjustments to the Woodstox code, especially to class com.ctc.wstx.osgi.WstxBundleActivator so that the code can be compiled against the OSGi core API in version 4.3.0 or later. This should be an easy thing to do because we just have to make it compile in that environment (handle the generics), and still ensure that builds do not break for the current requirements (Java 6, OSGi core API code before version 4.3). The impact should be minimal.

If you indeed like to also switch the org.osgi.core provider, then I agree that Woodstox should increment its version to 6.3. Still, there should be no breakage.

[cowtowncoder]

@nicoroeser Making code compile against multiple versions / packages sounds like a good safe improvement, agreed. Could you suggest diff or PR (and maybe how to test it against by, f.ex, temporarily changing dependency to verify compiling).
I guess I can also make the change once I know how to trigger failure to compile (since it does compiled with current deps). I just don't want to try speculative change without verifying it works.

[nicoroeser]

@cowtowncoder, please let’s first try whether you can reproduce the behavior. I have looked at the org.osgi.core artifact from the org.osgi group, and I think that the following steps should help.

1. In Woodstock’s pom.xml, modify the declared dependencies: change the used OSGI core API implementation from org.apache.felix to org.osgi, and explicitly set <version>[4.2.0]</version> for it. You should be able to complete a build. (I suggest you try to build with a Java 6 Development Kit or later, for best comparability to the next step.)
2. Now upgrade that same dependency declaration to <version>[4.3.0]</version> and try to build again. You are going to need JDK 6 or later for this build. I assume that the build will fail for the reasons I detailed in my previous messages.

If there is a failure in step 1, this suggests that something else is not right. If both steps succeed without changing the Woodstox code, this means that reproduction of this issue is not as easy as I had hoped for.

By the way, please do not use <version>[xyz]</version> (with square brackets) in version specifications for the final code. This is just meant for testing. The final version will probably work with something like <version>6.0.0</version> or <version>7.0.0</version> (whoops, not yet released to the Maven repo, it seems 😉).

[cowtowncoder]

@nicoroeser I am using JDK 8 for all builds at this point since earlier versions can not be used to actually publish new versions to Maven Central (due to some certificates not being included, or such) without some additional setup work.

I can not reproduce any compilation or test failure with org.osgi:org.osgi.core 4.2.0 or 4.3.0, but interestingly enough, 4.3.1 does fail.
That seems like some pretty unfortunate versioning on that component's part...
but at least I can reproduce it, it seems.

[cowtowncoder]

(removed comment -- looked like I may have misunderstood signatures of method in question)

[cowtowncoder]

For a while was worried there might be bigger incompatibility between Properties and Dictionary, but looks like signature has not changed regarding nominal just, just generic parameters (lack thereof).

[cowtowncoder]

As per commit comment, made the change to use intermediate variable to cast from Properties to Dictionary. Please let me know if this solves immediate question.
Update to new version of osgi-core would be next step, worth another issue.

[cowtowncoder]

Filed #133 for actual update -- not 100% sure which OSGi-core dep to upgrade to, but definitely time to do so.

Also contemplating on Java 8 update, will file separate issue for that.

[cowtowncoder]

Assuming #133 took care of this; if not, may be re-filed.