Singletons

For example this Plexus component:

@Component(role=Component.class, hint="my")
public class MyComponent
    implements Component
{
}

can be converted to:

@Named("my")
@Singleton
public class MyComponent
    implements Component
{
}

Naming Variants

Components which are not directly looked up by names, or otherwise used in a context where the name is important you can omit the value for @Named and the full-qualified-class-name of the component will be used as the name instead.

package components;
@Named
@Singleton
public class MyComponent
    implements Component
{
}

Results in a component with implicit name of “components.MyComponent”

Additionally the Sisu Plexus integration has special handling for Plexus default components. Many Plexus applications define objects like:

@Component(role=Component.class)
public class DefaultComponent
    implements Component
{
}

The Default prefix on the component implementation class causes the binding to be translated to @Named("default"), so the conversion would look like:

package components;
@Named
@Singleton
public class DefaultComponent
    implements Component
{
}

BUT the name bound for this component would be “default”.

Instance

By default in Plexus, components are singletons, but this is not the case for every component. This Plexus component is not a singleton:

@Component(role=Component.class, hint="my", instantiationStrategy="per-lookup")
public class MyComponent
    implements Component
{
}

and is converted to:

@Named("my")
public class MyComponent
    implements Component
{
}

Notice this is the same as the example above, except with-out the @Singleton annotation.

Only per-lookup and singleton instantiation strategies have reasonable mappings into Sisu. The keep-alive and poolable strategies are not supported.

Additionally other Plexus-specific component configuration such as lifecycle-handlers, factories, composer, configurator, alias, version, profile, isolatedRealm are NOT supported.

Type Override

By default the type of the component is determined automatically, though in some rare cases an explicit type is required. To specify the explicit binding type use the @Typed annotation:

@Named("my")
@Typed(Component.class)
public class MyComponent
    extends SomeSupportClassHardToGuessTypeFrom
{
}

Descriptions

In some cases component descriptions are required. There is no standard annotation to provide this, however Sisu provides a custom annotation for this.

@Component(role=Component.class, hint="my", description="My custom component")
public class MyComponent
    implements Component
{
}

becomes:

@Named("my")
@Singleton
@Description("My custom component")
public class MyComponent
    implements Component
{
}

Basics

@Requirement defines injection points for legacy Plexus components. These more-or-less line-up directly with replacement with @Inject, though there are more options available as @Inject is support for fields, constructors and methods, where @Requirement only worked with fields. The recommended option is to replace legacy Plexus injection with constructor injection where possible.

@Component(role=Component.class, hint="my")
public class MyComponent
    implements Component
{
    @Requirement
    private AnotherComponent another;
}

becomes:

@Named("my")
@Singleton
public class MyComponent
    implements Component
{
    private final AnotherComponent another;

    @Inject
    public MyComponent(final AnotherComponent another) {
        this.another = another;
    }
}

Use of constructor injection in this fashion has some impact on replacing legacy Plexus lifecycle Initializable and Contextualizable interfaces, which often only exist to perform setup once injection is performed.

Alternatives

Other options for conversions using field injection:

@Named("my")
@Singleton
public class MyComponent
    implements Component
{
    @Inject
    private AnotherComponent another;
}

This is not recommended, as it makes it difficult to UNIT test the code w/o a full container to provide injection, which in itself can be problematic for UNIT testing. We highly recommend this form of injection NOT BE USED.

or method injection:

@Named("my")
@Singleton
public class MyComponent
implements Component
{
    private AnotherComponent another;

    @Inject
    public setAnotherComponent(final AnotherComponent another) {
        this.another = another;
    }
}

Optional

Optional components are configured to be @Nullable

@Component(role=Component.class, hint="my")
public class MyComponent
    implements Component
{
    @Requirement(optional=true)
    private AnotherComponent another;
}

becomes:

@Named("my")
@Singleton
public class MyComponent
    implements Component
{
    private final AnotherComponent another;

    @Inject
    public MyComponent(final @Nullable AnotherComponent another) {
        this.another = another;
    }
}

Names and Hints

Legacy Plexus component hints become @Named:

@Component(role=Component.class, hint="my")
public class MyComponent
    implements Component
{
    @Requirement(hint="foo")
    private AnotherComponent another;
}

becomes:

@Named("my")
@Singleton
public class MyComponent
    implements Component
{
    private final AnotherComponent another;

    @Inject
    public MyComponent(final @Named("foo") AnotherComponent another) {
        this.another = another;
    }
}

Types

Legacy Plexus component roles, which are normally only used for collection types are generally not needed:

@Component(role=Component.class, hint="my")
public class MyComponent
    implements Component
{
    @Requirement(role=AnotherComponent.class)
    private List components;
}

becomes:

@Named("my")
@Singleton
public class MyComponent
implements Component
{
    private final List components;

    @Inject
    public MyComponent(final List components) {
        this.components = components;
    }
}

Basics

@Component(role=Component.class, hint="my")
public class MyComponent
    implements Component
{
    @Configuration(name="configDir")
    private File configDir;
}

becomes:

@Named("my")
@Singleton
public class MyComponent
    implements Component
{
    private final File configDir;

    @Inject
    public MyComponent(final @Named("${configDir}") configDir) {
        this.configDir = configDir;
    }
}

Defaults

Default values are provided by expression syntax.

@Component(role=Component.class, hint="my")
public class MyComponent
    implements Component
{
    @Configuration(name="configDir", value="defaultDir")
    private File configDir;
}

becomes:

@Named("my")
@Singleton
public class MyComponent
    implements Component
{
    private final File configDir;

    @Inject
    public MyComponent(final @Named("${configDir:-defaultDir}") configDir) {
        this.configDir = configDir;
    }
}

Initializable

By and far this can be replaced by using constructor-inject, and performing the initialize() at the end of the constructor.

@Component(role=Component.class, hint="my")
public class MyComponent
    implements Component, Initializable
{
    @Requirement
    private AnotherComponent another;

    public initialize() throws InitializationException {
        another.init();
    }
}

becomes:

@Named("my")
@Singleton
public class MyComponent
    implements Component
{
    private final AnotherComponent another;

    @Inject
    public MyComponent(final AnotherComponent another) {
    this.another = another;
        another.init();
    }
}

Contextualizable

Similar to Initializable, though if the context is needed you can inject the container context parameters with:

@Named("my")
@Singleton
public class MyComponent
    implements Component
{
    @Inject
    public MyComponent(final @Parameters Map params) {
        // do something with \_context\_ params
    }
}

Startable

Support for Sisu/JSR250 lifecycle annotations is available when enabled for the Plexus wrapper ([Maven 3.5+](https://issues.apache.org/jira/browse/MNG-6084) enables JSR250 support).

If JSR250 support is not enabled then applications can use other techniques to handle start/stop behavior. The examples below show the solution used in Sonatype Nexus, which relies on a modified implementation of the Google-Guava EventBus to manage lifecycle events.

@Component(role=Component.class, hint="my")
public class MyComponent
    implements Component, Startable
{
    public start() throws StartingException {
        // do something to "start"
    }

    public stop() throws StoppingException {
        // do something to "stop"
    }
}

becomes:

import org.sonatype.sisu.goodies.eventbus.EventBus;
import com.google.common.eventbus.Subscribe;

@Named("my")
@Singleton
public class MyComponent
    implements Component
{
    private final EventBus eventBus;

    @Inject
    public MyComponent(final EventBus eventBus) {
        this.eventBus = eventBus;
        eventBus.register(this);
    }

    @Subscribe
    public on(final NexusStartedEvent event) throws Exception {
        // do something to "start"
    }

    @Subscribe
    public on(final NexusStoppedEvent event) throws Exception {
        // do something to "stop"

        eventBus.unregister(this);
    }
}

Disposable

Similar to Startable use of events are used to handle replacement for Disposable components.

@Component(role=Component.class, hint="my")
public class MyComponent
    implements Component, Disposable
{
    public dispose() {
        // do something to "dispose"
    }
}

becomes:

import org.sonatype.sisu.goodies.eventbus.EventBus;
import com.google.common.eventbus.Subscribe;

@Named("my")
@Singleton
public class MyComponent
    implements Component
{
    private final EventBus eventBus;

    @Inject
    public MyComponent(final EventBus eventBus) {
        this.eventBus = eventBus;
        eventBus.register(this);
    }

    @Subscribe
    public on(final NexusStoppedEvent event) throws Exception {
        // do something to "dispose"

        eventBus.unregister(this);
    }
}