Wiki source code of Component Module

Version 4.1 by Vincent Massol on 2009/08/20 22:56
Show last authors
1 {{box cssClass="floatinginfobox" title="**Contents**"}}{{toc start="2" depth="3"/}}{{/box}}
2
3 = Component Module =
4
5 [[XWiki's Architecture>>platform:DevGuide.Architecture]] is based on [[Component-oriented Development>>http://en.wikipedia.org/wiki/Component-based_software_engineering]] (see also this [[Plexus Component Tutorial>>http://plexus.codehaus.org/ref/why-use-components.html]] to understand the benefits of using Components).
6
7 There are several Component Manager solutions out there for Java. To name a few:
8 * [[Guice>>http://code.google.com/p/google-guice/]]
9 * [[OSGi>>http://www.osgi.org/]]
10 * [[JSR291>>http://jcp.org/en/jsr/detail?id=291]], [[JSR277>>http://jcp.org/en/jsr/detail?id=277]], [[JSR294>>http://jcp.org/en/jsr/detail?id=294]], [[Project Jigsaw>>http://openjdk.java.net/projects/jigsaw/]]
11
12 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 with the idea to implement a [[Guice>>http://code.google.com/p/google-guice/]] bridge as soon as Guice starts implementing [[JSR299>>http://jcp.org/en/jsr/detail?id=299]]/[[JSR330>>http://jcp.org/en/jsr/detail?id=330]] annotations.
13
14 == Features ==
15
16 The Component Module defines the following features:
17 * Annotations to declare Component interfaces, Component implementations and Component dependencies (a.k.a as Component Requireements). Note that as soon as [[JSR299>>http://jcp.org/en/jsr/detail?id=299]]/[[JSR330>>http://jcp.org/en/jsr/detail?id=330]] become official we'll drop our annotations and use these instead.
18 * Ability to have Singleton Components and Per-lookup Components (a new instance is created when the component is retrieved)
19 * Ability to define a Hint to separate different Components implementations implementing the same Component interface.
20 * Automatic Field-based injection of Component Dependencies. Support for List and Map injections.
21 * Ability for Components to perform some initialization when they are instantiated.
22 * Ability for Components to log things.
23 * Component Events to be notified when a new Component is registered/unregistered in the system
24 * [Future] Ability to define Component Realms, i.e. the ability to isolate groups of components.
25
26 == Component Registration ==
27
28 There are two ways to register a Component:
29 * By setting Java Annotations on the Component Interface and the Component implementation and declaring the Component implementation in a ##META-INF/components.txt## file.
30 * By programatically registering the Component against the Component Manager instance.
31
32 === Using Annotations ===
33
34 The following Annotations are available:
35 * ##ComponentRole##: Used to declare an Interface as a Component Interface (a.k.a Role)
36 * ##Component##: Used to declare a class implementing a Component Interface as a Component implementation
37 * ##InstantiationStrategy##: Used to declare a Component implementation as being a singleton or not
38 * ##Requirement##: Used to declare a field as requiring a Component implementation to be injected at runtime
39
40 Here's a quick example:
41
42 {{code language="java"}}
43 @ComponentRole
44 public interface Macro
45 {
46 List<Block> execute();
47 }
48 {{/code}}
49
50 {{code language="java"}}
51 @Component("message")
52 public class MessageMacro implements Macro
53 {
54 @Requirement
55 private Execution execution;
56
57 @Requirement("box")
58 private Macro boxMacro;
59
60 public List<Block> execute()
61 {
62 ...
63 }
64 }
65 {{/code}}
66
67 In this example:
68 * The ##Macro## interface is the Component Interface
69 * 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.
70 * 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.
71
72 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:
73
74 {{code language="none"}}
75 org.xwiki.rendering.internal.macro.message.MessageMacro
76 {{/code}}
77
78 ==== List and Map injections ====
79
80 You may want to need 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 of Map defined.
81
82 For example to be injected all ##Macro## implementations you'd use:
83
84 {{code language="java"}}
85 @Requirement
86 private List<M acro> macros;
87 {{/code}}
88
89 or
90
91 {{code language="java"}}
92 @Requirement
93 private Map<String, Macro> macros;
94 {{/code}}
95
96 In the second example the Map keys are the Hint values.
97
98 ==== Getting access to the Component Manager ====
99
100 Automatic dependency injection is great and easy but there are time when you don't know at compile time what you want injected. For these situation you can have the ##ComponentManager## injected. For example:
101
102 {{code language="java"}}
103 @Requirement
104 private ComponentManager componentManager;
105 {{/code}}
106
107 See below for the API available on ##ComponentManager##.
108
109 ==== Overrides ====
110
111 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 creating a ##META-INF/component-overrides.txt## file and listing the implementation to use (using the same format as for the ##components.txt## file).
112
113 == Component Manager ==
114
115 The Component Manager is a key class when using Components. It allows to lookup components and register new components programatically. Here's the API it offers:
116
117 {{code language="java"}}
118 <T> boolean hasComponent(Class<T> role);
119 <T> boolean hasComponent(Class<T> role, String roleHint);
120 <T> T lookup(Class<T> role) throws ComponentLookupException;
121 <T> T lookup(Class<T> role, String roleHint) throws ComponentLookupException;
122 <T> void release(T component) throws ComponentLifecycleException;
123 <T> Map<String, T> lookupMap(Class<T> role) throws ComponentLookupException;
124 <T> List<T> lookupList(Class<T> role) throws ComponentLookupException;
125 <T> void registerComponent(ComponentDescriptor<T> componentDescriptor) throws ComponentRepositoryException;
126 <T> void registerComponent(ComponentDescriptor<T> componentDescriptor, T componentInstance) throws ComponentRepositoryException;
127 void unregisterComponent(Class< ? > role, String roleHint);
128 <T> ComponentDescriptor<T> getComponentDescriptor(Class<T> role, String roleHint);
129 <T> List<ComponentDescriptor<T>> getComponentDescriptorList(Class<T> role);
130 {{/code}}
131
132 There's only one instance of the Component Manager in the system.
133
134 Note that when you're writing a Component you normally don't even need to have access to it since all you need to do is declare dependencies using Annotations as explained above.
135
136 == Component Initialization ==
137
138 This is done by implementing the ##org.xwiki.component.phase.Initializable## interface. For example:
139
140 TODO
141
142 == Component Logging ==
143
144 TODO
145
146 == Tutorial ==
147
148 See the [["Writing a XWiki Component" tutorial>>platform:DevGuide.WritingComponents]].

About

About

Support

Platform

User Guide

Admin Guide

Developer Guide

Projects

XWiki

Extensions

Other

Contribute

Status

Practices

Under the Hood

Get Involved

Get Connected