Blame - ipojo/annotations/doc/how-to-use-ipojo-annotations.html - onos-felix

<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="http://cwiki.apache.org/confluence/images/icons/linkext7.gif" height="7" width="7" align="absmiddle" alt="" border="0"></SUP></A></SPAN></LI>

18

<LI><A href="http://felix.apache.org/site/documentation.html" title="documentation">documentation</A></LI>

19

<LI><A href="http://felix.apache.org/site/mailinglists.html" title="mailinglists">mailing lists</A></LI>

20

<LI><A href="http://felix.apache.org/site/contributing.html" title="Contributing">contributing</A></LI>

21

22

<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="http://cwiki.apache.org/confluence/images/icons/linkext7.gif" height="7" width="7" align="absmiddle" alt="" border="0"></SUP></A></SPAN></LI>

23

<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="http://cwiki.apache.org/confluence/images/icons/linkext7.gif" height="7" width="7" align="absmiddle" alt="" border="0"></SUP></A></SPAN>

24

25

26

27

</LI>

</UL>

</DIV>

<P>iPOJO defines several annotations to help developer to define their components. This page presents an example of iPOJO annotation and describes provided annotations.</P>

34

35

<H1><A name="HowtouseiPOJOAnnotations-GettingiPOJOAnnotations%3A"></A>Getting iPOJO Annotations:</H1>

36

37

<P>iPOJO Annotations are defines inside the org.apache.felix.ipojo.annotations project. You can download the Jar file 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="http://cwiki.apache.org/confluence/images/icons/linkext7.gif" height="7" width="7" align="absmiddle" alt="" border="0"></SUP></A></SPAN>.<BR>

38

Once added to your class path / build path / dependencies, you can use the annotations as normal annotations. These annotations are automatically processed by the iPOJO manipulator.</P>

39

40

<H2><A name="HowtouseiPOJOAnnotations-InEclipse%3A"></A>In Eclipse:</H2>

41

42

<P>Add the org.apache.felix.ipojo.annotations jar file in your build path. Do not forget to use a Java compiler accepting annotations (1.5 or higher).</P>

43

44

<H2><A name="HowtouseiPOJOAnnotations-InMaven%3A"></A>In Maven:</H2>

45

46

<P>Add the following dependency:</P>

47

48

49

<SPAN class="code-tag"><groupId></SPAN>org.apache.felix<SPAN class="code-tag"></groupId></SPAN>

50

<SPAN class="code-tag"><artifactId></SPAN>org.apache.felix.ipojo.annotations<SPAN class="code-tag"></artifactId></SPAN>

51

<SPAN class="code-tag"><version></SPAN>0.8.0-SNAPSHOT<SPAN class="code-tag"></version></SPAN>

52

53

</DIV></DIV>

54

<P>Moreover, you need to set that the source code and the target code are Java 1.5 code. To achieve this, just add the following plugin in your plugins section:</P>

55

56

57

<SPAN class="code-tag"><groupId></SPAN>org.apache.maven.plugins<SPAN class="code-tag"></groupId></SPAN>

58

<SPAN class="code-tag"><artifactId></SPAN>maven-compiler-plugin<SPAN class="code-tag"></artifactId></SPAN>

</DIV></DIV>

<P>Just add the org.apache.felix.ipojo.annotations jar file in your class path.</P>

69

70

<H1><A name="HowtouseiPOJOAnnotations-Anexampleofusage%3A"></A>An example of usage:</H1>

71

72

<P>To illustrate annotations usage, let taking the tutorial example. In this tutorial, there are two components:</P>

73

<UL>

74

<LI>The first one provides the hello service</LI>

75

<LI>The second one uses the provided hello service<BR>

76

You can download the <SPAN class="nobr"><A href="http://felix.apache.org/site/how-to-use-ipojo-annotations.data/hello.impl.annotated-0.0.1-src.zip" title="hello.impl.annotated-0.0.1-src.zip attached to How to use iPOJO Annotations">provider<SUP><IMG class="rendericon" src="http://cwiki.apache.org/confluence/images/icons/link_attachment_7.gif" height="7" width="7" align="absmiddle" alt="" border="0"></SUP></A></SPAN> project and the <SPAN class="nobr"><A href="http://felix.apache.org/site/how-to-use-ipojo-annotations.data/hello.client.annotation-0.0.1-src.zip" title="hello.client.annotation-0.0.1-src.zip attached to How to use iPOJO Annotations">consumer<SUP><IMG class="rendericon" src="http://cwiki.apache.org/confluence/images/icons/link_attachment_7.gif" height="7" width="7" align="absmiddle" alt="" border="0"></SUP></A></SPAN> project.</LI>

</UL>

<H2><A name="HowtouseiPOJOAnnotations-HelloServiceProvider"></A>Hello Service Provider</H2>

81

82

<P>The provider uses two annotations. The "component" annotation is mandatory and defines that the class defines a component type. Then the "provides" annotation just declare that the defined component type provides a service.</P>

83

84

<PRE class="code-java"><SPAN class="code-keyword">package</SPAN> ipojo.example.hello.impl;

85

86

<SPAN class="code-keyword">import</SPAN> ipojo.example.hello.Hello;

87

88

<SPAN class="code-keyword">import</SPAN> org.apache.felix.ipojo.annotations.Component;

89

<SPAN class="code-keyword">import</SPAN> org.apache.felix.ipojo.annotations.Provides;

90

91

/**

92

* Component implementing the Hello service.

**/

@Component

@Provides

<SPAN class="code-keyword">public</SPAN> class HelloImpl <SPAN class="code-keyword">implements</SPAN> Hello {

97

<SPAN class="code-keyword">public</SPAN> <SPAN class="code-object">String</SPAN> sayHello(<SPAN class="code-object">String</SPAN> name) { <SPAN class="code-keyword">return</SPAN> <SPAN class="code-quote">"hello "</SPAN> + name; }

}</PRE>

</DIV></DIV>

<H2><A name="HowtouseiPOJOAnnotations-HelloServiceConsumer"></A>Hello Service Consumer</H2>

102

103

<P>The Hello Service Consumer use more annotations. First it used the componenet annotation. To defines its "immediate" behavior, it add the 'immediate' attribute.<BR>

104

Then, it uses the requires annotation to define a service dependency. Finally, it uses the validate and invalidate annotations to define lifecycle callbacks.</P>

105

106

<PRE class="code-java"><SPAN class="code-keyword">package</SPAN> ipojo.example.hello.client;

107

108

<SPAN class="code-keyword">import</SPAN> org.apache.felix.ipojo.annotations.Component;

109

<SPAN class="code-keyword">import</SPAN> org.apache.felix.ipojo.annotations.Invalidate;

110

<SPAN class="code-keyword">import</SPAN> org.apache.felix.ipojo.annotations.Requires;

111

<SPAN class="code-keyword">import</SPAN> org.apache.felix.ipojo.annotations.Validate;

112

113

<SPAN class="code-keyword">import</SPAN> ipojo.example.hello.Hello;

114

115

@Component(name=<SPAN class="code-quote">"AnnotedHelloClient"</SPAN>, immediate=<SPAN class="code-keyword">true</SPAN>)

116

<SPAN class="code-keyword">public</SPAN> class HelloClient <SPAN class="code-keyword">implements</SPAN> <SPAN class="code-object">Runnable</SPAN> {

117

118

@Requires

119

<SPAN class="code-keyword">private</SPAN> Hello[] m_hello; <SPAN class="code-comment">// Service Dependency

120

</SPAN>

121

<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;

122

<SPAN class="code-keyword">private</SPAN> <SPAN class="code-object">boolean</SPAN> end;

123

124

<SPAN class="code-keyword">public</SPAN> void run() {

125

<SPAN class="code-keyword">while</SPAN> (!end) {

126

<SPAN class="code-keyword">try</SPAN> {

127

invoke();

128

<SPAN class="code-object">Thread</SPAN>.sleep(DELAY);

129

} <SPAN class="code-keyword">catch</SPAN> (InterruptedException ie) { }

130

/* will recheck end */

}

}

<SPAN class="code-keyword">public</SPAN> void invoke() {

135

<SPAN class="code-keyword">for</SPAN> (<SPAN class="code-object">int</SPAN> i = 0; i < m_hello.length; i++) { <SPAN class="code-object">System</SPAN>.out.println(m_hello[i].sayHello(<SPAN class="code-quote">"Clement"</SPAN>)); }

}

@Validate

<SPAN class="code-keyword">public</SPAN> void starting() { <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>); end = <SPAN class="code-keyword">false</SPAN>; T.start(); }

140

141

@Invalidate

142

<SPAN class="code-keyword">public</SPAN> void stopping() { end = <SPAN class="code-keyword">true</SPAN>; }

}</PRE>

</DIV></DIV>

<H1><A name="HowtouseiPOJOAnnotations-DefinedAnnotations"></A>Defined Annotations</H1>

147

148

<P>This section lists defined annotations and how to use them.</P>

149

150

<H2><A name="HowtouseiPOJOAnnotations-@Component"></A>@Component</H2>

151

152

<P><B>Goal:</B> Defines a component type<BR>

153

<B>Target:</B> The component implementation class<BR>

154

<B>Attributes:</B></P>

155

<UL>

156

<LI>name : defines the component type name (optional, default = the class name)</LI>

157

<LI>factory: defines the factory name (optional, default = "false")</LI>

158

<LI>immediate: defines the component type as immediate (optional, default = "false")</LI>

159

<LI>architecture: enable the architecture exposition (optional, default = "false")</LI>

160

<LI>propagation: enable configuration property propagation (on provided services) (optional, default = "false")</LI>

</UL>

<H2><A name="HowtouseiPOJOAnnotations-@Provides"></A>@Provides</H2>

165

166

<P><B>Goal:</B> Defines that the component type provide services<BR>

167

<B>Target:</B> The component implementation class<BR>

168

<B>Attributes:</B></P>

169

<UL>

170

<LI>specifications: defines the provided interface (optional, default = all implemented interfaces)</LI>

171

<LI>factory: defines the service object creation policy ("SINGLETON" or "SERVICE") (optional, default = "SINGLETON")</LI>

</UL>

<P><EM>Note:</EM> "SERVICE" means OSGi service factory.</P>

176

177

<H2><A name="HowtouseiPOJOAnnotations-@Requires"></A>@Requires</H2>

178

179

<P><B>Goal:</B> Defines a service dependency<BR>

180

<B>Target:</B> Field<BR>

181

<B>Attributes:</B></P>

182

<UL>

183

<LI>Filter: defines the LDAP filter (optional)</LI>

184

<LI>Optional: defines if the dependency is optional (optional, default = "false")</LI>

185

<LI>Id: defines the dependency Id (useful to identify bind & unbind methods) (optional, default = field name) (if a dependency with the same id is already created (by a @bind or @unbind annotation), it merges the dependencies).</LI>

186

<LI>Nullable: enable or disable the Null Object injection when the dependency is optional and no providers are available (optional, default = "true")</LI>

187

<LI>Default-Implementation: set the Default-Implmentation (optional, by default iPOJO uses a Null object)</LI>

188

<LI>Policy: defines the binding policy (accepted value : dynamic, static, dynamic-priority) (optional, default = "dynamic")</LI>

189

<LI>Comparator: defines the comparator to use to sort service references (optional, default = OSGi Service Reference Comparator)</LI>

</UL>

<H2><A name="HowtouseiPOJOAnnotations-@ServiceProperty"></A>@ServiceProperty</H2>

194

195

<P><B>Goal:</B> Defines a service property<BR>

196

<B>Target:</B> Field or Method<BR>

197

<B>Attributes:</B></P>

198

<UL>

199

<LI>name: property name (optional, default=field name or computed by removing "set" from the method name (for instance setFoo(String ff) will get the Foo name))</LI>

200

<LI>value: property value (optional, default=no value)</LI>

</UL>

<P><EM>note:</EM> if another service property with the same name is defined the method or the field is added to the existing property</P>

205

206

<H2><A name="HowtouseiPOJOAnnotations-@Property"></A>@Property</H2>

207

208

<P><B>Goal:</B> Defines a property<BR>

209

<B>Target:</B> Field or Method<BR>

210

<B>Attributes:</B></P>

211

<UL>

212

<LI>name: property name (optional, default=field name computed by removing "set" from the method name (for instance setFoo(String ff) will get the Foo name))</LI>

213

<LI>value: property value (optional, default=no value)</LI>

</UL>

<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>

<P><B>Goal:</B> Defines a bind method<BR>

222

<B>Target:</B> Method<BR>

223

<B>Attributes:</B></P>

224

<UL>

225

<LI>Id: Dependency Id, if the id is already defines in a "@requires " or "@unbind" annotation, it adds this method as a bind method of the already created dependency. (optional, default= no id, compute an id if the method name begin by "bind" (for instance "bindFoo" will have the "Foo" id))</LI>

226

<LI>Specification : required dependency (optional)</LI>

227

<LI>Aggregate : is the dependency an aggregate dependency (optional, default= "false")</LI>

228

<LI>Optional: is the dependency an optional dependency (optional, default= "false")</LI>

229

<LI>Filter: dependency LDAP filter (optional)</LI>

230

<LI>Policy: defines the binding policy (accepted value : dynamic, static, dynamic-priority) (optional, default = "dynamic")</LI>

231

<LI>Comparator: defines the comparator to use to sort service references (optional, default = OSGi Service Reference Comparator)</LI>

</UL>

<H2><A name="HowtouseiPOJOAnnotations-@Unbind"></A>@Unbind</H2>

236

237

<P><B>Goal:</B> Defines an unbind method<BR>

238

<B>Target:</B> Method<BR>

239

<B>Attributes:</B></P>

240

<UL>

241

<LI>Id: Dependency Id, if the id is already defines in a "@requires" or "@bind" annotation, it adds this method as an unbind method of the already created dependency. (optional, default= no id, compute an id if the method name begin by "unbind" (for instance "unbindFoo" will have the "Foo" id))</LI>

242

<LI>Specification : required dependency (optional)</LI>

243

<LI>Aggregate : is the dependency an aggregate dependency (optional, default= "false")</LI>

244

<LI>Optional: is the dependency an optional dependency (optional, default= "false")</LI>

245

<LI>Filter: dependency LDAP filter (optional)</LI>

246

<LI>Policy: defines the binding policy (accepted value : dynamic, static, dynamic-priority) (optional, default = "dynamic")</LI>

247

<LI>Comparator: defines the comparator to use to sort service references (optional, default = OSGi Service Reference Comparator)</LI>

</UL>

<H2><A name="HowtouseiPOJOAnnotations-@Validate"></A>@Validate</H2>

252

253

<P><B>Goal:</B> defines a validate lifecycle callback<BR>

254

<B>Target:</B> method</P>

255

256

<H2><A name="HowtouseiPOJOAnnotations-@Invalidate"></A>@Invalidate</H2>

257

258

<P><B>Goal:</B> defines a validate lifecycle callback<BR>

259

<B>Target:</B> method</P>

260

261

<H1><A name="HowtouseiPOJOAnnotations-Metadatafileandannotationmerge"></A>Metadata file and annotation merge</H1>

262

263

<P>It is possible to defines component type both in the metadata file (in XML) and by using annotation. However, if a component type defined by using annotations has the same name than a type define in the XML file, the XML descriptor override the annotation defined type. However, a warning message is launched during the manipulation.</P>

264

265

<H1><A name="HowtouseiPOJOAnnotations-Instancecreation"></A>Instance creation</H1>

266

267

<P>Annotation can only be used to define component type. To define instances, you need to use the XML descriptor. Instance can refer to annotated types by referring to their names.</P>

268

269

<PRE class="code-xml"><SPAN class="code-tag"><instance component=<SPAN class="code-quote">"ipojo.example.hello.impl.HelloImpl"</SPAN>/></SPAN>

270

<SPAN class="code-tag"><instance component=<SPAN class="code-quote">"AnnotedHelloClient"</SPAN>/></SPAN></PRE>

271

</DIV></DIV>

272

273

<H1><A name="HowtouseiPOJOAnnotations-UsingCustomAnnotations"></A>Using Custom Annotations</H1>

274

275

<P>External handlers can provides their own annotations. Using these annotations just requires to add them to your build path. To external handlers annotations, please refer to the external handler documentation.</P></TD>

</FORM>

<HR>

<H6><A name="HowtouseiPOJOAnnotations-Overview"></A><B>Overview</B></H6>

284

<UL>

285

286

<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>

287

<LI><A href="http://felix.apache.org/site/download.html" title="Download">Download & Install </A></LI>

</UL>

<H6><A name="HowtouseiPOJOAnnotations-GettingStarted"></A><B>Getting Started</B></H6>

292

<UL>

293

<LI><A href="http://felix.apache.org/site/ipojo-in-10-minutes.html" title="iPOJO in 10 minutes">iPOJO in 10 minutes</A></LI>

294

<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>

295

<LI><A href="http://felix.apache.org/site/ipojo-advanced-tutorial.html" title="iPOJO Advanced Tutorial">iPOJO Advanced Tutorial</A></LI>

</UL>

<H6><A name="HowtouseiPOJOAnnotations-UserGuide"></A><B>User Guide</B></H6>

300

<UL>

301

<LI><A href="http://felix.apache.org/site/describing-components.html" title="Describing components">Describing components</A></LI>

302

<LI><A href="#" title="How to use iPOJO Annotations">How to use iPOJO Annotations</A></LI>

303

<LI><A href="http://felix.apache.org/site/ipojo-advanced-topics.html" title="iPOJO Advanced Topics">Advanced Topics</A></LI>

</UL>

<H6><A name="HowtouseiPOJOAnnotations-Tools"></A><B>Tools</B></H6>

309

<UL>

310

<LI><A href="http://felix.apache.org/site/ipojo-eclipse-plug-in.html" title="iPOJO Eclipse Plug-in">iPOJO Eclipse Plug-in</A></LI>

311

<LI><A href="http://felix.apache.org/site/ipojo-ant-task.html" title="iPOJO Ant Task">iPOJO Ant Task</A></LI>

312

<LI><A href="http://felix.apache.org/site/ipojo-maven-plug-in.html" title="iPOJO Maven Plug-in">iPOJO Maven Plug-in</A></LI>

313

<LI><A href="http://felix.apache.org/site/ipojo-concepts-overview.html" title="iPOJO Concepts Overview">iPOJO concepts overview</A></LI>

</UL>

<H6><A name="HowtouseiPOJOAnnotations-DeveloperGuide"></A><B>Developer Guide</B></H6>

318

<UL>

319

<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>

320

<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>

</UL>

<H6><A name="HowtouseiPOJOAnnotations-Misc%26Contact"></A><B>Misc & Contact</B></H6>

325

<UL>

326

<LI><A href="http://felix.apache.org/site/apache-felix-ipojo-issuestracker.html" title="apache-felix-ipojo-issuestracker">Issues Tracker</A></LI>

327

<LI><A href="http://felix.apache.org/site/apache-felix-ipojo-supportedvms.html" title="apache-felix-ipojo-supportedVMs">Supported JVMs</A></LI>

328

<LI><A href="http://felix.apache.org/site/apache-felix-ipojo-supportedosgi.html" title="apache-felix-ipojo-supportedOSGi">Supported OSGi Implementations</A></LI>

329

<LI><A href="http://felix.apache.org/site/future-ideas.html" title="Future Ideas">Future Ideas</A></LI>

330

<LI><SPAN class="nobr"><A href="http://cwiki.apache.org/confluence/pages/createpage.action?spaceKey=FELIX&title=Contact&linkCreation=true&fromPageId=82824" title="Create Page: Contact" class="createlink">Contact<SUP><IMG class="rendericon" src="http://cwiki.apache.org/confluence/images/icons/plus.gif" height="7" width="7" align="absmiddle" alt="" border="0"></SUP></A></SPAN></LI>

331

<LI><A href="http://felix.apache.org/site/related-works.html" title="Related Works">Related Works</A></LI>

332

<LI><A href="http://felix.apache.org/site/article-presentations.html" title="Article & Presentations">Article & Presentations</A></LI>

</UL>

<HR>