Apache

Docs Dependencies and repositories

Make a dependency optional

Let your library use a dependency for one feature without passing it on to every project that uses the library.

Holds for
3.93.104.0
Kind
How-to guide
Source
Edit this page
Wrong?
Report a problem

Use this when you publish a library with a feature that needs another library, and most users of your library will not use that feature. A data access library that supports several databases needs every database driver to compile, but each user needs only the driver of their own database.

Mark the dependency optional

Set <optional> to true on the dependency in your library's POM:

pom.xml

<dependency>
  <groupId>org.postgresql</groupId>
  <artifactId>postgresql</artifactId>
  <version>42.7.14</version>
  <optional>true</optional>
</dependency>

For your library itself nothing changes: the dependency is on its compile, test and runtime classpath as before. The difference is for the projects that depend on your library. Maven does not pass an optional dependency on to them, and mvn dependency:tree in such a project shows your library without it.

Tell users what to add

A user who wants the feature declares the dependency in their own project:

pom.xml

<dependency>
  <groupId>org.postgresql</groupId>
  <artifactId>postgresql</artifactId>
  <version>42.7.14</version>
</dependency>

Nothing in Maven tells the user that this is needed; without it, the feature fails at runtime with a ClassNotFoundException or NoClassDefFoundError. Say in your library's documentation which optional dependency each feature needs, and which versions you tested with. Your code should check that the classes are present before it uses the feature, and report the missing dependency by name.

Consider a module instead

An optional dependency leaves the work to your users. If you can, split the feature into a module of its own that has the dependency as a normal one: mylib-core without the driver, and mylib-postgresql with it. A user then picks the module for their database and gets the right driver with it, in a version you chose. Split a project into modules shows how.

Optional or provided

Both keep the dependency out of the projects that use your library, for different reasons:

  • <optional>true</optional> says that your library works without the dependency, and that the user decides whether to add it.
  • <scope>provided</scope> says that the dependency is always needed, and that the environment the code runs in supplies it, such as a servlet container that supplies the Servlet API. A provided dependency is also left out of your own runtime classpath, and so out of a WAR you build.

Dependency scopes lists what each scope does.