For a list of changes in Edition 2.0, please see the release notes for this edition in the Nexus book.

• Read the Book for FREE online,
• Download the Nexus Book PDF, or
• Read the Book on Scribd

Special thanks to John Yeary and Anders Hammar for providing essential feedback and for identifying typos and errors.

Repository Management with Sonatype Nexus

Maven 3.0

With Maven 3.x we have made our best attempt to listen to users, find out what they need and want, and make reasonable preparations and plans to fix the problems, implement useful features, and create the integration points for working properly with third-party systems like Nexus and Hudson. While there have been many new feature requests — and we have many new features done or in the works — the number one concern is backward compatibility. Maven 3.x makes an ardent attempt to be 100% backward-compatible with Maven 2.x. All your Maven 2.x builds should work out of the box using 3.x without change to your projects. We simply can’t cause pain to the existing user base. We are very cognizant that even small changes can have a huge impact and so we have tried achieve complete Maven 2.x fidelity with Maven 3.x.

In Maven 3.x we have reduced the number of modules, we have simplified and extracted the artifact resolution system, we have put a performance framework in place, and we have created an enormous set of integration tests for Maven’s core and for many of the core plugins. We are constantly trying to validate core features and core plugins are working properly. We hope with the simplifications that we have made that more people will get involved in the project. We have done some heavy overhauling of many of the internals to make way for future features and I believe Maven 3.x is really the only path forward for Maven. What’s the technique we used to decide on how to plan and work toward the completion of Maven 3.x? A very practical approach to determining an optimal path called desire lines.

Desire Lines

A desire line usually represents the shortest or most easily navigated route between an origin and destination. The width and amount of erosion of the line represents the amount of demand. The term was coined by Gaston Bachelard in his book The Poetics of Space. Desire lines can usually be found as shortcuts where constructed pathways take a circuitous route. A concrete example: the pathways around the Berkeley campus in California. During the early years of Berkeley no pathways were paved. Instead they let inhabitants walk in optimal paths between the buildings and location over a period time to form clear pathways over the grass. Once these pathways had been established they could be paved to make the pathway more permanent. This is very similar to what happened with Maven 2.x. Consider Maven 2.x the pathways marked in the grass. Consider Maven 3.x taking all that learning from Maven 2.x and adopting the optimal form of use and codifying those forms of use i.e. paving the desire lines.

Over the course of hundreds of thousands of people using Maven we have a very good idea of what these optimal pathways look like now. Here are a few examples of some of the things we’ve seen and the things we have to do in order to make these lasting improvements.

Responding to invitations for improvement

There are many things in Maven 2.x that work reasonably well but have some minor flaws which cause irritation:

• Dependency management. How to effectively manage what we will call a target platform (intentionally using the Eclipse nomenclature). It is easy to manage the versions of an applications runtime or its target platform. But what happens when you start pulling in multiple, separately developed target platforms.
• Version specifications and version ranges. Maven’s notion of this is workable, but when it comes to the version specification and ranges it’s time to just defer to OSGi in this regard. What OSGi specifies and what Maven specifies are not wildly different but different enough to cause some problems. We’ll be working on aligning Maven to the version specification of OSGi.
• The way plugins interact with embedded environments was just wrong. We allowed for no support for incremental changes. The result is that in M2Eclipse when you change an individual resource, that individual resource can be processed efficiently and not fire up all of Maven to run the whole build lifecycle. Sorry, but you won’t have time to get a coffee anymore.
• There are slew more, but we’ll save those for other blog entries.

Responding to … being completely wrong

There are some things in Maven 2.x we just didn’t get right and we have to make reparations:

• Composition versus inheritance in the POM. There are some great debugged toolchains like we have in the Apache Organization POM for releasing, but this toolchain is not easily consumable by outside projects because it makes no sense to inherit from the Apache Organization POM for your projects. So how can we make these chunks of debugged combinations of plugins and their associated configuration? We will introduce mixins to help with this. Essentially it will be a POM consisting of plugins and configurations that can be externally parameterized. These mixins will be deployed to a repository and be referenced with a standard coordinate. Basically it will be an intelligent import with validation which will allow composition in your POMs.
• Checking out the whole source tree versus an individual module and parent element versioning. We have always intentionally made projects specify versions in the parent elements. When you check out individual modules this is necessary. But for projects where the whole source tree is checked out, the version of the parent can be inferred and the requirement for specifying the version element in the parent can be removed.
• Clean separation of operations that need to happen at the beginning and end of the lifecycle versus in the lifecycle itself. To make the OSGi integration we created work we needed to get at the projects before the build lifecycle was executed so we added a clear hook before lifecycle execution. What we have done to make OSGi integration work in Maven 3.x is simply not possible in Maven 2.x. We also had a terrible problem with reporting and aggregation because there was no clear point at which the lifecycle was over. Now once the build lifecycle is complete there is a clear hook to get the projects in the reactor so they can be processed easily. Accurate aggregation is now possible.

• Again, there are slew more, but we’ll also save those for other blog entries.

Responding to under-utilization of what exists

Unfortunately there are still a lot of powerful features and plugins in Maven that a lot of people don’t know about. We have tried to remedy this situation with the four books that we constantly update stream, and a stream of blog posts, and the soon to be enterprise Maven users list which will focus on the holistic and systematic use of Maven, M2Eclipse, Nexus and Hudson. We need to do a better job explaining end-to-end best practices for developing, testing, and provisioning software. We also need to do a better job describing some of the incredibly useful plugins we have like the enforcer plugin and the dependency plugin.

But again, our best attempt to show people what is available through the four books that we have:

• Maven: The Definitive Guide
• Repository Management with Nexus
• Developing with Eclipse and Maven
• The Maven Handbook

Here is a picture I always use to illustrate the point that even though something may be sitting directly in front of you, it’s not always immediately obvious unless someone points it out to you. Th is is very much the case where we see users asking us for help with particular use cases and in frequently it’s very easy to answer the question by pointing to a URL. My example is the Fedex logo which was designed to have an arrow being formed between the last two letters of the logo. Quite ingenious but most people I point this out to haven’t notice it.

We are going to try a lot harder to make sure the value that exists is easier to find. I don’t enjoy reading blog posts from unhappy users at all, but I especially don’t like it when I know there is a solution which has been documented somewhere. Those painful situations can be reduced if not eliminated completely.

Backward Compatibility

I can’t stress enough how important backward compatibility is to us. We have done a non-trivial amount of work to pave the way for new capabilities in Maven 3.x while preserving 100% backward compatibility for:

• Maven itself and the behaviour that users expect from the CLI
• Artifact Resolution API
• Plugin API
• Plugin configuration
• Site generation (even though we’ve extracted site/reporting entirely into the maven-site-plugin)

We must ensure that plugins and reports written against the Maven 2.0.x APIs remain viable in 3.0. We don’t want people rewriting their plugins or having to change their projects at all or it will simply be chaos. We simply have too many users and requiring changes will have an enormous human cost so we’ve been slow in announcing Maven 3.x. The version of Maven 3.x you can pull from the Sonatype grid is probably the best version of Maven that has existed but we are still being careful about releasing it. If you want to try it you can find it here.

We must also ensure that POMs of version 4.0.0 are supported in 3.x along with the behavior currently experienced. We will need to make changes to the POM in order to introduce many of the new features so we’ve made the requisite preparation. We are relying heavily on our integrations tests right now but as we move forward the work that Benjamin is doing on the project/model-builder will help us to accommodate different versions of a POM, and different formats we decide to support. The model-builder code has no limitation with respect to formats. We can support XML, or any source that anyone can dream up. These implementations may find use outside of Maven. For example someone might build something with the Maven, JRuby, and Mercury to create a JRuby-based system. The same could be done for Groovy. We already have some examples of this with the Polyglot Maven project we’ve started which will be the topic of a subsequent post.

We have managed to keep almost everything backward compatible and we will go so far as to provide an isolated execution environment that can contain older versions of the plugin API so that everything from the past can continue to work in Maven 3.x. We will not truly be able to do this until we change the internal Maven runtime over to OSGi but we know what needs to be done.

Integration Testing

An enormous amount of time and energy has gone into improving the the integration tests for Maven. The integration tests are the gatekeeper and let us determine that we have a Maven 3.x that is compatible for Maven 2.x. We now have 506 integration tests that will help protect us as we move forward. We will likely approach 600 integration tests by the time we reach the Maven 3.0 GA.

All core Maven plugins now have ITs and we have started branching out into the Mojo project to create plugin ITs there as well. We have a good pattern so we are encouraging anyone writing a Maven plugin to create ITs so that we can help ensure we don’t break people in the future. We have really taken fixing the problems we see seriously. I couldn’t help but make a little spoof of the SNL skit and adapting it for the Maven perspective.

In the next post I will start talking about some of the technical changes we have made to Maven 3.x in order to achieve our goals. Those will include:

• Refactored model/project builder (the support Polyglot Maven uses)
• Queryable lifecycle
• Lifecycle Extension points
• Error and integrity reporting
• Mercury: Jetty Client & SAT4J
• Embedding
• Incremental build support (used heavily in M2Eclipse for performance improvements, these are changes to the plugin API)

I plan to try and write something about Maven 3.x frequently in preparation for the Maven 3.x talks in Stockholm, Dusseldorf, Cologne, and Devoxx.

Stay tuned!

• Proxy Repository Browsing – With Nexus 1.4, the local cache and logical index views have been separated into separate tabs. We found that the previous single tab with a combo box to select the source was confusing.
• Publishing Web Sites to Nexus Professional – Nexus Professional 1.4 provides you with a WebDAV endpoint for publishing a web site. You can configure a Site repository that can be used as a publishing destination for project documentation. This means you don’t have to worry about providing some alternate solution to host your reports. The full support of Nexus security applies to this new type of repository, so you can control access at a very fine grained level.
• Repository Configuration Changes
  • Fine-grained control of Redeployment for Hosted Repositories: Nexus 1.4 provides administrators a simplied way to control how a hosted repository deals with the redeployment of artifacts. You can configure a repository to allow for the redeployment of previously deployed artifacts, allow for one-time deployment, or to provide a read-only interface for clients.
• Improvements to the Staging Plugin – The staging plugin had numerous improvements in the 1.4 release to increase usability and provide new functions for staging artifact bundle and verifying that staging repositories follow user configurable rule sets.
  • Support for Staging Rulesets: Nexus Professional 1.4 provides administrators with the ability to define a set of rules to apply to staging repositories before they can be promoted. The 1.4 release can validate that staging repositories contain valid POMs, valid PGP signatures, javadocs, and sources for all artifacts. The rules are pluggable and we expect to add more rules in the near future to support the Apache repository and our OSS hosting repository
  • Support for Uploading Artifact Bundles: The staging plugin now accepts artifact bundle uploads. Artifact bundles are archives which contain one or more associated artifacts, they are used to publish artifacts to the Central Maven repository, and you can use Artifact bundles to validate artifacts uploaded to Nexus.
  • General Usability Improvements in the Staging Plugin: This release of the Staging plugin focused on usability, the Staging plugin is full of improvements that make the user interface more intuitive and easier to use.
• User Account Plugin – The User Account Plugin in Nexus Professional gives unauthenticated Nexus users the ability to sign-up for a Nexus account. When this feature is enabled, a new user would click a sign-up link, fill out a simple profile form, read a captcha, and then activate a new account via an email confirmation message. Nexus Administrators can configure the default roles and permissions that are granted to newly signed up users.
• Repository Summary Panel – The repository summary panel provides statistics and configuration information for a specific repository. Users can consult the repository summary panel to gather the necessary distribution management settings for Maven configuration.
• Security Improvements – Many improvements to the user security model. In general, it is now easier to configure custom role mappings for externally managed users, and Sonatype has paid close attention to the user interface for managing users and roles. It is easier than ever to configure and secure a Nexus repository.
  • New User Role Tree: Click on a user and then click on the user role tree to see how each role contributes to the permissions for a particular user.
  • New User Privilege Trace feature: this features allows Nexus administrators to pinpoint which roles contribute which permissions to a particular user. While the user role tree provides an intuitive interface that lists role in a hierarchy, the privilege trace panel under user administration provides an alternate view. Click on a particular permission to find the roles contribute that permission to a user.
  • New Role Tree: Since a Nexus role can consist of both roles and privileges, we’ve provided an intuitive tree browser that allows an administrator to browse the hierarchy of roles and privileges associated with a Nexus Role.
  • Fine-grained control of View Repository Privilege: Nexus added the ability to configure a role to prevent users from browsing particular repositories. This is used to provide a cleaner view to users, for example to show them only groups they use via Maven and not confuse them with all the repositories aggregated by that group.
• Integration with Atlassian Crowd – Atlassian Crowd is a capable user and directory management system that can consolidate authorization and authentication to a central server. Nexus Professional’s Atlassian Crowd plugin provides seamless integration between Nexus and Atlassian’s Crowd server.
• Automated Nexus Error Reporting – Nexus 1.4 ships with an automated error repository system which can be configured to report Nexus exceptions and errors to the Nexus Issue Tracker. If configured, the system will send data to Sonatype’s Jira instance. The information contained includes the configuration (all passwords are obfuscated) as well as a file list of the repositories and exception traces. All of this data is encrypted using public-key cryptography so only Sonatype can view the contents. We expect that this information will allow us to further refine the stability of Nexus.
• Upgrades to the Nexus Book
  • A new chapter on Nexus Best Practices.
  • A new chapter on publishing web sites to Nexus.
  • Over 100 corrections and clarifications.
  • Over 80 new figures and diagrams.
  • Addition of a New Nexus Book Cover with the Nexus Logo
  

What is a Repository Manager?

• A proxy for remote repositories which caches artifacts saving both bandwidth and time required to retrieve a software artifact from a remote repository, and
• A host for internal artifacts providing an organization with a deployment target for software artifacts.

In addition to these two core features, a repository manager also allows you to manage binary software artifacts through the software development, quality assurance, and production release lifecycle. In addition to these core features, a repository manager can search software artifacts, audit development and release transactions, and integrate with external security systems such as LDAP. A repository manager is a powerful tool that encourages collaboration and provides visibility into the workflow which surrounds binary software artifacts.

A richer, more detailed description of the features of a repository manager include:

Management of Software Artifacts

A repository manager is able to manage packaged binary software artifacts. In Java development, this would include JARs containing bytecode, source, or javadoc. In other environments, such as Flex, this would include any SWCs or SWFs generated by a Flex build.

Management of Software Metadata

A repository manager should have some knowledge of the metadata which describes artifacts. In a Maven repository this would include project coordinates (groupId, artifactId, version, classifier) and information about a given artifact’s releases.

Proxying of External Repositories

Proxying an external repository yields more stable builds as the artifacts used in a build can be served to clients from the repository manager’s cache even if the external repository becomes unavailable. Proxying also saves bandwidth and time as checking for the presence of an artifact on a local network is often orders of magnitude faster than querying a heavily loaded public repository. Proxying an external repository such as the Central Maven repository is also an act of good citizenship; reducing the bandwidth burden on Central helps to preserve a valuable public resource.

Deployment to Hosted Repositories

Organizations which deploy internal snapshots and releases to hosted repositories have an easier time distributing software artifacts across different teams and departments. When a department or development group deploys artifacts to a hosted repository, other departments and development groups can develop systems in parallel, relying upon dependencies served from both release and snapshot repositories. Finding an efficient way to distribute the binary software artifacts during the development cycle is essential for an organization that needs to scale system complexity and number of developers. Once you start using Nexus as a sharing mechanism across development teams, each team can then focus on smaller, more manageable systems. The web application team can focus on the code that directly supports the web application while it depends on the binary software artifacts from a team managing an Enterprise Service Bus.

Searching an Index of Artifacts

When you collect software artifacts and metadata in a repository manager, you gain the ability to create indexes and allow users and systems to search for artifacts. With a Nexus index, an IDE such as Eclipse has almost instantaneous access to the contents of all proxy repositories (including the Central repository) as well as access to your own internal and 3rd party artifacts. If a user needs to search for a particular artifact, they can use the built-in auto-completion capabilities of Eclipse, and the IDE will perform a query against an index of the repository. If you need to update a library to the latest version, click on the POM editor and use the auto-complete feature in m2eclipse. If you need to search for all artifacts which contain a specific class name, you can use m2eclipse to search an index of Maven repository artifacts by class name. While the Central repository transformed the way that software is distributed, the Nexus index format brings the power of search to massive libraries of software artifacts.

Infrastructure for Artifact Management

A repository manager should also provide the appropriate infrastructure for managing software artifacts and a solid API for extension. In Nexus, Sonatype has provided a plugin API which allows developers to customize both the behavior and functionality of the tool. Here are just some of the features which are available as Nexus Plugins in Nexus Professional: Release Audits and Compliance, Support for Workflow and Process, Integration with External Security Providers.

Enterprise Repository Management

Once you adopt the core features of a repository manager, you start to view a product like Nexus Open Source or Nexus Professional as a tool which enables more efficient collaboration between development groups. Nexus Professional builds upon the foundations of a repository manager and adds capabilities such as Procurement and Staging.

Managing Project Dependencies

Many organizations require some level of oversight over the open source libraries and external artifacts that are let into an organization’s development cycle. An organization could have specific legal or regulatory constraints which require every dependency to be subjected to a rigorous legal or security audit before it is integrated into a development environment. Another organization might have an architecture group which needs to make sure that a large set of developers only have access to a well-defined list of dependencies or specific versions of dependencies. Using the Procurement features of Nexus Professional, managers and architecture groups have the ability to allow and deny specific artifacts from external repositories.

Managing a Software Release

Nexus Professional adds some essential workflow to the process of staging software to a release repository. Using Nexus Professional, developers can deploy to a staging directory which can trigger a message to a Release Manager or to someone responsible for QA. Quality assurance (or a development manager) can then test and certify a release having the option to promote a release to the release repository or to discard a release if it didn’t meet release standards. Nexus Professional’s staging features allow managers to specify which personnel are allowed to certify that a release can be promoted to a release repository giving an organization more control over what software artifacts are released and who can release them.

Integration with LDAP

Nexus Professional integrates with an LDAP directory, allowing an organization to connect Nexus to an existing directory of users and groups. Nexus authenticates users against an LDAP server and provides several mechanisms for mapping existing LDAP groups to Nexus roles.

Advanced Security

Using Nexus Professional, an organization can define a master User Password Encryption Key. Each user will be given a separate Maven settings file with an encrypted password using the Maven Nexus plugin. When users interact with Nexus, Nexus uses the User Password Encryption Key to decrypt a user’s Nexus credentials avoiding the need to send an easily compromised plain-text password over the network.

Settings Templates

Nexus Professional allows you to define Maven settings templates for developers. Developers can then automatically receive updates to Maven settings (~/.m2/settings.xml) using the Maven Nexus plugin. The ability to define Maven settings templates and to distribute customized Maven settings files to developers makes it easy for an organization to change global profiles or repository configuration without relying on developers to manually install a new settings file in a development environment.

p2 Repository Support

Nexus Professional supports the p2 repository format used by the new Eclipse provisioning platform. You can use the p2 plugin to consolidate, provision, and control the plugins that are being used in an Eclipse IDE. Using Nexus procurement, repository groups, and proxy repositories to consolidate multiple plugin repositories, an organization can use Nexus Professional to standardize the configuration of Eclipse IDE development environments.

For more Information about Sonatype Nexus: http://www.sonatype.com/products/nexus

To download your free trial of Nexus Professional: http://www.sonatype.com/products/downloads

• Modifier SNAPSHOT is a modifier for a “base” version. If you specify 1.0-SNAPSHOT, this translates to “give me the latest development version for the base 1.0″. The assumption behind the SNAPSHOT modifier is that developers are continuously pumping out version after version in order to get to 1.0. A development team is constantly and repeatedly deploying snapshot into repositories, and others can use them without requesting the exact version.
• Version name LATEST. This is used without a base version and simply means – find and give me the latest possible version of an artifact be it a SNAPSHOT or a RELEASE.
• Version name RELEASE . Same as LATEST, but excludes any SNAPSHOT dependencies.

The last two are true virtual versions as there is no POM with such version set. In Maven 2, virtual versions are only used by plugin dependencies, Mercury treats them as first class citizens and can process virtual versions anywhere in artifact metadata (with the exception of version range definitions).

SNAPSHOT is a much more convoluted virtual version, and there are a lot of problems and contradictions involved in the resolution of SNAPSHOT dependencies:

The local repository could house both timestamped snapshot binaries and -SNAPSHOT binaries, like mercury-artifact-1.0-alpha-6-20090305.234653-4.jar and mercury-artifact-1.0-alpha-6-SNAPSHOT.jar. Let’s call them timestamped snapshots (TS) and non-timestamped snapshots (SN) respectively . While the install plugin does create non-timestamped (SN) binaries, the deploy plugin only creates timestamped snapshots (TS) binaries in the remote repopository. Remote repositories usually contain only timestamped (TS) snapshots, but I saw several cases where people copied the contents of a local repository to a server and hoped to use it as a remote repository.

The file’s last modification date on timestamped snapshot (TS ) could be before or after the non-timestamped snapshot (SN), if one exists. And it’s hard to select a correct version based on either name or modification date.

All these different options prevent consistent processing of virtual versions by repository management code. While LATEST and RELEASE are more or less well defined and allow formal processing, SNAPSHOT leaves a lot to wish for. The above listed scenario’s don’t allow a consistent treatment of snapshots. Take for example Mercury – if it uses a select non-timestamped (SN) artifacts if they exist strategy, there is a good chance that the non-timestamped artifact isn’t as recent as the timestamped artifact – leading to possible compilation errors. On the other hand, if Mercury tries to avoid this situation by looking at file timestamps, one bad file date could wreak havoc.

To summarize – there is no “right” solution, as each approach could be broken easily by primitive and often inevitable repository modifications. By removing these literal “SNAPSHOT” files and requiring all snapshots to be timestamped, we can make the SNAPSHOT virtual version as consistent and reliable as the RELEASE and LATEST virtual version. Mercury, tries to be as backward-compatible as possible, recreating the already established algorithm for resolving SNAPSHOT dependencies.

The real solution, the way to fix this mess, is to get rid of literal “SNAPSHOT” files in the repository altogether.

Please check this posting first. It contains the latest information on the subject.

<br/> <br/>

What exactly is provided:

• Configuration
  • named authentication elements to be used by repository or proxy authentication
  • supports both name/password or certificate pointer (file or URL) plus optional password
  • named repository configurations
  • local repositories (not limited to one)
  • remote repositories
  • stream verification per repository – separate for reading and writing
  • currently supported SHA-1 and PGP (.asc)
• named dependency sets
  • lists dependencies and optionally – their Maven scopes
  • standardized on a one-string naming convention
  • supports OSGi-syntax version ranges
• ant path creation/alteration
  • a task that either creates a new ant path or adds to existing one
  • optionally allows to specify Maven-like scope for the path resolution
• repository writes
  • allows to write named files into repositories
  • optional classifiers, types
  • signature generation is configured per repository
  • SHA1, PGP

Where to get mercury-ant-tasks?

All the development releases will be deployed to this site; grab the latest snapshot and:

• put it into ${user.home}/.ant/lib
• if you plan to use PGP signatures – also put there bcpg-jdk15-140.jar and bcprov-jdk15-140.jar from this central repository location
• if interested – my test build.xml contains all the unit test scripts

mercury-ant-tasks howto-by-example

This snippet shows how to define mercury namespace in the ant project markup

<project name="mercury-ant-test" default="compile"
xmlns:merc="antlib:org.apache.maven.mercury.ant.tasks" > ... </project>

This snippet shows how to define two repositories – one remote, one local. You don’t have to always define a local repository, but in this case binaries would reside in temp. location and will be reloaded from the remote on each invocation of the merc:resolve task

<merc:config id="conf">
  <merc:repo id="localRepo" dir="/maven.repo"/>
  <merc:repo id="central" url="http://repo1.maven.org/maven2"/>
</merc:config>

This snippet shows how to define authenticated repository and hide the password in the external file, so that each OS user can have their own credentials

<property file="~/.secret/secret.properties"/>
 
<merc:config id="conf">
  <merc:auth id="repo-auth" name="${repo.user}" pass="${repo.pass}"/>
  <merc:repo id="localRepo" dir="/maven.repo"/>
  <merc:repo id="central" url="http://repo1.maven.org/maven2"
             authid="repo-auth"/>
</merc:config>

This snippet shows how to configure a repository for PGP signature generation and checking; here secret keyring password is also kept in external file. Key ID always is a 16-digit hex number – use GnuPG GUI to look it up (and also generate/manipulate your keys). The verifier will accept any key from pubring.gpg for the signature

<property file="~/.secret/secret.properties"/>
 
<merc:config id="conf">
 
  <merc:auth id="repo-auth" name="${repo.user}" pass="${repo.pass}"/>
 
  <merc:repo id="localRepo" dir="/maven.repo"/>
 
  <merc:repo id="central" url="http://repo1.maven.org/maven2"
                    authid="repo-auth">
 
    <merc:verifywrite type="pgp">
      <property name="keyring" value="/home/me/pgp/secring.gpg"/>
      <property name="pass" value="${secret.keyring.pass}"/>
      <property name="key" value="0EDB5D91141BC4F2"/>
    </merc:verifywrite>
 
    <merc:verifyread type="pgp">
      <property name="keyring" value="/home/me/pgp/pubring.gpg"/>
    </merc:verifyread>
 
  </merc:repo>
 
</merc:config>

This snippet shows how to define authenticated repository and hide the password in the external file, so that each OS user can have their own credentials

<property file="~/.secret/secret.properties"/>
<merc:config id="conf">
  <merc:auth id="repo-auth" name="${repo.user}" pass="${repo.pass}"/>
  <merc:repo id="localRepo" dir="/maven.repo"/>
  <merc:repo id="central" url="http://repo1.maven.org/maven2"
                    authid="repo-auth"/>
</merc:config>

This snippet shows how to define a dependency set. Junit will only be added to paths that define scope=”test”

<merc:dep id="my-libs">
  <merc:dependency name="asm:asm:[2.0,3.0)"/>
  <merc:dependency name="junit:junit:[4.0.1,):::test"/>
  </merc:dep>

This snippet shows how to resolve a dependency set and add the resulting binaries to “compile-path” path. This path will not include JUnit from previous snippet

<merc:resolve pathid="compile-path" depid="my-libs" configid="conf" />
<javac srcdir="${src}" destdir="${target}" classpathref="compile-path" />

This snippet shows how to resolve a dependency set in test scope and add the resulting binaries to “test-compile-path” path. This path will have JUnit

<merc:resolve pathid="test-compile-path"
                      depid="my-libs"
                      configid="conf"
                      scope="test"
/>

This snippet shows how to write a jar file and it’s sources to a repository

<merc:write repoid="remoteRepo"
                   name="t:t:1.0"
                   file="${basedir}/target/t.jar"
/>
<merc:write repoid="remoteRepo"
                   name="t:t:1.0:sources"
                   file="${basedir}/target/t-src.jar"
/>

mercury-ant-tasks reference

Now, let’s have a closer look at ant mercury markup. To make it available to ant, provide a namespace definition on the project level, for example: <project name="test" default="compile" xmlns:merc="antlib:org.apache.maven.mercury.ant.tasks">

Everywhere here I mention named – named configuration, named set. It means named in ant sense: something that has an id attribute value, and then we can reference that particular object (configuration, set, etc) by this value.

• Decouple major Maven components, making them available as stand-alone building blocks rather then having Maven as as one big monolith, not usable outside of its environment.
• Artifact – clearly separate an Artifact from its metadata.
• Repository – convert a repository into active component. It used to give back just pathOf(), now it accepts GAV collections and gives back either metadata or full blown Artifacts.
• Transport – an API in development.
• DependencyTreeBuilder main API for dependency graph creation and conflict resolution.
• Decouple container, so that these components are just plain pojos.
• Introduce Jetty-based HTTP/HTTPS and WebDAV transactional transport layer.
• Asynchronous downloads and uploads. One of the few successful usages of Java NIO in OSS.
• Transactional operations – all-or-nothing for file sets.
• Move integrity control into transport layer, upper level components should not care about these details.
• Abstract out metadata cache, provide at least one implementation there.
• Integrate these changes back to Maven 3.x to make it even better platform than it is right now (if it is possible to be better )

Currently Mercury can already be used for accessing repositories, and conflict resolution is under testing.

All that, plus the necessity to provide tool integration, led to the idea to introduce an event framework into Mercury. All major processing object implement EventGenerator interface, that allows client code to register MercuryEventListener implementations and unRegister them as well.

MercuryEvent in itself has

• local TZ based start timestamp
• long duration in millis
• enumeration based type, which is also used for event partitioning
• name – obviously to identify this event
• tag to record lightweight information about event
• result to record the outcome of the event
• Map based payload – for tool integration to get access to typed objects, event wants to carry to the tool

Client code has several options to play with:

• event listener can declare a BitSet based mask of event types it wants to be notified about
• event manager could be configured with a mask of event types it will propagate
• there is a system property to define which event types should be propagated by the event manager, if one is created by the client code

The event manager itself separates event dispatching from event generator code via a thread pool, so that events are only placed into an event queue in the event generator thread, and then are sent out to listeners in parallel to the main code.

There is also a DumbListener, implemented to just peek at the events – prints them out to system.out or any other output stream.