NiFi NAR Files Explained

An Introduction to Processor and Controller Service Packaging

by Chris Herrera

As we work with our customers on consulting and development projects involving Apache NiFi, one of us inevitably gets asked about NiFi NAR files — what are they, how does NiFi use them, and how are they built — along those lines, the explanations below should help out.

What is a NAR file

NAR stands for NiFi Archive. The reason for creating a custom packaging for a NiFi processor is to provide a bit of Java ClassLoader isolation. The processors and controller services all come from different companies and contributors, utilizing differing versions of libraries (such as apache-commons, etc…). A NAR file provides isolation from the potential issue of NoClassDefFoundError exceptions being thrown for having the wrong version of a dependency already loaded in the ClassLoader from a different processor.

NAR File Structure

A NAR file essentially mirrors the Java Web application ARchive (WAR) or Java Application ARchive (JAR) with a few differences. Instead of a WEB-INF folder that would be present in a WAR file, the root directory is META-INF (as would be in a JAR). Under the META-INF root directory, are descriptive files such as LICENSE, DEPENDENCIES (which list the license information of the bundled dependencies), and NOTICE (which contains the license of the processor itself).

Additionally, there are 3 key files/directories under META-INF as well. First is the MANIFEST.MF file. This is the same as the manifest file that is generated for any jar, however, this one includes a Nar-id that is used to identify the nar to the NiFi Nar Unpacker. The later versions of NiFi also contain Nar-Version and dependency manifest entries that will be included to support workflows such as processor versioning. It also includes helpful metadata around the version of Java and Maven used to build the NAR and where it came from.

Sub-Directories

In addition to the files, there are 2 directories, bundled-dependencies and maven.

Maven

The maven directory contains the POM file (the Maven build description file) used to build the NAR, as well as a pom.properties file that contains the maven-compliant details (the 3 key elements that maven uses for dependency identification) of the NAR (groupId, artifiactID, version). The maven directory is only useful to determine the lineage of the build itself.

Bundled-dependencies

The bundled-dependencies contains the actual jar files that will be used by the processor and accompanying controller services (if the NAR contains a controller service). These jar files will also be loaded in the ClassLoader that is dedicated to that processor.

NAR File at Runtime

When NiFi starts, it will take all of the NAR files from the /lib directory and extract them to work/nar/extensions/<your-nar>/. The structure beyond there will be exactly as described in the NAR File Structure section above.

How to Build A Nar

By far, the easiest way to build a NAR is to start development using the Maven Archtype for processors or controller services, this will create a maven project the NAR plugin as well as any dependencies needed from the framework in to the controller service or property.

The above effective POM snippet from the Archtype shows the NAR plugin.

How to Unpack a NAR on the Command Line

As mentioned earlier, NAR is just a modified WAR packaging (which in-itself is a lightly-modified packaging structure from JAR). Therefore the easiest way to unpack a NAR file is to use the jar command line utility. Assuming you have the JRE bin directory in your system path the instruction would be:

jar –xvf <nar-file-name.nar>

I hope this helped shed some light on NiFi NAR files — be sure and look for more NiFi content in upcoming posts.

Feel free to share this blog on other channels and be sure and keep up with all new content from Hashmap at https://medium.com/hashmapinc.

Chris Herrera is a Senior Enterprise Architect at Hashmap working across industries with a group of innovative technologists and domain experts accelerating the value of connected data for the open source community and customers. Feel free to tweet @cherrera2001 and connect with him on LinkedIn at linkedin.com/in/cherrera2001.