Wiki source code of Writing XWiki components

Version 38.1 by AreyouKiddingme on 2011/07/25

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
37.5	7	You should start by reading the [[Reference document on XWiki Components>>extensions:Extension.Component Module]].
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
37.5	17	As you've read in the [[XWiki Component Reference>>extensions:Extension.Component Module]] 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
37.4	19	After you've [[installed Maven and added XWiki repositories in your profile>>dev:Community.Building#HInstallingMaven]], open a shell prompt and type:
37.2	20
28.2	21	{{code language="none"}}
28.1	22	mvn archetype:generate -DarchetypeCatalog=http://svn.xwiki.org/svnroot/xwiki/platform/xwiki-tools/trunk/xwiki-archetypes/xwiki-archetype-component/archetype-catalog.xml
28.2	23	{{/code}}
1.1	24
38.1	25	{{info}}
	26	As of July, 2011, the svn version of source tree seems to be outdated, github (https://github.com/xwiki/) is rumored to be the correct place to look for the latest xwiki code. So you might try something like:
	27
	28	{{code language="none"}}
	29	mvn archetype:generate -DarchetypeCatalog=https://raw.github.com/xwiki/xwiki-platform/master/xwiki-platform-tools/xwiki-platform-tool-archetypes/xwiki-platform-tool-archetype-component/archetype-catalog.xml
	30	{{/code}}
	31
	32	However, I had no luck with the direct URL and after several attempts came to something like:
	33
	34	{{code language="none"}}
	35	wget https://raw.github.com/xwiki/xwiki-platform/master/xwiki-platform-tools/xwiki-platform-tool-archetypes/xwiki-platform-tool-archetype-component/archetype-catalog.xml
	36	mv archetype-catalog.xml /tmp
	37	mvn archetype:generate -DarchetypeCatalog=file:///tmp/archetype-catalog.xml
	38	{{/code}}
	39	{{/info}}
	40
28.1	41	Then follow the instructions. For example:
37.2	42
28.2	43	{{code language="none"}}
28.1	44	vmassol@target $ mvn archetype:generate -DarchetypeCatalog=http://svn.xwiki.org/svnroot/xwiki/platform/xwiki-tools/trunk/xwiki-archetypes/xwiki-archetype-component/archetype-catalog.xml
	45	[INFO] Scanning for projects...
	46	[INFO]
	47	[INFO] ------------------------------------------------------------------------
	48	[INFO] Building Maven Stub Project (No POM) 1
	49	[INFO] ------------------------------------------------------------------------
	50	[INFO]
	51	[INFO] >>> maven-archetype-plugin:2.0:generate (default-cli) @ standalone-pom >>>
	52	[INFO]
	53	[INFO] <<< maven-archetype-plugin:2.0:generate (default-cli) @ standalone-pom <<<
	54	[INFO]
	55	[INFO] --- maven-archetype-plugin:2.0:generate (default-cli) @ standalone-pom ---
	56	[INFO] Generating project in Interactive mode
	57	[INFO] No archetype defined. Using maven-archetype-quickstart (org.apache.maven.archetypes:maven-archetype-quickstart:1.0)
	58	Choose archetype:
	59	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.)
	60	Choose a number: : 1
	61	Downloading: http://maven.xwiki.org/snapshots/org/xwiki/platform/tools/xwiki-archetype-component/1.0-SNAPSHOT/maven-metadata.xml
	62	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)
	63	Downloading: http://maven.xwiki.org/snapshots/org/xwiki/platform/tools/xwiki-archetype-component/1.0-SNAPSHOT/maven-metadata.xml
	64	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)
	65	Define value for property 'groupId': : com.acme
	66	Define value for property 'artifactId': : example
	67	Define value for property 'version': 1.0-SNAPSHOT: :
	68	Define value for property 'package': com.acme: :
	69	Confirm properties configuration:
	70	groupId: com.acme
	71	artifactId: example
	72	version: 1.0-SNAPSHOT
	73	package: com.acme
	74	Y: : Y
	75	[INFO] ----------------------------------------------------------------------------
	76	[INFO] Using following parameters for creating project from Old (1.x) Archetype: xwiki-archetype-component:1.0-SNAPSHOT
	77	[INFO] ----------------------------------------------------------------------------
	78	[INFO] Parameter: groupId, Value: com.acme
	79	[INFO] Parameter: packageName, Value: com.acme
	80	[INFO] Parameter: package, Value: com.acme
	81	[INFO] Parameter: artifactId, Value: example
	82	[INFO] Parameter: basedir, Value: /Users/vmassol/dev/xwiki/trunks-clean4/platform/tools/xwiki-archetypes/target
	83	[INFO] Parameter: version, Value: 1.0-SNAPSHOT
	84	[INFO] ******************* End of debug info from resources from generated POM *********************
	85	[INFO] project created from Old (1.x) Archetype in dir: /Users/vmassol/dev/xwiki/trunks-clean4/platform/tools/xwiki-archetypes/target/example
	86	[INFO] ------------------------------------------------------------------------
	87	[INFO] BUILD SUCCESS
	88	[INFO] ------------------------------------------------------------------------
	89	[INFO] Total time: 12.868s
	90	[INFO] Finished at: Sun Nov 14 18:27:52 CET 2010
	91	[INFO] Final Memory: 9M/81M
	92	[INFO] ------------------------------------------------------------------------
	93	vmassol@target $
28.2	94	{{/code}}
1.1	95
28.2	96	Then go in the created directory (##example## in our example above) and run ##mvn install## to build your component.
1.1	97
29.1	98	== The Component explained ==
27.1	99
29.1	100	Assume, for the following explanations, that the package you used is ##com.acme##
26.1	101
29.1	102	Navigating in the component project folder, you will see the following standard Maven project structure:
26.1	103
30.1	104	{{code language="none"}}
1.1	105	pom.xml
29.1	106	src/main/java/com/acme/HelloWorld.java
	107	src/main/java/com/acme/internal/DefaultHelloWorld.java
33.1	108	src/main/java/com/acme/internal/HelloWorldScriptService.java
19.1	109	src/main/resources/META-INF/components.txt
29.1	110	src/test/java/com/acme/HelloWorldTest.java
26.1	111	{{/code}}
1.1	112
33.1	113	which correspond 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.
26.1	114
29.1	115	If you have a look in the ##pom.xml##, you'll notice the following dependencies:
26.1	116
30.1	117	{{code language="xml"}}
29.1	118	<dependencies>
1.1	119	<dependency>
	120	<groupId>org.xwiki.platform</groupId>
29.1	121	<artifactId>xwiki-core-component-default</artifactId>
1.1	122	<version>${platform.core.version}</version>
	123	</dependency>
29.1	124	<!-- Testing dependencies -->
1.1	125	<dependency>
29.1	126	<groupId>org.xwiki.platform</groupId>
	127	<artifactId>xwiki-core-shared-tests</artifactId>
	128	<version>${platform.core.version}</version>
1.1	129	<scope>test</scope>
29.1	130	</dependency>
1.1	131	</dependencies>
26.1	132	{{/code}}
27.1	133
29.1	134	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	135
26.1	136	The interface file (##HelloWorld.java##) contains the definition of a regular Java interface, and looks like this:
	137
30.1	138	{{code language="java"}}
29.1	139	@ComponentRole /* annotation used for declaring the service our component provides */
19.1	140	public interface HelloWorld
	141	{
	142	String sayHello();
	143	}
26.1	144	{{/code}}
1.1	145
29.1	146	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	147
26.1	148	Then we have the implementation of the interface, the ##DefaltHelloWorld## class.
23.1	149
30.1	150	{{code language="java"}}
29.1	151	@Component /* annotation used for declaring a component implementation */
	152	public class DefaultHelloWorld implements HelloWorld
26.1	153	{{/code}}
19.1	154
29.1	155	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	156
30.1	157	{{code language="java"}}
29.1	158	@Component("database")
	159	public class DatabaseHelloWorld implements HelloWorld
26.1	160	{{/code}}
27.1	161
29.1	162	Then the ##sayHello## in ##DefaultHelloWorld## is basic in this example:
26.1	163
30.1	164	{{code language="java"}}
19.1	165	/**
	166	* Says hello by returning a greeting to the caller.
	167	*
	168	* @return A greeting.
	169	*/
	170	public String sayHello()
	171	{
	172	return "Hello world!";
	173	}
26.1	174	{{/code}}
1.1	175
29.1	176	And now, the ##components.txt## file, in which component implementations present in this jar are specified for the ##ComponentManager## to register them.
1.1	177
30.1	178	{{code language="none"}}com.acme.internal.DefaultHelloWorld{{/code}}
1.1	179
27.1	180	= How to find my component and use it? =
24.1	181
27.1	182	== From other components ==
1.1	183
30.1	184	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.
27.1	185
30.1	186	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:
27.1	187
26.1	188	{{code}}
19.1	189	@Component
30.1	190	public class DefaultSocializer implements Socializer
1.1	191	{
	192	[...]
	193
	194	/** Will be injected by the component manager */
19.1	195	@Requirement
1.1	196	private HelloWorld helloWorld;
	197
	198	[...]
	199	}
26.1	200	{{/code}}
1.1	201
26.1	202	Note the ##@Requirement## annotation, which instructs the component manager to inject the required component where needed.
27.1	203
26.1	204	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	205
26.1	206	{{code}}
30.1	207	public class DefaultSocializer implements Socializer
1.1	208	{
	209	[...]
	210
	211	public void startConversation()
	212	{
	213	this.helloWorld.sayHello();
	214
	215	[...]
	216	}
	217
	218	[...]
	219	}
26.1	220	{{/code}}
1.1	221
26.1	222	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	223
	224	== From non-components java code (e.g. older plugins) ==
1.1	225
31.1	226	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.
30.2	227
31.1	228	To use our greetings provider component, we would simply invoke:
27.1	229
26.1	230	{{code}}
31.1	231	HelloWorld greeter = Utils.getComponent(HelloWorld.class);
1.1	232	greeter.sayHello();
26.1	233	{{/code}}
1.1	234
26.1	235	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	236
37.5	237	{{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 as described in the [[Component Module Reference>>extensions:Extension.Component Module]].{{/info}}
1.1	238
27.1	239	== From wiki pages ==
15.1	240
32.1	241	Components can be made accessible to wiki pages by writing a ##ScriptService## implementation. They can then be access using any provided scripting language (velocity, groovy, python, ruby, php, etc).
1.1	242
32.1	243	Let's make our ##sayHello## method accessible:
	244
	245	{{code language="java"}}
	246	@Component("hello")
	247	public class HelloWorldScriptService implements ScriptService
	248	{
	249	@Requirement
	250	private HelloWorld helloWorld;
	251
	252	public String greet()
	253	{
	254	return this.helloWorld.sayHello();
	255	}
	256	}
	257	{{/code}}
	258
	259	Notice the component hint used (the ##hello## part in the ##@Component##). This is the name under which the script service will be accessible from scripting languages.
	260
	261	For example to access it in velocity you'd write:
	262	{{code language="none"}}
	263	$services.hello.greet()
	264	{{/code}}
	265
	266	From Groovy:
	267	{{code language="none"}}
	268	services.hello.greet()
	269	{{/code}}
	270
34.1	271	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:
32.1	272	{{code language="none"}}
34.1	273	...
32.1	274	com.acme.internal.HelloWorldScriptService
	275	{{/code}}
	276
33.1	277	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:
	278	{{code language="xml"}}
	279	<dependency>
	280	<groupId>org.xwiki.platform</groupId>
	281	<artifactId>xwiki-core-script</artifactId>
	282	<version>${platform.core.version}</version>
	283	</dependency>
	284	{{/code}}
	285
35.1	286	= Accessing Legacy code =
1.1	287
35.1	288	By legacy we mean old XWiki code that hasn't been moved to components yet.
1.1	289
27.1	290	== The XWiki data model ==
1.1	291
26.1	292	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	293
26.1	294	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	295
26.1	296	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	297
26.1	298	For example:
1.1	299
26.1	300	{{code}}
19.1	301	@Component
1.1	302	public class DefaultHelloWorld implements HelloWorld
	303	{
	304	/** Provides access to documents. Injected by the Component Manager. */
19.1	305	@Requirement
1.1	306	private DocumentAccessBridge documentAccessBridge;
	307
	308	[...]
	309
	310	private String getConfiguredGreeting()
	311	{
	312	return documentAccessBridge.getProperty("XWiki.XWikiPreferences", "greeting_text");
	313	}
26.1	314	{{/code}}
1.1	315
27.1	316	== The XWiki context ==
1.1	317
26.1	318	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	319
26.1	320	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	321
26.1	322	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	323
26.1	324	{{code}}
	325	/** Provides access to the request context. Injected by the Component Manager. */
19.1	326	@Requirement
1.1	327	private Execution execution;
	328
	329	[...]
	330
	331	private void workWithTheContext()
	332	{
	333	ExecutionContext context = execution.getContext();
	334	// Do something with the execution context
	335	}
26.1	336	{{/code}}
1.1	337
26.1	338	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.
	339
	340	{{code}}
	341	private void workWithTheContext()
1.1	342	{
	343	ExecutionContext context = execution.getContext();
	344	Map<Object, Object> xwikiContext = (Map<Object, Object>) context.getProperty("xwikicontext");
	345	// Do something with the XWiki context
	346	}
26.1	347	{{/code}}
1.1	348
26.1	349	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	350
27.1	351	== Code outside components ==
1.1	352
26.1	353	You can use external libraries as in any other maven module, just declare the right dependencies in your module's ##pom.xml##.
27.1	354
26.1	355	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	356
26.1	357	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	358
1.1	359	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.
	360
35.1	361	= Deploying the Component =
1.1	362
32.1	363	Now that we have a functioning Component let's build it and deploy it to a XWiki Enterprise instance:
	364	* To build the component, issue ##mvn install##. This generates a JAR in the ##target## directory of your project.
	365	* 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.
	366
	367	Your component is now ready for service.
	368
	369	Enjoy!
	370

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