If your plugin needs to be compatible with Maven 2.x, take a look at the sources of Maven Dependency Plugin. This example provides a sophisticated example of using the Maven 2.x dependency resolution API. But if legacy Maven support is of no concern to you, read on and see how the Maven 3.x API handles the job.

Aether Plugin Dependencies

To make use of the new Maven 3.x Plugin API add the following dependencies to your plugin project’s POM:

The dependency on maven-plugin-api shouldn’t be surprising – the more interesting bits are aether-api and aether-util. Depending on your use case, the latter dependency might not be required for your plugin given aether-util is just a collection of utility classes. For our example however, it will be handy to have org.sonatype.aether.util.artifact.DefaultArtifact around.

Mojo Parameters

Now that the plugin build path is set up, we can continue to add some parameters to our plugin that will grab the repository system:

In contrast to Maven 2.x, a single component of type RepositorySystem is sufficient for all resolution work. This repository system generally takes a request bean as input and hands back a result bean. When performing multiple repository operations, some inputs tend to be the same like the local repository, the offline mode, proxies etc. These configuration values are represented by the RepositorySystemSession.

The remote repositories to resolve from are always specific to a certain operation. For our example, we’re going to use the remote plugin repositories of the current project. Alternatively, the expression ${project.remoteProjectRepositories} is available to grab the project dependency repositories. Which set of remote repositories to use depends on the kind of artifacts the plugin is going to resolve. Artifacts that are compile/runtime/test dependencies of a project need to be resolved from ${project.remoteProjectRepositories}. Plugins or other artifacts that merely support the build need to be resolved from ${project.remotePluginRepositories}.

Mojo Execution

Equipped with the plugin parameters shown in the previous section, we can start to do some real work with project dependencies:

This code snippet resolves a single artifact that is hard-coded here for the sake of conciseness. By employing other methods of the repoSystem transitive resolution or version query can be performed as well.

Tip: To help with the common task of transitively resolving project dependencies, the maven-core artifact provides the component org.apache.maven.project.ProjectDependenciesResolver.

A complete plugin project ready to run and play with can be found in our Git repo at https://github.com/sonatype/aether-demo-maven-plugin.

A final note to avoid confusion when experimenting with the new API: Unlike the Maven 2.x API, Artifact instances in Aether are immutable. As such the result of a resolution operation returns new Artifact instances. That is why it is essential that the log statement above uses result.getArtifact().getFile() and not artifact.getFile().

The Sonatype newsletter helps you catch up on everything we’ve been up to, and read about upcoming projects, releases and presentations from the Sonatype team.

If you want to get updates from the Sonatype team the moment news breaks and cannot wait until the next newsletter, subscribe to this Twitter feed:

• http://twitter.com/SonatypeCM

If  you would like to get on our mailing list, you can subscribe here.

Can you give us an introduction to Aether?

Aether is a library for interacting with artifact repositories. This involves the specification of local repository formats, remote repository formats, workspaces, transports, and artifact resolution. People are generally familiar with repositories whether they be local or remote. Workspaces are additional sources where artifacts can be resolved from. Workspaces can be used in IDEs to provide resolution of projects you are working on, in shells like the Maven Shell or Roo, or any other long-lived process where a developer needs to resolve against in-development projects. I think people are familiar with various transports but HTTP is by far the dominant transport used with artifact repositories, but Aether lets you define additional ones if you need to. Along with all the rules to resolve artifacts taking into consideration any transformations, relocations, and conflict resolution strategies you might need to employ. We also plan to allow Aether to define version schemes, but the first work was just started on this by Alin Dreghiciu.

It is very important to note that Aether has no dependencies on Maven. When I said Aether is a library for interacting with artifact repositories, I didn’t mean Maven artifact repositories. Aether is a general purpose library for interacting with artifact repositories. If you wanted to specify your dependency metadata in a properties files Aether will let you do that. If you want to store your artifacts in a database Aether will let you do that. But, of course, we needed Aether to work for Maven so we created an implementation of what we call an ArtifactDescriptorReader to process Maven POMs. That implementation lives in the Maven codebase and that’s how we make Aether work for Maven.

Why is interoperability at the repository level, so important for Maven projects?

It’s more a question of interoperability between tools that interact with Maven repositories. Maven projects interoperate because they all use Maven. What we want to ensure is that projects building with SBT, Leinigen, Gradle, Buildr, Ant, or a homegrown system interoperate reliably with Maven repositories. Maven repositories are the defacto standard storehouses of JVM components. If a project that builds with Gradle can’t interoperate with a project built with Maven on the same machine because the local repository format that Ivy produces is not compatible then we see that as highly problematic. We want to prevent these problems, and we know that people creating these build tools would prefer to use as neutral a library as possible. Of course, to interoperate with Maven repositories integrators will require the ArtifactDescriptorReader to process POMs from remote repositories but they can create their own format for describing their dependency metadata.

At the project announcement, it is stated that “if compatibility with Maven repositories is important for your project then it’s not going to get any better than Aether.” Why is this?

If a project is using the Aether implementations that Maven itself is using then they are guaranteed to have the same behavior Maven does for resolving artifacts. If SBT is using the exact same code as Maven to read and process POMs, and the same local repository implementation then the level of interoperability is pretty much guaranteed. All the various tools may want to express their dependencies in their own particular way, but it would be bad if they interpreted POMs differently, did conflict resolution differently, or deployed artifact metadata incorrectly. These types of problems just wreak havoc for the average user trying to use artifacts from Maven repositories.

What is Aether’s relationship to Mercury and SAT4J library?

Mercury was our previous attempt at a library like Aether. We learned many things from Mercury, but it was a failed attempt because we tried to do too much at once. We tried to completely separate the resolution code from Maven, and introduce SAT4J at the same time. This proved to be a fatal mistake, but we have learned from our mistakes. Since Mercury we’ve brought Pascal Rapicault, the lead of the Eclipse p2 project, to the Sonatype team. Pascal is very familiar with SAT4J, but more importantly Pascal has a very good working relationship with Daniel Le Berre, who is the author of the SAT4J library. In talking with Pascal about our goals for Aether we concluded that we should design Aether to eventually allow a collaboration with SAT4J but not use it in our first pass. Our primary goal was to create a general purpose library that could be used in any tool including Maven. It’s also going to take more research and experimentation to understand exactly how we will integrate SAT4J. It’s not a question of if we will integrate SAT4J, it’s a question of when.

What is the current status of Aether Ant Tasks?

The Aether Ant Tasks are functional. They currently do the basic resolving, installing, and deploying. But there are some clarifications that we want to make in the syntax before we make an official release. The Aether Ant Tasks can be found in their own branch at Github. For those interested in discussing what the syntax should look like for the Aether Ant Tasks we encourage you to subscribe to the Aether development list. One short term goal with the Aether Ant Tasks is to provide a complete Ant-based solution for submitting artifacts to Maven Central.

We also intend to demonstrate how to make submissions to Maven Central programmatically using Aether so integrators can participate as freely in the exchange of JVM artifacts as Maven projects do now.

Aether (pronounced ē’thər, as in flying though the ether) aims to be the standard library for interacting with Maven repositories. Without question, the most important aspect of the Maven ecosystem is interoperability at the repository level. There are many emerging options in the build space for JVM-based languages, but the one thing they all have in common is their interaction with Maven repositories. It’s clear that Maven repositories play a critical role within JVM-based development infrastructures and Aether will provide the necessary interoperability, through a common set of tools and APIs, that’s critical for happy users in the ecosystem.

Aether & Maven 3.x

Benjamin Bentmann, Sonatype’s lead on Maven 3.x, has fully integrated Aether back into Maven 3.x. Though Aether is an extraction from Maven, Aether is not Maven specific. That said Maven 3.x and Maven repositories are our first priorities. The upshot is that if you embed Aether, you will be embedding the same library that Maven 3.x uses when it interacts with a Maven repository. If compatibility with Maven repositories is important for your project then it’s not going to get any better than Aether.

Aether & Mercury

Mercury was our first attempt at extracting a Repository API from Maven and that didn’t work. We bit off more then we could chew, and so our first attempt was a learning experience. We attempted to integrate the excellent SAT4J library but didn’t have enough experience to pull that off. In addition there may be features of SAT4J Maven requires that are not present yet. As such, we felt it better to attempt something less ambitious, yet functional, and invest in research for future improvements.

Aether, p2 & SAT4J

As part that investment, we will be collaborating in sponsored research with Daniel Le Berre, who is the author of SAT4J. Daniel is a tenured professor at University of Lens, and researcher at Centre de Recherche en Informatique de Lens and is affiliated with Centre National de la Recherche Scientifique. His work will not only help us with p2, but also with many things we want to accomplish in Maven. We see a lot of overlap in the work Sonatype is doing on Maven and p2 and ultimately we really see there being one artifact resolving framework.

Aether & Ant

Rest assured there will be excellent Aether Ant Tasks. Making sure that Aether works flawlessly inside Maven 3.x is our first priority, but we are committed to making a set of excellent Aether Ant Tasks. If you’re interested in Aether Ant Tasks you can follow the progress here.

Aether Resources

If you are interested in Aether here are the goods:

• Aether Sources @ Github
• Aether Issue Tracking @ Sonatype
• Aether Wiki @ Sonatype
• Mailing lists:
  • Aether Users @ sonatype.org
  • Aether Developers @ sonatype.org
  • Aether SCM @ sonatype.org

P.S. Thanks to Pierre-A Grégoire for the name Aether!