Gitiles
Code Review Sign In
gerrit.onosproject.org / onos-felix / 373a57d8c50f05e872ed874a0f5e42d99cb7a35c / . / ipojo / annotations / doc / how-to-use-ipojo-annotations.html
blob: 1ce24bacfef41edbc09d7c038051a33eb8f51df5 [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>
Clement Escoffier373a57d2009-07-21 12:06:46 +0000[diff] [blame^]15 <li><a href="http://felix.apache.org/site/downloads.cgi" rel="nofollow">downloads</a></li>
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame]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>
Clement Escoffier373a57d2009-07-21 12:06:46 +0000[diff] [blame^]19 <li><a href="http://www.apache.org/" rel="nofollow">asf</a></li>
20 <li><a href="http://www.apache.org/foundation/sponsorship.html" rel="nofollow">sponsorship</a></li>
21 <li><a href="http://www.apache.org/foundation/thanks.html" rel="nofollow">sponsors</a>
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]22<!-- ApacheCon Ad -->
Clement Escoffier373a57d2009-07-21 12:06:46 +0000[diff] [blame^]23<iframe src="how-to-use-ipojo-annotations_files/button.html" style="border-width: 0pt; float: left;" scrolling="no" frameborder="0" height="135" width="135"></iframe>
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame]24<p style="height: 100px;">
25<!-- ApacheCon Ad -->
26</p></li></ul> </div>
27 <div class="main">
Clement Escoffier373a57d2009-07-21 12:06:46 +0000[diff] [blame^]28<style type="text/css">
29 @import url(http://people.apache.org/~clement/ipojo/site/superfish.css);
30</style>
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]31
Clement Escoffier373a57d2009-07-21 12:06:46 +0000[diff] [blame^]32<style type="text/css">
33 @import url(http://people.apache.org/~clement/ipojo/site/style.css);
34</style>
35
36<p>
37<script class="javascript" src="how-to-use-ipojo-annotations_files/shCore.js"></script>
38<script class="javascript" src="how-to-use-ipojo-annotations_files/shBrushCSharp.js"></script>
39<script class="javascript" src="how-to-use-ipojo-annotations_files/shBrushPhp.js"></script>
40<script class="javascript" src="how-to-use-ipojo-annotations_files/shBrushJScript.js"></script>
41<script class="javascript" src="how-to-use-ipojo-annotations_files/shBrushVb.js"></script>
42<script class="javascript" src="how-to-use-ipojo-annotations_files/shBrushSql.js"></script>
43<script class="javascript" src="how-to-use-ipojo-annotations_files/shBrushXml.js"></script>
44<script class="javascript" src="how-to-use-ipojo-annotations_files/shBrushShell.js"></script>
45<script class="javascript" src="how-to-use-ipojo-annotations_files/shBrushDelphi.js"></script>
46<script class="javascript" src="how-to-use-ipojo-annotations_files/shBrushPython.js"></script>
47<script class="javascript" src="how-to-use-ipojo-annotations_files/shBrushJava.js"></script>
48
49<script type="text/javascript" src="how-to-use-ipojo-annotations_files/jquery-1.js"></script>
50<script type="text/javascript" src="how-to-use-ipojo-annotations_files/hoverIntent.js"></script>
51<script type="text/javascript" src="how-to-use-ipojo-annotations_files/superfish.js"></script>
52<script type="text/javascript" src="how-to-use-ipojo-annotations_files/supersubs.js"></script>
53
54<script type="text/javascript">
55
56 $(document).ready(function(){
57 $("ul.sf-menu").supersubs({
58 minWidth: 14, // minimum width of sub-menus in em units
59 maxWidth: 30, // maximum width of sub-menus in em units
60 extraWidth: 1 // extra width can ensure lines don't sometimes turn over
61 // due to slight rounding differences and font-family
62 }).superfish(); // call supersubs first, then superfish, so that subs are
63 // not display:none when measuring. Call before initialising
64 // containing tabs for same reason.
65 });
66
67</script>
68</p><div class="main">
69<div class="page-header">
70<img src="how-to-use-ipojo-annotations_files/header.png" class="header">
71<a href="http://ipojo.org/"><img src="how-to-use-ipojo-annotations_files/ipojo.png" class="header-logo" width="225"></a>
72<ul class="sf-menu sf-js-enabled sf-shadow" id="ipojo-menu">
73<li class="current">
74<!-- Menu Overview -->
75<a href="" class="sf-with-ul">Overview<span class="sf-sub-indicator"> »</span><span class="sf-sub-indicator"> »</span><span class="sf-sub-indicator"> »</span></a>
76<ul style="float: none; width: 14em; display: none; visibility: hidden;">
77 <li style="white-space: normal; float: left; width: 100%;">
78 <a style="float: none; width: auto;" href="http://felix.apache.org/site/apache-felix-ipojo.html" title="Apache Felix iPOJO">Home</a>
79 </li>
80 <li style="white-space: normal; float: left; width: 100%;">
81 <a style="float: none; width: auto;" href="http://felix.apache.org/site/apache-felix-ipojo-why-choose-ipojo.html" title="apache-felix-ipojo-why-choose-ipojo">Why choose iPOJO</a>
82 </li>
83 <li style="white-space: normal; float: left; width: 100%;">
84 <a style="float: none; width: auto;" href="http://felix.apache.org/site/apache-felix-ipojo-successstories.html" title="apache-felix-ipojo-successstories">Success stories</a>
85 </li>
86 <li style="white-space: normal; float: left; width: 100%;">
87 <a style="float: none; width: auto;" href="http://felix.apache.org/site/apache-felix-ipojo-feature-overview.html" title="Apache Felix iPOJO Feature Overview">Features</a>
88 </li>
89</ul>
90</li>
91
92<li class="">
93<!-- Menu download -->
94</li><li>
95<a href="http://felix.apache.org/site/download.html" title="Download">Download </a>
96</li>
97
98<li class="">
99<!-- Menu Documentation -->
100<a href="" class="sf-with-ul">Documentation<span class="sf-sub-indicator"> »</span><span class="sf-sub-indicator"> »</span><span class="sf-sub-indicator"> »</span></a>
101<ul style="float: none; width: 14em; display: none; visibility: hidden;">
102 <!-- sub- menu : getting started -->
103 <li style="white-space: normal; float: left; width: 100%;" class="">
104 <a style="float: none; width: auto;" href="" class="sf-with-ul">Getting Started<span class="sf-sub-indicator"> »</span><span class="sf-sub-indicator"> »</span><span class="sf-sub-indicator"> »</span></a>
105 <ul style="left: 14em; float: none; width: 14em; display: none; visibility: hidden;">
106 <li style="white-space: normal; float: left; width: 100%;"><a style="float: none; width: auto;" href="http://felix.apache.org/site/ipojo-in-10-minutes.html" title="iPOJO in 10 minutes">iPOJO in 10 minutes</a></li>
107 <li style="white-space: normal; float: left; width: 100%;"><a style="float: none; width: auto;" href="" title="How to use iPOJO Annotations">Using Annotations</a></li>
108 <li style="white-space: normal; float: left; width: 100%;"><a style="float: none; width: auto;" href="http://felix.apache.org/site/ipojo-hello-word-maven-based-tutorial.html" title="iPOJO Hello Word (Maven-Based) tutorial">Maven tutorial</a></li>
109 <li style="white-space: normal; float: left; width: 100%;"><a style="float: none; width: auto;" href="http://felix.apache.org/site/ipojo-advanced-tutorial.html" title="iPOJO Advanced Tutorial">Advanced tutorial</a></li>
110 <li style="white-space: normal; float: left; width: 100%;"><a style="float: none; width: auto;" href="http://felix.apache.org/site/apache-felix-ipojo-dosgi.html" title="apache-felix-ipojo-dosgi">Using Distributed OSGi</a></li>
111 <li style="white-space: normal; float: left; width: 100%;"><a style="float: none; width: auto;" href="http://felix.apache.org/site/ipojo-composition-tutorial.html" title="iPOJO Composition Tutorial">Application Composition</a></li>
112 </ul>
113 </li> <!-- end of getting started -->
114 <!-- sub menu : Describing Components -->
115 <li style="white-space: normal; float: left; width: 100%;" class="">
116 <a style="float: none; width: auto;" href="http://felix.apache.org/site/describing-components.html" class="sf-with-ul">Describing components<span class="sf-sub-indicator"> »</span><span class="sf-sub-indicator"> »</span><span class="sf-sub-indicator"> »</span></a>
117 <ul style="left: 14em; float: none; width: 14em; display: none; visibility: hidden;">
118 <li style="white-space: normal; float: left; width: 100%;"><a style="float: none; width: auto;" href="http://felix.apache.org/site/service-requirement-handler.html" title="Service Requirement Handler">Requiring a service</a></li>
119 <li style="white-space: normal; float: left; width: 100%;"><a style="float: none; width: auto;" href="http://felix.apache.org/site/providing-osgi-services.html" title="Providing OSGi services">Providing a service</a></li>
120 <li style="white-space: normal; float: left; width: 100%;"><a style="float: none; width: auto;" href="http://felix.apache.org/site/lifecycle-callback-handler.html" title="Lifecycle Callback Handler">Lifecycle management</a></li>
121 <li style="white-space: normal; float: left; width: 100%;"><a style="float: none; width: auto;" href="http://felix.apache.org/site/configuration-handler.html" title="Configuration Handler">Configuration</a></li>
122 <li style="white-space: normal; float: left; width: 100%;"><a style="float: none; width: auto;" href="http://felix.apache.org/site/architecture-handler.html" title="Architecture Handler">Introspection</a></li>
123 <li style="white-space: normal; float: left; width: 100%;"><a style="float: none; width: auto;" href="http://felix.apache.org/site/controller-lifecycle-handler.html" title="Controller Lifecycle Handler">Impacting the lifecycle</a></li>
124 <li style="white-space: normal; float: left; width: 100%;"><a style="float: none; width: auto;" href="http://felix.apache.org/site/event-admin-handlers.html" title="Event Admin Handlers">Asynchronous communication</a></li>
125 <li style="white-space: normal; float: left; width: 100%;"><a style="float: none; width: auto;" href="http://felix.apache.org/site/ipojo-jmx-handler.html" title="iPOJO JMX Handler">JMX management</a></li>
126 <li style="white-space: normal; float: left; width: 100%;"><a style="float: none; width: auto;" href="http://felix.apache.org/site/extender-pattern-handler.html" title="Extender Pattern Handler">Extender pattern</a></li>
127 <li style="white-space: normal; float: left; width: 100%;"><a style="float: none; width: auto;" href="http://felix.apache.org/site/white-board-pattern-handler.html" title="White Board Pattern Handler">Whiteboard pattern</a></li>
128 <li style="white-space: normal; float: left; width: 100%;"><a style="float: none; width: auto;" href="http://felix.apache.org/site/temporal-service-dependency.html" title="Temporal Service Dependency">Temporal dependencies</a></li>
129 </ul>
130 </li> <!-- End of describing components -->
131 <!-- sub- menu : User Guide -->
132 <li style="white-space: normal; float: left; width: 100%;" class="">
133 <a style="float: none; width: auto;" href="" class="sf-with-ul">User Guide<span class="sf-sub-indicator"> »</span><span class="sf-sub-indicator"> »</span><span class="sf-sub-indicator"> »</span></a>
134 <ul style="left: 14em; float: none; width: 14em; display: none; visibility: hidden;">
135 <li style="white-space: normal; float: left; width: 100%;"><a style="float: none; width: auto;" href="http://felix.apache.org/site/using-xml-schemas.html" title="Using XML Schemas">XML Schemas</a></li>
136 <li style="white-space: normal; float: left; width: 100%;"><a style="float: none; width: auto;" href="http://felix.apache.org/site/apache-felix-ipojo-api.html" title="apache-felix-ipojo-api">API</a></li>
137 <li style="white-space: normal; float: left; width: 100%;"><a style="float: none; width: auto;" href="http://felix.apache.org/site/apache-felix-ipojo-testing-components.html" title="apache-felix-ipojo-testing-components">Testing components</a></li>
138 <li style="white-space: normal; float: left; width: 100%;"><a style="float: none; width: auto;" href="http://felix.apache.org/site/apache-felix-ipojo-eclipse-integration.html" title="apache-felix-ipojo-eclipse-integration">Eclipse Integration</a></li>
139 <li style="white-space: normal; float: left; width: 100%;"><a style="float: none; width: auto;" href="http://felix.apache.org/site/ipojo-faq.html" title="iPOJO FAQ">FAQ</a></li>
140 <li style="white-space: normal; float: left; width: 100%;"><a style="float: none; width: auto;" href="http://felix.apache.org/site/ipojo-reference-card.html" title="iPOJO-Reference-Card">Reference Card</a></li>
141 </ul>
142 </li> <!-- end of user guide -->
143 <!-- sub- menu : Dev Guide -->
144 <li class="" style="white-space: normal; float: left; width: 100%;">
145 <a style="float: none; width: auto;" href="" class="sf-with-ul">Advanced Topics<span class="sf-sub-indicator"> »</span><span class="sf-sub-indicator"> »</span><span class="sf-sub-indicator"> »</span></a>
146 <ul style="left: 14em; float: none; width: 14em; display: none; visibility: hidden;">
147 <li style="white-space: normal; float: left; width: 100%;"><a style="float: none; width: auto;" href="http://felix.apache.org/ipojo/api/1.2.0" rel="nofollow">Javadoc</a></li>
148 <li style="white-space: normal; float: left; width: 100%;"><a style="float: none; width: auto;" href="http://felix.apache.org/site/how-to-write-your-own-handler.html" title="How to write your own handler">Handler guide</a></li>
149 <li style="white-space: normal; float: left; width: 100%;"><a style="float: none; width: auto;" href="http://felix.apache.org/site/how-to-use-ipojo-manipulation-metadata.html" title="How to use iPOJO Manipulation Metadata">Manipulation Metadata </a></li>
150 <li style="white-space: normal; float: left; width: 100%;"><a style="float: none; width: auto;" 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>
151 </ul>
152 </li> <!-- End of Dev guide -->
153</ul>
154</li> <!-- End of doc -->
155<!-- Menu 4 : Tools -->
156<li class="">
157<a href="" class="sf-with-ul">Tools<span class="sf-sub-indicator"> »</span><span class="sf-sub-indicator"> »</span><span class="sf-sub-indicator"> »</span></a>
158<ul style="float: none; width: 14em; display: none; visibility: hidden;">
159 <li style="white-space: normal; float: left; width: 100%;"><a style="float: none; width: auto;" href="http://felix.apache.org/site/ipojo-ant-task.html" title="iPOJO Ant Task">Ant Task</a></li>
160 <li style="white-space: normal; float: left; width: 100%;"><a style="float: none; width: auto;" href="http://felix.apache.org/site/ipojo-eclipse-plug-in.html" title="iPOJO Eclipse Plug-in">Eclipse Plugin</a></li>
161 <li style="white-space: normal; float: left; width: 100%;"><a style="float: none; width: auto;" href="http://felix.apache.org/site/ipojo-maven-plug-in.html" title="iPOJO Maven Plug-in">Maven Plugin</a></li>
162 <li style="white-space: normal; float: left; width: 100%;"><a style="float: none; width: auto;" href="http://felix.apache.org/site/apache-felix-ipojo-online-manipulator.html" title="apache-felix-ipojo-online-manipulator">Online Manipulator</a></li>
163 <li style="white-space: normal; float: left; width: 100%;"><a style="float: none; width: auto;" href="http://felix.apache.org/site/ipojo-webconsole-plugin.html" title="iPOJO Webconsole Plugin">Webconsole plugin</a></li>
164 <li style="white-space: normal; float: left; width: 100%;"><a style="float: none; width: auto;" href="http://felix.apache.org/site/apache-felix-ipojo-junit4osgi.html" title="apache-felix-ipojo-junit4osgi">Junit4OSGi</a></li>
165</ul>
166</li><!-- End of tools -->
167<!-- Menu 5 : Misc -->
168<li class="">
169<a href="" class="sf-with-ul">Misc<span class="sf-sub-indicator"> »</span><span class="sf-sub-indicator"> »</span><span class="sf-sub-indicator"> »</span></a>
170<ul style="float: none; width: 14em; display: none; visibility: hidden;">
171 <li style="white-space: normal; float: left; width: 100%;"><a style="float: none; width: auto;" href="http://felix.apache.org/site/apache-felix-ipojo-issuestracker.html" title="apache-felix-ipojo-issuestracker">Issues Tracker</a></li>
172 <li style="white-space: normal; float: left; width: 100%;"><a style="float: none; width: auto;" href="http://felix.apache.org/site/apache-felix-ipojo-supportedvms.html" title="apache-felix-ipojo-supportedVMs">Supported JVMs</a></li>
173 <li style="white-space: normal; float: left; width: 100%;"><a style="float: none; width: auto;" href="http://felix.apache.org/site/apache-felix-ipojo-supportedosgi.html" title="apache-felix-ipojo-supportedOSGi">Supported OSGi Implementations</a></li>
174 <li style="white-space: normal; float: left; width: 100%;"><a style="float: none; width: auto;" href="http://ipojo-dark-side.blogspot.com/" rel="nofollow">iPOJO's Dark Side Blog</a></li>
175 <li style="white-space: normal; float: left; width: 100%;"><a style="float: none; width: auto;" href="http://felix.apache.org/site/article-presentations.html" title="Article &amp; Presentations">Article &amp; Presentations</a></li>
176</ul>
177</li><!-- End of misc -->
178</ul> <!-- End of the menu -->
179</div> <!-- Page header -->
180
181
182<div class="content">
183
184<h1><a name="HowtouseiPOJOAnnotations-HowtouseiPOJOannotations"></a>How to use iPOJO annotations</h1>
185
186<p><em>You can use annotations to define your component types. This page presents supported iPOJO annotations.</em></p>
187
188<div class="toc">
189<ul>
190 <li><a href="#HowtouseiPOJOAnnotations-GettingiPOJOAnnotations%253A">Getting iPOJO Annotations:</a></li>
191<ul>
192 <li><a href="#HowtouseiPOJOAnnotations-InEclipse">In Eclipse</a></li>
193 <li><a href="#HowtouseiPOJOAnnotations-InMaven">In Maven</a></li>
194 <li><a href="#HowtouseiPOJOAnnotations-InAnt">In Ant</a></li>
195</ul>
196 <li><a href="#HowtouseiPOJOAnnotations-Anexampleofusage">An example of usage</a></li>
197<ul>
198 <li><a href="#HowtouseiPOJOAnnotations-HelloServiceProvider">Hello Service Provider</a></li>
199 <li><a href="#HowtouseiPOJOAnnotations-HelloServiceConsumer">Hello Service Consumer</a></li>
200</ul>
201 <li><a href="#HowtouseiPOJOAnnotations-DefinedAnnotations">Defined Annotations</a></li>
202<ul>
203 <li><a href="#HowtouseiPOJOAnnotations-@Component">@Component</a></li>
204 <li><a href="#HowtouseiPOJOAnnotations-@Provides">@Provides</a></li>
205 <li><a href="#HowtouseiPOJOAnnotations-@Requires">@Requires</a></li>
206 <li><a href="#HowtouseiPOJOAnnotations-@ServiceProperty">@ServiceProperty</a></li>
207 <li><a href="#HowtouseiPOJOAnnotations-@Property">@Property</a></li>
208 <li><a href="#HowtouseiPOJOAnnotations-@Updated%255CNewsinthe1.3.0SNAPSHOTversion%255C">@Updated <b>[ News in the 1.3.0-SNAPSHOT version ]</b></a></li>
209 <li><a href="#HowtouseiPOJOAnnotations-@Bind">@Bind</a></li>
210 <li><a href="#HowtouseiPOJOAnnotations-@Unbind">@Unbind</a></li>
211 <li><a href="#HowtouseiPOJOAnnotations-@Validate">@Validate</a></li>
212 <li><a href="#HowtouseiPOJOAnnotations-@Invalidate">@Invalidate</a></li>
213 <li><a href="#HowtouseiPOJOAnnotations-TemporalDependencies%2528externalhandler%2529">Temporal Dependencies (external handler)</a></li>
214 <li><a href="#HowtouseiPOJOAnnotations-ExposinginstancesasaJMXMBean%2528externalhandler%2529">Exposing instances as a JMX MBean (external handler)</a></li>
215</ul>
216 <li><a href="#HowtouseiPOJOAnnotations-AdvancedtopicsandFAQ">Advanced topics and FAQ</a></li>
217<ul>
218 <li><a href="#HowtouseiPOJOAnnotations-Metadatafileandannotationmerge">Metadata file and annotation merge</a></li>
219 <li><a href="#HowtouseiPOJOAnnotations-Instancecreation">Instance creation</a></li>
220 <li><a href="#HowtouseiPOJOAnnotations-UsingCustomAnnotations">Using Custom Annotations</a></li>
221</ul>
222</ul></div>
223
224<h2><a name="HowtouseiPOJOAnnotations-GettingiPOJOAnnotations:"></a>Getting iPOJO Annotations:</h2>
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]225
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame]226<p>iPOJO Annotations are defines inside the
227org.apache.felix.ipojo.annotations project. You can download the Jar
Clement Escoffier373a57d2009-07-21 12:06:46 +0000[diff] [blame^]228file of this project from the <a href="http://felix.apache.org/site/download.html" title="Download">download</a> page. Sources are available on the <a href="http://felix.apache.org/site/sourcecode.html" rel="nofollow">Felix trunk</a>.<br>
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame]229Once added to your class path / build path / dependencies, you can use
230the annotations as normal annotations. These annotations are
231automatically processed by the iPOJO manipulator.</p>
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]232
Clement Escoffier373a57d2009-07-21 12:06:46 +0000[diff] [blame^]233<h3><a name="HowtouseiPOJOAnnotations-InEclipse"></a>In Eclipse</h3>
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]234
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame]235<p>Add the org.apache.felix.ipojo.annotations jar file in your build
236path. Do not forget to use a Java compiler accepting annotations (1.5
237or higher).</p>
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]238
Clement Escoffier373a57d2009-07-21 12:06:46 +0000[diff] [blame^]239<h3><a name="HowtouseiPOJOAnnotations-InMaven"></a>In Maven</h3>
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]240
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame]241<p>Add the following dependency:</p>
Clement Escoffier373a57d2009-07-21 12:06:46 +0000[diff] [blame^]242<div class="code">
243<div class="dp-highlighter"><table class="dp-xml" border="0" cellpadding="0" cellspacing="0"><tbody><tr><td class="line1"><span></span><span class="tag">&lt;</span><span>dependency</span><span class="tag">&gt;</span><span>&nbsp;</span></td></tr><tr><td class="line2">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span class="tag">&lt;</span><span>groupId</span><span class="tag">&gt;</span><span>org.apache.felix</span><span class="tag">&lt;/</span><span>groupId</span><span class="tag">&gt;</span><span>&nbsp;</span></td></tr><tr><td class="line1">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span class="tag">&lt;</span><span>artifactId</span><span class="tag">&gt;</span><span>org.apache.felix.ipojo.annotations</span><span class="tag">&lt;/</span><span>artifactId</span><span class="tag">&gt;</span><span>&nbsp;</span></td></tr><tr><td class="line2">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span class="tag">&lt;</span><span>version</span><span class="tag">&gt;</span><span>1.2.0</span><span class="tag">&lt;/</span><span>version</span><span class="tag">&gt;</span><span>&nbsp;</span></td></tr><tr><td class="line1"><span class="tag">&lt;/</span><span>dependency</span><span class="tag">&gt;</span><span>&nbsp;</span></td></tr></tbody></table></div><textarea style="display: none;" name="newcodemacro" class="xml:nocontrols:nogutter" rows="10" readonly="readonly">&lt;dependency&gt;
244 &lt;groupId&gt;org.apache.felix&lt;/groupId&gt;
245 &lt;artifactId&gt;org.apache.felix.ipojo.annotations&lt;/artifactId&gt;
246 &lt;version&gt;1.2.0&lt;/version&gt;
247&lt;/dependency&gt;</textarea>
248<script class="javascript">
249 if(!window.newcodemacro_initialised)
250 {
251 window.newcodemacro_initialised = true;
252 window.oldonloadmethod = window.onload;
253 window.onload = function(){
254 dp.SyntaxHighlighter.HighlightAll('newcodemacro');
255 if(window.oldonloadmethod)
256 {
257 window.oldonloadmethod();
258 }
259 }
260 }
261
262</script>
263</div>
264
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame]265<p>Moreover, you need to set that the source code and the target code
266are Java 1.5 code. To achieve this, just add the following plugin in
267your plugins section:</p>
Clement Escoffier373a57d2009-07-21 12:06:46 +0000[diff] [blame^]268<div class="code">
269<div class="dp-highlighter"><table class="dp-xml" border="0" cellpadding="0" cellspacing="0"><tbody><tr><td class="line1"><span></span><span class="tag">&lt;</span><span>plugin</span><span class="tag">&gt;</span><span>&nbsp;</span></td></tr><tr><td class="line2">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span class="tag">&lt;</span><span>groupId</span><span class="tag">&gt;</span><span>org.apache.maven.plugins</span><span class="tag">&lt;/</span><span>groupId</span><span class="tag">&gt;</span><span>&nbsp;</span></td></tr><tr><td class="line1">&nbsp;&nbsp;&nbsp;&nbsp;<span class="tag">&lt;</span><span>artifactId</span><span class="tag">&gt;</span><span>maven-compiler-plugin</span><span class="tag">&lt;/</span><span>artifactId</span><span class="tag">&gt;</span><span>&nbsp;</span></td></tr><tr><td class="line2">&nbsp;&nbsp;&nbsp;&nbsp;<span class="tag">&lt;</span><span>configuration</span><span class="tag">&gt;</span><span>&nbsp;</span></td></tr><tr><td class="line1">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span class="tag">&lt;</span><span>source</span><span class="tag">&gt;</span><span>1.5</span><span class="tag">&lt;/</span><span>source</span><span class="tag">&gt;</span><span>&nbsp;</span></td></tr><tr><td class="line2">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span class="tag">&lt;</span><span>target</span><span class="tag">&gt;</span><span>1.5</span><span class="tag">&lt;/</span><span>target</span><span class="tag">&gt;</span><span>&nbsp;</span></td></tr><tr><td class="line1">&nbsp;&nbsp;&nbsp;&nbsp;<span class="tag">&lt;/</span><span>configuration</span><span class="tag">&gt;</span><span>&nbsp;</span></td></tr><tr><td class="line2"><span class="tag">&lt;/</span><span>plugin</span><span class="tag">&gt;</span><span>&nbsp;</span></td></tr></tbody></table></div><textarea style="display: none;" name="newcodemacro" class="xml:nocontrols:nogutter" rows="10" readonly="readonly">&lt;plugin&gt;
270 &lt;groupId&gt;org.apache.maven.plugins&lt;/groupId&gt;
271 &lt;artifactId&gt;maven-compiler-plugin&lt;/artifactId&gt;
272 &lt;configuration&gt;
273 &lt;source&gt;1.5&lt;/source&gt;
274 &lt;target&gt;1.5&lt;/target&gt;
275 &lt;/configuration&gt;
276&lt;/plugin&gt;</textarea>
277<script class="javascript">
278 if(!window.newcodemacro_initialised)
279 {
280 window.newcodemacro_initialised = true;
281 window.oldonloadmethod = window.onload;
282 window.onload = function(){
283 dp.SyntaxHighlighter.HighlightAll('newcodemacro');
284 if(window.oldonloadmethod)
285 {
286 window.oldonloadmethod();
287 }
288 }
289 }
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]290
Clement Escoffier373a57d2009-07-21 12:06:46 +0000[diff] [blame^]291</script>
292</div>
293
294
295<h3><a name="HowtouseiPOJOAnnotations-InAnt"></a>In Ant</h3>
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]296
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame]297<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]298
Clement Escoffier373a57d2009-07-21 12:06:46 +0000[diff] [blame^]299<h2><a name="HowtouseiPOJOAnnotations-Anexampleofusage"></a>An example of usage</h2>
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]300
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame]301<p>To illustrate annotations usage, let taking the tutorial example. In this tutorial, there are two components:</p>
302<ul>
303 <li>The first one provides the hello service</li>
304 <li>The second one uses the provided hello service<br>
Clement Escoffier373a57d2009-07-21 12:06:46 +0000[diff] [blame^]305You can download the archive containing the examples and a preconfigured version of Felix <a href="http://people.apache.org/%7Eclement/ipojo/tutorials/annotations/annotation-tutorial.zip" rel="nofollow">here</a>.</li>
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame]306</ul>
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]307
308
Clement Escoffier373a57d2009-07-21 12:06:46 +0000[diff] [blame^]309<h3><a name="HowtouseiPOJOAnnotations-HelloServiceProvider"></a>Hello Service Provider</h3>
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]310
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame]311<p>The provider uses two annotations. The "component" annotation is
312mandatory and defines that the class defines a component type. Then the
313"provides" annotation just declare that the defined component type
314provides a service.</p>
Clement Escoffier373a57d2009-07-21 12:06:46 +0000[diff] [blame^]315<div class="code">
316<div class="dp-highlighter"><table class="dp-c" border="0" cellpadding="0" cellspacing="0"><tbody><tr><td class="line1"><span></span><span class="keyword">package</span><span>&nbsp;ipojo.example.hello.impl;&nbsp;</span></td></tr><tr><td class="line2">&nbsp;</td></tr><tr><td class="line1"><span class="keyword">import</span><span>&nbsp;ipojo.example.hello.Hello;&nbsp;</span></td></tr><tr><td class="line2">&nbsp;</td></tr><tr><td class="line1"><span class="keyword">import</span><span>&nbsp;org.apache.felix.ipojo.annotations.Component;&nbsp;</span></td></tr><tr><td class="line2"><span class="keyword">import</span><span>&nbsp;org.apache.felix.ipojo.annotations.Provides;&nbsp;</span></td></tr><tr><td class="line1">&nbsp;</td></tr><tr><td class="line2"><span class="comment">/**</span></td></tr><tr><td class="line1"><span class="comment">&nbsp;&nbsp;*&nbsp;Component&nbsp;implementing&nbsp;the&nbsp;Hello&nbsp;service.</span></td></tr><tr><td class="line2"><span class="comment">&nbsp;**/</span><span>&nbsp;</span></td></tr><tr><td class="line1"><span class="preprocessor">@Component</span><span>&nbsp;</span></td></tr><tr><td class="line2"><span class="preprocessor">@Provides</span><span>&nbsp;</span></td></tr><tr><td class="line1"><span class="keyword">public</span><span>&nbsp;</span><span class="keyword">class</span><span>&nbsp;HelloImpl&nbsp;</span><span class="keyword">implements</span><span>&nbsp;Hello&nbsp;{&nbsp;</span></td></tr><tr><td class="line2">&nbsp;&nbsp;&nbsp;&nbsp;<span class="keyword">public</span><span>&nbsp;String&nbsp;sayHello(String&nbsp;name)&nbsp;{&nbsp;&nbsp;</span></td></tr><tr><td class="line1">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span class="keyword">return</span><span>&nbsp;</span><span class="string">"hello&nbsp;"</span><span>&nbsp;+&nbsp;name;&nbsp;&nbsp;</span></td></tr><tr><td class="line2">&nbsp;&nbsp;&nbsp;&nbsp;}&nbsp;</td></tr><tr><td class="line1">}&nbsp;</td></tr></tbody></table></div><textarea style="display: none;" name="newcodemacro" class="java:nocontrols:nogutter" rows="10" readonly="readonly">package ipojo.example.hello.impl;
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]317
Clement Escoffier373a57d2009-07-21 12:06:46 +0000[diff] [blame^]318import ipojo.example.hello.Hello;
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]319
Clement Escoffier373a57d2009-07-21 12:06:46 +0000[diff] [blame^]320import org.apache.felix.ipojo.annotations.Component;
321import org.apache.felix.ipojo.annotations.Provides;
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]322
323/**
324 * Component implementing the Hello service.
325 **/
326@Component
327@Provides
Clement Escoffier373a57d2009-07-21 12:06:46 +0000[diff] [blame^]328public class HelloImpl implements Hello {
329 public String sayHello(String name) {
330 return "hello " + name;
Clement Escoffier83507512008-10-13 07:33:03 +0000[diff] [blame]331 }
Clement Escoffier373a57d2009-07-21 12:06:46 +0000[diff] [blame^]332}</textarea>
333<script class="javascript">
334 if(!window.newcodemacro_initialised)
335 {
336 window.newcodemacro_initialised = true;
337 window.oldonloadmethod = window.onload;
338 window.onload = function(){
339 dp.SyntaxHighlighter.HighlightAll('newcodemacro');
340 if(window.oldonloadmethod)
341 {
342 window.oldonloadmethod();
343 }
344 }
345 }
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]346
Clement Escoffier373a57d2009-07-21 12:06:46 +0000[diff] [blame^]347</script>
348</div>
349
350
351<h3><a name="HowtouseiPOJOAnnotations-HelloServiceConsumer"></a>Hello Service Consumer</h3>
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]352
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame]353<p>The Hello Service Consumer use more annotations. First it used the
354component annotation. To defines its "immediate" behavior, it add the
355'immediate' attribute.<br>
356Then, it uses the requires annotation to define a service dependency.
357Finally, it uses the validate and invalidate annotations to define
358lifecycle callbacks.</p>
Clement Escoffier373a57d2009-07-21 12:06:46 +0000[diff] [blame^]359<div class="code">
360<div class="dp-highlighter"><table class="dp-c" border="0" cellpadding="0" cellspacing="0"><tbody><tr><td class="line1"><span></span><span class="keyword">package</span><span>&nbsp;ipojo.example.hello.client;&nbsp;</span></td></tr><tr><td class="line2">&nbsp;</td></tr><tr><td class="line1"><span class="keyword">import</span><span>&nbsp;org.apache.felix.ipojo.annotations.Component;&nbsp;</span></td></tr><tr><td class="line2"><span class="keyword">import</span><span>&nbsp;org.apache.felix.ipojo.annotations.Invalidate;&nbsp;</span></td></tr><tr><td class="line1"><span class="keyword">import</span><span>&nbsp;org.apache.felix.ipojo.annotations.Requires;&nbsp;</span></td></tr><tr><td class="line2"><span class="keyword">import</span><span>&nbsp;org.apache.felix.ipojo.annotations.Validate;&nbsp;</span></td></tr><tr><td class="line1">&nbsp;</td></tr><tr><td class="line2"><span class="keyword">import</span><span>&nbsp;ipojo.example.hello.Hello;&nbsp;</span></td></tr><tr><td class="line1"><span class="preprocessor"></span></td></tr><tr><td class="line2"><span class="preprocessor">@Component(name="AnnotedHelloClient",&nbsp;immediate=true)</span><span>&nbsp;</span></td></tr><tr><td class="line1"><span class="keyword">public</span><span>&nbsp;</span><span class="keyword">class</span><span>&nbsp;HelloClient&nbsp;</span><span class="keyword">implements</span><span>&nbsp;Runnable&nbsp;{&nbsp;</span></td></tr><tr><td class="line2"><span class="preprocessor"></span></td></tr><tr><td class="line1"><span class="preprocessor">@Requires</span><span>&nbsp;</span></td></tr><tr><td class="line2"><span class="keyword">private</span><span>&nbsp;Hello[]&nbsp;m_hello;&nbsp;</span><span class="comment">//&nbsp;Service&nbsp;Dependency</span><span>&nbsp;</span></td></tr><tr><td class="line1">&nbsp;</td></tr><tr><td class="line2"><span class="keyword">private</span><span>&nbsp;</span><span class="keyword">final</span><span>&nbsp;</span><span class="keyword">static</span><span>&nbsp;int&nbsp;DELAY=10000;&nbsp;</span></td></tr><tr><td class="line1"><span class="keyword">private</span><span>&nbsp;</span><span class="keyword">boolean</span><span>&nbsp;end;&nbsp;</span></td></tr><tr><td class="line2">&nbsp;</td></tr><tr><td class="line1">&nbsp;<span class="keyword">public</span><span>&nbsp;</span><span class="keyword">void</span><span>&nbsp;run()&nbsp;{&nbsp;</span></td></tr><tr><td class="line2">&nbsp;&nbsp;&nbsp;&nbsp;<span class="keyword">while</span><span>&nbsp;(!end)&nbsp;{&nbsp;</span></td></tr><tr><td class="line1">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span class="keyword">try</span><span>&nbsp;{&nbsp;</span></td></tr><tr><td class="line2">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;invoke();&nbsp;</td></tr><tr><td class="line1">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Thread.sleep(DELAY);&nbsp;</td></tr><tr><td class="line2">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;}&nbsp;<span class="keyword">catch</span><span>&nbsp;(InterruptedException&nbsp;ie)&nbsp;{&nbsp;}&nbsp;</span></td></tr><tr><td class="line1">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span class="comment">/*&nbsp;will&nbsp;recheck&nbsp;end&nbsp;*/</span><span>&nbsp;</span></td></tr><tr><td class="line2">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;}&nbsp;</td></tr><tr><td class="line1">}&nbsp;</td></tr><tr><td class="line2">&nbsp;</td></tr><tr><td class="line1"><span class="keyword">public</span><span>&nbsp;</span><span class="keyword">void</span><span>&nbsp;invoke()&nbsp;{&nbsp;</span></td></tr><tr><td class="line2">&nbsp;&nbsp;&nbsp;&nbsp;for&nbsp;(int&nbsp;i&nbsp;=&nbsp;0;&nbsp;i&nbsp;&lt;&nbsp;m_hello.length;&nbsp;i++)&nbsp;{&nbsp;&nbsp;</td></tr><tr><td class="line1">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;System.out.println(m_hello[i].&nbsp;</td></tr><tr><td class="line2">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;sayHello(<span class="string">"Clement"</span><span>));&nbsp;&nbsp;</span></td></tr><tr><td class="line1">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;}&nbsp;</td></tr><tr><td class="line2">}&nbsp;</td></tr><tr><td class="line1"><span class="preprocessor"></span></td></tr><tr><td class="line2"><span class="preprocessor">&nbsp;@Validate</span><span>&nbsp;</span></td></tr><tr><td class="line1">&nbsp;<span class="keyword">public</span><span>&nbsp;</span><span class="keyword">void</span><span>&nbsp;starting()&nbsp;{&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</span></td></tr><tr><td class="line2">&nbsp;&nbsp;&nbsp;&nbsp;Thread&nbsp;T&nbsp;=&nbsp;new&nbsp;Thread(<span class="keyword">this</span><span>);&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</span></td></tr><tr><td class="line1">&nbsp;&nbsp;&nbsp;&nbsp;end&nbsp;=&nbsp;<span class="keyword">false</span><span>;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</span></td></tr><tr><td class="line2">&nbsp;&nbsp;&nbsp;&nbsp;T.start();&nbsp;&nbsp;</td></tr><tr><td class="line1">&nbsp;}&nbsp;</td></tr><tr><td class="line2"><span class="preprocessor"></span></td></tr><tr><td class="line1"><span class="preprocessor">&nbsp;@Invalidate</span><span>&nbsp;</span></td></tr><tr><td class="line2">&nbsp;<span class="keyword">public</span><span>&nbsp;</span><span class="keyword">void</span><span>&nbsp;stopping()&nbsp;{&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</span></td></tr><tr><td class="line1">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;end&nbsp;=&nbsp;<span class="keyword">true</span><span>;&nbsp;&nbsp;</span></td></tr><tr><td class="line2">&nbsp;}&nbsp;</td></tr><tr><td class="line1">}&nbsp;</td></tr></tbody></table></div><textarea style="display: none;" name="newcodemacro" class="java:nocontrols:nogutter" rows="10" readonly="readonly">package ipojo.example.hello.client;
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]361
Clement Escoffier373a57d2009-07-21 12:06:46 +0000[diff] [blame^]362import org.apache.felix.ipojo.annotations.Component;
363import org.apache.felix.ipojo.annotations.Invalidate;
364import org.apache.felix.ipojo.annotations.Requires;
365import org.apache.felix.ipojo.annotations.Validate;
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]366
Clement Escoffier373a57d2009-07-21 12:06:46 +0000[diff] [blame^]367import ipojo.example.hello.Hello;
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]368
Clement Escoffier373a57d2009-07-21 12:06:46 +0000[diff] [blame^]369@Component(name="AnnotedHelloClient", immediate=true)
370public class HelloClient implements Runnable {
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]371
372@Requires
Clement Escoffier373a57d2009-07-21 12:06:46 +0000[diff] [blame^]373private Hello[] m_hello; // Service Dependency
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]374
Clement Escoffier373a57d2009-07-21 12:06:46 +0000[diff] [blame^]375private final static int DELAY=10000;
376private boolean end;
377
378 public void run() {
379 while (!end) {
380 try {
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]381 invoke();
Clement Escoffier373a57d2009-07-21 12:06:46 +0000[diff] [blame^]382 Thread.sleep(DELAY);
383 } catch (InterruptedException ie) { }
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]384 /* will recheck end */
385 }
386}
387
Clement Escoffier373a57d2009-07-21 12:06:46 +0000[diff] [blame^]388public void invoke() {
389 for (int i = 0; i &lt; m_hello.length; i++) {
390 System.out.println(m_hello[i].
391 sayHello("Clement"));
Clement Escoffier83507512008-10-13 07:33:03 +0000[diff] [blame]392 }
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]393}
394
395 @Validate
Clement Escoffier373a57d2009-07-21 12:06:46 +0000[diff] [blame^]396 public void starting() {
397 Thread T = new Thread(this);
398 end = false;
Clement Escoffier83507512008-10-13 07:33:03 +0000[diff] [blame]399 T.start();
400 }
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]401
402 @Invalidate
Clement Escoffier373a57d2009-07-21 12:06:46 +0000[diff] [blame^]403 public void stopping() {
404 end = true;
Clement Escoffier83507512008-10-13 07:33:03 +0000[diff] [blame]405 }
Clement Escoffier373a57d2009-07-21 12:06:46 +0000[diff] [blame^]406}</textarea>
407<script class="javascript">
408 if(!window.newcodemacro_initialised)
409 {
410 window.newcodemacro_initialised = true;
411 window.oldonloadmethod = window.onload;
412 window.onload = function(){
413 dp.SyntaxHighlighter.HighlightAll('newcodemacro');
414 if(window.oldonloadmethod)
415 {
416 window.oldonloadmethod();
417 }
418 }
419 }
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]420
Clement Escoffier373a57d2009-07-21 12:06:46 +0000[diff] [blame^]421</script>
422</div>
423
424
425<h2><a name="HowtouseiPOJOAnnotations-DefinedAnnotations"></a>Defined Annotations</h2>
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]426
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame]427<p>This section lists defined annotations and how to use them.</p>
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]428
Clement Escoffier373a57d2009-07-21 12:06:46 +0000[diff] [blame^]429<h3><a name="HowtouseiPOJOAnnotations-@Component"></a>@Component</h3>
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]430
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame]431<p><b>Goal:</b> Defines a component type<br>
432<b>Target:</b> The component implementation class<br>
433<b>Attributes:</b></p>
434<ul>
435 <li>name : defines the component type name (optional, default = the class name)</li>
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame]436 <li>immediate: defines the component type as immediate (optional, default = "false")</li>
437 <li>architecture: enable the architecture exposition (optional, default = "false")</li>
438 <li>propagation: enable configuration property propagation (on provided services) (optional, default = "false")</li>
Clement Escoffier373a57d2009-07-21 12:06:46 +0000[diff] [blame^]439 <li>managedservice : set the Managed Service PID. (optional, default = no PID (i.e. the managed service will not be exposed)).</li>
440 <li>factory_method
441: set the factory-method. The specified method must be a static method
442and return a pojo object.(optional, default = iPOJO uses the 'regular'
443constructor).</li>
444 <li>public_factory : set if the component type is public. (optional, default = true).</li>
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame]445</ul>
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]446
447
Clement Escoffier373a57d2009-07-21 12:06:46 +0000[diff] [blame^]448<h3><a name="HowtouseiPOJOAnnotations-@Provides"></a>@Provides</h3>
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]449
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame]450<p><b>Goal:</b> Defines that the component type provide services<br>
451<b>Target:</b> The component implementation class<br>
452<b>Attributes:</b></p>
453<ul>
454 <li>specifications: defines the provided interface (optional, default = all implemented interfaces)</li>
Clement Escoffier373a57d2009-07-21 12:06:46 +0000[diff] [blame^]455 <li>strategy
456: the service object creation strategy. Possible values : SINGLETON,
457SERVICE, METHOD, INSTANCE or the strategy class name. With SINGLETON
458there is only one POJO per component instance, SERVICE means OSGi
459Service factory, METHOD delegates the creation to the factory-method of
460the component, INSTANCE creates one service object per requiring
461instance. For other strategies, specify the qualified name of the
462CreationStrategy class. (optional, default = SINGLETON)</li>
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame]463</ul>
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]464
465
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]466
Clement Escoffier373a57d2009-07-21 12:06:46 +0000[diff] [blame^]467<div class="box">
468 <div class="box-blue-header">
469 <div class="box-blue-title">
470 <img src="how-to-use-ipojo-annotations_files/information.gif"> <b>OSGi Service Factory</b>
471 </div>
472 </div>
473 <div class="box-blue-content">
474The <tt>SERVICE</tt> strategy means OSGi service factory. So, one service object per asking bundle will be created.
475 </div>
476 <div class="box-blue-footer"></div>
477</div>
478
479
480
481
482<div class="box">
483 <div class="box-blue-header">
484 <div class="box-blue-title">
485 <img src="how-to-use-ipojo-annotations_files/information.gif"> <b>Changes between the 1.0.0 and the 1.2.0</b>
486 </div>
487 </div>
488 <div class="box-blue-content">
489The <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.
490 </div>
491 <div class="box-blue-footer"></div>
492</div>
493
494
495<h3><a name="HowtouseiPOJOAnnotations-@Requires"></a>@Requires</h3>
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]496
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame]497<p><b>Goal:</b> Defines a service dependency<br>
498<b>Target:</b> Field<br>
499<b>Attributes:</b></p>
500<ul>
501 <li>Filter: defines the LDAP filter (optional)</li>
502 <li>Optional: defines if the dependency is optional (optional, default = "false")</li>
503 <li>Id:
504defines the dependency Id (useful to identify bind &amp; unbind
505methods) (optional, default = field name) (if a dependency with the
506same id is already created (by a @bind or @unbind annotation), it
507merges the dependencies).</li>
508 <li>Nullable: enable or disable the
509Null Object injection when the dependency is optional and no providers
510are available (optional, default = "true")</li>
511 <li>Default-Implementation: set the Default-Implmentation (optional, by default iPOJO uses a Null object)</li>
512 <li>Policy: defines the binding policy (accepted value : dynamic, static, dynamic-priority) (optional, default = "dynamic")</li>
513 <li>Comparator: defines the comparator to use to sort service references (optional, default = OSGi Service Reference Comparator)</li>
514 <li>From : defines the specific provider to use</li>
Clement Escoffier373a57d2009-07-21 12:06:46 +0000[diff] [blame^]515 <li>Specification
516: the required service specification. This attribute is required for
517Collection field. (optional, default = annotated field type).</li>
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame]518</ul>
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]519
520
Clement Escoffier373a57d2009-07-21 12:06:46 +0000[diff] [blame^]521<h3><a name="HowtouseiPOJOAnnotations-@ServiceProperty"></a>@ServiceProperty</h3>
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]522
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame]523<p><b>Goal:</b> Defines a service property<br>
524<b>Target:</b> Field<br>
525<b>Attributes:</b></p>
526<ul>
527 <li>name: property name (optional, default=field name</li>
528 <li>value: property value (optional, default=no value)</li>
Clement Escoffier373a57d2009-07-21 12:06:46 +0000[diff] [blame^]529 <li>mandatory : is the property mandatory? (optional, default=false)</li>
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame]530</ul>
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]531
532
Clement Escoffier373a57d2009-07-21 12:06:46 +0000[diff] [blame^]533
534<div class="box">
535 <div class="box-blue-header">
536 <div class="box-blue-title">
537 <img src="how-to-use-ipojo-annotations_files/information.gif"> <b>Mandatory property</b>
538 </div>
539 </div>
540 <div class="box-blue-content">
541A mandatory property must receive a value either from the component type description (<tt>value</tt> attribute, or the instance configuration.
542 </div>
543 <div class="box-blue-footer"></div>
544</div>
545
546
547<h3><a name="HowtouseiPOJOAnnotations-@Property"></a>@Property</h3>
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]548
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame]549<p><b>Goal:</b> Defines a property<br>
550<b>Target:</b> Field or Method<br>
551<b>Attributes:</b></p>
552<ul>
553 <li>name: property name (optional, default=field name computed by
554removing "set" from the method name (for instance setFoo(String ff)
555will get the Foo name))</li>
556 <li>value: property value (optional, default=no value)</li>
Clement Escoffier373a57d2009-07-21 12:06:46 +0000[diff] [blame^]557 <li>mandatory : is the property mandatory? (optional, default=false)</li>
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame]558</ul>
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]559
560
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]561
Clement Escoffier373a57d2009-07-21 12:06:46 +0000[diff] [blame^]562<div class="box">
563 <div class="box-blue-header">
564 <div class="box-blue-title">
565 <img src="how-to-use-ipojo-annotations_files/information.gif"> <b>Field and Method</b>
566 </div>
567 </div>
568 <div class="box-blue-content">
569If another property with the same name is defined the method or the field is added to the existing property.
570 </div>
571 <div class="box-blue-footer"></div>
572</div>
573
574
575<h3><a name="HowtouseiPOJOAnnotations-@Updated\Newsinthe1.3.0SNAPSHOTversion\"></a>@Updated <b>[ News in the 1.3.0-SNAPSHOT version ]</b></h3>
576<p><b>Goal:</b> Defines method called when a reconfiguration is completed.<br>
577<b>Target:</b> a method (receiving a dictionary in argument)</p>
578
579<h3><a name="HowtouseiPOJOAnnotations-@Bind"></a>@Bind</h3>
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]580
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame]581<p><b>Goal:</b> Defines a bind method<br>
582<b>Target:</b> Method<br>
583<b>Attributes:</b></p>
584<ul>
585 <li>Id: Dependency Id, if the id is already defines in a
586"@requires " or "@unbind" annotation, it adds this method as a bind
587method of the already created dependency. (optional, default= no id,
588compute an id if the method name begin by "bind" (for instance
589"bindFoo" will have the "Foo" id))</li>
590 <li>Specification : required dependency (optional)</li>
591 <li>Aggregate : is the dependency an aggregate dependency (optional, default= "false")</li>
592 <li>Optional: is the dependency an optional dependency (optional, default= "false")</li>
593 <li>Filter: dependency LDAP filter (optional)</li>
594 <li>Policy: defines the binding policy (accepted value : dynamic, static, dynamic-priority) (optional, default = "dynamic")</li>
595 <li>Comparator: defines the comparator to use to sort service references (optional, default = OSGi Service Reference Comparator)</li>
596 <li>From : defines the specific provider to use</li>
597</ul>
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]598
599
Clement Escoffier373a57d2009-07-21 12:06:46 +0000[diff] [blame^]600<h3><a name="HowtouseiPOJOAnnotations-@Unbind"></a>@Unbind</h3>
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]601
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame]602<p><b>Goal:</b> Defines an unbind method<br>
603<b>Target:</b> Method<br>
604<b>Attributes:</b></p>
605<ul>
606 <li>Id: Dependency Id, if the id is already defines in a
607"@requires" or "@bind" annotation, it adds this method as an unbind
608method of the already created dependency. (optional, default= no id,
609compute an id if the method name begin by "unbind" (for instance
610"unbindFoo" will have the "Foo" id))</li>
611 <li>Specification : required dependency (optional)</li>
612 <li>Aggregate : is the dependency an aggregate dependency (optional, default= "false")</li>
613 <li>Optional: is the dependency an optional dependency (optional, default= "false")</li>
614 <li>Filter: dependency LDAP filter (optional)</li>
615 <li>Policy: defines the binding policy (accepted value : dynamic, static, dynamic-priority) (optional, default = "dynamic")</li>
616 <li>Comparator: defines the comparator to use to sort service references (optional, default = OSGi Service Reference Comparator)</li>
617 <li>From : defines the specific provider to use</li>
618</ul>
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]619
620
Clement Escoffier373a57d2009-07-21 12:06:46 +0000[diff] [blame^]621<h3><a name="HowtouseiPOJOAnnotations-@Validate"></a>@Validate</h3>
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]622
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame]623<p><b>Goal:</b> defines a validate lifecycle callback<br>
624<b>Target:</b> method</p>
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]625
Clement Escoffier373a57d2009-07-21 12:06:46 +0000[diff] [blame^]626<h3><a name="HowtouseiPOJOAnnotations-@Invalidate"></a>@Invalidate</h3>
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]627
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame]628<p><b>Goal:</b> defines a validate lifecycle callback<br>
629<b>Target:</b> method</p>
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]630
Clement Escoffier373a57d2009-07-21 12:06:46 +0000[diff] [blame^]631<h3><a name="HowtouseiPOJOAnnotations-TemporalDependencies(externalhandler)"></a>Temporal Dependencies (external handler)</h3>
Clement Escoffier83507512008-10-13 07:33:03 +0000[diff] [blame]632
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame]633<p>The temporal dependency handler is an external handler. However, it
634can be used with an annotation defined in the iPOJO annotations jar
635file. <br>
636The annotation is org.apache.felix.ipojo.handler.temporal.Requires and targets a field. <br>
637<b>Attributes:</b></p>
638<ul>
639 <li>filter : specify the dependency filter</li>
640 <li>timeout : specify the dependency timeout (optional)</li>
641 <li>onTimeout
642: specify the onTimeout action (null, nullable, empty-array,
643default-implementation (specify the class name in this case) (optional).</li>
Clement Escoffier373a57d2009-07-21 12:06:46 +0000[diff] [blame^]644 <li>specification
645: the required service specification. This attribute is required for
646Collection field. (optional, default = annotated field type).</li>
647 <li>Proxy : Inject a proxy instead of the real object. This allows passing this reference to collaborators. (Default = false)</li>
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame]648</ul>
Clement Escoffier83507512008-10-13 07:33:03 +0000[diff] [blame]649
650
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]651
Clement Escoffier373a57d2009-07-21 12:06:46 +0000[diff] [blame^]652
653<h3><a name="HowtouseiPOJOAnnotations-ExposinginstancesasaJMXMBean(externalhandler)"></a>Exposing instances as a JMX MBean (external handler)</h3>
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]654
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame]655<p>The JMX Handler allows exposing an instance as a JMX MBean. To
656configure the JMX handler directly from your code, three annotations
657are 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]658
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame]659<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>
660<ul>
661 <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>
662 <li>objectname: set the MBean objectname. The objectname must follow JMX specification. (default: <tt>package-name:factory-name:instance-name</tt>)</li>
663 <li>domain: set the MBean domain. (default: <tt>package-name</tt>)</li>
664 <li>name: set the MBean name. (default: <tt>instance-name</tt>).</li>
665</ul>
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]666
667
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame]668<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>
669<ul>
670 <li>name: set the property name</li>
671 <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>
672 <li>notification: enables notification on this property. By default notifications are disabled.</li>
673</ul>
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]674
675
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame]676<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>
677<ul>
678 <li>description: set the method description.</li>
679</ul>
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]680
681
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame]682
Clement Escoffier373a57d2009-07-21 12:06:46 +0000[diff] [blame^]683<h2><a name="HowtouseiPOJOAnnotations-AdvancedtopicsandFAQ"></a>Advanced topics and FAQ</h2>
684
685<h3><a name="HowtouseiPOJOAnnotations-Metadatafileandannotationmerge"></a>Metadata file and annotation merge</h3>
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame]686
687<p>It is possible to defines component type both in the metadata file
688(in XML) and by using annotation. However, if a component type defined
689by using annotations has the same name than a type define in the XML
690file, the XML descriptor override the annotation defined type. However,
691a warning message is launched during the manipulation.</p>
692
Clement Escoffier373a57d2009-07-21 12:06:46 +0000[diff] [blame^]693<h3><a name="HowtouseiPOJOAnnotations-Instancecreation"></a>Instance creation</h3>
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame]694
695<p>Annotation can only be used to define component type. To define
696instances, you need to use the XML descriptor. Instance can refer to
697annotated types by referring to their names.</p>
Clement Escoffier373a57d2009-07-21 12:06:46 +0000[diff] [blame^]698<div class="code">
699<div class="dp-highlighter"><table class="dp-xml" border="0" cellpadding="0" cellspacing="0"><tbody><tr><td class="line1"><span></span><span class="tag">&lt;</span><span>instance&nbsp;</span><span class="attribute">component</span><span>=</span><span class="attribute-value">"ipojo.example.hello.impl.HelloImpl"</span><span>/&gt;&nbsp;</span></td></tr><tr><td class="line2"><span class="tag">&lt;</span><span>instance&nbsp;</span><span class="attribute">component</span><span>=</span><span class="attribute-value">"AnnotedHelloClient"</span><span>/&gt;&nbsp;</span></td></tr></tbody></table></div><textarea style="display: none;" name="newcodemacro" class="xml:nocontrols:nogutter" rows="10" readonly="readonly">&lt;instance component="ipojo.example.hello.impl.HelloImpl"/&gt;
700&lt;instance component="AnnotedHelloClient"/&gt;</textarea>
701<script class="javascript">
702 if(!window.newcodemacro_initialised)
703 {
704 window.newcodemacro_initialised = true;
705 window.oldonloadmethod = window.onload;
706 window.onload = function(){
707 dp.SyntaxHighlighter.HighlightAll('newcodemacro');
708 if(window.oldonloadmethod)
709 {
710 window.oldonloadmethod();
711 }
712 }
713 }
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame]714
Clement Escoffier373a57d2009-07-21 12:06:46 +0000[diff] [blame^]715</script>
716</div>
717
718
719<h3><a name="HowtouseiPOJOAnnotations-UsingCustomAnnotations"></a>Using Custom Annotations</h3>
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame]720
721<p>External handlers can provides their own annotations. Using these
722annotations just requires to add them to your build path. To external
723handlers annotations, please refer to the external handler
Clement Escoffier373a57d2009-07-21 12:06:46 +0000[diff] [blame^]724documentation.
725<br clear="all">
726<br clear="all"></p>
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]727
Clement Escoffier373a57d2009-07-21 12:06:46 +0000[diff] [blame^]728 </div>
729 <img src="how-to-use-ipojo-annotations_files/footer.png" class="footer">
730</div>
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame]731
732<script type="text/javascript">
733var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www.");
734document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E"));
735</script><script src="how-to-use-ipojo-annotations_files/ga.js" type="text/javascript"></script>
736<script type="text/javascript">
Clement Escoffier373a57d2009-07-21 12:06:46 +0000[diff] [blame^]737try{
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame]738var pageTracker = _gat._getTracker("UA-1518442-4");
739pageTracker._trackPageview();
Clement Escoffier373a57d2009-07-21 12:06:46 +0000[diff] [blame^]740} catch(err) {}
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame]741</script>
Clement Escoffier373a57d2009-07-21 12:06:46 +0000[diff] [blame^]742
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame]743 </div>
Clement Escoffier373a57d2009-07-21 12:06:46 +0000[diff] [blame^]744 </body><div FirebugVersion="1.4.0" style="display: none;" id="_firebugConsole"></div></html>