So far, XWiki has chosen to be independent of all existing Components Managers and instead to define some simple Component interfaces that can then be bound on any existing Component Manager. XWiki is currently implementing its own lightweight Component Manager. The future will depend on whether there'll be a standard solution in JavaSE (CDI is the best candidate so far). When a standard solution exists, we'll probably move to it.

Features

The Component Module defines the following features:

Annotations to declare Component interfaces, Component implementations and Component dependencies (a.k.a as Component Requirements). Starting with 3.1 we now support JSR330 annotations.

Ability to have Singleton Components and Per-lookup Components (a new instance is created when the component is retrieved).

Ability to define a Hint to separate different Components implementations implementing the same Component interface.

Automatic Field-based injection of Component Dependencies. Support for List and Map injections.

Ability for Components to perform some initialization when they are instantiated.

Ability for Components to log things.

Component Events to be notified when a new Component is registered/unregistered in the system.

Ability to define Component Realms, i.e. the ability to isolate groups of components.

New in 3.3 Ability to define JSR330 Providers as Components and to have them injected automatically.

Component Registration

There are two ways to register a Component:

By setting Java Annotations on the Component Interface and the Component implementation and declaring the Component implementation in a META-INF/components.txt file.

By programmatically registering the Component against the Component Manager instance.

Using Annotations

The following Annotations are available:

Role: Used to declare an Interface as a Component Role. Before 4.0, you had to use @ComponentRole which is now deprecated

Component: Used to declare a class implementing a Component Interface as a Component implementation

Starting with 3.1 the @Singleton annotation should be used instead when specifying a Singleton component. However for a per lookup lifecycle you should still use @InstantiationStrategy(ComponentInstantiationStrategy.PER_LOOKUP). If not specified the default is currently a Singleton but since JSR330 has a default of Per Lookup we might change this in the future.

Inject: Used to declare a field as requiring a Component implementation to be injected at runtime Requires 3.1+, before that you had to use Requirement

Named: Used to give a Hint to the Role to specify which implementation should be injected. Requires 3.1+

The MessageMacro class is declared as a Macro with a message Hint (to differentiate it from other implementations). Note that you can leave the hint empty, in which case it'll be the default hint.

The MessageMacro needs 2 other components injected: Execution and Macro. The implementation injected will be found at runtime by the Component Manager. An Execution implementation with a default Hint will be injected and a Macro implementation with the box Hint will be injected.

A Component Interface + a Hint must be unique across the system. If you have 2 Components registered with the same Component Interface and the same Hint then the Component Manager will only register one of them and a warning will be printed in the logs. That's unless you really want this and have defined an override.

In addition, for our MessageMacro component to be available at runtime, you need to list it with its fully-qualified name in a META-INF/components.txt file:

org.xwiki.rendering.internal.macro.message.MessageMacro

Registering and Using a Provider

Providers are useful for the following use cases:

You wish to break a cyclic dependency

You wish to lazily get a component instance (instead of it getting injected when your Component is looked up the first time)

You wish to control how you return the instance you're providing for. For example you may wish to read the Component Hint from a configuration file and return the instance of the Component matching that Hint dynamically

Providers are registered as standard components with the @Component , @Named and @Singleton annotations. However unlike other Components you don't need to tag any interface with @Role. All you need to do is implement javax.inject.Provider as shown in this example:

In this example the ConfiguredQueryExecutorProvider Provider is in charge of returning instances of QueryExecutor.

To use it you would get it injected as follows:

...@Injectprivate Provider<QueryExecutor> queryExecutorProvider;...

Note that you don't need to register a custom Provider to be able to get it injected. If no registered Provider is found the Component Manager injects a default Provider which simply does a lookup of the Component Role it provides using the Component Manager. This is very useful for "dynamic injection", i.e. the ability to lookup Components when you need them and not have them injected when your Component is first initialized. This allows your code to easily react to the registration of new Components at runtime.

Registering a Component with several Hints

You can register a component several times, for different hints. In this case several instances of the component will be registered. For example, to register our MessageMacro for the 3 hints info, error, warning you would use:

While this feature is still valid in 3.1+, in the future we'll either drop this feature (since there are workarounds) or we'll add the ability to specify several @Named annotations. We recommend to not start depending on this feature as much as possible to prevent future incompatibilities.

Registering a Component with several Roles

You can make a component providing several roles by implementing the corresponding interfaces. However note that each role will produce a different instance.

It is generally recommended to separate roles implementations in different classes as much as possible.

List and Map injections

You may want to have all the Component implementations of a given Component Interface injected. To do this you simply need to have a field of type List or Map defined.

For example to have all Macro implementations injected you'd use:

@Injectprivate List<Macro> macros;

or

@Injectprivate Map<String, Macro> macros;

In the second example the Map keys are the Hint values.

Getting access to the Component Manager

Component's ComponentManager

Automatic dependency injection is great and easy, but there are times when you don't know at compile time what you want injected. For these situations you can inject the ComponentManager. For example to get the ComponentManager in which the component is registered you can do:

@Injectprivate ComponentManager componentManager;

See below for the API available on ComponentManager.

Root Component Manager

Since 4.1.4 you can access the root ComponentManager the following way:

@Inject@Named("root")private ComponentManager componentManager;

Context Component Manager

Context Component Manager is a proxy Component Manager allowing to access a different Component Manager depending on the context (associated to the current wiki, the current user, etc.).

Since 4.1.4 you can access the context ComponentManager the following way:

but this is going to fail if no context ComponentManager can be found.

Overrides

Sometimes you'll have several JARs with Component implementations for the Component Interface and same Hint. In this case you need to tell the Component Manager which implementation to use. This is done by using a priority in your META-INF/components.txt files. The implementation with the highest priority will be used (highest means with the smaller value, 0 being the maximum priority and default priority is 1000 when not specified).

For example to register the com.acme.MyComponentImplementation component implementation with a priority of 500 you'd write:

500:com.acme.MyComponentImplementation

Prior to 3.3M1 we used to support overrides (which is still supported for backward compatibility) by creating a META-INF/component-overrides.txt file and listing the implementation to use (using the same format as for the components.txt file). The overriding Component needed to be defined in both files: META-INF/components.txt (because the new implementation was a component itself) and META-INF/component-overrides.txt.

Component Manager

The Component Manager is a key class when using Components. It allows you to lookup components and register new components programatically. Here's the API it offers:

You are then guaranteed that when your component is instantiated its initialize() method will be called.

Using a constructor doesn't always work since you might need dependency injections to be done prior to the initialization happening.

Don't use static to initialize variables in a component. First, using static is an anti pattern and we have the notion of Singleton in Components for that purpose. In addition if you do this then your component will get the static initialized when the Component Annotation Loader registers components instead of when your component is called the first time it's used, thus penalizing the startup cost of XWiki

Component Disposal

If your Component implementation needs to perform some cleanup when XWiki is stopped, you'll need to make it implement the org.xwiki.component.phase.Disposable interface. For example:

You are then guaranteed that when XWiki stops or when your extension is uninstalled, your component's dispose() method will be called.

The order used by the ComponentManager to dispose its components is computed based on declared dependencies.

XWiki 6.2.1+ However there might be cases when you wish a Component's dispose() method to be called before or after all other components. In this case you can use the DisposePriority annotation. The default priority is 1000. A higher value will mean disposing after all other components not having this annotation. For example:

@Component@Singleton@DisposePriority(10000)publicclassDefaultHibernateSessionFactoryimplements HibernateSessionFactory, Disposable{...@Overridepublicvoiddispose()throws ComponentLifecycleException{... called after other components in order to shut down the database late...}...}

Component Logging

If your Component implementation needed to log something it can get injected a SLF4J Logger automatically. For example:

Priori to 3.1, if your Component implementation needed to log something it would have needed to implement the org.xwiki.component.phase.LogEnabled interface. However in order to make it even easier we were providing a org.xwiki.component.logging.AbstractLogEnabled class that your component could simply extend.

Note that getInstance calls will return null if the Component cannot be looked up and the exception can be retrieved using services.component.lastError.

In Velocity getInstance methods are accessible since 6.1.

Now if you need to register a new Component implementation you'll need to get hold of the Component Manager in which you wish to register it (Root Component Manager or Component Manager specific to a given subwiki) by using the getComponentManager(String namespace) API.

For example to register your component in the Root Component Manager (i.e. it'll be visible from the main wiki and in all subwikis), you'd write in Groovy:

If you wish to override only some methods of an existing component you can use the Solution 1, by creating a class that extends the existing component's class and that overrides only the method you wish to modify. Then, you register your component over the existing one.

One advantage of Wiki Components (Solution 1) is that they are registered when XWiki starts, whereas if you choose Solution 2, you need to handle registration yourself. If you wish to use Solution 2 but still have your component registered at startup you'll need to implement an EventListener component and listen to the ApplicationReadyEvent or the WikiReadyEvent (for subwikis), and perform the component registration in the onEvent() method.

Component Events

There are several events related to Components that you could listen to, for example in order to execute some code whenever a component is registered:

org.xwiki.component.event.ComponentDescriptorAddedEvent: Event sent to tell that a new Component Descriptor has been registered.

org.xwiki.component.event.ComponentDescriptorRemovedEvent: Event sent to tell that a new Component Descriptor has been unregistered.

Tutorial

Internals

The default ComponentManager implementation is in EmbeddableComponentManager (in the xwiki-commons-component-default module). It's instantiated in the XWikiServletContextListener class (in the xwiki-platform-container-servlet module).