See what components are used, which versions, and when updates are available

We want to make component based development as easy as possible by providing you the tools to choose the right components from the beginning to speed development, improve quality, and reduce costly rework. This plugin, the first of a series of development tools, helps you tame the issues typically associated with utilizing open source Java components, including:

• Determining when new component versions are available and making informed update decisions
• Understanding what versions of each component are used in your project
• Identifying where specific components are used
• Updating components throughout your project

The plugin is build tool agnostic, and so works with all Java projects in general (Java, PDE, Maven, etc.).

This is just the beginning. We’ll be adding features to help you choose components that meet your security, quality, and licensing standards by providing useful information about each component right in the IDE.  For example, we’ll alert you when a component, or one of its dependencies has known security vulnerabilities. You’ll also be able to tell how each component or dependency is licensed without having to hunt through the code yourself.

So tame your dependencies today and get the Sonatype Insight Plugin for Eclipse.

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().

While Maven 3 is a dramatic improvement over Maven 2 from the perspective of performance, extensibility, and architecture, most end-users are motivated by plugins. This has been true about Maven from the beginning, while the framework has value, it is the plugins that make the difference. This blog focuses on the changes that are of interest to plugin authors.

Accessing Project Dependencies

The easiest way for a plugin to get the entire set of transitive dependencies for a project is the mojo annotation @requiresDependencyResolution. This annotation is configured with one of the values: compile, runtime or test, which denote the dependency scope a plugin is interested in. What has been proven troublesome is the subtle fact that the runtime classpath is not a superset of the compile classpath, i.e. dependencies of scope provided and system are not included in the runtime classpath.

Now, what shall plugin authors do that need to inspect the union of the compile and runtime classpaths? So far, the answer was either to request the test classpath or to programmatically do dependency resolution with the proper scope filter. Neither of these two approaches are really attractive for one reason or the other. So we eventually added support for a new annotation value in Maven 3.0, compile+runtime, that ensures project dependencies with the scopes compile, runtime, provided and system get resolved.

Requiring Dependency Collection

While we are at dependency resolution, Maven 3.0 also introduces the new annotation @requiresDependencyCollection. Admittedly, the name of this new annotation differs only slightly from the existing @requiresDependencyResolution annotation but there’s a rather important difference regarding the effect.

Dependency resolution consists of two phases. Phase one is determining the coordinates of all the transitive dependencies, phase two is getting the files for these artifacts which potentially involves downloading them. If one is only interested in phase one, we talk about dependency collection. In more detail, if a plugin goal declares @requiresDependencyCollection compile, it can inspect all transitive compile time dependencies of the project via MavenProject.getArtifacts(). But unlike @requiresDependencyResolution, the returned artifact instances might be unresolved, i.e. have no file associated with them.

It might seem odd to have unresolved artifacts but let me try to sketch the use cases that motivate this. While unresolved artifacts can not be used to create classpaths, they still allow a plugin to inspect the set of transitive dependencies, look for unwanted artifacts, check versions etc. If that reminds you of the Maven Release Plugin or the Maven Enforcer Plugin, great. Those plugins and others are usually invoked in very early lifecycle phases of the build, in particular, before any artifacts have been packaged or even any classes have been compiled. If those plugins try to resolve dependencies during a multi-module build with inter-project dependencies, they can’t succeed, what hasn’t been built yet cannot be resolved.

In Maven 2.x, there’s a hack that tolerates resolution errors if all of the missing artifacts are in the reactor but it still leaves your build with an ugly warning and the plugin in question with unsatisfied requirements. @requiresDependencyCollection is the answer to this situation and will help to eventually fix some long-standing issues in the previously-mentioned plugins. So if your plugin doesn’t need the actual files but only the coordinates of the project dependencies, consider to use the new annotation when targetting Maven 3.0 as a prerequisite.

Writing Thread-safe Maven Plugins

Related to the new support for parallel building in Maven 3.0, there’s also a new mojo annotation @threadSafe. Right now, this annotation is nothing more than an informative suggestion. When Maven 3.0 is asked to perform a parallel build and encounters a plugin that isn’t marked as thread-safe, it will print a prominent warning that your build might fail as historically, plugin authors assumed a sequential execution and, as such, didn’t code with concurrency and thread safety in mind.

Unlike the previously mentioned extension to the Mojo API, this new annotation can be safely added to a plugin that targets Maven 2.x as runtime. So once you have reviewed your code and possibly adjusted it to support concurrent mojo execution, feel free to add this annotation to disable the build warning from Maven 3.0. In addition to disabling the warning, the generated plugin site will also indicate that the goal supports parallel builds.

Using Generics with Maven Plugins

Given that Maven 2.2.x already requires Java 1.5 to run, more and more plugins are moving to Java 1.5 as well. To enable the benefits of Java 1.5, the Maven API has been updated to use generics, thereby easing plugin coding. Furthermore, Maven 3.0 allows to use enums for plugin configuration parameters.

Fixes to the Classloader Hierarchy

The last change I want to mention is the reworked class loader hierarchy. Build extensions can now contribute additional APIs and components that other plugins can utilize during the build. The APIs and components contributed by extensions are shared across all projects using the same extension which allows plugins to easily exchange domain-specific data structures during the build, e.g. via MavenProject.getContextValue() or via some stateful singleton from the extension. If that sounds interesting to you, have a look at the wiki article Maven 3.x Class Loading which describes the revised class loading in more depth.

As we transition this feature to Nexus Open Source, we are also announcing a new Nexus Enterprise LDAP plugin that will support more advanced deployment use cases including support for federated LDAP servers and more intelligent caching of authentication information.

Features included in the newly open-source Nexus Professional LDAP plugin:

• Active Directory Support
• Authentication via Bind, SASL, or attribute
• Ability to map LDAP groups to Nexus Roles
• Ability to assign an LDAP user a specific role
• Support for common security models used in Active Directory and LDAP.
• Support for Static and Dynamic Groups

Authentication

The Nexus LDAP Authentication Realm which will be available in the Open Source LDAP plugin supports a number of integration patterns for authentication including:

• Authentication via a bind: Delegates authentication to the LDAP server
• SASL Authentication: Delegates a SASL authentaction to the LDAP server
• Password Attribute: Nexus checks an encrypted field in the user records.

Role Mapping

Nexus Open Source can now be configured to map LDAP groups to Nexus roles . Setting up Nexus to use LDAP groups means you only need to make changes in one location. The next time a user logs in, changes a password, or assigns roles Nexus will automatically synchronize with the LDAP server and these changes will automatically take effect the next time the user logs into the Nexus server. It is also possible to grant users Nexus specific roles, or only use LDAP for authentication and leave the authorization to Nexus.   Brian Fox discussed three approaches to user management in a previous blog post: Three Approaches to User Management in Nexus .

Support for Multiple Security Models for User and Group Mapping Nexus supports all of the common security models used in LDAP servers.   This includes data models used in products like Microsoft’s Active Directory and standards-driven approaches such as posix.  We’ve had a lot of positive customer feedback about the intuitive configuration interface which lets you test the role and user mapping from the Nexus administrative interface    If you need to make a change to a group or role mapping, you can test it immediately in the context of Nexus to see if users and groups are being retrieved from your LDAP, Active Directory, or Crowd server.

Support for Static and Dynamic Groups Users and groups can be mapped one of two ways in LDAP. Dynamic groups are defined by the user object, whereas static groups are defined by the group. The trade off is speed to ease of management. For dynamic groups one simple query is need to get the user information and which groups that user belongs to, as it is all in one object. With static groups two queries are needed, one to get the user information, and another to check which groups the users is part of. Some LDAP setups user one or the other, some have both where the information is synchronized using triggers.

Stay Tuned

So where’s the plugin?   How can you install it?  Stay tuned, the Nexus 1.5.0 release will be available this Wednesday afternoon.   Once that release is completed, we will post detailed instructions for people interested in installing Nexus 1.5.0 or upgrading from a prior Nexus installation.

In the Repository panel of Nexus, there are two tabs for browsing artifacts. The first one is called “Browse Storage” and is used to browse all artifacts stored/cached locally by the Nexus instance. For a hosted repository, the tree displayed under “Browse Storage” will contain all available artifacts. For a proxy repository, you will only find those artifacts that have been cached due to earlier requests. The second tab, “Browse Index”, allows you to browse artifacts through the repository’s index.  If the remote repository provides an up-to-date index and you have configured Nexus to download this remote index, all of the artifacts in the remote repository will be visible under the “Browse Index” tab.   While the “Browse Index” tab works for all of the major public Maven repositories, it doesn’t allow you to browse remote repositories which do not publish a Nexus index.

This is where the Nexus Remote Repository Browsing Plugin (nexus-rrb-plugin) comes into play. The plugin adds a third browsing tab for proxy repositories, the “Browse Remote” tab. In this tab, it is possible to browse the actual remote repository from within the Nexus UI. Below you find a screen shot of the new tab.

Before this plugin, the user was forced to browse the remote repository in a separate browser window. Not only is this inconvenient, but for many users it is not possible as the URL of the remote repository is normally only visible to administrators. Also, the connection to the remote repository will be initiated from the Nexus instance. The benefit of this is that it will work even if your network setup prevents direct access from the clients to the remote repository.

This first version of the plugin doesn’t add any bells and whistles to the browsing. The tab is added to all proxy repositories and is available to all users. However, it does support browsing of Maven repositories at S3, such as the SpringSource repository.  This ability to browse a repository hosted on S3 is significant as it is tricky to do this via a normal web browser.

As mentioned above, the nexus-rrb-plugin is included as a core plugin in the upcoming Nexus 1.5.0 release.   This means that it will be available as a part of the core Nexus OSS offering.   Once Nexus 1.5.0 is released, please try it out and use the issue tracker for reporting any problems you run into and enhancements you would like to see – we’re especially interested in hearing about repositories that the plugin cannot handle! Questions and discussions may be posted to the Nexus mailing list.

In this post, I’m going to walk you through the process of creating a new Nexus plugin using the m2eclipse plugin for eclipse from start to finish including all steps in the process.  After reading this post you will know about the easiest way to get started working on your own Nexus plugin.

Some things to note are that I am using the latest m2e 0.9.9 dev build available from the http://m2eclipse.sonatype.org/update-dev update site. I am also using eclipse 3.5.1.  All maven builds have been done using local build of latest maven 3.0-SNAPSHOT, however, that is not a requirement for the plugins to work, just a recommendation as maven 3 (in my opinion) is much better than maven 2

Configuring Your Environment for the Nexus Plugin Project

To successfully create a Nexus Plugin using the Nexus Plugin archetype, you will need to configure your Maven Settings to include both the Sonatype Forge repository and the Central Maven repository. If you are already using Nexus and you have configured your settings.xml to use a single, consolidated repository group, all you need to do is add a proxy repository for the Sonatype Forge repository to your repository group. If you are not using Nexus, you will need to use a settings.xml that resembles the following sample:

<settings>
  <profiles>
    <profile>
      <id>sonatype-forge</id>
      <repositories>
        <repository>
          <id>sonatype-forge</id>
          <url>http://repository.sonatype.org/content/groups/forge/</url>
          <releases>
            <enabled>true</enabled>
          </releases>
          <snapshots>
            <enabled>true</enabled>
          </snapshots>
        </repository>
      </repositories>
      <pluginRepositories>
        <pluginRepository>
          <id>sonatype-forge</id>
          <url>http://repository.sonatype.org/content/groups/forge/</url>
          <releases>
            <enabled>true</enabled>
          </releases>
          <snapshots>
            <enabled>true</enabled>
          </snapshots>
        </pluginRepository>
      </pluginRepositories>
    </profile>
  </profiles>
  <activeProfiles>
    <activeProfile>sonatype-forge</activeProfile>
  </activeProfiles>
</settings>

Creating a New Project with the Nexus Plugin Archetype

Let’s start by creating a ‘New Maven Project’ in m2eclipse.

Select Maven > Maven Project, and click on Next until you reach the archetype selection. On this screen you can search for and select the archetype which will create your new project. Note that you must use the 1.2 version of the nexus-plugin-archetype.

Enter the GAV (groupId, artifactId, version) params that will uniquely define the plugin, and click on Next.

Targeting the Proper Nexus Version

After supplying the project identifiers, you will see a panel that display the archetype property ${nexusVersion}. This is the version of Nexus that your plugin will target and it will associate your project with the proper set of dependencies for a specific version of Nexus.

By default the nexus-plugin-archetype will target Nexus version 1.4.1.   If you are targeting 1.4.1, it is important that you add the following to your project’s dependency management because of a problem w/ the parent POM of Nexus 1.4.1. If you are not tied to using Nexus 1.4.1 we strongly recommend that you update the Nexus version you are targeting 1.4.2-SNAPSHOT and disregard this change. The 1.4.2-SNAPSHOT POMs have been updated properly and they do not require the following dependency management workaround.

<dependencyManagement>
    <dependencies>
        <!- Workaround for swizzle-jira:1.3.3-SONATYPE-2, as it has an incorrect parent ->
        <dependency>
            <groupId>org.codehaus.swizzle</groupId>
            <artifactId>swizzle-jira</artifactId>
            <version>1.3.3-SONATYPE-221</version>
        </dependency>
    </dependencies>
</dependencyManagement>

If you have already generated the project, and you need to change the target Nexus version you will need to edit this new project’s POM. Open up the POM of your Nexus Plugin and find the section that defines properties. You will need to change the nexus-version property to target a Nexus version. After creating a project with the Nexus Plugin archetype, you will see a properties section of the POM that contains a ${nexusVersion} reference as follows:

<project>
  ...
  <properties>
    <!-- Set the Nexus version here, against which you build the plugin -->
    <nexus-version>${nexusVersion}</nexus-version>
  </properties>
  ...
</project>

Click Next after setting the ${nexusVersion}, and voila, we have a nexus-plugin project.

Building and Deploying the Plugin Project

Your new Nexus plugin project has some sample components you can use as a starting point for your own plugin development.

You can now build this project and expand the bundle right into your nexus installation ${nexus-work-dir}/plugin-repository/

And when Nexus starts it will find the plugin and load it automatically. For this sample plugin, you should see the log message in the Nexus log:

Plugin manager “ACTIVATE” on plugin “org.sonatype.nexus.plugin:test-plugin:0.0.1-SNAPSHOT” was successful.

As expected, you are now able to properly use the new plexus resource, I used curl to perform a GET against the default /sample/hello service added to my Nexus instance. The best part is that we have achieved everything you see above with absolutely zero code, Maven Archetypes really do simplify things for you

If you want to make a standalone jar (ie one with no dependencies) executable, here’s how you do it:

<pluginManagement>
  <plugins>
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-jar-plugin</artifactId>
        <configuration>
          <archive>
            <manifest>
              <addClasspath>true</addClasspath>
              <mainClass>com.yourcompany.YourClass</mainClass>
            </manifest>
         </archive>
       </configuration>
    </plugin>
  </plugins>
</pluginManagement>

If however you have dependencies, you will probably want to bundle them into a single jar, otherwise making it executable is not very helpful. You can use the assembly plugin to do it like this:

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-assembly-plugin</artifactId>
    <executions>
      <execution>
         <goals>
           <goal>attached</goal>
         </goals>
         <phase>package</phase>
         <configuration>
           <descriptorRefs>
             <descriptorRef>jar-with-dependencies</descriptorRef>
          </descriptorRefs>
          <archive>
            <manifest>
              <mainClass>com.yourcompany.YourClass</mainClass>
            </manifest>
          </archive>
        </configuration>
     </execution>
  </executions>
</plugin>

A few comments:

1. I didn’t specify plugin versions in the example. You should always specify a plugin version, but you should do it in the pluginManagement section instead. See this post for how and why.
2. Notice the assembly plugin configuration has an execution, while the jar plugin does not. This is because the jar plugin will run automatically based on the packaging, which is assumed to be “jar” in this example. The assembly plugin needs an execution to “bind” it to the lifecycle and here we tell it which goal to run and which phase to run in.
3. Notice also that the jar plugin is configured in pluginManagement. This is my personal best practice and I explain why here.

See more Maven How-Tos and Best Practices here.

This post covers some of the initial steps, that are required to write a plugin for Nexus. Although Nexus is a Plexus application, we want to give 3rd party developers ability to extend Nexus, without forcing them to know Plexus. We also want to give 3rd party developers the ability to extend Nexus, without burying themselves into Nexus internals. Clearly if someone wants to add complex, highly custom behavior to Nexus they will need to dive into the internals, but it should be easy to add a simple extension to Nexus without having a PhD in Nexus Internals. We are also committed to adopting 3rd party “specs/suggestions/APIs” that look promising, even if it comes from another IoC provider.

Now, let’s replace the “Nexus” in above sentences with “Sonatype Application” in the sentences above. It’s not so different, right? At Sonatype, we’re convinced that providing an intuitive plugin and extension mechanism is critical for adoption and we want to make it as straightforward as possible. To start this discussion, we need first a look at how Plexus works.

Plexus in 3 minutes

Plexus “managed beans” are called “components”. In contrast to the way most people use Spring, where each bean has a unique name or “ID”, Plexus components are addressed with two coordinates: role and hint.

Plexus encourages the use of interfaces when defining components. Generally spoken, when implementing one component in Plexus, you will almost always end up with two compilation units: a Java interface, that sets the contract that your component fulfills, and an implementation (or multiple implementations) that implements the contract interface. Again, this is not enforced at all, but is considered as “best practice”.

While these two coordinates are internally represented as plain strings, the role is usually a FQN of the interface that component “provides” (or implements). For example, the role might be something like “com.sonatype.component.TestComponent” which is the FQN of an interface used to define the contract of the component. This is not enforced at all in Plexus and it’s tooling (for example, the plexus-component-metadata Maven plugin), but again, is considered a “best practice”. The “hint” is actually a free string qualifier, to be able to differentiate amongst multiple implementors (components) with same role, if needed. There is one special hint used internally by Plexus: “default”, which is used when no hint is supplied.

Why is this important? Well, usually you have two major situations with your components (managed beans). For one component contract interface you either have:

• one “default” implementation across your application (singular case),
• or you may have multiple different implementations of same component contract (plural case)

Do not confuse the singular case with “singleton” pattern: in both cases the components (managed beans) are singletons. We are just providing one or multiple implementations for same interface. But in both cases, the actual classes being created by container are singletons (unless you say different in your Plexus annotations, but that’s another story, and I don’t want to complicate existing examples).

Another case is how the “consumer” of that component — which is probably some other component in your application — decides which implementation it wants to use. Or maybe it doesn’t care at all?

The simplest example of “singular” case, the component contract interface and it’s implementation:

public interface MyComponent
{
  String getHello();
}
 
@Component( role=MyComponent.class )
public class DefaultMyComponent
  implements MyComponent
{
  public String getHello() {
    return "hello";
  }
}

That’s all you need. We just created a MyComponent component contract (interface), and provided one implementation. The implementation is even annotated using Plexus annotation, that states “this class is a component with role MyComponent”. Since we say nothing about the hint of component, Plexus implicitly manages it as “default” implementation (one-and-only).

The consumer of this component does something like this:

@Component( role=SomeOtherComponent.class )
public class AComponentConsumer
  implements SomeOtherComponent
{
  @Requirement
  private MyComponent myComponent;
 
  ...
}

Here, with @Requirement annotation we declared a “requirement” (we need it injected) to the MyComponent interface. The Plexus will try to fulfill this requirement by looking up a component with role MyComponent, and hint “default” (implicit hint), since we did not say anything about needed hint.

For the second case (one contract, multiple implementations), the most simpler example is this:

public interface Archiver
{
    void archive( File source, File archiveFile )
      throws IOException;
 
    void unarchive( File archiveFile, File destination )
      throws IOException;
}

and having component implementations like these:

@Component( role=Archiver.class, hint-"zip" )
public class ZipArchiver
  implements Archiver
{
  ...
}
 
@Component( role=Archiver.class, hint-"tgz" )
public class TgzArchiver
  implements Archiver
{
  ...
}
 
@Component( role=Archiver.class, hint-"7z" )
public class SevenZArchiver
  implements Archiver
{
  ...
}

The consumer of Archiver does something like this:

@Component( role=SomeOtherComponent.class )
public class AComponentConsumer
  implements SomeOtherComponent
{
  @Requirement( hint="zip" )
  private Archiver zipArchiver;
 
  ...
}

In case above we “wired” the AComponentConsumer to support “zip” archives only. But we may do something like this:

@Component( role=SomeOtherComponent.class )
public class AComponentConsumer
  implements SomeOtherComponent
{
  @Requirement( role=Archiver.class )
  private List archivers;
 
  ...
}

or

@Component( role=SomeOtherComponent.class )
public class AComponentConsumer
  implements SomeOtherComponent
{
  @Requirement( role=Archiver.class )
  private Map archivers;
 
  public void archive( File src, File dest )
    throws IOException
  {
    String destExt = getFileExtension( dest );
 
    if ( archivers.containsKey( destExt ) )
    {
      Archiver archiver = archivers.get( destExt );
 
      archiver.archive( src, dest );
      ...
    }
    else
    {
      throw new IOException( "Archive format unsupported!" );
    }
  }
}

It is obvious, that in this example, Plexus will inject a Map<String, Archiver> into AComponentConsumer, where the String keys will be hints of components in the Map, and values will be Archiver instances with given key.

So?

So, why is this important? — you ask. Well, in Nexus, the “extension points” are simply taken, “marked” interfaces (roles), that will be automatically pulled by Plexus collection lookups similar to this last example. Marked by Nexus developers, and pointed out as “extension point” to the 3rd party plugin developers.

Actually, up to now, this was how Nexus supported “plugins”. “Plugins” and not plugins, up to now, the job of the developer was to code Plexus components, build them, provide Plexus descriptors for the plugin (usually by annotating the classes as above and using the plexus-component-metadata plugin, which embeds the descriptor into resulting JAR), and “drop it” into Nexus lib.

Since the developers implemented and marked their classes as @Component with roles that were looked up, after booting up Nexus with new JAR in it’s lib folder, Nexus was aware of these and would start using them as if they were a part of the “core”. Simple as that.

The downside of this approach is twofold:

• 3rd party developers are forced to use Plexus, plexus tooling, etc. Also, they must be aware of Nexus internals, for example that Repository components should be **prototypes**, and not **singletons**.
• the plugins are more like “extensions”, since they total and uncontrolled access to all of the Nexus internals, not just extension points.

The Idea

In short:

• let the “host application developers” mark and parametrize the extension points (@ExtensionPoint)
• let the “3rd party plugin developers” create extensions by implementing interfaces marked with @ExtensionPoint.
• provide IoC abilities for “3rd party pluging developers”
• let the “3rd party plugin developers” create their own managed beans, components with all the IoC benefits
• load the plugin in separate classloader

Okay, let’s draft the idea: having “extension points”, which are all simple Java interfaces (component contracts) and are provided by “host application” developers (in this case Nexus developers). This is simple to understand: the host application developers are the one who know the what, where, and how about what is extensible within the application. Thus, we need to provide some means for developers, to mark their interfaces as @ExtensionPoint. Almost always, the case with components here is the “plural” case (one component interface, with multiple implementations, 3rd party developers just adding new ones to the pool of existing). But again, usually the host application developers are the ones who knos, and should provide information on extension points about instantiation details of the component implementations (singletons versus prototypes for example).

When the host application API has decorated interfaces (API), the 3rd party plugin developers may kick in, by implementing @ExtensionPoints. All they have to do is pick a component interface marked as @ExtensionPoint, and implement it. That’s all. And what about IoC?

We decided to accept the @Inject project proposal at code.google.com, and use “meta-metadata” to decorate the components. Since @Inject already proposes a meta-metadata to make possible to annotate classes and use them across Guice and Spring, we thought making it work with Plexus would be nice too.

Thus, in short, 3rd party Nexus plugin developers should use @Inject annotations only. Naturally, when deployed to Nexus, their components will be “powered by Plexus” under the hud, but it’s not their problem and they should not care about it.

The Nexus Plugin Manager will have another great feature: class loader separation. Right now, since as I said, the plugin JAR was just dropped into Nexus lib folder, that implicitly means that plugins were doomed to use the same versions of dependencies that were already present in Nexus (newly introduced dependencies are fine, though). This led to the proliferation and over user of the Maven Shade plugin. Don’t get me wrong, I think this plugin is very-very useful, but it must be used with care (not to mention it’s flaw, that it “shades” stuff always under hidden package, instead to somewhere module specific place. Two jars with same shaded dependency may again clash).

One more thing: the @Inject proposal does not mention how to create new managed beans, they have no means to annotate a new component (well, in case of Guice it happens implicitly with @Inject, making the interface needed in binding). This is where another new annotation comes in: @Managed. The @Managed annotation will be used on Java interfaces only, to mark them as component contracts.

So, in short:

• Host application developers should point out the “extension point” interfaces in the apps. Also, they should provide as much “metadata” as possible about the instances of those components.
• plugin developers should only care about implementing those marked interfaces, and not fiddle with annotating them with some container-specific stuff
• use @Inject project annotations
• add ability to plugin developers to enjoy the benefits of IoC containers, and let them defined their own components (again, no Plexus needed).

Teaser

Here is an example of a theoretical implementation of artifact virus scanner for Nexus. In short: we want to make sure no virus infected artifact will come in our Nexus instance. Internal deployments are considered “safe”, thus proxy requests are checked only.

These is what we need to implement this plugin:

• A Virus scanner implementation (not shown here for example’s brevity’s sake)
• A Nexus RequestProcessor (extension point) implementation. RequstProcessor components are able to interact with every Nexus request, and stop their execution at different stages
• A Nexus RepositoryCustomizer (extension point) implementation, to inject the RequestProcessor from above to repositories we want

We start with creating a managed component contract for Virus Scanner:

package org.sample.plugin;
 
import java.io.InputStream;
 
import org.sonatype.nexus.plugins.Managed;
 
@Managed
public interface VirusScanner
{
    boolean hasVirus( InputStream is );
}

Then we implement it. This is a “singular” case, the newly introduced component contract interface has only one default implementation:

package org.sample.plugin;
 
import java.io.InputStream;
 
import javax.inject.Named;
 
public class XYVirusScanner
    implements VirusScanner
{
 
    public boolean hasVirus( InputStream is )
    {
        // DO THE JOB HERE
        return resultOfTheScanning;
    }
 
}

Next, a RequestProcessor. It requires VirusScanner to do the work. We are not making a decision until we get to the content in shouldCache(). We are using the @Inject annotations to inject our newly created component. Since VirusScannerRequestProcessor implements a Nexus extension point (they are “plural” components), we need to reference it later (see below in VirusScannerRepositoryCustomizer), we are “naming it” with the @Named annotation.

package org.sample.plugin;
 
import java.io.IOException;
 
import javax.inject.Inject;
import javax.inject.Named;
 
import org.sonatype.nexus.proxy.ResourceStoreRequest;
import org.sonatype.nexus.proxy.access.Action;
import org.sonatype.nexus.proxy.item.AbstractStorageItem;
import org.sonatype.nexus.proxy.item.StorageFileItem;
import org.sonatype.nexus.proxy.repository.ProxyRepository;
import org.sonatype.nexus.proxy.repository.Repository;
import org.sonatype.nexus.proxy.repository.RequestProcessor;
 
@Named( "virusScanner" )
public class VirusScannerRequestProcessor
    implements RequestProcessor
{
    @Inject
    private VirusScanner virusScanner;
 
    public boolean process( Repository repository, ResourceStoreRequest request, Action action )
    {
        // don't decide until have content
        return true;
    }
 
    public boolean shouldProxy( ProxyRepository repository, ResourceStoreRequest request )
    {
        // don't decide until have content
        return true;
    }
 
    public boolean shouldCache( ProxyRepository repository, AbstractStorageItem item )
    {
        if ( item instanceof StorageFileItem )
        {
            StorageFileItem file = (StorageFileItem) item;
 
            // do a virus scan
            try
            {
                return virusScanner.hasVirus( file.getInputStream() );
            }
            catch ( IOException e )
            {
                // handle it
                return false;
            }
        }
        else
        {
            return true;
        }
    }
 
}

Finally, we are creating a RepositoryCustomizer (also a “plural” component, but we don’t care about naming it), that will inject our RequestProcessor into repository instances we need. In this case, those are proxy repositories (the only ones able to fetch artifacts from remote repositories).

package org.sample.plugin;
 
import javax.inject.Inject;
import javax.inject.Named;
 
import org.sonatype.nexus.configuration.ConfigurationException;
import org.sonatype.nexus.plugins.RepositoryCustomizer;
import org.sonatype.nexus.proxy.repository.ProxyRepository;
import org.sonatype.nexus.proxy.repository.Repository;
import org.sonatype.nexus.proxy.repository.RequestProcessor;
 
public class VirusScannerRepositoryCustomizer
    implements RepositoryCustomizer
{
    @Inject
    private @Named( "virusScanner" )
    RequestProcessor virusScannerRequestProcessor;
 
    public boolean isHandledRepository( Repository repository )
    {
        // handle proxy reposes only
        return repository.getRepositoryKind().isFacetAvailable( ProxyRepository.class );
    }
 
    public void configureRepository( Repository repository )
        throws ConfigurationException
    {
        repository.getRequestProcessors().put( "virusScanner", virusScannerRequestProcessor );
    }
 
}

That’s all for now. In the next part, we will make more in-depth explanations of the plugin API, and explain what is happening “behind the curtains”. Have fun!

Some plugins are what we call “aggregators” which means they actually do want all the information about the full multi-module build before execution. These plugins, when run on a tree of projects cause Maven to resolve all the children before calling the plugin’s execute() method. In this mode a plugin executes just once, but effectively on the whole tree at once. (as a side note, you never want to bind an aggregator goal in your pom as this would cause the plugin to run an n! recursive build since the lifecycle would step into each child and execute the aggregator…which would cause Maven to reresolve all the children, etc)

Sometimes neither of those behaviors are what you want. If I want a plugin to run only once in my build, I can do that by only binding it once in a pom. But what if you want it to run once regardless of if I start my build at the root, or somewhere down in a module? An example of where this is handy is the maven-enforcer-plugin… if you’re checking environmental constraints like jdk, os, maven version, it’s pretty much guaranteed that this can’t change between the root and when the next module is built.

This has most recently cropped up as a use case in the maven-assembly-plugin. We want to configure the plugin to produce a source archive during releases of the entire tree. Since the root project would contain the code below that point, we don’t need to also archive the source for each sub-module separately. We want to be able to configure this at our “Maven” or “Apache” pom (the moral equivalent of a “Corporate” pom) and have it simply work regardless of where a build is launched from.

It turns out that it is fairly easy for a plugin to programatically detect when it is building the project at the execution root (that is where mvn was launched). The code looks like this:

57

        boolean result = mavenSession.getExecutionRootDirectory().equalsIgnoreCase(basedir.toString());

A full mojo to implement this would look like this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58

/**
* @goal skipper
* @execute phase="validate"
**/
public class SkipperMojo extends AbstractMojo
{
    /**
     * Base directory of the project.
     *
     * @parameter default-value="${basedir}"
     * @required
     * @readonly
     */
    private File basedir;
 
    /**
     * This will cause the assembly to run only at the top of a given module tree. That is, run in the project
     * contained in the same folder where the mvn execution was launched.
     * @parameter expression="${runOnlyAtExecutionRoot}" default-value="false"
     * @since 2.2-beta-4
     */
    private boolean runOnlyAtExecutionRoot;
 
    public void execute()
        throws MojoExecutionException, MojoFailureException
    {
 
        //run only at the execution root.
        if (runOnlyAtExecutionRoot && !isThisTheExecutionRoot())
        {
            getLog().info( "Skipping the assembly in this project because it's not the Execution Root" );
        }
        else
        {
            getLog().info("Doing something usefull");
        }
   }
    /**
     * Returns true if the current project is located at the Execution Root Directory (where mvn was launched)
     * @return
     */
    protected boolean isThisTheExecutionRoot()
    {
        Log log = this.getLog();
        log.debug("Root Folder:" + mavenSession.getExecutionRootDirectory());
        log.debug("Current Folder:"+ basedir );
        boolean result = mavenSession.getExecutionRootDirectory().equalsIgnoreCase(basedir.toString());
        if (result)
        {
            log.debug( "This is the execution root." );
        }
        else
        {
            log.debug( "This is NOT the execution root." );
        }
        return result;
    }
}

“This ended up being a much longer article than I anticipated but we’ve covered a lot of ground. Maven has worked it’s dependency voodoo which saved an enormous amount of time downloading jars and messing with classpaths. We’ve seen how the PAX toolkit from OPS4J makes creating, modifying and provisioning OSGi bundles a breeze. While the actual code examples were pretty trivial, we successfully managed to code up bundles in Java, Scala and Groovy. I think this displays a lot of the power that is offered by OSGi and points to a bright future for enterprise development on the JVM.”

Project-driven Plugins: Distributed, Open Innovation

In this case Maven is bridging a number of popular projects that have all created well-documented Maven plugins. Maven is the essential “glue” that allows someone like Brian to take a number of unrelated technologies and use them in ways that the designers of GMaven or the Scala plugin could never have predicted. As Maven matures and continues to evolve its Plugin API, we’re starting to see more projects and more systems commit to using it as an enabling “platform” for development. Those projects that have adopted Maven have found it beneficial to host and drive the Maven plugins that relate to their project or technology. Better support for Maven increases the adoption of Groovy, Scala, and (in this case) OSGi.

The PAX plugin is maintained and hosted by the Ops4J project, the Scala plugin is hosted and maintained by the Scala community, and the GMaven plugin is hosted and maintained by the Groovy community. Each community feels strongly enough about providing Maven support for their technology that they have made it a part of their project. This is important because it suggests an evolving approach to the way Maven plugins are created and supported. Four years ago, it was unlikely to see a project like Scala or Ops4J creating and hosting a Maven plugin. While Maven was already ubiquitous, projects still didn’t see Maven support as a primary concern. Instead, the plugin development would happen as part of the Maven community or in an ancillary community of Maven plugins known as the Mojo project at Codehaus.

Mojo is an important bridge. It allows third-party actors to craft support for tools like JBoss and GWT, but it is an aggregate, disjoint community with a single mailing list, perfunctory release votes, and little shared discussion about architecture or planning. It is a free-for-all. While Mojo does host some essential plugins it is also a dumping grounds for half-finished, owner-less plugins. As more projects provide their own Maven support, people should consider moving project from Mojo to the projects that develop the specific technologies in question. This is the “distributed” open innovation that will encourage quality, well-documented plugins.

Why Companies and Projects Need to “Own” Their Maven Support

We’ve transitioned into a point where projects need to start hosting and owning the Maven plugins that enable developers to use their software. Google would have been better off if they had invested a day or two crafting a solid Maven plugin for AppEngine before they announced Java support. Similarly, they should think about driving the development of the GWT plugin. If your project’s artifacts are available through the Central Maven repository, that is a first step, but if your project also publishes an artifact and a really compelling Maven plugin, you’ve made it trivial and easy for people to adopt your technology. “Going to market” without good Maven support no longer makes sense, and you should know that more and more developers are start with the question “how does this fit into my Maven build?” If your answer is “shrug, we don’t use Maven”, it is very likely that they will seek out other solutions that provide better integration.

If you are a tool vendor or create an open source framework, you should be hosting your own Maven plugin as a part of your project. If you support an SCM like Perforce or Clearcase, you should make sure that your software provides a solid SCM provider for Maven. If your company or project develops a server, you should be working with the Maven project to make sure that it integrates with Maven. To do otherwise is to invite your customers or users to look elsewhere for better integration. If you let someone else drive your Maven plugin, you are really just delegating an essential support function to the community. The message you are sending is, “we don’t really care that you use Maven, it isn’t a priority, someone will do the integration work for us”. This is true, but when that happens, you lose an opportunity to interact with your users and your customers.

PS: Brian’s post also inspired me to file this JIRA issue on the MVNDEF book project. Our book’s need code examples that can be more easily copied to the clipboard.