Validating Modules Against the Target Platform

After you write a module in Liferay Workspace, you can validate it before deployment to make sure of several things:

  • Will my app deploy successfully?
  • Will there be some sort of missing requirement?
  • If there’s an issue, how do I diagnose it?

These are all common worries that can be frustrating.

Instead of deploying your app and checking for errors in the log, you can validate your app before deployment. This is done by calling Liferay Workspace’s resolve task, which validates your modules against a targeted platform.

You’ll cover the following topics in this section:

Continue on to learn how this works.

Resolving Your Modules

You can resolve your modules before deployment. This can be done by calling the resolve Gradle task provided by Liferay Workspace.

./gradlew resolve

This task gathers all the capabilities provided by

  • the specified version of Liferay DXP (i.e., targeted platform)
  • the current workspace’s modules

Some capabilities/information gathered by the resolve task that are validated include

  • declared required capabilities
  • module versions
  • package imports/use constraints
  • service references

It also computes a list of run requirements for your project. Then it compares the current project’s requirements against the gathered capabilities. If your project requires something not available in the gathered list of capabilities, the task fails.

The task can only validate OSGi modules. It does not work with WAR-style projects, themes, or npm portlets.

The resolve task can automatically gather the available capabilities from your workspace, but you must specify this for your targeted Liferay DXP version. To do this, open your workspace’s gradle.properties file and set the liferay.workspace.target.platform.version property to the version you want to target. For example,

liferay.workspace.target.platform.version=7.2.0

If you’re using Liferay DXP, you can set the property like this:

liferay.workspace.target.platform.version=7.2.10

The versions following a GA1 release of DXP follow fix pack versions (e.g., 7.2.10.fp1, 7.2.10.fp2, etc.).

Setting the target platform property provides a static distro JAR for the specified version of Liferay DXP, which contains all the metadata (i.e., capabilities, packages, versions, etc.) running in that version. The distro JAR is a complete snapshot of everything provided in the OSGi runtime; this serves as the target platform’s list of capabilities that your modules are validated against.

You can now validate your module projects before deploying them! If the resolver throws errors, see the article on how to resolve common output errors reported by the resolve task. Sometimes, you must modify the resolve task’s default behavior to successfully validate your app. See the next section for more information.

Modifying the Target Platform’s Capabilities

In a perfect world, everything the resolve task gathers and checks against would work during your development process. Unfortunately, there are exceptions that may force you to modify the default functionality of the resolve task.

There are two scenarios you may run into during development that require a modification for your project to pass the resolver check.

  • You’re depending on a third party library that is not available in the targeted Liferay DXP instance or the current workspace.
  • You’re depending on a customized distribution of Liferay DXP.

You’ll explore these use cases next.

Depending on Third Party Libraries Not Included in Liferay DXP

The resolve task, by default, gathers all of Liferay DXP’s capabilities and the capabilities of your workspace’s modules. What if, however, your module depends on a third party project that is not included in either space (e.g., Google Guava)?. The resolve task fails by default if your project depends on this project type. You probably plan to have this project deployed and available at runtime, so it’s not a concern, but the resolver doesn’t know that; you must customize the resolver to bypass this.

There are three ways you can do this:

For help resolving third party dependency errors, see the Resolving Third Party Library Package Dependencies tutorial.

Depending on a Customized Distribution of Liferay DXP

There are times when manually specifying your project’s list of dependent JARs does not suffice. If your app requires a customized Liferay DXP instance to run, you must regenerate the target platform’s default list of capabilities with an updated list. Two examples of a customized Liferay DXP instance are described below:

Example 1: Leveraging an External Feature

There are many external features/frameworks available that are not included in the downloadable bundle by default. After deploying a feature/framework, it’s available for your module projects to leverage. When validating your app, however, the resolve task does not have access to external capabilities not included by default. For example, Audience Targeting is an example of this type of external framework. If you’re creating a Liferay Audience Targeting rule that depends on the Audience Targeting framework, you can’t easily provide a slew of JARs for your module. In this case, you should install the platform your code depends on and regenerate an updated list of capabilities that your Liferay DXP instance provides.

Example 2: Leveraging a Customized Core Feature

You can extend Liferay DXP’s core features to provide a customized experience for your intended audience. Once deployed, you can assume these customizations are present and build other things on top of them. The new capabilities resulting from your customizations are not available, however, in the target platform’s default list of capabilities. Therefore, when your application relies on non-default capabilities, it fails during the resolve task. To get around this, you must regenerate a new list of capabilities that your customized Liferay DXP instance provides.

To regenerate the target platform’s capabilities (distro JAR) based on the current workspace’s Liferay DXP instance, follow the Depending on a Customized Distribution of Liferay DXP article.

Including the Resolver in Your Gradle Build

By default, Liferay Workspace provides the resolve task as an independent executable. It’s provided by the Target Platform Gradle plugin and is not integrated in any other Gradle processes. This gives you control over your Gradle build without imposing strategies you may not want included in your default build process.

With that said, the resolve task can be useful to include in your build process if you want to check for errors in your module projects before deployment. Instead of resolving your projects separately from your standard build, you can build and resolve them all in one shot.

In Liferay Workspace, the recommended path for doing this is adding it to the default check Gradle task. The check task is provided by default in a workspace by the Java plugin. Adding the resolve task to the check lifecycle task also promotes the resolve task to run for CI and other test tools that typically run the check task for verification. Of course, Gradle’s build task also depends on the check task, so you can run gradlew build and run the resolver too.

You can learn how to include the resolver in your Gradle build by visiting this article.

Continue on for various step-by-step instructions for configuring/manipulating the resolver task.

« Targeting a Platform with MavenAdding a Third Party Library's Capabilities to the Resolver's Capabilities »
¿Fue útil este artículo?
Usuarios a los que les pareció útil: 0 de 0