Configuring Dependencies

Using external artifacts in your project requires configuring their dependencies. To do this, look up the artifact’s attributes and plug them into dependency entries for your build system (either Gradle, Maven, or Ant/Ivy). Your build system downloads the dependency artifacts your project needs to compile successfully.

Before specifying an artifact as a dependency, you must first find its attributes. Artifacts have these attributes:

• Group ID: Authoring organization
• Artifact ID: Name/identifier
• Version: Release number

This tutorial shows you how to make sure your projects have the right dependencies:

• Find Core artifacts
• Find Liferay app and independent artifacts
• Configure dependencies

Finding Core Artifacts

Each Liferay artifact is a JAR file whose META-INF/MANIFEST.MF file contains the artifact’s OSGi metadata. The manifest also specifies the artifact’s attributes. For example, these two OSGi headers specify the artifact ID and version:

Bundle-SymbolicName:  [artifact ID]
Bundle-Version: [version]

Important: Artifacts in Liferay DXP fix packs override Liferay DXP installation artifacts. Subfolders of a fix pack ZIP file’s binaries folder hold the artifacts. If an installed fix pack provides an artifact you depend on, specify the version of that fix pack artifact in your dependency.

This table lists the group ID, artifact ID, version, and origin for each core Liferay DXP artifact:

Core Liferay DXP Artifacts:

File	Group ID	Artifact ID	Version	Origin
portal-kernel.jar	com.liferay.portal	com.liferay.portal.kernel	(see JAR’s MANIFEST.MF)	fix pack ZIP, Liferay DXP installation, or Liferay DXP dependencies ZIP
portal-impl.jar	com.liferay.portal	com.liferay.portal.impl	(see JAR’s MANIFEST.MF)	fix pack ZIP or Liferay DXP .war
portal-test.jar	com.liferay.portal	com.liferay.portal.test	(see JAR’s MANIFEST.MF)	fix pack ZIP or Liferay DXP .war
portal-test-integration.jar	com.liferay.portal	com.liferay.portal.test.integration	(see JAR’s MANIFEST.MF)	fix pack ZIP or Liferay DXP .war
util-bridges.jar	com.liferay.portal	com.liferay.util.bridges	(see JAR’s MANIFEST.MF)	fix pack ZIP or Liferay DXP .war
util-java.jar	com.liferay.portal	com.liferay.util.java	(see JAR’s MANIFEST.MF)	fix pack ZIP or Liferay DXP .war
util-slf4j.jar	com.liferay.portal	com.liferay.util.slf4j	(see JAR’s MANIFEST.MF)	fix pack ZIP or Liferay DXP .war
util-taglibs.jar	com.liferay.portal	com.liferay.util.taglib	(see JAR’s MANIFEST.MF)	fix pack ZIP or Liferay DXP .war
com.liferay.* JAR files	com.liferay	(see JAR’s MANIFEST.MF)	(see JAR’s MANIFEST.MF)	fix pack ZIP, Liferay DXP installation, Liferay DXP dependencies ZIP, or the OSGi ZIP

Next, you’ll learn how to find artifacts for Liferay DXP apps and independent modules.

Finding Liferay App and Independent Artifacts

Independent modules and modules that make up Liferay DXP’s apps aren’t part of the Liferay DXP core. You must still, however, find their artifact attributes if you want to declare dependencies on them. The resources below provide the artifact details for Liferay DXP’s apps and independent modules:

Resource	Artifact Type
App Manager	Deployed modules
Reference Docs	Liferay DXP modules (per release)
Maven Central	All artifact types: Liferay DXP and third party, module and non-module

Important: com.liferay is the group ID for all Liferay DXP’s apps and independent modules.

The App Manager is the best source for information on deployed modules. You’ll learn about it next.

App Manager

The App Manager knows what’s deployed on your Liferay DXP server. You can use it to find whatever modules you’re looking for.

Follow these steps to get a deployed module’s information:

1. In Liferay DXP, navigate to Control Panel → Apps → App Manager.

2. Search for the module by its display name, symbolic name, or related keywords. You can also browse for the module in its app. Whether browsing or searching, the App Manager shows the module’s artifact ID and version number.

Figure 1: You can inspect deployed module artifact IDs and version numbers.

Figure 2: The App Manager aggregates Liferay and independent modules.

If you don’t know a deployed module’s group, use the Felix Gogo Shell to find it:

1. Open a Gogo Shell session by entering the following into a command prompt:

   telnet localhost 11311
   

   This results in a g!: the Felix Gogo Shell command prompt.

2. Search for the module by its display name (e.g., Liferay Bookmarks API) or a keyword. In the results, note the module’s number. You can use it in the next step. For example, these results show the Liferay Bookmarks API module’s number is 52:

   g! lb | grep "Liferay Bookmarks API"
   
      52|Active     |   10|Liferay Bookmarks API (2.0.1)
   

3. To list the module’s manifest headers, pass the module number to the headers command. In the results, note the Bundle-Vendor value: you’ll match it with an artifact group in a later step:

   g! headers 52
   
   Liferay Bookmarks API (52)
   --------------------------
   Manifest-Version = 1.0
   Bnd-LastModified = 1464725366614
   Bundle-ManifestVersion = 2
   Bundle-Name = Liferay Bookmarks API
   Bundle-SymbolicName = com.liferay.bookmarks.api
   Bundle-Vendor = Liferay, Inc.
   Bundle-Version = 2.0.1
   ...
   

4. Disconnect from the Gogo Shell session:

   g! disconnect
   

5. On Maven Central or MVNRepository, search for the module by its artifact ID.

6. Determine the group ID by matching the Bundle-Vendor value from step 3 with a group listed that provides the artifact.

Next, you’ll learn how to use Liferay DXP’s reference documentation to find a Liferay DXP app module’s attributes.

Reference Docs

Liferay DXP’s app Javadoc lists each app module’s artifact ID, version number, and display name. This is the best place to look up Liferay DXP app modules that aren’t yet deployed to your Liferay DXP instance.

Note: To find artifact information on a Core Liferay DXP artifact, refer to the previous section Finding Core artifacts.

Follow these steps to find a Liferay DXP app module’s attributes in the Javadoc:

1. Navigate to Javadoc for an app module class. If you don’t have a link to the class’s Javadoc, find it by browsing https://docs.liferay.com/dxp/apps.

2. Copy the class’s package name.

3. Navigate to the Overview page.

4. On the Overview page, search for the package name you copied in step 2.

The heading above the package name shows the module’s artifact ID, version number, and display name. Remember, the group ID for all app modules is com.liferay.

Figure 3: Liferay DXP app Javadoc overviews list each app module's display name, followed by its group ID, artifact ID, and version number in a colon-separated string. It's a Gradle artifact syntax.

Note: Module version numbers aren’t currently included in any tag library reference docs.

Next, you’ll learn how to look up artifacts on MVNRepository and Maven Central.

Maven Central

Most artifacts, regardless of type or origin, are on MVNRepository and Maven Central. These sites can help you find artifacts based on class packages. It’s common to include an artifact’s ID in the start of an artifact’s package names. For example, if you depend on the class org.osgi.service.component.annotations.Component, search for the package name org.osgi.service.component.annotations on one of the Maven sites.

Note: Make sure to follow the instructions listed earlier to determine the version of Liferay artifacts you need.

Now that you have your artifact’s attribute values, you’re ready to configure a dependency on it.

Configuring Dependencies

Specifying dependencies to build systems is straightforward. Edit your project’s build file, specifying a dependency entry that includes the group ID, artifact ID, and version number.

Note: To configure third-party libraries in a module, see the tutorial Adding Third Party Libraries to a Module.

Note that different build systems use different artifact attribute names, as shown below:

Artifact Terminology

Framework	Group ID	Artifact ID	Version
Gradle	group	name	version
Maven	groupId	artifactId	version
Ivy	org	name	rev

The following examples demonstrate configuring a dependency on Liferay’s Journal API module for Gradle, Maven, and Ivy.

Gradle

Here’s the dependency configured in a build.gradle file:

dependencies {
    compileOnly group: "com.liferay", name: "com.liferay.journal.api", version: "1.0.1"
    ...
}

Maven

Here’s the dependency configured in a pom.xml file:

<dependency>
    <groupId>com.liferay</groupId>
    <artifactId>com.liferay.journal.api</artifactId>
    <version>1.0.1</version>
</dependency>

Ivy

Here’s the dependency configured in an ivy.xml file:

<dependency name="com.liferay.journal.api" org="com.liferay" rev="1.0.1" />

Important: Liferay DXP exports many third-party packages. If you’re developing a WAR, deploy it to check if the packages you’re using are in the OSGi runtime container already. If they are already in there, specify their corresponding artifacts as being “provided”. Here’s how to specify a provided dependency:

Maven: <scope>provided</scope>

Gradle: providedCompile

Don’t deploy a provided package’s JAR again or embed the JAR in your project. Exporting the same package from different JARs leads to “split package” issues, whose side affects differ from case to case. If the package is in a third-party library (not an OSGi module), refer to Resolving Third Party Library Dependencies.

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, follow the instructions for adding a third-party library (not an OSGi module).

Nice! Now you know how to find artifacts and configure them as dependencies. Now that’s a skill you can depend on!

Related Topics

Importing Packages

Reference

Liferay API Modules

Adding Third Party Libraries to a Module

Third Party Packages Portal Exports

Classes Moved from portal-service.jar

Tooling

Portlets