Writing XWiki Components

This tutorial guides you through the creation of a XWiki component, which is a way to extend or customize the XWiki platform. Indeed the XWiki platform is composed of components and it's possible to replace the default implementations with your own implementations. It's also possible to add new component implementations to extend the platform such as by implementing new Rendering Macros.

You should start by reading the Reference document on XWiki Components.

Let's get started!

Enough talking, let's see some code!

In the following tutorial we will guide you through writing a simple component, helping you to quickly get oriented in the XWiki components world and explaining how it works.

Creating a XWiki component using Maven

As you've read in the XWiki Component Reference writing a component is  a three-steps process (component interface, component implementation and registration of component).

To make it easier for you to get started, we have created a Maven Archetype to help create a simple component module with a single command. 

After you've installed Maven, open a shell prompt an type: mvn archetype:generate.

This will list all archetypes available on Maven Central. If instead you wish to directly use the XWiki Component Archetype, you can directly type (update the version to use the version you wish to use):

Then follow the instructions. For example:

Then go in the created directory (example in our example above) and run mvn install to build your component.

The Component explained

Assume, for the following explanations, that the package you used is com.acme

Navigating in the component project folder, you will see the following standard Maven project structure:

which corresponds to the default files created: the HelloWorld interface (a.k.a component role), its implementation DefaultHelloWorld (component implementation), a test class for this component HelloWorldTest, the component declaration file components.txt and the Maven project pom.xml file. The HelloWorldScriptService file is described below when we explain how to make the component's API available to wiki pages.

If you have a look in pom.xml you'll notice the following dependencies:

The code above defines the dependency on the xwiki-core-component-api in the core which is where XWiki Component notions are defined. There's also a dependency on xwiki-core-shared-tests which provides helper classes to easily test components.

The interface file (HelloWorld.java) contains the definition of a regular Java interface and looks like this: 

Keep in mind that this interface specifies the API that other components can use on your component. In our case, we'll build a polite component that can sayHello().

Then we have the implementation of the interface, the DefaultHelloWorld class. 

Note that optionally, there is a @Named annotation to specify a component hint. This is useful especially when we want to distinguish between several implementations for the same type of component. Image we had a special HelloWorld implementation taking the greeting message from a database; it could look like:

Then the sayHello in DefaultHelloWorld is basic in this example:

And now, the components.txt file, in which component implementations present in this jar are specified for the ComponentManager to register them.

How to find my component and use it?

From other components

To access your component from another component we use the components engine, and specify the dependencies, leaving instantiation and component injection to the be handled by the component manager.

In order to use the HelloWorld component, you need a reference to it in the the component that uses it. For this, you should use a member variable in the implementation of the using component, for example, a Socializer component will need to be able to say hello to the world:

Note the @Inject annotation, which instructs the component manager to inject the required component where needed.

And that's it, you can now use the helloWorld member anywhere in the DefaultSocializer class freely, without further concerns, it will be assigned by the component manager provided that the HelloWorld component is on the classpath at runtime when the Socializer is used. Such as:

More, note that all through the process of defining a communication path between two components, we never referred components implementations, all specifications being done through roles and interfaces: the implementation of a service is completely hidden from any code external to the component.

From non-components java code (e.g. older plugins)

For this kind of usages, since we cannot use the component-based architecture advantages and the "magic" of the component manager, the XWiki team has created a helper method that acts like a bridge between component code and non-component code, the com.xpn.xwiki.web.Utils.getComponent(String role, String hint) that gets the specified component instance from the component manager and returns it. As seen in the previous sections, the hint is an optional identifier, additional to role, used to differentiate between implementations of the same interface: the roles identify services while the hints help differentiate between implementations. The getComponent function also has a signature without the hint parameter, that uses the default hint.

To use our greetings provider component, we would simply invoke:

A component is represented by its interface, the implementation for such a service can be provided by any code, any class so relying on the implementation type is neither good practice (since the interface contract should be enough for a component), nor safe. In the future, a maven enforcer plugin will be setup in the build lifecycle, so that any reference to component implementations (located in an "internal" subpackage) will cause build errors.

From wiki pages

Components can be made accessible to wiki pages by writing a ScriptService implementation. They can then be accessed using any provided scripting language (velocity, groovy, python, ruby, php, etc).

Let's make our sayHello method accessible:

For example to access it in Velocity you'd write: $services.hello.greet().

From Groovy: services.hello.greet().

Now for our script service to work we need to register it as a component and thus add it to the META-INF/components.txt file:

We also need to make the Script Service infrastructure available in our classpath. This is done by adding the following in your pom.xml file:

Accessing Legacy code

By legacy we mean old XWiki code that hasn't been moved to components yet.

The XWiki data model

Since the XWiki data model (documents, objects, attachments, etc.) reside in the big, old xwiki-core module, and since we don't want to add the whole core and all its dependencies as a dependency of a simple lightweight component (this would eventually lead to a circular dependency, which is not allowed by maven), the current strategy, until the data model is completely turned into a component, is to use a bridge between the new component architecture and the old xwiki-core.

In short, the way this works is based on the fact that implementations for a component don't have to be in the same .jar as the interface, and there is no dependency from the component interface to the actual implementation, only the other way around. So, we made a few simple components that offer basic access to XWiki documents, and declare the classes in xwiki-core as the default implementation for those components.

If your component needs to access the XWiki data model, it will use the components from the xwiki-core-bridge module for that. Note that these interfaces are rather small, so you can't do everything that you could with the old model. If you need to add some methods to the bridge, feel free to propose it on the mailing list.

For example:

Querying the data model

Queries can be performed by using an instance of a QueryManager, which can be obtained and used as follows :

The XWiki context

Note that the XWiki context is deprecated. It was an older way of keeping track of the current request, which had to be passed around from method to method, looking like a ball and chain present everywhere in the code.

In the component world, the current request information is held in an execution context. This is actually more powerful than the old XWiki context, as it is a generic execution context, and you can create one anytime you want and use it anyway you want. And you don't have to manually pass it around with all method calls, as execution contexts are managed by the Execution component, which you can use just like any other XWiki component.

In short, if you want to get access to the execution context (which holds context information inserted by the new components), you must declare an injection point on the Execution component (located in the xwiki-commons-context module), and then you can write:

If you still need to access the old XWiki context, then you can get a reference to it from the execution context, but you should not cast it to an XWikiContext, which would pull the whole xwiki-core as a dependency, but to a Map. You won't be able to access all the properties, like the current user name or the URL factory, but you can access anything placed in the internal map of the XWikiContext.

If you want not just to use the execution context, but to make something available in every execution context, you can create an implementation of the ExecutionContextInitializer component, and populate newly created execution contexts, just like with velocity contexts.

Code outside components

You can use external libraries as in any other maven module, just declare the right dependencies in your module's pom.xml.

As a general rule, you should not work with any non-componentized XWiki code, as the way the old code was designed leads to an eventual dependency on the whole xwiki-core module, which we are trying to avoid. If the component you are writing is needed by other modules (which is the case with most components, since a component which isn't providing any usable/used services is kind of useless), then this will likely lead to an eventual cyclic dependency, which will break the whole build.

If you need some functionality from the old core, consider rewriting that part as a new component first, and then use that new component from your code. You should ask first on the devs mailing list, so that we can design and implement it collaboratively.

If the effort needed for this is too large, you can try creating a bridge component, by writing just the interfaces in a new module, and make the classes from the core the default implementation of those interfaces. Then, since in the end the xwiki-core, the bridge component and your component will reside in the same classpath, plexus will take care of coupling the right classes. Be careful when writing such bridges, as they are short lived (since in the end all the old code will be replaced by proper components), and if the future real component will have a different interface, then you will have to rewrite your code to adapt to the new method names, or worse, the new component logic.

Deploying the Component

Now that we have a functioning Component let's build it and deploy it to a XWiki Enterprise instance:

• To build the component, issue mvn install. This generates a JAR in the target directory of your project.
• To install it into a XWiki Enterprise instance, just copy that JAR file in XE_WAR_HOME/WEB-INF/lib where XE_WAR_HOME is where the XWiki Enterprise WAR is deployed.

Your component is now ready for service.

Enjoy!

See also

• Component Module