Ask Questions and Find Answers

Hello,
I want to use "Apache Commons Configuration2" in my service builder project. While this would be an easy task in a normal java environment I simply can't get it to work with OSGi.
...
According to my understanding of it, "Apache Commons Configuration2" is already an OSGi module (MANIFEST.MF exists and contains OSGi configuration). Therefore it should be enough to add the library to my build file and the -includeresource instruction inside bnd.bnd.

For actual pointers, we'd need to know what classes are still missing. My recommendation would be to

• not use -includeresource, but rather deploy the bundle as well. It's an OSGi bundle already, and deploying it separately will shrink your own bundle's size dramatically
• Figure out the dependencies that it requires and deploy them as well to the runtime. (if you run into non-OSGi-bundles while figuring out those dependencies, -includeresource might be an ugly quickfix method again, but you should prefer to use it as last resort)
  

So here's a thing...

First, any module that is OSGi-enabled can be deployed into the OSGi container by dropping it into the Liferay deploy folder. From a project perspective, you are either going to use "compile" or "compileOnly" directives (in Gradle) or the "provided" scope (in Maven) to satisfy compile time dependencies.

As an OSGi module, though, it becomes your responsibility to resolve any 3rd party dependencies the OSGi-enabled module has. In your case, you've seen the long list of "optional" dependencies that you'd need to take care of resolving.


The good news for you is that each of the listed packages are also provided by OSGi-enabled modules. The bad news for you is that they each will come with their own list of other transient dependencies, so pretty soon your "I'll just deploy commons-config2 into the OSGi container becomes a nightmare.

What makes this even harder is that OSGi does not understand the "optional" designation bound to a transient dependency. This may sound obtuse, but if you think about it, the container really can't know if you (the developer) will want the org.apache.commons.jexl2 or not. After all, that depends upon what features of commons-config2 you are going to use, and at module deployment time the container can't read your mind to know if you plan on using features bound to JEXL or not. So even though the dependency is listed as "optional" in the manifest, to the OSGi container it must be satisfied or explicitly masked.

So you already know about how to satisfy the transient dependencies (and the headache that comes with that), so how about the masking part? Well, that is going to be done using a fragment bundle to adjust the manifest of the OSGi-enabled module. Similar to what I covered here: https://liferay.dev/blogs/-/blogs/fixing-module-package-access-modifiers but instead of adding packages for export, you're going to use the Import-Package directive to mask off those packages you know you don't need. So if you were going to use all of the transient dependencies except for JEXL, for example, you'd have the directive like:

Import-Package: !org.apache.commons.jexl2, *

This will block the load of JEXL but still allow for importing the rest of the dependencies.

As a fragment bundle, this will attach itself to the fragment host and modify its manifest so the details are controlled by you and not by the container.

Finally, as an aside, consider this: Liferay already comes with commons-configuration support baked in. The portal-ext.properties, the portlet-ext.properties and service-ext.properties support, the use of environment variables in those files, "include-and-override" support, all of these things come from just using the Liferay facilities.

So you really should be asking yourself, do I really need another configuration handling package in my environment? What is the key feature that I need from commons-configuration2 and is it really worth all of these issues to use its version instead of sticking with Liferay's commons-configuration support?

Another example is commons-lang3. I work with developers that just want to go off and pull in commons-lang3 (because it's the latest and greatest), but I always reject their PRs when I see it. Why? Because Liferay already provides commons-lang (commons-lang2 I guess is what it really should be called), and typically the devs aren't using a feature exclusive to lang3 in order to justify using it instead.

Is this important? Well, no, not really, OSGi is happy to have commons-lang2 and commons-lang3 as well as commons-configuration and commons-configuration2 in the same container. It's not going to complain about that at all as long as the transient dependencies are satisfied.

I reject it though because even though OSGi might support all of the different versions, I don't want my projects getting sucked into a vortex of each developer picking one or the other; instead i want to be consistent in all projects. Sticking with commons-lang2 and commons-configuration is a easy restriction to live under since functionality between the versions is still pretty similar. The consistency I get across my projects is knowing that all developers will be using commons-lang2 and no developer is making a choice on their own.

I would encourage you to consider the same when thinking about pulling in commons-configuration2... You may have a good reason to include it to justify all of this, and if so, please ignore this last bit of advice. But if you can't single out a needed feature that only commons-configuration2 provides that commons-configuration does not, I would encourage you to consider sticking with the provided commons-configuration support and keep your portal implementations as simple as possible.