Resolving Third Party Library Package Dependencies

The OSGi framework lets you build applications composed of multiple modules. The modules must resolve their Java package dependencies for the framework to assemble the modules into a working system. In a perfect world, every Java library would be an OSGi bundle (module), but many libraries aren’t. So how do you resolve the packages your OSGi module needs from non-OSGi third party libraries?

Here is the main workflow for resolving third party Java library packages:

Step 1 - Find an OSGi module of the library: Projects, such as Eclipse Orbit and ServiceMix Bundles, convert hundreds of traditional Java libraries to OSGi modules. Their artifacts are available at these locations:

• Eclipse Orbit
• ServiceMix Bundles

Deploying the module to Liferay’s OSGi framework lets you share it on the system. If you find a module for the library you need, deploy it. Then add a compileOnly (Gradle) or <scope>provided</scope> (Maven) dependency for it in your module. When you deploy your module, the OSGi framework wires the dependency module to your module. If there’s no OSGi module based on the Java library, go to Step 2.

Tip: Refrain from embedding library JARs that provide the same packages that Liferay DXP or existing modules provide already.

Note: If you’re developing a WAR that requires a different version of a third-party package that Liferay DXP or another module exports, specify that package in your Import-Package: list. If the package provider is an OSGi module, publish its exported packages by deploying that module. Otherwise, rename the third-party library (not an OSGi module) differently from the JAR that the WAB generator excludes and embed the JAR in your project.

Step 2 - Resolve the Java packages privately in your module: You can copy required library packages into your OSGi module or embed them wholesale, if you must. The rest of the tutorial shows you how to do this.

Note: Liferay’s Gradle plugin com.liferay.plugin automates several third party library configuration steps. The plugin is applied to Liferay Workspace Gradle module projects created in Liferay Developer Studio or using Liferay Blade CLI automatically.

To leverage the com.liferay.plugin plugin outside of Liferay Workspace, add code like the listing below to your Gradle project:

buildscript {
    dependencies {
        classpath group: "com.liferay", name: "com.liferay.gradle.plugins", version: "3.2.29"
    }

    repositories {
        maven {
            url "https://repository-cdn.liferay.com/nexus/content/groups/public"
        }
    }
}

apply plugin: "com.liferay.plugin"

If you use Gradle without the com.liferay.plugin plugin, you’ll have to embed the third party libraries wholesale.

The recommended package resolution workflow is next.

Library Package Resolution Workflow

When you depend on a library JAR, much of the time you only need parts of it. Explicitly specifying only the Java packages you need makes your bundle more modular. This also insulates modules that depend on your module from unneeded packages.

Here’s a configuration workflow that minimizes dependencies and Java package imports:

1. Add the library as a compile-only dependency (e.g., compileOnly in Gradle).

2. Copy only the library packages you need by specifying them in a conditional package instruction (Conditional-Package) in your bnd.bnd file. Here are some examples:

   Conditional-Package: foo.common* adds packages your module uses such as foo.common, foo.common-messages, foo.common-web to your module’s class path.

   Conditional-Package: foo.bar.* adds packages your module uses such as foo.bar and all its sub-packages (e.g., foo.bar.baz, foo.bar.biz, etc.) to your module’s class path.

   Deploy your module. If a class your module needs or class its dependencies need isn’t found, go back to main workflow Step 1 - Find an OSGi module version of the library to resolve it.

   Important: Resolving packages by using compile-only dependencies and conditional package instructions assures you use only the packages you need and avoids unnecessary transitive dependencies. It’s recommended to use the steps up to this point, as much as possible, to resolve required packages.

3. If a library package you depend on requires non-class files (e.g., DLLs, descriptors) from the library, then you might need to embed the library wholesale in your module. This adds the entire library to your module’s classpath.

Next you’ll learn how to embed libraries in your module.

Embedding Libraries in a Module

You can use Gradle, Maven, or Ivy to embed libraries in your module. Below are examples for adding Apache Shiro using all three build utilities.

Embedding a Library Using Gradle

Open your module’s build.gradle file and add the library as a dependency in the compileInclude configuration:

dependencies {
    compileInclude group: 'org.apache.shiro', name: 'shiro-core', version: '1.1.0'
}

The com.liferay.plugin plugin’s compileInclude configuration is transitive. The compileInclude configuration embeds the artifact and all its dependencies in a lib folder in the module’s JAR. Also, it adds the artifact JARs to the module’s Bundle-ClassPath manifest header.

Note: The compileInclude configuration does not download transitive optional dependencies. If your module requires such artifacts, add them as you would another third party library.

Note: If the library you’ve added as a dependency in your build.gradle file has transitive dependencies, you can reference them in an -includeresource: instruction by name without having to add them explicitly to the list of dependencies. See how it’s used in the Maven section next.

Embedding a Library Using Maven or Ivy

Follow these steps:

1. Open your module’s build file and add the library as a dependency in the provided scope:

   Maven:

   <dependency>
     <groupId>org.apache.shiro</groupId>
     <artifactId>shiro-core</artifactId>
     <version>1.1.0</version>
     <scope>provided</scope>
   </dependency>
   

   Ant/Ivy:

   <dependency conf="provided" name="shiro-core" org="org.apache.shiro" rev="1.1.0" />
   

2. Open your module’s bnd.bnd file and add the library to an -includeresource instruction:

   -includeresource: META-INF/lib/shiro-core.jar=shiro-core-[0-9]*.jar;lib:=true
   

   This instruction adds the shiro-core-[version].jar file as an included resource in the module’s META-INF/lib folder. The META-INF/lib/shiro-core.jar is your module’s embedded library. The expression [0-9]* helps the build tool match the library version to make available on the module’s classpath. The lib:=true directive adds the embedded JAR to the module’s classpath via the Bundle-Classpath manifest header.

Lastly, if after embedding a library you get unresolved imports when trying to deploy to Liferay, you may need to blacklist some imports:

Import-Package:\
    !foo.bar.baz,\
    *

The * character represents all packages that the module refers to explicitly. Bnd detects the referenced packages.

Congratulations! Resolving all of your module’s package dependencies, especially those from traditional Java libraries, is a quite an accomplishment.

Related Topics

Importing Packages

Exporting Packages

Creating Modules with Blade CLI