How to Import a Maven Dependency into Hybris

Hybris uses ant to build the project. However, you may see some Maven-style dependencies in files called "external-dependencies.xml". They are not automatically imported when you execute "ant clean all", I will describe here how to make use of them to import a new library into your extension.

File "external-dependencies.xml"

This is the file that looks like a pom.xml, where you will include the dependencies to import your needed libraries. For example, here I am importing two Spring libraries:

The location of the file slightly differs depending on whether you work in a regular extension or a web extension. Both types of extensions have this file available in the root:

But in addition to that, web extensions also have this file inside the web/webroot/WEB-INF folder:

Enabling Maven

To enable Hybris to download the dependencies using Maven, first of all you need to have Maven installed.

Second, you need to add usemaven="true" in your extensioninfo.xml in the extension where you want to import your dependency:

After that, you just execute "ant clean all", and during the process your dependency will be downloaded and imported into the extension's "lib" folder or in web/webroot/WEB-INF/lib, depending on which of the two external-dependencies.xml files you edited:

Task "updateMavenDependencies"

Hybris's build also has a target called "updateMavenDependencies". Sometimes we just want to download the new dependencies into the "lib" folder, and not necessarily rebuild the whole project. In this case you run this from the hybris/bin/platform directory:

ant updateMavenDependencies        

This will delete all libraries from all the "lib" folder of all extensions with usemaven="true", and then will replace them with whatever is in that extension's "external-dependencies.xml" file.

File "unmanaged-dependencies.txt"

The "unmanaged-dependencies.txt" file lists Java libraries (JAR files) that are not managed by Maven.

The files listed in "unmanaged-dependencies.txt" need to be included in the build process but are not available in public Maven repositories or are custom libraries specific to the project.

You can see an example of how to use this file in the OOTB "backoffice" extension:

The libraries enumerated in this file - will not be touched by Maven during the build.

File ".lastupdate"

The .lastupdate file plays a critical role in ensuring that any changes to the libraries (such as additions, removals, or updates) are recognized by the build system. This triggers necessary rebuilds or refreshes of the application to include the new or updated libraries.

If your build doesn't download the needed Maven dependencies, it may help to delete this file from the "lib" directory, so the Maven update starts fresh.

Conclusion

This article explains how to import Maven dependencies into a Hybris project, as well as various tips and tricks around this process.