Gitiles
Code Review Sign In
gerrit.onosproject.org / onos-felix / 8251f6064f6c9de65a2b72bb0a803d855ba13ac5 / . / ipojo / annotations / doc / how-to-use-ipojo-annotations.html
blob: cb9e468af412aef75f4dae82149d2e94ef789840 [file] [log] [blame]
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]1<!DOCTYPE HTML PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame^]2<html><head>
3
4
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]5
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame^]6 <title>Apache Felix - How to use iPOJO Annotations</title>
7 <link rel="stylesheet" href="how-to-use-ipojo-annotations_files/site.css" type="text/css" media="all">
8 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
9 </head><body>
10 <div class="title"><div class="logo"><a href="http://felix.apache.org/site/index.html"><img alt="Apache Felix" src="how-to-use-ipojo-annotations_files/logo.png" border="0"></a></div><div class="header"><a href="http://www.apache.org/"><img alt="Apache" src="how-to-use-ipojo-annotations_files/apache.png" border="0"></a></div></div>
11 <div class="menu">
12<ul>
13 <li><a href="http://felix.apache.org/site/news.html" title="news">news</a></li>
14 <li><a href="http://felix.apache.org/site/license.html" title="license">license</a></li>
15 <li><span class="nobr"><a href="http://felix.apache.org/site/downloads.cgi" title="Visit page outside Confluence" rel="nofollow">downloads<sup><img class="rendericon" src="how-to-use-ipojo-annotations_files/linkext7.gif" alt="" align="absmiddle" border="0" width="7" height="7"></sup></a></span></li>
16 <li><a href="http://felix.apache.org/site/documentation.html" title="documentation">documentation</a></li>
17 <li><a href="http://felix.apache.org/site/mailinglists.html" title="mailinglists">mailing lists</a></li>
18 <li><a href="http://felix.apache.org/site/contributing.html" title="Contributing">contributing</a></li>
19 <li><span class="nobr"><a href="http://www.apache.org/" title="Visit page outside Confluence" rel="nofollow">asf<sup><img class="rendericon" src="how-to-use-ipojo-annotations_files/linkext7.gif" alt="" align="absmiddle" border="0" width="7" height="7"></sup></a></span></li>
20 <li><span class="nobr"><a href="http://www.apache.org/foundation/sponsorship.html" title="Visit page outside Confluence" rel="nofollow">sponsorship<sup><img class="rendericon" src="how-to-use-ipojo-annotations_files/linkext7.gif" alt="" align="absmiddle" border="0" width="7" height="7"></sup></a></span></li>
21 <li><span class="nobr"><a href="http://www.apache.org/foundation/thanks.html" title="Visit page outside Confluence" rel="nofollow">sponsors<sup><img class="rendericon" src="how-to-use-ipojo-annotations_files/linkext7.gif" alt="" align="absmiddle" border="0" width="7" height="7"></sup></a></span>
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]22<!-- ApacheCon Ad -->
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame^]23<iframe src="how-to-use-ipojo-annotations_files/button.html" style="border-width: 0pt; float: left;" scrolling="no" width="135" frameborder="0" height="135"></iframe>
24<p style="height: 100px;">
25<!-- ApacheCon Ad -->
26</p></li></ul> </div>
27 <div class="main">
28<table class="sectionMacro" border="0" cellpadding="5" cellspacing="0" width="100%"><tbody><tr>
29<td class="confluenceTd" valign="top" width="80%">
30<p>iPOJO defines several annotations to help developer to define their
31components. This page presents an example of iPOJO annotation and
32describes provided annotations.</p>
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]33
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame^]34<h1><a name="HowtouseiPOJOAnnotations-GettingiPOJOAnnotations:"></a>Getting iPOJO Annotations:</h1>
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]35
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame^]36<p>iPOJO Annotations are defines inside the
37org.apache.felix.ipojo.annotations project. You can download the Jar
38file of this project from the <a href="http://felix.apache.org/site/download.html" title="Download">download</a> page. Sources are available on the <span class="nobr"><a href="http://felix.apache.org/site/sourcecode.html" title="Visit page outside Confluence" rel="nofollow">Felix trunk<sup><img class="rendericon" src="how-to-use-ipojo-annotations_files/linkext7.gif" alt="" align="absmiddle" border="0" width="7" height="7"></sup></a></span>.<br>
39Once added to your class path / build path / dependencies, you can use
40the annotations as normal annotations. These annotations are
41automatically processed by the iPOJO manipulator.</p>
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]42
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame^]43<h2><a name="HowtouseiPOJOAnnotations-InEclipse:"></a>In Eclipse:</h2>
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]44
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame^]45<p>Add the org.apache.felix.ipojo.annotations jar file in your build
46path. Do not forget to use a Java compiler accepting annotations (1.5
47or higher).</p>
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]48
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame^]49<h2><a name="HowtouseiPOJOAnnotations-InMaven:"></a>In Maven:</h2>
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]50
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame^]51<p>Add the following dependency:</p>
52<div class="code"><div class="codeContent">
53<pre class="code-xml"><span class="code-tag">&lt;dependency&gt;</span>
54 <span class="code-tag">&lt;groupId&gt;</span>org.apache.felix<span class="code-tag">&lt;/groupId&gt;</span>
55 <span class="code-tag">&lt;artifactId&gt;</span>org.apache.felix.ipojo.annotations<span class="code-tag">&lt;/artifactId&gt;</span>
56 <span class="code-tag">&lt;version&gt;</span>1.0.0<span class="code-tag">&lt;/version&gt;</span>
57<span class="code-tag">&lt;/dependency&gt;</span></pre>
58</div></div>
59<p>Moreover, you need to set that the source code and the target code
60are Java 1.5 code. To achieve this, just add the following plugin in
61your plugins section:</p>
62<div class="code"><div class="codeContent">
63<pre class="code-xml"><span class="code-tag">&lt;plugin&gt;</span>
64 <span class="code-tag">&lt;groupId&gt;</span>org.apache.maven.plugins<span class="code-tag">&lt;/groupId&gt;</span>
65 <span class="code-tag">&lt;artifactId&gt;</span>maven-compiler-plugin<span class="code-tag">&lt;/artifactId&gt;</span>
66 <span class="code-tag">&lt;configuration&gt;</span>
67 <span class="code-tag">&lt;source&gt;</span>1.5<span class="code-tag">&lt;/source&gt;</span>
68 <span class="code-tag">&lt;target&gt;</span>1.5<span class="code-tag">&lt;/target&gt;</span>
69 <span class="code-tag">&lt;/configuration&gt;</span>
70<span class="code-tag">&lt;/plugin&gt;</span></pre>
71</div></div>
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]72
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame^]73<h2><a name="HowtouseiPOJOAnnotations-InAnt:"></a>In Ant :</h2>
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]74
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame^]75<p>Just add the org.apache.felix.ipojo.annotations jar file in your class path.</p>
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]76
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame^]77<h1><a name="HowtouseiPOJOAnnotations-Anexampleofusage:"></a>An example of usage:</h1>
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]78
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame^]79<p>To illustrate annotations usage, let taking the tutorial example. In this tutorial, there are two components:</p>
80<ul>
81 <li>The first one provides the hello service</li>
82 <li>The second one uses the provided hello service<br>
83You can download the archive containing the examples and a preconfigured version of Felix <span class="nobr"><a href="http://people.apache.org/%7Eclement/ipojo/tutorials/annotations/annotation-tutorial.zip" title="Visit page outside Confluence" rel="nofollow">here<sup><img class="rendericon" src="how-to-use-ipojo-annotations_files/linkext7.gif" alt="" align="absmiddle" border="0" width="7" height="7"></sup></a></span>.</li>
84</ul>
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]85
86
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame^]87<h2><a name="HowtouseiPOJOAnnotations-HelloServiceProvider"></a>Hello Service Provider</h2>
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]88
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame^]89<p>The provider uses two annotations. The "component" annotation is
90mandatory and defines that the class defines a component type. Then the
91"provides" annotation just declare that the defined component type
92provides a service.</p>
93<div class="code"><div class="codeContent">
94<pre class="code-java"><span class="code-keyword">package</span> ipojo.example.hello.impl;
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]95
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame^]96<span class="code-keyword">import</span> ipojo.example.hello.Hello;
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]97
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame^]98<span class="code-keyword">import</span> org.apache.felix.ipojo.annotations.Component;
99<span class="code-keyword">import</span> org.apache.felix.ipojo.annotations.Provides;
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]100
101/**
102 * Component implementing the Hello service.
103 **/
104@Component
105@Provides
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame^]106<span class="code-keyword">public</span> class HelloImpl <span class="code-keyword">implements</span> Hello {
107 <span class="code-keyword">public</span> <span class="code-object">String</span> sayHello(<span class="code-object">String</span> name) {
108 <span class="code-keyword">return</span> <span class="code-quote">"hello "</span> + name;
Clement Escoffier83507512008-10-13 07:33:03 +0000[diff] [blame]109 }
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame^]110}</pre>
111</div></div>
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]112
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame^]113<h2><a name="HowtouseiPOJOAnnotations-HelloServiceConsumer"></a>Hello Service Consumer</h2>
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]114
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame^]115<p>The Hello Service Consumer use more annotations. First it used the
116component annotation. To defines its "immediate" behavior, it add the
117'immediate' attribute.<br>
118Then, it uses the requires annotation to define a service dependency.
119Finally, it uses the validate and invalidate annotations to define
120lifecycle callbacks.</p>
121<div class="code"><div class="codeContent">
122<pre class="code-java"><span class="code-keyword">package</span> ipojo.example.hello.client;
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]123
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame^]124<span class="code-keyword">import</span> org.apache.felix.ipojo.annotations.Component;
125<span class="code-keyword">import</span> org.apache.felix.ipojo.annotations.Invalidate;
126<span class="code-keyword">import</span> org.apache.felix.ipojo.annotations.Requires;
127<span class="code-keyword">import</span> org.apache.felix.ipojo.annotations.Validate;
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]128
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame^]129<span class="code-keyword">import</span> ipojo.example.hello.Hello;
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]130
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame^]131@Component(name=<span class="code-quote">"AnnotedHelloClient"</span>, immediate=<span class="code-keyword">true</span>)
132<span class="code-keyword">public</span> class HelloClient <span class="code-keyword">implements</span> <span class="code-object">Runnable</span> {
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]133
134@Requires
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame^]135<span class="code-keyword">private</span> Hello[] m_hello; <span class="code-comment">// Service Dependency
136</span>
137<span class="code-keyword">private</span> <span class="code-keyword">final</span> <span class="code-keyword">static</span> <span class="code-object">int</span> DELAY=10000;
138<span class="code-keyword">private</span> <span class="code-object">boolean</span> end;
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]139
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame^]140 <span class="code-keyword">public</span> void run() {
141 <span class="code-keyword">while</span> (!end) {
142 <span class="code-keyword">try</span> {
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]143 invoke();
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame^]144 <span class="code-object">Thread</span>.sleep(DELAY);
145 } <span class="code-keyword">catch</span> (InterruptedException ie) { }
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]146 /* will recheck end */
147 }
148}
149
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame^]150<span class="code-keyword">public</span> void invoke() {
151 <span class="code-keyword">for</span> (<span class="code-object">int</span> i = 0; i &lt; m_hello.length; i++) {
152 <span class="code-object">System</span>.out.println(m_hello[i].
153 sayHello(<span class="code-quote">"Clement"</span>));
Clement Escoffier83507512008-10-13 07:33:03 +0000[diff] [blame]154 }
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]155}
156
157 @Validate
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame^]158 <span class="code-keyword">public</span> void starting() {
159 <span class="code-object">Thread</span> T = <span class="code-keyword">new</span> <span class="code-object">Thread</span>(<span class="code-keyword">this</span>);
160 end = <span class="code-keyword">false</span>;
Clement Escoffier83507512008-10-13 07:33:03 +0000[diff] [blame]161 T.start();
162 }
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]163
164 @Invalidate
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame^]165 <span class="code-keyword">public</span> void stopping() {
166 end = <span class="code-keyword">true</span>;
Clement Escoffier83507512008-10-13 07:33:03 +0000[diff] [blame]167 }
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame^]168}</pre>
169</div></div>
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]170
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame^]171<h1><a name="HowtouseiPOJOAnnotations-DefinedAnnotations"></a>Defined Annotations</h1>
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]172
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame^]173<p>This section lists defined annotations and how to use them.</p>
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]174
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame^]175<h2><a name="HowtouseiPOJOAnnotations-@Component"></a>@Component</h2>
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]176
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame^]177<p><b>Goal:</b> Defines a component type<br>
178<b>Target:</b> The component implementation class<br>
179<b>Attributes:</b></p>
180<ul>
181 <li>name : defines the component type name (optional, default = the class name)</li>
182 <li>factory: defines the factory name (optional, default = "false")</li>
183 <li>immediate: defines the component type as immediate (optional, default = "false")</li>
184 <li>architecture: enable the architecture exposition (optional, default = "false")</li>
185 <li>propagation: enable configuration property propagation (on provided services) (optional, default = "false")</li>
186</ul>
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]187
188
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame^]189<h2><a name="HowtouseiPOJOAnnotations-@Provides"></a>@Provides</h2>
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]190
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame^]191<p><b>Goal:</b> Defines that the component type provide services<br>
192<b>Target:</b> The component implementation class<br>
193<b>Attributes:</b></p>
194<ul>
195 <li>specifications: defines the provided interface (optional, default = all implemented interfaces)</li>
196 <li>factory: defines the service object creation policy ("SINGLETON" or "SERVICE") (optional, default = "SINGLETON")</li>
197 <li><b>[1.1.0-SNAPSHOT]</b> the <tt>factory</tt> attribute became <tt>strategy</tt>. A third policy is now available (<tt>instance</tt>) allowing to create one service object per asking instance. Moreover, it is also possible to indicates the <tt>CreationStrategy</tt> class name.</li>
198</ul>
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]199
200
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame^]201<p><em>Note:</em> "SERVICE" means OSGi service factory.</p>
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]202
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame^]203<h2><a name="HowtouseiPOJOAnnotations-@Requires"></a>@Requires</h2>
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]204
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame^]205<p><b>Goal:</b> Defines a service dependency<br>
206<b>Target:</b> Field<br>
207<b>Attributes:</b></p>
208<ul>
209 <li>Filter: defines the LDAP filter (optional)</li>
210 <li>Optional: defines if the dependency is optional (optional, default = "false")</li>
211 <li>Id:
212defines the dependency Id (useful to identify bind &amp; unbind
213methods) (optional, default = field name) (if a dependency with the
214same id is already created (by a @bind or @unbind annotation), it
215merges the dependencies).</li>
216 <li>Nullable: enable or disable the
217Null Object injection when the dependency is optional and no providers
218are available (optional, default = "true")</li>
219 <li>Default-Implementation: set the Default-Implmentation (optional, by default iPOJO uses a Null object)</li>
220 <li>Policy: defines the binding policy (accepted value : dynamic, static, dynamic-priority) (optional, default = "dynamic")</li>
221 <li>Comparator: defines the comparator to use to sort service references (optional, default = OSGi Service Reference Comparator)</li>
222 <li>From : defines the specific provider to use</li>
223</ul>
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]224
225
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame^]226<h2><a name="HowtouseiPOJOAnnotations-@ServiceProperty"></a>@ServiceProperty</h2>
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]227
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame^]228<p><b>Goal:</b> Defines a service property<br>
229<b>Target:</b> Field<br>
230<b>Attributes:</b></p>
231<ul>
232 <li>name: property name (optional, default=field name</li>
233 <li>value: property value (optional, default=no value)</li>
234</ul>
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]235
236
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame^]237<h2><a name="HowtouseiPOJOAnnotations-@Property"></a>@Property</h2>
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]238
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame^]239<p><b>Goal:</b> Defines a property<br>
240<b>Target:</b> Field or Method<br>
241<b>Attributes:</b></p>
242<ul>
243 <li>name: property name (optional, default=field name computed by
244removing "set" from the method name (for instance setFoo(String ff)
245will get the Foo name))</li>
246 <li>value: property value (optional, default=no value)</li>
247</ul>
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]248
249
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame^]250<p><em>note:</em> if another property with the same name is defined the method or the field is added to the existing property</p>
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]251
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame^]252<h2><a name="HowtouseiPOJOAnnotations-@Bind"></a>@Bind</h2>
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]253
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame^]254<p><b>Goal:</b> Defines a bind method<br>
255<b>Target:</b> Method<br>
256<b>Attributes:</b></p>
257<ul>
258 <li>Id: Dependency Id, if the id is already defines in a
259"@requires " or "@unbind" annotation, it adds this method as a bind
260method of the already created dependency. (optional, default= no id,
261compute an id if the method name begin by "bind" (for instance
262"bindFoo" will have the "Foo" id))</li>
263 <li>Specification : required dependency (optional)</li>
264 <li>Aggregate : is the dependency an aggregate dependency (optional, default= "false")</li>
265 <li>Optional: is the dependency an optional dependency (optional, default= "false")</li>
266 <li>Filter: dependency LDAP filter (optional)</li>
267 <li>Policy: defines the binding policy (accepted value : dynamic, static, dynamic-priority) (optional, default = "dynamic")</li>
268 <li>Comparator: defines the comparator to use to sort service references (optional, default = OSGi Service Reference Comparator)</li>
269 <li>From : defines the specific provider to use</li>
270</ul>
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]271
272
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame^]273<h2><a name="HowtouseiPOJOAnnotations-@Unbind"></a>@Unbind</h2>
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]274
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame^]275<p><b>Goal:</b> Defines an unbind method<br>
276<b>Target:</b> Method<br>
277<b>Attributes:</b></p>
278<ul>
279 <li>Id: Dependency Id, if the id is already defines in a
280"@requires" or "@bind" annotation, it adds this method as an unbind
281method of the already created dependency. (optional, default= no id,
282compute an id if the method name begin by "unbind" (for instance
283"unbindFoo" will have the "Foo" id))</li>
284 <li>Specification : required dependency (optional)</li>
285 <li>Aggregate : is the dependency an aggregate dependency (optional, default= "false")</li>
286 <li>Optional: is the dependency an optional dependency (optional, default= "false")</li>
287 <li>Filter: dependency LDAP filter (optional)</li>
288 <li>Policy: defines the binding policy (accepted value : dynamic, static, dynamic-priority) (optional, default = "dynamic")</li>
289 <li>Comparator: defines the comparator to use to sort service references (optional, default = OSGi Service Reference Comparator)</li>
290 <li>From : defines the specific provider to use</li>
291</ul>
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]292
293
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame^]294<h2><a name="HowtouseiPOJOAnnotations-@Validate"></a>@Validate</h2>
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]295
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame^]296<p><b>Goal:</b> defines a validate lifecycle callback<br>
297<b>Target:</b> method</p>
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]298
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame^]299<h2><a name="HowtouseiPOJOAnnotations-@Invalidate"></a>@Invalidate</h2>
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]300
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame^]301<p><b>Goal:</b> defines a validate lifecycle callback<br>
302<b>Target:</b> method</p>
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]303
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame^]304<h2><a name="HowtouseiPOJOAnnotations-TemporalDependencies(externalhandler)"></a>Temporal Dependencies (external handler)</h2>
Clement Escoffier83507512008-10-13 07:33:03 +0000[diff] [blame]305
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame^]306<p>The temporal dependency handler is an external handler. However, it
307can be used with an annotation defined in the iPOJO annotations jar
308file. <br>
309The annotation is org.apache.felix.ipojo.handler.temporal.Requires and targets a field. <br>
310<b>Attributes:</b></p>
311<ul>
312 <li>filter : specify the dependency filter</li>
313 <li>timeout : specify the dependency timeout (optional)</li>
314 <li>onTimeout
315: specify the onTimeout action (null, nullable, empty-array,
316default-implementation (specify the class name in this case) (optional).</li>
317</ul>
Clement Escoffier83507512008-10-13 07:33:03 +0000[diff] [blame]318
319
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]320
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame^]321<h2><a name="HowtouseiPOJOAnnotations-ExposinginstancesasaJMXMBean(externalhandler)\Newinthe1.1.0SNAPSHOTversion\"></a>Exposing instances as a JMX MBean (external handler) [New in the 1.1.0-SNAPSHOT version]</h2>
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]322
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame^]323<p>The JMX Handler allows exposing an instance as a JMX MBean. To
324configure the JMX handler directly from your code, three annotations
325are provided. They are in the <tt>org.apache.felix.ipojo.handlers.jmx</tt> package</p>
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]326
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame^]327<p>The <tt>@org.apache.felix.ipojo.handlers.jmx.Config</tt> (<tt>@Config</tt> if the package it correctly imported) annotation is a type annotation (so placed on the <tt>class</tt> element. This annotation indicates that the instance will be exposed as an MBean. This annotation supports:</p>
328<ul>
329 <li>usesMOSGi: set to <tt>true</tt> to use MOSGi. Otherwise, the MBean will be exposed in the MBean Platform Server (default: <tt>false</tt>).</li>
330 <li>objectname: set the MBean objectname. The objectname must follow JMX specification. (default: <tt>package-name:factory-name:instance-name</tt>)</li>
331 <li>domain: set the MBean domain. (default: <tt>package-name</tt>)</li>
332 <li>name: set the MBean name. (default: <tt>instance-name</tt>).</li>
333</ul>
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]334
335
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame^]336<p>The <tt>@org.apache.felix.ipojo.handlers.jmx.Property</tt> (<tt>@Property</tt>) annotation is a field annotation indicating that the field is exposed in the MBean. The supported attributes are:</p>
337<ul>
338 <li>name: set the property name</li>
339 <li>rights: set the access permission. Possible values are <tt>r</tt> (read only) and <tt>w</tt> (read and write). By default, properties are in read-only mode.</li>
340 <li>notification: enables notification on this property. By default notifications are disabled.</li>
341</ul>
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]342
343
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame^]344<p>The <tt>@org.apache.felix.ipojo.handlers.jmx.Method</tt> (<tt>@Method</tt>) annotation is a method annotation indicating that the method is exposed in the MBean. Only one attribute can be customized:</p>
345<ul>
346 <li>description: set the method description.</li>
347</ul>
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]348
349
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame^]350
351<h1><a name="HowtouseiPOJOAnnotations-Metadatafileandannotationmerge"></a>Metadata file and annotation merge</h1>
352
353<p>It is possible to defines component type both in the metadata file
354(in XML) and by using annotation. However, if a component type defined
355by using annotations has the same name than a type define in the XML
356file, the XML descriptor override the annotation defined type. However,
357a warning message is launched during the manipulation.</p>
358
359<h1><a name="HowtouseiPOJOAnnotations-Instancecreation"></a>Instance creation</h1>
360
361<p>Annotation can only be used to define component type. To define
362instances, you need to use the XML descriptor. Instance can refer to
363annotated types by referring to their names.</p>
364<div class="code"><div class="codeContent">
365<pre class="code-xml"><span class="code-tag">&lt;instance component=<span class="code-quote">"ipojo.example.hello.impl.HelloImpl"</span>/&gt;</span>
366<span class="code-tag">&lt;instance component=<span class="code-quote">"AnnotedHelloClient"</span>/&gt;</span></pre>
367</div></div>
368
369<h1><a name="HowtouseiPOJOAnnotations-UsingCustomAnnotations"></a>Using Custom Annotations</h1>
370
371<p>External handlers can provides their own annotations. Using these
372annotations just requires to add them to your build path. To external
373handlers annotations, please refer to the external handler
374documentation.</p></td>
375<td class="confluenceTd" valign="top" width="20%">
376<h6><a name="HowtouseiPOJOAnnotations-Overview"></a><b>Overview</b></h6>
377<ul>
378 <li><a href="http://felix.apache.org/site/apache-felix-ipojo.html" title="Apache Felix iPOJO">Home Page</a></li>
379 <li><a href="http://felix.apache.org/site/apache-felix-ipojo-feature-overview.html" title="Apache Felix iPOJO Feature Overview">iPOJO Feature Overview</a></li>
380 <li><a href="http://felix.apache.org/site/download.html" title="Download">Download &amp; Install </a></li>
381</ul>
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]382
383
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame^]384<h6><a name="HowtouseiPOJOAnnotations-GettingStarted"></a><b>Getting Started</b></h6>
385<ul>
386 <li><a href="http://felix.apache.org/site/ipojo-in-10-minutes.html" title="iPOJO in 10 minutes">iPOJO in 10 minutes</a></li>
387 <li><a href="" title="How to use iPOJO Annotations">How to use iPOJO Annotations</a></li>
388 <li><a href="http://felix.apache.org/site/ipojo-hello-word-maven-based-tutorial.html" title="iPOJO Hello Word (Maven-Based) tutorial">iPOJO Hello Word (Maven-Based) tutorial</a></li>
389 <li><a href="http://felix.apache.org/site/ipojo-advanced-tutorial.html" title="iPOJO Advanced Tutorial">iPOJO Advanced Tutorial</a></li>
390 <li><a href="http://felix.apache.org/site/ipojo-composition-tutorial.html" title="iPOJO Composition Tutorial">iPOJO Composition Tutorial</a></li>
391</ul>
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]392
393
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame^]394<h6><a name="HowtouseiPOJOAnnotations-UserGuide"></a><b>User Guide</b></h6>
395<ul>
396 <li><a href="http://felix.apache.org/site/describing-components.html" title="Describing components">Describing components (handler list) </a></li>
397 <li><a href="http://felix.apache.org/site/using-xml-schemas.html" title="Using XML Schemas">Using XML Schemas</a></li>
398 <li><a href="http://felix.apache.org/site/apache-felix-ipojo-testing-components.html" title="apache-felix-ipojo-testing-components">Testing components</a></li>
399 <li><a href="http://felix.apache.org/site/ipojo-advanced-topics.html" title="iPOJO Advanced Topics">Advanced Topics</a></li>
400 <li><a href="http://felix.apache.org/site/ipojo-faq.html" title="iPOJO FAQ">FAQ</a></li>
401</ul>
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]402
403
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame^]404<h6><a name="HowtouseiPOJOAnnotations-Tools"></a><b>Tools</b></h6>
405<ul>
406 <li><a href="http://felix.apache.org/site/ipojo-eclipse-plug-in.html" title="iPOJO Eclipse Plug-in">iPOJO Eclipse Plug-in</a></li>
407 <li><a href="http://felix.apache.org/site/ipojo-ant-task.html" title="iPOJO Ant Task">iPOJO Ant Task</a></li>
408 <li><a href="http://felix.apache.org/site/ipojo-maven-plug-in.html" title="iPOJO Maven Plug-in">iPOJO Maven Plug-in</a></li>
409 <li><a href="http://felix.apache.org/site/apache-felix-ipojo-junit4osgi.html" title="apache-felix-ipojo-junit4osgi">Junit4OSGi</a></li>
410 <li><a href="http://felix.apache.org/site/ipojo-concepts-overview.html" title="iPOJO Concepts Overview">iPOJO concepts overview</a></li>
411</ul>
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]412
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame^]413
414<h6><a name="HowtouseiPOJOAnnotations-DeveloperGuide"></a><b>Developer Guide</b></h6>
415<ul>
416 <li>API: <span class="nobr"><a href="http://people.apache.org/%7Eclement/ipojo/api/1.0/" title="Visit page outside Confluence" rel="nofollow">1.0<sup><img class="rendericon" src="how-to-use-ipojo-annotations_files/linkext7.gif" alt="" align="absmiddle" border="0" width="7" height="7"></sup></a></span></li>
417 <li><a href="http://felix.apache.org/site/how-to-write-your-own-handler.html" title="How to write your own handler">How to write your own handler</a></li>
418 <li><a href="http://felix.apache.org/site/how-to-use-ipojo-manipulation-metadata.html" title="How to use iPOJO Manipulation Metadata">How to use iPOJO Manipulation Metadata</a></li>
419 <li><a href="http://felix.apache.org/site/dive-into-the-ipojo-manipulation-depths.html" title="Dive into the iPOJO Manipulation depths">Dive into the iPOJO Manipulation depths</a></li>
420</ul>
421
422
423<h6><a name="HowtouseiPOJOAnnotations-Misc&amp;Contact"></a><b>Misc &amp; Contact</b></h6>
424<ul>
425 <li><a href="http://felix.apache.org/site/apache-felix-ipojo-issuestracker.html" title="apache-felix-ipojo-issuestracker">Issues Tracker</a></li>
426 <li><a href="http://felix.apache.org/site/apache-felix-ipojo-supportedvms.html" title="apache-felix-ipojo-supportedVMs">Supported JVMs</a></li>
427 <li><a href="http://felix.apache.org/site/apache-felix-ipojo-supportedosgi.html" title="apache-felix-ipojo-supportedOSGi">Supported OSGi Implementations</a></li>
428 <li><span class="nobr"><a href="http://ipojo-dark-side.blogspot.com/" title="Visit page outside Confluence" rel="nofollow">iPOJO's Dark Side Blog<sup><img class="rendericon" src="how-to-use-ipojo-annotations_files/linkext7.gif" alt="" align="absmiddle" border="0" width="7" height="7"></sup></a></span></li>
429 <li><a href="http://felix.apache.org/site/future-ideas.html" title="Future Ideas">Future Ideas</a></li>
430 <li><a href="http://felix.apache.org/site/contact.html" title="Contact">Contact</a></li>
431 <li><a href="http://felix.apache.org/site/related-works.html" title="Related Works">Related Works</a></li>
432 <li><a href="http://felix.apache.org/site/article-presentations.html" title="Article &amp; Presentations">Article &amp; Presentations</a></li>
433</ul>
434
435
436<hr>
437<div class="" align="center">
438<p><span class="nobr"><a href="http://cwiki.apache.org/confluence/createrssfeed.action?types=blogpost&amp;statuses=created&amp;statuses=modified&amp;spaces=FELIX&amp;labelString=iPOJO&amp;rssType=atom&amp;maxResults=10&amp;timeSpan=5&amp;publicFeed=true&amp;title=iPOJO%20Atom%20Feed" title="Stay tuned!" rel="nofollow"><img src="how-to-use-ipojo-annotations_files/feed-icon-32x32.png" align="absmiddle" border="0"><sup><img class="rendericon" src="how-to-use-ipojo-annotations_files/linkext7.gif" alt="" align="absmiddle" border="0" width="7" height="7"></sup></a></span></p></div>
439
440<script type="text/javascript">
441var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www.");
442document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E"));
443</script><script src="how-to-use-ipojo-annotations_files/ga.js" type="text/javascript"></script>
444<script type="text/javascript">
445var pageTracker = _gat._getTracker("UA-1518442-4");
446pageTracker._trackPageview();
447</script>
448</td></tr></tbody></table>
449 </div>
450 </body></html>