Update maven-bundle-plugin instructions to export package containing XSD files

[GeertZondervan]

Impact

• Bug fix (non-breaking change which fixes expected existing functionality)
• Enhancement/New feature (adds functionality without impacting existing logic)
• Breaking change (fix or feature that would cause existing functionality to change)

Description

Currently XSD files can not be loaded from the liquibase-core.jar in an OSGI environment (using the OSGiResourceAccessor). The LiquibaseEntityResolver can not find the XSD resource. A workaround is to set secureParsing to false, so XSD can be looked up remotely.

The liquibase-core.jar contains two directories (packages). liquibase and www.liquibase.org. ONLY the liquibase package and it's sub-packages are being exported in the MANIFEST.MF. This means the XSD files, which are all under www.liquibase.org.xml.ns.dbchangelog, can not be accessed in an OSGI environment.

The reason why the XSD's are not exported in the MANIFEST.MF right now is because currently no Export-Package tag is specified in the maven-bundle-plugin instructions. This means the default behavior of the maven-bundle-plugin is used:

Export-Package> is now assumed to be the set of packages in your local Java sources, excluding the default package '.' and any packages containing 'impl' or 'internal'. (before version 2 of the bundleplugin it was based on the symbolic name)

See: https://felix.apache.org/documentation/subprojects/apache-felix-maven-bundle-plugin-bnd.html#_default_behavior

The XSD's have been moved to /src/main/recources, so they are not automatically included in the export.

I simply added an Export-Package tag to the maven-bundle-plugin which includes all the packages under liquibase and the www.liquibase.org.xml.ns.dbchangelog package. This ensures that all packages are being exported in the MANIFEST.MF.

With these in the OSGI headers, and using theOSGiResourceAccessor, XSD files could be found by LiquibaseEntityResolver again.

I think this fixes the issue #2817.
Since the XSD files are a crucial part of Liquibase, I think this package should always be exported. This also allows OSGI environment to disable remote lookup, something we have been waiting for.

[ponziani]

Hi @GeertZondervan,

Since the LiquibaseEntityResolver is a class in the liquibase-core, I don't understand how exporting these packages (to make them available for other bundles) will help LiquibaseEntityResolver to find the XSD's.

Can you please explain ?

Thanks,
Steven

[GeertZondervan]

Hi @GeertZondervan,

Since the LiquibaseEntityResolver is a class in the liquibase-core, I don't understand how exporting these packages (to make them available for other bundles) will help LiquibaseEntityResolver to find the XSD's.

Can you please explain ?

Thanks, Steven

Hello @ponziani

I will try to explain it by just documenting my findings.

When instantiating the OSGiResourceAccessor class we need to provide it with a Bundle in the constructor.
This will ofcourse be our own bundle, the bundle in which we store our changelog XML files. The OSGiResourceAccessor extends the ClassLoaderResourceAccessor and simply gets the the class loader from the provided bundle.

So the classloader used by our ResourceAccessor is that of our bundle, which means our changelogs can be found just fine.

But then it goes looking for the XSD files we have specified in our changelog. Now this is what happens in LiquibaseEntityResolver.resolveEntity(...):

It first tries to find the resourceUri using
URL resourceUri = this.getSearchClassloader().getResource(path);
which tries to get the classloader from the current thread, which again is that of our own bundle.

If this fails it tries to get the resource from the ResourceAccessor
Resource resource = Scope.getCurrentScope().getResourceAccessor().get(path);
This also is not found because it uses the classloader this.classLoader.getResources(path). And the classloader in the ResourceAccessor is that of our own bundle.

So you see, our bundle can access all classes in the liquibase-core.jar since these are exported in the MANIFEST.MF.
The XSD package in resources are not exported, so our bundle (classloader) can not access them.
When explicitly exporting the www.liquibase.org.xml.ns.dbchangelog it can access them with the OSGiResourceAccessor.

Right now the liquibase-core bundle exports everything anyway, except for the XSD files. An argument can be made that the XSD files are pretty much part of the Liquibase API. Shouldn't these always be exported/available?

When writing this comment, I actually thought of another workaround. And that is the use a CompositeResourceAccessor with two OSGiResourceAccessors. I've tested this an would look something like this:

import liquibase.parser.core.xml.LiquibaseEntityResolver;
import liquibase.resource.CompositeResourceAccessor;
import liquibase.resource.OSGiResourceAccessor;
import org.osgi.framework.Bundle;
import org.osgi.framework.BundleContext;
import org.osgi.framework.FrameworkUtil;

BundleContext context = FrameworkUtil
                     .getBundle(LiquibaseEntityResolver.class).getBundleContext();  //<< Random liquibase-core class
CompositeResourceAccessor compositeResourceAccessor = new CompositeResourceAccessor(
	new OSGiResourceAccessor(bundle),             // Our bundle
	new OSGiResourceAccessor(context.getBundle())   // Liquibase bundle
	);
Liquibase liquibase = new Liquibase(path, compositeResourceAccessor, database);

But this seems kinda "hacky" to me. To use it like this is nowhere documented.
Maybe the OSGiResourceAccessor should be refactored to always be a composite that has at least one OSGI or Classloader accessor using the liquibase bundle?

[ponziani]

Hi @GeertZondervan,

Thanks for your explanation.

If this fails it tries to get the resource from the ResourceAccessor Resource resource = Scope.getCurrentScope().getResourceAccessor().get(path); This also is not found because it uses the classloader this.classLoader.getResources(path). And the classloader in the ResourceAccessor is that of our own bundle.

That is where your scenario differs from mine, the classloader in the ResourceAccessor is not that of our own bundle. I had a look and it turns out that is because we are not using the Liquibase-class (probably a legacy workaround).

Using the Liquibase-class it does work with your fix (the extra export), but only after adding the package to the Import-Packages from our own bundle as well.

[ponziani]

Hi @GeertZondervan,

I've given it another thought.

1. I think the liquibase-core should be able to resolve it's own XSD's without an extra export.
2. The original solution proposed by @jherkel would require an extra OSGi-dependecy for liquibase-core, which I'm not fond of.
3. I like your suggestion of making OSGiResourceAccessor a CompositeResourceAccessor
4. The extra export might still be useful, but not for this issue imho.

[GeertZondervan]

Using the Liquibase-class it does work with your fix (the extra export), but only after adding the package to the Import-Packages from our own bundle as well.

Ah yes, we also need to add the import to our own bundle. But that is something we are used to with working in OSGI.

Just FYI, after my last comment, I am using this in our application and it does fix the issue, without having to add an extra export.

CompositeResourceAccessor compositeResourceAccessor = new CompositeResourceAccessor(
	// Can access resources from our OSGI bundle (such as our changelog xml files).
	new OSGiResourceAccessor(bundle),
	// Can access resources from the liquibase-core bundle (such as XSD files which are not
	// exported by the liquibase bundle).
	new ClassLoaderResourceAccessor(Liquibase.class.getClassLoader())
);

Liquibase liquibase = new Liquibase(path, compositeResourceAccessor, database);

[github-actions]

Unit Test Results

  5 239 files  ±  0    5 239 suites  ±0   38m 9s ⏱️ + 4m 47s
  4 823 tests  - 18    4 603 ✔️  - 21     220 💤 +3  0 ❌ ±0 
61 867 runs   - 12  55 851 ✔️  - 17  6 016 💤 +5  0 ❌ ±0 

Results for commit d961a4d. ± Comparison against base commit 6da6059.

♻️ This comment has been updated with latest results.

[filipelautert]

This PR adds the Export-Package section to maven-bundle-plugin instructions, and this way XSD files become accessible by OSGi applications.
By adding this tag the only file that gets changed on liquibase-core jar is MANIFEST.MF .

[XDelphiGrl]

@nvoxland, hi! Would you mind taking a quick look and making sure everything here looks good to you? @GeertZondervan and @ponziani give excellent reasoning and documentation of why this change is desirable for OSGI environments but I want to ensure you don't see any pitfalls related to non-OSGI environments.

Thanks!

PS @GeertZondervan - Your description and discussion is amazing! Wherever you work is lucky to have you! :)
PPS @nvoxland - Would this count as a Major Release only change?

[GeertZondervan]

@XDelphiGrl Thank you for the compliment! :)

[XDelphiGrl]

This PR makes it possible for OSGI environments to locate the Liquibase XSD files in the core jar without having to set secureParsing=FALSE.

• Fix is limited to the pom file and has no functional impact outside of OSGI environments.
• Functional and test harness executions passing.
• No additional testing required.

APPROVED