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.

Nexus OSS Core has more than 120 REST Resources

Nexus: A Core of REST Services

When we started the Nexus project, I called it a “blind” application.  A “blind” webapp is one with no UI technology whatsoever built-in.   All it publishes is a few static files, and a REST API.   All of the UI that you see in Nexus is Javascript.   Your browser executes Javascript which, in turn, interacts with a set of services.   The only presentation technology on the server side is a trivial Velocity template used to render the initial “shell” of the page.

The server-side application you call Nexus, doesn’t generate the UI, that is all Javascript.   It is a completely separate and standalone application, that runs in your browser! A self contained JavaScript application (powered by ExtJS), that communicates with Nexus server, using REST calls only.  This has one very important consequence: whatever Nexus functionality you are able to reach using the Nexus User Interface (and I do mean all), you can do with a plain REST client.     If you want to automate a task, you can use a tool like curl, or some Ruby script, or any HTTP capable client.   You can even start to implement your own custom interface if you would like a completely customized UI.

As I said, it was like this since day one. But, we always had one major issue that prevented wider acceptance of Nexus’ REST API: we had no up-to-date documentation for it.    It wasn’t a priority, we spent much of our time trying to integrate the only existing REST framework (restlet.org) with Plexus, and since we were moving so quickly to implement new features, we didn’t think it made sense to stop and document an ever-changing interface.  We did maintain a wiki page which described the REST services from the beginning of the project, it always provided stale information given our aggressive development pace.

REST Documentation: Using Enunciate

I’ve been looking at the Enunciate project for some time, and it appears to be the solution to our REST document issues.  Enunciate is a cool project hosted on Codehaus, with a bold promise:

Enunciate is designed to make your life easier. Enunciate deals with your deployment difficulties, documentation, and client-side code. By using Enunciate to publish your service interfaces, not only will you have all three Web service interfaces (SOAP, REST, and AMF), but you’ll also have full up-to-date documentation generated, strongly typed ActionScript code that you can use to invoke your remote services from your Flex code, and rich client-side libraries that can be used to access your Web services from a variety of platforms (including Mac/iPhone).

Our initial plans are to use Enunciate in a “lite” mode to generate documentation (and potentially client side code) for our current REST API. Later, we plan to integrate it more closely into new Nexus “Remoting API” implementation, and it will be the backbone of our REST services when we will implement version 2.0 of our API.

Here is just a taste of what is to come.  We’ve used Enunciate to generate documentation for our REST services, and the work is proceeding very quickly.   Here is a snapshot of the documentation we will be releasing soon.

Remaining Problems to Solve

When our REST API was concieved in Q4 of 2007 we didn’t have the rich array of options that we have today.   One major REST library was available, and that was Restlet.  JSR311 wasn’t around back then, so we were forced to code directly to the Restlet API.  Back in 2007, it was very cool to create Plexus components that were then automatically published as REST Resources in Nexus. But today, the same thing looks very cumbersome and is not what one would call a “state of the art”. Back then, we had these goals in mind:

• have complete REST API published on Nexus
• have a decoupled UI application
• provide XML/JSON serialized transport to REST Resource without any effort, with proper content negotiation (XML was kept as “Plan B”)
• make our REST Resources as Plexus components (to enjoy all the benefits of IoC, and later pluggability)

While we fulfilled much of these goals above, we did that at a high cost.  For a Nexus core developer (or Nexus plugin developer), it is very cumbersome to create a new REST Resource using our classes, compared to what REST libraries are available today. Current state-of-the-art REST libraries make our initial implementation seem somewhat naive (hence the need to move toward new libraries like Enunciate). Our 1st and biggest mistake was a very deep class hierarchy in our current API.  While all the “defaults” are properly configured, it is often difficult to create a non-trivial Resource in the current API if you are not intimately familiar with the system.

Also, in the initial design, we use XStream with a custom driver to produce JSON. Back then, it was a real pain to produce proper JSON out of Java.   Today, we have libraries like Jackson.   In the next interation of refactoring, you’ll see update the infrastructure used to produce our REST services to bring it up to speed with what is available today.

The Benefits of “enunciating” a REST API

At first, we will use Enunciate with Nexus during build time only, to generate HTML documentation of our REST API. This documentation will be available publicly, but will also be bundled with every Nexus instance!   Our work to modify our own REST infrastructure is going to require some “invasive” work, but I have to emphasize that Enunciate is not invasive if you use it on a modern JSR311 based REST applications. Enunciate is invasive for us only, since we are about to use it on a home grown, non-JSR311 REST application.

Enunciate gathers and builds your services model using your sources and all the metadata it finds (Java5 annotations, Javadoc).  To “enunciate” the Nexus REST API, we had to add JSR311 annotations to our existing REST Resources.  There was one more problem to solve: our method signatures are more “servlet like”, and they didn’t fit the model of a JSR311 REST Application. While a JSR311 application method signature completely describes the method expectations about payload, parameters, and response type, our methods – whether GET, PUT, POST or DELETE – have almost same signature: RestRequest, RestResponse, Variant. Hence, we had to add more metainformation describing what a method does: what it expects as input, if any, and what it sends out as response.

Luckily, it turned out that this was the only piece missing, and Enunciate was happy to generate documentation for us. Ryan added the new annotation that describes the “alternate REST Signature” of the method, and Enunciate got all the information it needed to generate documentation for us.

Another painful step yet to be completed is “freeing” our REST DTOs from Modello. Initially, we knew we wanted to version the DTOs used in REST. Hence, we used Modello to generate the DTOs. Later, problems with Modello and Restlet forced us to always use version 1.0 of our REST DTOs. Since Enunciate requires that DTOs have JAXB2 annotations, we decided to store our DTOs as code and ditch Modello in our builds.

All this looks like a lot of work, but it is actually pretty straightforward.   While this might seem dull to someone not developing Nexus, this work is going to bring real value once it is completed.    In addition to solving our documentation problems, Enunciate is going to open up a world of possibilities once we migrate our REST services over to the framework.

For more information about Enunciate, the Enunciate Wiki contains a nice example of how to use Enunciate in case like ours is, without JAX-RS. Example is shown here.  Examples of Enunciate generated documentation can be seen on it’s site. There is a great walk-through, with static examples.

Expect More Changes in the Next Few Months

As Nexus graduated from alphas, betas and now is at a 1.5.0 version, we realize we have to change gears to keep up. Enunciate is the 1st “newcomer” technology to Nexus stack.  There will be more to come.   Think of this as the Nexus 100,000 mile checkup.  We’re taking a look at the stack and taking this as an opportunity to upgrade where necessary.

One last note, this post is not about any deficiencies in Restlet.  Restlet is a great framework, and it served us well.  We – the Nexus Project team – are very thankful to Restlet.org project with all the help we got from them and for the great library they made.

Guice-Bean Extension Layer

Our goal is to create a general-purpose bean injection layer on top of the raw custom injection API provided by Guice. This layer will take care of registering the necessary MembersInjectors as well as scanning class hierarchies for potential bean properties. All the client needs to do is decide whether or not to supply a binding for a given property.  The primary class in this layer is BeanListener:

public class BeanListener
    implements TypeListener
{
    public BeanListener( final BeanBinder beanBinder )
    {
        // ...etc...
    }
}

This is a TypeListener implementation that you can register with Guice to provide bean injection for any type. It accepts a single argument of type BeanBinder, which the client is expected to implement:

public interface BeanBinder
{
    <B> PropertyBinder bindBean( TypeLiteral<B> type, TypeEncounter<B> encounter );
}

The single bindBean method should supply a PropertyBinder based on the type of bean being injected. This means clients can customize or cache information on a per-type basis, or simply provide the same PropertyBinder implementation for all bean types. Returning null will disable bean injection for that type.  The PropertyBinder interface does the same job as BeanBinder, but at the property level:

public interface PropertyBinder
{
    <T> PropertyBinding bindProperty( BeanProperty<T> property );
}

This is the point where clients decide whether or not to bind a particular property. They can either return an implementation of PropertyBinding which should inject the property, or return null to ignore this property. This process continues until all the bean properties have been scanned – unless the client returns the LAST_BINDING constant from the PropertyBinder API, which will immediately stop the scanning for the current bean. LAST_BINDING is supposed to be used by binders who know they can’t supply any more bindings, because then there’s no point in continuing the scan.  So what does a PropertyBinding look like?

public interface PropertyBinding
{
    <B> void injectProperty( B bean );
}

Well, not much as you can see! It has a single method injectProperty which is the trigger for injecting a value into the appropriate property of the given bean. How this value is created and how it is injected into the bean is up to the client, but most clients will use the BeanProperty supplied in the original bindProperty method to do the actual injection:

public interface BeanProperty<T>
{
    <A extends Annotation> A getAnnotation( Class<A> annotationType );

    TypeLiteral<T> getType();

    String getName();

    <B> void set( B bean, T value );
}

Specifically the set method lets you inject a value into this property for a given bean instance. Notice how you can also query the generic type, name, as well as any annotations attached to the bean property. You can use any or all of this information to determine what value to inject into the property: for example by querying XML metadata, runtime annotations, maybe even pulling values out of a database.

Property names are normalized – a setter method called “setValue” has a property name of “value”

The BeanProperty currently doesn’t tell you whether it’s backed by a field or setter method. This is because we don’t need this information in our use-case and don’t believe others will, but some sort of query method could be added in the future if necessary.

Enough talk, let’s actually try and use this extension layer in a small example!

Example

We begin by creating an example Maven project:

mvn archetype:create "-DgroupId=example.bean.guice" "-DartifactId=guice-bean-example"

cd guice-bean-example/

Remove the example App files, as we’ll be adding our own files soon:

rm src/main/java/example/bean/guice/App.java
rm src/test/java/example/bean/guice/AppTest.java

Now edit the POM, first we need to add a dependency to the guice-bean-inject library:

  <dependencies>
    <!-- ... -->
    <dependency>
      <groupId>org.sonatype.spice.inject</groupId>
      <artifactId>guice-bean-inject</artifactId>
      <version>0.1.0</version>
    </dependency>
    <!-- ... -->
  </dependencies>

This will also pull in the guice-bean-reflect and guice-patches libraries

We also need to tell Maven to compile at the Java5 level, because this is the minimum required by Guice:

  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-compiler-plugin</artifactId>
        <configuration>
          <source>1.5</source>
          <target>1.5</target>
        </configuration>
      </plugin>
    </plugins>
  </build>

We’re now ready to add our example code, let’s start with a very simple “do nothing” binder:

package example.bean.guice;

import org.sonatype.guice.bean.inject.BeanBinder;
import org.sonatype.guice.bean.inject.PropertyBinder;

import com.google.inject.TypeLiteral;
import com.google.inject.spi.TypeEncounter;

public class SimpleBeanBinder
  implements BeanBinder
{
  public <B> PropertyBinder bindBean( TypeLiteral<B> type, TypeEncounter<B> encounter )
  {
    return null;
  }
}

Well that’s fairly useless! We should at least return some property binders which in turn return some property bindings, otherwise nothing will be injected. To save on typing we’ll put our injection code in a couple of nested anonymous classes, but we could just as well have created named classes. Let’s also use the bean property to do the actual injection (for the moment we will just inject null).

package example.bean.guice;

import org.sonatype.guice.bean.inject.BeanBinder;
import org.sonatype.guice.bean.inject.PropertyBinder;
import org.sonatype.guice.bean.inject.PropertyBinding;
import org.sonatype.guice.bean.reflect.BeanProperty;

import com.google.inject.TypeLiteral;
import com.google.inject.spi.TypeEncounter;

public class SimpleBeanBinder
  implements BeanBinder
{
  public <B> PropertyBinder bindBean( TypeLiteral<B> type, TypeEncounter<B> encounter )
  {
    return new PropertyBinder()
    {
      public <T> PropertyBinding bindProperty( final BeanProperty<T> property )
      {
        return new PropertyBinding()
        {
          public <C> void injectProperty( C bean )
          {
            property.set( bean, null );
          }
        };
      }
    };
  }
}

We made the property parameter final so we could use it inside the anonymous class

Next we need to provide actual values for our bean properties. We’re free to get these values from anywhere we want, but to keep this example simple we’ll just get them from the Guice injector. So how do we access the injector while we’re still configuring bindings? Well the TypeEncounter has methods to look up the Provider for a given binding Key. But be careful – we can’t use these providers during the property binding call because the injector is still being initialized. We can only use them once the injection phase starts, such as in the injectProperty method.

Our example bean binder takes the simple name of the bean class, appends the property name, and turns it into a JSR 330 binding annotation like @Named("PersonBean.name"). In practice you’ll also want to include the package name to avoid collisions. The appropriate value provider is supplied by the TypeEncounter using a key based on the binding annotation and property type. We store the provider in a final variable so we can access it later on when we need to inject the property value into a bean.

package example.bean.guice;

import javax.inject.Named;
import javax.inject.Provider;

import org.sonatype.guice.bean.inject.BeanBinder;
import org.sonatype.guice.bean.inject.PropertyBinder;
import org.sonatype.guice.bean.inject.PropertyBinding;
import org.sonatype.guice.bean.reflect.BeanProperty;

import com.google.inject.Key;
import com.google.inject.TypeLiteral;
import com.google.inject.spi.TypeEncounter;
import com.google.inject.util.Jsr330;

public class SimpleBeanBinder
  implements BeanBinder
{
  public <B1> PropertyBinder bindBean( final TypeLiteral<B1> type, final TypeEncounter<B1> encounter )
  {
    return new PropertyBinder()
    {
      public <T> PropertyBinding bindProperty( final BeanProperty<T> property )
      {
        // simple mapping id, not guaranteed to be unique as we don't include the package namespace
        Named valueId = Jsr330.named( type.getRawType().getSimpleName() + "." + property.getName() );
        final Provider<T> valueProvider = encounter.getProvider( Key.get( property.getType(), valueId ) );

        return new PropertyBinding()
        {
          public <C> void injectProperty( C bean )
          {
            property.set( bean, valueProvider.get());
          }
        };
      }
    };
  }
}

We now have a working bean binder that maps bean properties to JSR 330 named bindings. To finish things off, let’s add a bit of logging so we can see what the binder is doing during the test:

package example.bean.guice;

import java.util.logging.Level;
import java.util.logging.Logger;

import javax.inject.Named;
import javax.inject.Provider;

import org.sonatype.guice.bean.inject.BeanBinder;
import org.sonatype.guice.bean.inject.PropertyBinder;
import org.sonatype.guice.bean.inject.PropertyBinding;
import org.sonatype.guice.bean.reflect.BeanProperty;

import com.google.inject.Key;
import com.google.inject.TypeLiteral;
import com.google.inject.spi.TypeEncounter;
import com.google.inject.util.Jsr330;

public class SimpleBeanBinder
  implements BeanBinder
{
  private final Logger LOGGER = Logger.getLogger( SimpleBeanBinder.class.getName() );

  void log( String message )
  {
    // blank method+class to remove clutter  
    LOGGER.logp( Level.INFO, "", "", message );
  }

  public <B1> PropertyBinder bindBean( final TypeLiteral<B1> type, final TypeEncounter<B1> encounter )
  {
    log( "Binding bean <" + type + ">" );
    return new PropertyBinder()
    {
      public <T> PropertyBinding bindProperty( final BeanProperty<T> property )
      {
        log( "Binding property [" + property.getName() + "]" );

        // simple mapping id, not guaranteed to be unique as we don't include the package namespace
        Named valueId = Jsr330.named( type.getRawType().getSimpleName() + "." + property.getName() );
        final Provider<T> valueProvider = encounter.getProvider( Key.get( property.getType(), valueId ) );

        return new PropertyBinding()
        {
          public <C> void injectProperty( C bean )
          {
            T value = valueProvider.get();
            log( "Injecting property [" + property.getName() + "] with \"" + value + "\"" );
            property.set( bean, value );
          }
        };
      }
    };
  }
}

OK so we have our simple bean binder, now we need a bean to test it with. How about the following:

package example.bean.guice;

public class PersonBean
{
  private int age;

  private String name;

  public void setName( String name )
  {
    this.name = name.toUpperCase();
  }

  public String getName()
  {
    return name;
  }

  public int getAge()
  {
    return age;
  }
}

This is a trivial bean that mixes field and setter injection, it is definitely not meant to represent good coding practice!

Finally we need to write a test that exercises our bean binder. The following jUnit test bootstraps a Guice injector that uses our binder along with a couple of constant bindings for each of the bean properties. Guice will handle converting the constant strings to the right types. The injector is used to inject the example bean instance into the test, where its properties are checked against the expected values.

package example.bean.guice;

import javax.inject.Inject;

import junit.framework.TestCase;

import org.sonatype.guice.bean.inject.BeanListener;

import com.google.inject.AbstractModule;
import com.google.inject.Guice;
import com.google.inject.TypeLiteral;
import com.google.inject.matcher.Matchers;
import com.google.inject.util.Jsr330;

public class PersonBeanTest
  extends TestCase
{
  @Inject
  PersonBean personBean;

  @Override
  protected void setUp()
  {
    Guice.createInjector( new AbstractModule()
    {
      @Override
      protected void configure()
      {
        bindListener( Matchers.only( TypeLiteral.get( PersonBean.class ) ),
                      new BeanListener( new SimpleBeanBinder() ) );

        bindConstant().annotatedWith( Jsr330.named( "PersonBean.name" ) ).to( "John Smith" );
        bindConstant().annotatedWith( Jsr330.named( "PersonBean.age" ) ).to( "42" );
      }
    } ).injectMembers( this );
  }

  public void testNameBean()
  {
    // check the name was capitalized by the setter
    assertEquals( "JOHN SMITH", personBean.getName() );
    assertEquals( 42, personBean.getAge() );
  }
}

If you are doing a lot of Guice testing, you should take a look at the atunit library

We’re now ready to test our example bean binder! Type the following command to kick things off:

mvn clean install

You should see the usual Maven output followed by a successful test, which should look something like this:

-------------------------------------------------------
 T E S T S
-------------------------------------------------------
Running example.bean.guice.PersonBeanTest
Jan 8, 2010 12:27:07 AM
INFO: Binding bean <example.bean.guice.PersonBean>
Jan 8, 2010 12:27:08 AM
INFO: Binding property [name]
Jan 8, 2010 12:27:08 AM
INFO: Binding property [age]
Jan 8, 2010 12:27:08 AM
INFO: Injecting property [age] with "42"
Jan 8, 2010 12:27:08 AM
INFO: Injecting property [name] with "John Smith"
Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.785 sec

Results :

Tests run: 1, Failures: 0, Errors: 0, Skipped: 0

Congratulations, you’ve just used Guice to initialize a plain old bean with no annotations at all!

Next: Reflection

Interested in how the BeanListener finds bean properties? We’ll take a closer look at this in the next post in this series which will cover Generic Bean reflection.

Scope, Architecture, and Conventions

Our goal is to create a swap-in replacement for Plexus built on top of Guice. Ideally this should be done without changing the core Guice code, but if this is not possible then any fixes or new functionality should be written up and reported on the Guice issues page. While there is no guarantee that these changes will make it into an official Guice release, improvements that benefit a wider audience should have a better chance of making it into Guice.

Sonatype currently maintains a patched build of Guice trunk with the following major patches:

• Provide access to Guice’s own internal TypeConverters
• BytecodeGen and related AOP / bridge classloader fixes

This build also contains some experimental changes which have not yet been written up because they are still being tested:

• ability to turn off validation error about using @Singleton on an interface instead of an implementation class
• ability to turn off creation of parent JIT bindings when using child injectors (simplified version of this issue)

Guice/Plexus Integration Module Architecture

The solution is separated into re-usable, pluggable modules that together provide a replacement for the existing Plexus container. There is also an artifact that combines these modules into a single JAR, as this would make it easier to swap between the old and new container. Each module has a specific responsibility and any dependencies between modules is kept at a minimum. The following is a list of the components or modules that comprise the Guice/Plexus integration project.

guice-bean-inject

Extends Guice to support customized injection of named properties (fields and setter methods).

guice-bean-reflect

Provides utility methods and support code for reflection, bean properties, and resource scanning.

guice-plexus-metadata

Shared metadata interfaces, runtime implementations of Plexus annotations, and collection adapters.

guice-plexus-scanners

Annotation and XML scanners that provide metadata about components, requirements, and configuration.

guice-plexus-converters

Standard Plexus type conversion rules that can create instances from simple strings and XML markup.

guice-plexus-locators

Guice based registry that can locate components of a certain type, optionally ordered by name hints.

guice-plexus-bindings

Guice module that uses: scanners to find and bind Plexus component beans, converters to turn configurations into instances, and locators to find components based on requirements. This component also provides a simple lifecycle management API.

guice-plexus-shim

Creates an injector with Plexus bean support, adds Plexus lifecycles, and provides the container API.

A Brief introduction to Guice and JSR330

Guice is a Dependency Injection framework that injects constructors, methods, and fields annotated with @Inject. Guice recognizes both the JSR 330 and the original Guice form of this annotation.

Every injection point (constructor, method, or field) has a number of dependencies, each one represented by a key: the type to be injected plus an optional qualifier annotation that lets you choose between different implementations of the same type. For example:

public class Car {
   // Injectable constructor
   @Inject public Car(Engine engine) { ... }

   // Injectable field
   @Inject @Named("Corinthian Leather") private Seat seat;

   // Injectable package-private method
   @Inject void install(Windshield windshield, Trunk trunk) { ... }
}

Has the following injection points and dependency keys:

Constructor      ---> Key[ Engine ]
Field "seat"     ---> Key[ Seat, @Named( "Corinthian Leather" ) ]
Method "install" ---> Key[ Windshield ], Key[ Trunk ]

The Guice injector maintains a set of bindings that map dependency keys to providers that supply instances of the key type. These providers may use different strategies to supply instances: per-lookup, singleton, per-conversation, even your own custom strategies.

When you configure Guice you are registering bindings from one key to another, or between keys and providers:

// Key[ Seat ] ---> Key[ FoamSeatImpl ]
bind( Seat.class ).to( FoamSeatImpl.class );

// Key[ Seat, @Named( "Corinthian Leather" ) ] ---> Key[ LeatherSeatImpl ]
bind( Seat.class ).annotatedWith( Names.named( "Corinthian Leather" ) ).to( LeatherSeatImpl.class );

// Key[ Engine ] ---> Key[ V8EngineImpl ]
bind( Engine.class ).to( V8EngineImpl.class );

// Key[ V8EngineImpl ] ---> Provider[ V8EngineImpl, "singleton" ]
bind( V8EngineImpl.class ).in( Singleton.class );

// Key[ Windshield ] ---> Provider[ Windshield, "custom" ]
bind( Windshield.class ).toProvider( WindshieldProvider.class );

// Key[ Trunk ] ---> Provider[ TrunkImpl, "constant" ]
bind( Trunk.class ).toInstance( new TrunkImpl() );

The injector can also create certain types of bindings on-demand when no such explicit binding already exists, such as:

// Key[ FoamSeatImpl ] ---> Provider[ FoamSeatImpl , "per-lookup" ]
// Key[ LeatherSeatImpl] ---> Provider[ LeatherSeatImpl, "per-lookup" ]

The Key[...] and Provider[...] markup is pseudo-code

So far so good, but what if you have classes that don’t mark dependencies with @Inject? What if they’re identified in XML or marked with custom annotations like @Requirement or @Configuration?

TypeListeners, MembersInjectors, and InjectionListeners

Since 2.0 Guice has provided a way to supplement the core injection process with your own custom injections. Here’s what you need to do:

1. Register your custom TypeListener, using a Matcher to filter the specific types you are interested in, or Matchers.any() if you want to process all types
2. Guice will call your TypeListener once for each type that matches your chosen matcher, passing you a TypeEncounter
3. You can then analyze the type to be injected, prepare any custom injection data, and use the TypeEncounter to register aMembersInjector or InjectionListener for this type. Because the TypeListener is called per-type, and not per-instance, you should try to do as much preparation work here as possible to avoid spending too much time in the MembersInjector or InjectionListener
4. Guice will call your MembersInjector once for each instance it injects, after it has performed the core injection. You can then use the data prepared by your TypeListener to perform any custom injection
5. Finally Guice will call your InjectionListener once for each instance it injects, after all injections are complete. This is where you can hook in management code, such as start and stop life-cycle support

You’ll notice that Guice does not dictate how each type should be scanned or prepared for custom injection. While Guice does provide utility methods that can tell you which class members are annotated with @Inject, there’s no general-purpose mechanism to scan class members looking for custom annotations. On the one hand this is good, because it avoids bloating the core JAR with code you might not need. But on the other hand each custom injection client could end up implementing similar scanning code again and again. The recommended approach is to put optional code like this in an extension library that people can use if they need to, rather than keep folding it into the core.

We’re going to use custom injection to support Plexus components whose dependencies may be annotated or configured in XML. Plexus components are similar to Java beans in that they can have fields or setter methods, so rather than write a custom injector that’s closely tied to Plexus let’s see if we can develop an extension library for “beans” in general. That way we can build support for Plexus on top of it, and allow people to re-use it for other bean-style injections.