Wiki source code of Writing XWiki components

Version 29.1 by Vincent Massol on 2010/11/14

version	line-number	content
27.1	1	{{box cssClass="floatinginfobox" title="Contents"}}{{toc/}}{{/box}}
1.1	2
28.1	3	This tutorial guides you through the creation of an 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>>DevGuide.RenderingMacroTutorial]].
1.1	4
28.1	5	{{info}}Components replace the older Plugin architecture which has been deprecated a while ago.{{/info}}
	6
26.1	7	You should start by reading the [[Reference document on XWiki Components>>code:Modules.ComponentModule]].
1.1	8
27.1	9	= Let's get started! =
1.1	10
	11	Enough talking, let's see some code!
	12
	13	In the followings we will guide you through writing a simple component, helping you to quickly get oriented in XWiki components world and explaining how it works.
	14
28.1	15	== Creating a XWiki component using Maven ==
1.1	16
28.1	17	As you've read in the [[XWiki Component Reference>>code:Modules.ComponentModule]] writing a component is a three-streps process (component interface, component implementation, 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.
26.1	18
28.1	19	After you've [installed Maven>http://dev.xwiki.org/xwiki/bin/view/Community/Building#HInstallingMaven], open a shell prompt an type:
28.2	20	{{code language="none"}}
28.1	21	mvn archetype:generate -DarchetypeCatalog=http://svn.xwiki.org/svnroot/xwiki/platform/xwiki-tools/trunk/xwiki-archetypes/xwiki-archetype-component/archetype-catalog.xml
28.2	22	{{/code}}
1.1	23
28.1	24	Then follow the instructions. For example:
28.2	25	{{code language="none"}}
28.1	26	vmassol@target $ mvn archetype:generate -DarchetypeCatalog=http://svn.xwiki.org/svnroot/xwiki/platform/xwiki-tools/trunk/xwiki-archetypes/xwiki-archetype-component/archetype-catalog.xml
	27	[INFO] Scanning for projects...
	28	[INFO]
	29	[INFO] ------------------------------------------------------------------------
	30	[INFO] Building Maven Stub Project (No POM) 1
	31	[INFO] ------------------------------------------------------------------------
	32	[INFO]
	33	[INFO] >>> maven-archetype-plugin:2.0:generate (default-cli) @ standalone-pom >>>
	34	[INFO]
	35	[INFO] <<< maven-archetype-plugin:2.0:generate (default-cli) @ standalone-pom <<<
	36	[INFO]
	37	[INFO] --- maven-archetype-plugin:2.0:generate (default-cli) @ standalone-pom ---
	38	[INFO] Generating project in Interactive mode
	39	[INFO] No archetype defined. Using maven-archetype-quickstart (org.apache.maven.archetypes:maven-archetype-quickstart:1.0)
	40	Choose archetype:
	41	1: http://svn.xwiki.org/svnroot/xwiki/platform/xwiki-tools/trunk/xwiki-archetypes/xwiki-archetype-component/archetype-catalog.xml -> xwiki-archetype-component (Make it easy to create a maven project for creating a XWiki Component.)
	42	Choose a number: : 1
	43	Downloading: http://maven.xwiki.org/snapshots/org/xwiki/platform/tools/xwiki-archetype-component/1.0-SNAPSHOT/maven-metadata.xml
	44	Downloaded: http://maven.xwiki.org/snapshots/org/xwiki/platform/tools/xwiki-archetype-component/1.0-SNAPSHOT/maven-metadata.xml (383 B at 3.4 KB/sec)
	45	Downloading: http://maven.xwiki.org/snapshots/org/xwiki/platform/tools/xwiki-archetype-component/1.0-SNAPSHOT/maven-metadata.xml
	46	Downloaded: http://maven.xwiki.org/snapshots/org/xwiki/platform/tools/xwiki-archetype-component/1.0-SNAPSHOT/maven-metadata.xml (383 B at 4.9 KB/sec)
	47	Define value for property 'groupId': : com.acme
	48	Define value for property 'artifactId': : example
	49	Define value for property 'version': 1.0-SNAPSHOT: :
	50	Define value for property 'package': com.acme: :
	51	Confirm properties configuration:
	52	groupId: com.acme
	53	artifactId: example
	54	version: 1.0-SNAPSHOT
	55	package: com.acme
	56	Y: : Y
	57	[INFO] ----------------------------------------------------------------------------
	58	[INFO] Using following parameters for creating project from Old (1.x) Archetype: xwiki-archetype-component:1.0-SNAPSHOT
	59	[INFO] ----------------------------------------------------------------------------
	60	[INFO] Parameter: groupId, Value: com.acme
	61	[INFO] Parameter: packageName, Value: com.acme
	62	[INFO] Parameter: package, Value: com.acme
	63	[INFO] Parameter: artifactId, Value: example
	64	[INFO] Parameter: basedir, Value: /Users/vmassol/dev/xwiki/trunks-clean4/platform/tools/xwiki-archetypes/target
	65	[INFO] Parameter: version, Value: 1.0-SNAPSHOT
	66	[INFO] ******************* End of debug info from resources from generated POM *********************
	67	[INFO] project created from Old (1.x) Archetype in dir: /Users/vmassol/dev/xwiki/trunks-clean4/platform/tools/xwiki-archetypes/target/example
	68	[INFO] ------------------------------------------------------------------------
	69	[INFO] BUILD SUCCESS
	70	[INFO] ------------------------------------------------------------------------
	71	[INFO] Total time: 12.868s
	72	[INFO] Finished at: Sun Nov 14 18:27:52 CET 2010
	73	[INFO] Final Memory: 9M/81M
	74	[INFO] ------------------------------------------------------------------------
	75	vmassol@target $
28.2	76	{{/code}}
1.1	77
28.2	78	Then go in the created directory (##example## in our example above) and run ##mvn install## to build your component.
1.1	79
29.1	80	== The Component explained ==
27.1	81
29.1	82	Assume, for the following explanations, that the package you used is ##com.acme##
26.1	83
29.1	84	Navigating in the component project folder, you will see the following standard Maven project structure:
26.1	85
	86	{{code}}
1.1	87	pom.xml
29.1	88	src/main/java/com/acme/HelloWorld.java
	89	src/main/java/com/acme/internal/DefaultHelloWorld.java
19.1	90	src/main/resources/META-INF/components.txt
29.1	91	src/test/java/com/acme/HelloWorldTest.java
26.1	92	{{/code}}
1.1	93
29.1	94	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.
26.1	95
29.1	96	If you have a look in the ##pom.xml##, you'll notice the following dependencies:
26.1	97
	98	{{code}}
29.1	99	<dependencies>
1.1	100	<dependency>
	101	<groupId>org.xwiki.platform</groupId>
29.1	102	<artifactId>xwiki-core-component-default</artifactId>
1.1	103	<version>${platform.core.version}</version>
	104	</dependency>
29.1	105	<!-- Testing dependencies -->
1.1	106	<dependency>
29.1	107	<groupId>org.xwiki.platform</groupId>
	108	<artifactId>xwiki-core-shared-tests</artifactId>
	109	<version>${platform.core.version}</version>
1.1	110	<scope>test</scope>
29.1	111	</dependency>
1.1	112	</dependencies>
26.1	113	{{/code}}
27.1	114
29.1	115	The code above defines the dependency on the ##xwiki-core-component-default## 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.
1.1	116
26.1	117	The interface file (##HelloWorld.java##) contains the definition of a regular Java interface, and looks like this:
	118
	119	{{code}}
29.1	120	@ComponentRole /* annotation used for declaring the service our component provides */
19.1	121	public interface HelloWorld
	122	{
	123	String sayHello();
	124	}
26.1	125	{{/code}}
1.1	126
29.1	127	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()##.
27.1	128
26.1	129	Then we have the implementation of the interface, the ##DefaltHelloWorld## class.
23.1	130
26.1	131	{{code}}
29.1	132	@Component /* annotation used for declaring a component implementation */
	133	public class DefaultHelloWorld implements HelloWorld
26.1	134	{{/code}}
19.1	135
29.1	136	Note that optionally, the ##@Component## annotation can specify a //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 lile:
26.1	137
	138	{{code}}
29.1	139	@Component("database")
	140	public class DatabaseHelloWorld implements HelloWorld
26.1	141	{{/code}}
27.1	142
29.1	143	Then the ##sayHello## in ##DefaultHelloWorld## is basic in this example:
26.1	144
	145	{{code}}
19.1	146	/**
	147	* Says hello by returning a greeting to the caller.
	148	*
	149	* @return A greeting.
	150	*/
	151	public String sayHello()
	152	{
	153	return "Hello world!";
	154	}
26.1	155	{{/code}}
1.1	156
29.1	157	And now, the ##components.txt## file, in which component implementations present in this jar are specified for the ##ComponentManager## to register them.
1.1	158
29.1	159	{{code}}com.acme.internal.DefaultHelloWorld{{/code}}
1.1	160
27.1	161	= How to find my component and use it? =
24.1	162
27.1	163	== From other components ==
1.1	164
	165	To access your component from another component we use the components engine, and specify the dependencies declarative, leaving instantiation and component injection to the be handled by the component manager. The most straightforward way is the use of the requirements mechanism of plexus, specifying that our component is required by the component that needs to access it.
27.1	166
	167	Don't forget that any code that uses the component we wrote needs to have the component interface accessible in its classpath. Even if instantiation and dependency is handled by the engine at runtime, the code still needs to compile. If the two components are not in the same module (the same .jar), don't forget to add the module of the greeter component as a dependency of the module of any component that uses it.
	168
26.1	169	Then, to effectively use the ##HelloWorld## component, we need a reference to it in the the component that uses it. For this, we 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:
1.1	170
26.1	171	{{code}}
19.1	172	@Component
1.1	173	public class DefaultSocializer extends AbstractLogEnabled implements Socializer, Initializable
	174	{
	175	[...]
	176
	177	/** Will be injected by the component manager */
19.1	178	@Requirement
1.1	179	private HelloWorld helloWorld;
	180
	181	[...]
	182	}
26.1	183	{{/code}}
1.1	184
26.1	185	Note the ##@Requirement## annotation, which instructs the component manager to inject the required component where needed.
27.1	186
26.1	187	The content of ##components.txt## should be updated with:
19.1	188
26.1	189	{{code}}org.xwiki.component.internal.DefaultSocializer{{/code}}
1.1	190
26.1	191	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:
1.1	192
26.1	193	{{code}}
1.1	194	public class DefaultSocializer extends AbstractLogEnabled implements Socializer, Initializable
	195	{
	196	[...]
	197
	198	public void startConversation()
	199	{
	200	this.helloWorld.sayHello();
	201
	202	[...]
	203	}
	204
	205	[...]
	206	}
26.1	207	{{/code}}
1.1	208
26.1	209	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.
27.1	210
1.1	211	TODO: refer to the other ways of implementing dependencies but requirements mechanism. Details, explanations, links.
	212
27.1	213	== From non-components java code (e.g. older plugins) ==
1.1	214
26.1	215	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 (see more at [[http://plexus.codehaus.org/guides/developer-guide/building-components/component-identity.html>>http://plexus.codehaus.org/guides/developer-guide/building-components/component-identity.html]]). The ##getComponent## function also has a version without the ##hint## parameter, that uses the default hint.
27.1	216
26.1	217	To use our greetings provider component, we simply invoke:
1.1	218
26.1	219	{{code}}
19.1	220	HelloWorld greeter = (HelloWorld) Utils.getComponent(HelloWorld.class);
1.1	221	//use the HelloWorld service
	222	greeter.sayHello();
26.1	223	{{/code}}
1.1	224
26.1	225	Note that, even if, in fact, the object returned by this function is an instance of the DefaultHelloWorld, you should never declare your object of the implementation type nor cast to implementation instead of interface. 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.
27.1	226
26.1	227	{{info}}The usage of ##Utils.getComponent()## functions is highly discouraged, reserved for this type of situations, when you need to access a component from non-componentized code. For the componentized code, you should use either dependency declaration at 'compile-time' (as shown before with annotations) or, if you need to resolve components dependencies at runtime, use the ComponentManager, which you can access by implementing the Composable interface described above.{{/info}}
1.1	228
27.1	229	== From wiki pages ==
15.1	230
1.1	231	In order to use a component in wiki pages, we need to expose it to the scripting environments: groovy and velocity.
	232
27.1	233	=== Accessing a component from groovy ===
1.1	234
26.1	235	Since, in groovy, we have access to all classes and functions in XWiki (all this protected by the requirement for programming rights), it means that we can use the same method as in [[the previous section>>WritingComponents#HFromnoncomponentsjavacode28egolderplugins29]], using the ##Utils## class. A simple page that would print the greeting from the ##HelloWorld## component would look like this (of course, with your own package for the HelloWorld interface):
1.1	236
26.1	237	{{code}}
1.1	238	<%
19.1	239	def greeter = com.xpn.xwiki.web.Utils.getComponent(org.xwiki.component.HelloWorld.class);
1.1	240	println greeter.sayHello();
	241	%>
26.1	242	{{/code}}
1.1	243
	244	TODO: talk about the future plans (?) to make a component accessible in the groovy context through a groovy bridge.
	245
27.1	246	=== Accessing a component from velocity ===
1.1	247
	248	XWiki dev team is currently working on the design of a VelocityBridge interface that will handle components access from velocity. Until this specification is ready and its first implementation done, we can do it as follows:
	249
27.1	250	We write another component in our package, that implements the [[##VelocityContextInitializer##>>http://svn.xwiki.org/svnroot/xwiki/platform/core/trunk/xwiki-velocity/src/main/java/org/xwiki/velocity/VelocityContextInitializer.java]], which is responsible for the initialization of the velocity context in XWiki through its method ##initialize(VelocityContext context)##, called automatically when a new velocity context is created. As you probably guessed, we will use this function to add our ##HelloWorld## component to the velocity context.
	251
26.1	252	{{code}}
21.4	253	@Component("helloWorld")
1.1	254	public class HelloWorldVelocityContextInitializer implements VelocityContextInitializer
	255	{
	256	/** The key to add to the velocity context */
	257	public static final String VELOCITY_CONTEXT_KEY = "greeter";
	258
	259	/** The component instance to add to the velocity context, injected by the component manager */
19.2	260	@Requirement
1.1	261	private HelloWorld helloWorld;
	262
	263	/**
	264	* Add the component instance to the velocity context received as parameter.
	265	*/
	266	public void initialize(VelocityContext context)
	267	{
	268	context.put(VELOCITY_CONTEXT_KEY, this.helloWorld);
	269	}
	270	}
26.1	271	{{/code}}
1.1	272
26.1	273	The result of this will be the availability of the ##HelloWorld## instance in velocity through the key //greeter// (as in ##$greeter.sayHello()##).
27.1	274
26.1	275	This instance of ##HelloWorld## will be injected by the component manager in the ##helloWorld## member, due to the ##@Requirement## annotation.
27.1	276
26.1	277	In order to have the ##VelocityContextInitializer## component accessible to the component manager, therefore initialized indeed when a velocity context is created, we specify it as a component in the ##components.txt## file (in our case, the same file where we have ##DefaultHelloWorld## component):
1.1	278
26.1	279	{{code}}
25.1	280	[...]
	281	org.component.internal.vcinitializer.HelloWorldVelocityContextInitializer
26.1	282	{{/code}}
1.1	283
26.1	284	Note that this time, we specify a hint for component identification, because we need to differentiate this implementation of the ##VelocityContextInitializer## from the other implementations, as it is not the only component with this role in XWiki.
27.1	285
26.1	286	Of course, in order to for all this to compile, we need to have the ##VelocityContextInitializer## interface available on the classpath so we have this new dependency in the component module's pom:
1.1	287
26.1	288	{{code}}
	289	<dependency>
1.1	290	<groupId>org.xwiki.platform</groupId>
	291	<artifactId>xwiki-core-velocity</artifactId>
	292	<version>${platform.core.version}</version>
	293	</dependency>
26.1	294	{{/code}}
1.1	295
26.1	296	And that's it, you have made your ##HelloWorld## component velocity-accessible! Just recompile your package, copy it in the WEB-INF/lib folder of your xwiki webbapp container, and restart the server. You'll be able to get a greeting in velocity through:
1.1	297
26.1	298	{{code}}$greeter.sayHello(){{/code}}
1.1	299
27.1	300	For the automatic creation of a velocity accessible xwiki component through this method, we have also created a maven archetype for this purpose too, the [[xwiki-archetype-velocity-component-1.0-SNAPSHOT.jar>>attach:xwiki-archetype-velocity-component-1.0-SNAPSHOT.jar]]. Download it and use it as described in [[the first part of this tutorial>>WritingComponents#HCreatingaXWikicomponentusingmaven]].
1.1	301
27.1	302	= How do I find other code? =
1.1	303
27.1	304	== The XWiki data model ==
1.1	305
26.1	306	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##.
27.1	307
26.1	308	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 declared the classes in ##xwiki-core## as the default implementation for those components.
27.1	309
26.1	310	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>>dev:Community.MailingLists]].
27.1	311
26.1	312	For example:
1.1	313
26.1	314	{{code}}
19.1	315	@Component
1.1	316	public class DefaultHelloWorld implements HelloWorld
	317	{
	318	/** Provides access to documents. Injected by the Component Manager. */
19.1	319	@Requirement
1.1	320	private DocumentAccessBridge documentAccessBridge;
	321
	322	[...]
	323
	324	private String getConfiguredGreeting()
	325	{
	326	return documentAccessBridge.getProperty("XWiki.XWikiPreferences", "greeting_text");
	327	}
26.1	328	{{/code}}
1.1	329
27.1	330	== The XWiki context ==
1.1	331
26.1	332	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>>http://en.wikipedia.org/wiki/Ball_and_chain]] present everywhere in the code.
27.1	333
26.1	334	In the component world, the current request information is held in an [[execution context>>http://maven.xwiki.org/site/xwiki-core-parent/xwiki-core-context/apidocs/org/xwiki/context/ExecutionContext.html]]. 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>>http://maven.xwiki.org/site/xwiki-core-parent/xwiki-core-context/apidocs/org/xwiki/context/Execution.html]], which you can use just like any other XWiki component.
27.1	335
26.1	336	In short, if you want to get access to the execution context (which holds context information inserted by the new components), you must declare a requirement on the ##Execution## component (located in the ##xwiki-core-context## module), and then you can write:
1.1	337
26.1	338	{{code}}
	339	/** Provides access to the request context. Injected by the Component Manager. */
19.1	340	@Requirement
1.1	341	private Execution execution;
	342
	343	[...]
	344
	345	private void workWithTheContext()
	346	{
	347	ExecutionContext context = execution.getContext();
	348	// Do something with the execution context
	349	}
26.1	350	{{/code}}
1.1	351
26.1	352	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.
	353
	354	{{code}}
	355	private void workWithTheContext()
1.1	356	{
	357	ExecutionContext context = execution.getContext();
	358	Map<Object, Object> xwikiContext = (Map<Object, Object>) context.getProperty("xwikicontext");
	359	// Do something with the XWiki context
	360	}
26.1	361	{{/code}}
1.1	362
26.1	363	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>>http://maven.xwiki.org/site/xwiki-core-parent/xwiki-core-context/apidocs/org/xwiki/context/ExecutionContextInitializer.html]] component, and populate newly created execution contexts, just like with [[velocity contexts>>#HAccessingacomponentfromvelocity]].
1.1	364
27.1	365	== Code outside components ==
1.1	366
26.1	367	You can use external libraries as in any other maven module, just declare the right dependencies in your module's ##pom.xml##.
27.1	368
26.1	369	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.
27.1	370
26.1	371	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>>dev:Community.MailingLists]], so that we can design and implement it collaboratively.
27.1	372
1.1	373	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.
	374
27.1	375	= Deploying and using the component =
1.1	376
27.1	377	In order to have your component work with XWiki, build the maven module, and find the produced .jar in the target folder. Copy this .jar to the /WEB-INF/lib folder of your wiki instance, restart the servlet container and you're done: you should be able to access your component from velocity or groovy code, and other potential components depending on it should be able to look it up.

Wiki source code of Writing XWiki components

Quick Links

Navigation

About

About

Support

Platform

User Guide

Admin Guide

Developer Guide

Projects

XWiki

Extensions

Other

Contribute

Status

Practices

Under the Hood

Get Involved

Get Connected