A Guide to Maven Artifact Classifiers

1. Overview

In this tutorial, we’ll be looking at the role of a Maven artifact classifier. Following that, we’ll take a look at the various scenarios where they might be useful. Before concluding, we’ll briefly discuss the Maven artifact type as well.

2. What Is a Maven Artifact Classifier?

A Maven artifact classifier is an optional and arbitrary string that gets appended to the generated artifact’s name just after its version number. It distinguishes the artifacts built from the same POM but differing in content.

Let’s consider the artifact definition:

<groupId>com.baeldung</groupId>
<artifactId>maven-classifier-example-provider</artifactId>
<version>0.0.1-SNAPSHOT</version>

For this, the Maven jar plugin generates maven-classifier-example-provider-0.0.1-SNAPSHOT.jar.

2.1. Generating Artifacts With a Classifier

Let’s add a classifier configuration to the jar plugin:

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-jar-plugin</artifactId>
            <version>3.3.0</version>
            <executions>
                <execution>
                    <id>Arbitrary</id>
                    <goals>
                        <goal>jar</goal>
                    </goals>
                    <configuration>
                        <classifier>arbitrary</classifier>
                    </configuration>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

As a result, the maven-classifier-example-provider-0.0.1-SNAPSHOT-arbitrary.jar along with the maven-classifier-example-provider-0.0.1-SNAPSHOT.jar is generated.

2.2. Consuming Artifacts With a Classifier

We’re now able to generate an artifact with a custom suffix using a classifier. Let’s see how we can use a classifier to consume the same.

In order to consume the default artifact, we don’t have to do anything special:

<dependency>
    <groupId>com.baeldung</groupId>
    <artifactId>maven-classifier-example-provider</artifactId>
    <version>0.0.1-SNAPSHOT</version>
</dependency>

But, to consume the artifact with the custom suffix “arbitrary”, we’ll need to use the classifier element within the dependency element:

<dependency>
    <groupId>com.baeldung</groupId>
    <artifactId>maven-classifier-example-provider</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <classifier>arbitrary</classifier>
</dependency>

After all this, a good question is why we would want to use a classifier? So, let’s look at some practical use cases where a classifier would be useful.

3. Using the Sources Classifier

We might have noticed that each Maven artifact is often accompanied by a “-sources.jar” artifact. It contains the source code, i.e., the .java files for the main artifact. It’s useful for debugging purposes.

3.1. Generating Sources Artifact

Firstly, let’s generate a sources jar for the maven-classifier-example-provider module. We’ll use maven-source-plugin to do that:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-source-plugin</artifactId>
    <version>3.2.1</version>
    <executions>
        <execution>
            <id>attach-sources</id>
            <phase>verify</phase>
            <goals>
                <goal>jar-no-fork</goal>
            </goals>
        </execution>
    </executions>
</plugin>

Now, let’s run:

mvn clean install

As a result, the maven-classifier-example-provider-0.0.1-SNAPSHOT-sources.jar artifact is generated.

3.2. Consuming Sources Artifact

Now, to consume the sources artifact, there are several ways. Let’s take a look at one of them. We can fetch sources jar for selective dependencies using a classifier element within the dependency definition:

<dependency>
    <groupId>com.baeldung</groupId>
    <artifactId>maven-classifier-example-producer</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <classifier>sources</classifier>
</dependency>

Now, let’s run:

mvn clean install

As a result, the sources jar for this particular dependency is fetched. Generally, we don’t do this since it’ll unnecessarily pollute the POM. Hence, we usually prefer to use the capability of IDEs to attach the sources jar on-demand. Alternatively, we can also selectively fetch them via the mvn CLI command:

mvn dependency:sources -DincludeArtifactIds=maven-classifier-example-provider

In short, the key takeaway here is that the sources jar is referred to by using a sources classifier.

4. Using the Javadoc Classifier

In the same vein as the sources jar use case, we’ve Javadoc. It contains the documentation for the main jar artifact.

4.1. Generating Javadoc Artifact

Let’s use the maven-javadoc-plugin to generate the Javadoc artifact:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-javadoc-plugin</artifactId>
    <version>3.6.2</version>
    <executions>
        <execution>
            <id>attach-javadocs</id>
            <goals>
                <goal>jar</goal>
            </goals>
        </execution>
    </executions>
</plugin>

With the plugin defined, let’s run:

mvn clean install

As a result, the maven-classifier-example-provider-0.0.1-SNAPSHOT-javadoc.jar artifact is generated.

4.2. Consuming Javadoc Artifact

Let’s now download the generated Javadoc from a consumer perspective via mvn:

mvn dependency:resolve -Dclassifier=javadoc -DincludeArtifactIds=maven-classifier-example-provider

We can notice the -Dclassifier=javadoc option which specifies the classifier as javadoc.

5. Using the Tests Classifier

Now, let’s look at a different use case that a classifier can serve. There might be various reasons we may want to get the tests jar of a module. For one, there could be certain test stubs that we might want to reuse. Let’s see how we can get the tests to jar independent of the main jar artifact via a classifier.

5.1. Generating Tests Jar

Firstly, let’s generate the tests jar for the maven-classifier-example-provider module. In order to do that, we’ll use the Maven jar plugin by specifying test-jar goal:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-jar-plugin</artifactId>
    <version>3.3.0</version>
    <executions>
        <execution>
            <id>Test Jar</id>
            <goals>
                <goal>test-jar</goal>
            </goals>
        </execution>
    </executions>
</plugin>

Now, let’s run:

mvn clean install

As a result, the tests jar maven-classifier-example-provider-0.0.1-SNAPSHOT-tests.jar is generated and installed.

5.2. Consuming Tests Jar

And now, let’s get the tests jar dependency into our consumer module maven-classifier-example-consumer. We do this using the tests classifier:

<dependency>
    <groupId>com.baeldung</groupId>
    <artifactId>maven-classifier-example-provider</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <classifier>tests</classifier>
</dependency>

With that, we should be able to access the classes available in the test packages of maven-classifier-example-provider. 

6. Using Classifiers to Support Multiple Java Versions

Earlier, we had used an arbitrary classifier to build a second jar for our maven-classifier-example-provider module. Let’s now put that to more practical use.

Java is now releasing a newer version at a much faster cadence of 6 months. Consequently, it requires the module developers to be able to support multiple versions of Java. It might sound like a challenging task to build multiple jars for our modules compiled with different Java versions. That’s where the Maven classifier comes to the rescue. We can build multiple jars compiled with different Java versions using a single POM.

6.1. Compiling With Multiple Java Versions

Firstly, we’ll configure the Maven compiler plugin to generate compiled class files using both JDK 8 and JDK 11:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-compiler-plugin</artifactId>
    <version>3.12.1</version>
    <executions>
        <execution>
            <id>JDK 8</id>
            <phase>compile</phase>
            <goals>
                <goal>compile</goal>
            </goals>
            <configuration>
                <source>8</source>
                <target>8</target>
                <fork>true</fork>
            </configuration>
        </execution>
        <execution>
            <id>JDK 11</id>
            <phase>compile</phase>
            <goals>
                <goal>compile</goal>
            </goals>
            <configuration>
                <outputDirectory>${project.build.outputDirectory}_jdk11</outputDirectory>
                <executable>${jdk.11.executable.path}</executable>
                <source>8</source>
                <target>11</target>
                <fork>true</fork>
            </configuration>
        </execution>
    </executions>
</plugin>

We’re setting up two execution blocks, one for Java 8 and the other for Java 11.

Following this, we’ve configured the outputDirectory to be different for Java 11. On the other hand, Java 8 compilation will use the default outputDirectory.

Next comes the source and target Java version configuration. The source code is written using Java 8, so we keep the source version as 8 and modify the target version for Java 11 execution block as 11.

We’ve also explicitly provided the executable path for Java 11’s compiler javac. For Java 8, Maven will use the default javac configured on the system which in this case is Java 8’s javac:

mvn clean compile

As a result, two folders will be generated within the target folder – classes and classes_jdk11.

6.2. Generating Jar Artifacts for Multiple Java Versions

Secondly, we can proceed to package the module into two separate jars with the Maven jar plugin:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-jar-plugin</artifactId>
    <version>3.3.0</version>
    <executions>
        <execution>
            <id>default-package-jdk11</id>
            <phase>package</phase>
            <goals>
                <goal>jar</goal>
            </goals>
            <configuration>
                <classesDirectory>${project.build.outputDirectory}_jdk11</classesDirectory>
                <classifier>jdk11</classifier>
            </configuration>
        </execution>
    </executions>
</plugin>

We can notice that the classifier is set to jdk11.

Now, let’s run:

mvn clean install

As a result, two jars are generated – maven-classifier-example-provider-0.0.1-SNAPSHOT-jdk11.jar and maven-classifier-example-provider-0.0.1-SNAPSHOT.jar. The first one was compiled using the Java 11 compiler and the second using the Java 8 compiler.

6.3. Consuming Jar Artifact of a Specific Java Version

And finally, the consumers of our module can choose which jar artifact is relevant for them, based on the Java version they are using. Let’s see how we can use these jars from a consumer’s perspective.

If we’re working on a Java 8 project we wouldn’t have to do anything special. We’ll just add a vanilla dependency:

<dependency>
    <groupId>com.baeldung</groupId>
    <artifactId>maven-classifier-example-provider</artifactId>
    <version>0.0.1-SNAPSHOT</version>
</dependency>

However, if we’re working on a Java 11 project we’ve to explicitly ask for the jar compiled with Java 11 via a classifier:

<dependency>
    <groupId>com.baeldung</groupId>
    <artifactId>maven-classifier-example-provider</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <classifier>jdk11</classifier>
</dependency>

7. Artifact Classifier vs. Artifact Type

Before we conclude this article, let’s have a brief look at artifact type. While artifact type and classifier are closely related, they are not interchangeable. An artifact type defines the packing format of an artifact e.g. POM or jar. It also translates to the file extension in most cases. It may also have a corresponding classifier too.

In other words, the artifact type deals with the packing of the artifact and may use a classifier to modify the name of the artifact generated.

The two use cases that we saw earlier with the Java Sources and the Javadoc are examples of artifact types that use sources and javadoc as classifiers.

8. Conclusion

In this article, we saw how classifiers provide a way to generate multiple artifacts from a single POM file. Using a classifier, the consumers can pick and choose from the various artifacts of a particular module as needed.