Gitiles
Code Review Sign In
gerrit.onosproject.org / onos-felix / 8251f6064f6c9de65a2b72bb0a803d855ba13ac5 / . / ipojo / handler / temporal / doc / temporal-service-dependency.html
blob: 3a36dc055ed2bef9b787e7d24d4b9dc12d2781eb [file] [log] [blame]
Clement Escoffierbd7ff502008-06-06 12:12:01 +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 Escoffierbd7ff502008-06-06 12:12:01 +0000[diff] [blame]5
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame^]6 <title>Apache Felix - Temporal Service Dependency</title>
7 <link rel="stylesheet" href="temporal-service-dependency_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="temporal-service-dependency_files/logo.png" border="0"></a></div><div class="header"><a href="http://www.apache.org/"><img alt="Apache" src="temporal-service-dependency_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="temporal-service-dependency_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="temporal-service-dependency_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="temporal-service-dependency_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="temporal-service-dependency_files/linkext7.gif" alt="" align="absmiddle" border="0" width="7" height="7"></sup></a></span>
Clement Escoffierbd7ff502008-06-06 12:12:01 +0000[diff] [blame]22<!-- ApacheCon Ad -->
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame^]23<iframe src="temporal-service-dependency_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<h1><a name="TemporalServiceDependency-Thetemporaldependencyhandler"></a>The temporal dependency handler</h1>
Clement Escoffier83507512008-10-13 07:33:03 +0000[diff] [blame]31
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame^]32<p>Regular service dependencies participate to the instance lifecycle.
33Moreover, the injected service object is either available or not
34available. A temporal dependency handler is a little different and
35provides a different resolution pattern. Indeed, the temporal
36dependency does not invalidate the instance. Moreover, if not
37available, the temporal dependency waits (and so blocks the current
38thread) for a provider. Of course, the maximum waiting time can be
39specified. If a timeout occurs, the handler throws a runtime exception.<br>
40Using the handler</p>
Clement Escoffier83507512008-10-13 07:33:03 +0000[diff] [blame]41
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame^]42<p>First of all, you need to configure the component type to use the handler such as:</p>
43<div class="code"><div class="codeContent">
44<pre class="code-xml"><span class="code-tag">&lt;iPOJO <span class="code-keyword">xmlns:temporal</span>=<span class="code-quote">"org.apache.felix.ipojo.handler.temporal"</span>&gt;</span>
Clement Escoffier83507512008-10-13 07:33:03 +0000[diff] [blame]45&lt;component
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame^]46 className=<span class="code-quote">"org.apache.felix.ipojo.example.Temporal"</span>&gt;
Clement Escoffier83507512008-10-13 07:33:03 +0000[diff] [blame]47
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame^]48 <span class="code-tag"><span class="code-comment">&lt;!-- Temporal dependency configuration --&gt;</span></span>
49 <span class="code-tag">&lt;temporal:requires field=<span class="code-quote">"mytemporal"</span>/&gt;</span>
Clement Escoffier83507512008-10-13 07:33:03 +0000[diff] [blame]50
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame^]51 <span class="code-tag">&lt;provides/&gt;</span>
Clement Escoffier83507512008-10-13 07:33:03 +0000[diff] [blame]52
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame^]53<span class="code-tag">&lt;/component&gt;</span>
54<span class="code-tag">&lt;/iPOJO&gt;</span></pre>
55</div></div>
56<p>Notice that, this handler is an external handler. So, it uses the "org.apache.felix.ipojo.handler.temporal" namespace.<br>
57Once described, you can implement your component. The specified field
58will be mapped to the temporal dependency. As for regular field
59injection, aggregation, targeted service specification (i.e. interface)
60is discovered automatically. Filter, comparator and binding policy are
61also supported. However, the optional attribute is not supported. In
62fact, this attribute is meaningless in the case of a temporal
63dependency.<br>
64Using the field in your code will try to find a matching service
65provider. If a provider is available, the field receives the service
66object immediately. Else, the thread is stopped and waits for a
67provider. The default wait time is 3s (you can also specify this time).
68If no provider is available after this time, the thread throws a
69RuntimeException. If a provider becomes available during this time, the
70field receives immediately the value and the execution can continue.<br>
71Configuration</p>
Clement Escoffier83507512008-10-13 07:33:03 +0000[diff] [blame]72
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame^]73<p>The handler has only one mandatory attributes:</p>
74<ul>
75 <li>Field: the implementation field supporting the dependency</li>
76</ul>
Clement Escoffierbd7ff502008-06-06 12:12:01 +0000[diff] [blame]77
78
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame^]79<p>The handler supports on specific optional attributes:</p>
80<ul>
81 <li>Timeout: the maximum time waited in order to find a provider
82(default: 3s). For an infinite timeout, the timeout value is either
83"infinite" or "-1".</li>
84 <li>OnTimeout: specifies the action to do
85when the timeout occurs. Four actions are supported: null, nullable,
86empty-array, default-implementation. By default, no action is
87specified, and an exception occurs when the timeout is reached.</li>
88</ul>
Clement Escoffierbd7ff502008-06-06 12:12:01 +0000[diff] [blame]89
90
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame^]91<p>The attributes from "regular" dependencies are also supported (like filter).<br>
92OnTimeout actions</p>
Clement Escoffier83507512008-10-13 07:33:03 +0000[diff] [blame]93
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame^]94<p>When a timeout occurs, you can specify what the handler must do. By
95default, it throws a runtime exception. However, four others actions
96can be set in the 'onTimeout' attribute.</p>
97<ul>
98 <li>The null action (onTimeout="null") will return "null" instead of the service object.</li>
99 <li>The
100"nullable" action (onTimeout="nullable") will return a "Nullable"
101object instead of the service object. This object is a fake but can be
102used a regular service object. However, invoking actions on this object
103will do nothing. In the case of aggregate dependency, an array
104containing a "nullable" object is returned.</li>
105 <li>The empty-array
106action is only supported for aggregate dependency (the field must be an
107array). In this case, an empty-array is returned. <b>[ In the 1.1.0-SNAPSHOT version, the <tt>empty-array</tt> attribute became <tt>empty</tt>]</b></li>
108 <li>The
109default-implementation action is a little different. Instead of
110specifying the action, you need to specify the default-implementation
111(the qualified class name) that you want to use. For example
112onTimeout="o.a.f.i.MyDefaultLogServiceImpl". In this case, the handler
113will inject an instance of this object instead of a real service
114object. On aggregate dependency, an array with one
115default-implementation object is returned.</li>
116</ul>
Clement Escoffier83507512008-10-13 07:33:03 +0000[diff] [blame]117
118
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame^]119<div class="code"><div class="codeContent">
120<pre class="code-xml"><span class="code-tag">&lt;iPOJO <span class="code-keyword">xmlns:temporal</span>=<span class="code-quote">"org.apache.felix.ipojo.handler.temporal"</span>&gt;</span>
121&lt;component
122 className=<span class="code-quote">"org.apache.felix.ipojo.example.Temporal"</span>&gt;
Clement Escoffier83507512008-10-13 07:33:03 +0000[diff] [blame]123
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame^]124 <span class="code-tag"><span class="code-comment">&lt;!-- Temporal dependency configuration --&gt;</span></span>
125 <span class="code-tag">&lt;temporal:requires field=<span class="code-quote">"fs"</span> timeout=<span class="code-quote">"300"</span> ontimeout=<span class="code-quote">"nullable"</span>/&gt;</span>
126
127 <span class="code-tag">&lt;provides/&gt;</span>
128
129<span class="code-tag">&lt;/component&gt;</span>
130<span class="code-tag">&lt;/iPOJO&gt;</span></pre>
131</div></div>
132<h2><a name="TemporalServiceDependency-Collectionsupport\1.1.0SNAPSHOTversion\"></a>Collection support <b>[1.1.0-SNAPSHOT version ]</b></h2>
133<p>Temporal dependencies can also be injected inside Collection. To
134achieve this, the 'specification' attribute must indicates the looked
135specification, and the field must be a Collection.</p>
136<div class="code"><div class="codeContent">
137<pre class="code-xml"><span class="code-tag">&lt;iPOJO <span class="code-keyword">xmlns:temporal</span>=<span class="code-quote">"org.apache.felix.ipojo.handler.temporal"</span>&gt;</span>
138&lt;component
139 className=<span class="code-quote">"org.apache.felix.ipojo.example.Temporal"</span>&gt;
140
141 <span class="code-tag"><span class="code-comment">&lt;!-- Temporal dependency configuration --&gt;</span></span>
142 <span class="code-tag">&lt;temporal:requires field=<span class="code-quote">"mycollection"</span> specification=<span class="code-quote">"my.service.specification"</span>/&gt;</span>
143
144 <span class="code-tag">&lt;provides/&gt;</span>
145
146<span class="code-tag">&lt;/component&gt;</span>
147<span class="code-tag">&lt;/iPOJO&gt;</span></pre>
148</div></div>
149<h2><a name="TemporalServiceDependency-Proxysupport\1.1.0SNAPSHOTversion\"></a>Proxy support <b>[1.1.0-SNAPSHOT version ]</b></h2>
150<p>Temporal dependencies can also be injected as proxies. So it is possible to give the temporal dependency to helper object.<br>
151On 'scalar' dependencies, the service lookup is executed during an
152operation invocation. Timeout policies are also executed is the lookup
153failed.<br>
154On aggregate dependencies (necessary Collection), the service lookup is
155executed when the iterator(), and toArray(...) methods are invoked.
156Timeout policies <br>
157are also executed if the lookup failed.</p>
158
159<p>To set a temporal dependency as a proxy, just add the <tt>proxy</tt> attribute as follows:</p>
160<div class="code"><div class="codeContent">
161<pre class="code-xml"><span class="code-tag">&lt;iPOJO <span class="code-keyword">xmlns:temporal</span>=<span class="code-quote">"org.apache.felix.ipojo.handler.temporal"</span>&gt;</span>
162&lt;component
163 className=<span class="code-quote">"org.apache.felix.ipojo.example.Temporal"</span>&gt;
164
165 <span class="code-tag"><span class="code-comment">&lt;!-- Temporal dependencies configuration --&gt;</span></span>
166 <span class="code-tag">&lt;temporal:requires proxy=<span class="code-quote">"true"</span> field=<span class="code-quote">"fs"</span>/&gt;</span>
167 <span class="code-tag">&lt;temporal:requires proxy=<span class="code-quote">"true"</span> field=<span class="code-quote">"mycollection"</span> specification=<span class="code-quote">"my.service.specification"</span>/&gt;</span>
Clement Escoffierbd7ff502008-06-06 12:12:01 +0000[diff] [blame]168
169
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame^]170 <span class="code-tag">&lt;provides/&gt;</span>
171
172<span class="code-tag">&lt;/component&gt;</span>
173<span class="code-tag">&lt;/iPOJO&gt;</span></pre>
174</div></div>
175
176<p>By default, proxies are disabled.</p>
177
178<h2><a name="TemporalServiceDependency-Download"></a>Download </h2>
179
180<p>The handler is available on the <a href="http://felix.apache.org/site/download.html" title="Download">download</a> page.<br>
181Sources are available on the Felix trunk at the following location: <span class="nobr"><a href="http://svn.apache.org/repos/asf/felix/trunk/ipojo/handler/temporal" title="Visit page outside Confluence" rel="nofollow">http://svn.apache.org/repos/asf/felix/trunk/ipojo/handler/temporal<sup><img class="rendericon" src="temporal-service-dependency_files/linkext7.gif" alt="" align="absmiddle" border="0" width="7" height="7"></sup></a></span></p></td>
182<td class="confluenceTd" valign="top" width="20%">
183<h6><a name="TemporalServiceDependency-Overview"></a><b>Overview</b></h6>
184<ul>
185 <li><a href="http://felix.apache.org/site/apache-felix-ipojo.html" title="Apache Felix iPOJO">Home Page</a></li>
186 <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>
187 <li><a href="http://felix.apache.org/site/download.html" title="Download">Download &amp; Install </a></li>
188</ul>
Clement Escoffierbd7ff502008-06-06 12:12:01 +0000[diff] [blame]189
190
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame^]191<h6><a name="TemporalServiceDependency-GettingStarted"></a><b>Getting Started</b></h6>
192<ul>
193 <li><a href="http://felix.apache.org/site/ipojo-in-10-minutes.html" title="iPOJO in 10 minutes">iPOJO in 10 minutes</a></li>
194 <li><a href="http://felix.apache.org/site/how-to-use-ipojo-annotations.html" title="How to use iPOJO Annotations">How to use iPOJO Annotations</a></li>
195 <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>
196 <li><a href="http://felix.apache.org/site/ipojo-advanced-tutorial.html" title="iPOJO Advanced Tutorial">iPOJO Advanced Tutorial</a></li>
197 <li><a href="http://felix.apache.org/site/ipojo-composition-tutorial.html" title="iPOJO Composition Tutorial">iPOJO Composition Tutorial</a></li>
198</ul>
Clement Escoffierbd7ff502008-06-06 12:12:01 +0000[diff] [blame]199
200
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame^]201<h6><a name="TemporalServiceDependency-UserGuide"></a><b>User Guide</b></h6>
202<ul>
203 <li><a href="http://felix.apache.org/site/describing-components.html" title="Describing components">Describing components (handler list) </a></li>
204 <li><a href="http://felix.apache.org/site/using-xml-schemas.html" title="Using XML Schemas">Using XML Schemas</a></li>
205 <li><a href="http://felix.apache.org/site/apache-felix-ipojo-testing-components.html" title="apache-felix-ipojo-testing-components">Testing components</a></li>
206 <li><a href="http://felix.apache.org/site/ipojo-advanced-topics.html" title="iPOJO Advanced Topics">Advanced Topics</a></li>
207 <li><a href="http://felix.apache.org/site/ipojo-faq.html" title="iPOJO FAQ">FAQ</a></li>
208</ul>
Clement Escoffierbd7ff502008-06-06 12:12:01 +0000[diff] [blame]209
210
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame^]211<h6><a name="TemporalServiceDependency-Tools"></a><b>Tools</b></h6>
212<ul>
213 <li><a href="http://felix.apache.org/site/ipojo-eclipse-plug-in.html" title="iPOJO Eclipse Plug-in">iPOJO Eclipse Plug-in</a></li>
214 <li><a href="http://felix.apache.org/site/ipojo-ant-task.html" title="iPOJO Ant Task">iPOJO Ant Task</a></li>
215 <li><a href="http://felix.apache.org/site/ipojo-maven-plug-in.html" title="iPOJO Maven Plug-in">iPOJO Maven Plug-in</a></li>
216 <li><a href="http://felix.apache.org/site/apache-felix-ipojo-junit4osgi.html" title="apache-felix-ipojo-junit4osgi">Junit4OSGi</a></li>
217 <li><a href="http://felix.apache.org/site/ipojo-concepts-overview.html" title="iPOJO Concepts Overview">iPOJO concepts overview</a></li>
218</ul>
Clement Escoffierbd7ff502008-06-06 12:12:01 +0000[diff] [blame]219
220
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame^]221<h6><a name="TemporalServiceDependency-DeveloperGuide"></a><b>Developer Guide</b></h6>
222<ul>
223 <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="temporal-service-dependency_files/linkext7.gif" alt="" align="absmiddle" border="0" width="7" height="7"></sup></a></span></li>
224 <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>
225 <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>
226 <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>
227</ul>
Clement Escoffierbd7ff502008-06-06 12:12:01 +0000[diff] [blame]228
229
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame^]230<h6><a name="TemporalServiceDependency-Misc&amp;Contact"></a><b>Misc &amp; Contact</b></h6>
231<ul>
232 <li><a href="http://felix.apache.org/site/apache-felix-ipojo-issuestracker.html" title="apache-felix-ipojo-issuestracker">Issues Tracker</a></li>
233 <li><a href="http://felix.apache.org/site/apache-felix-ipojo-supportedvms.html" title="apache-felix-ipojo-supportedVMs">Supported JVMs</a></li>
234 <li><a href="http://felix.apache.org/site/apache-felix-ipojo-supportedosgi.html" title="apache-felix-ipojo-supportedOSGi">Supported OSGi Implementations</a></li>
235 <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="temporal-service-dependency_files/linkext7.gif" alt="" align="absmiddle" border="0" width="7" height="7"></sup></a></span></li>
236 <li><a href="http://felix.apache.org/site/future-ideas.html" title="Future Ideas">Future Ideas</a></li>
237 <li><a href="http://felix.apache.org/site/contact.html" title="Contact">Contact</a></li>
238 <li><a href="http://felix.apache.org/site/related-works.html" title="Related Works">Related Works</a></li>
239 <li><a href="http://felix.apache.org/site/article-presentations.html" title="Article &amp; Presentations">Article &amp; Presentations</a></li>
240</ul>
Clement Escoffierbd7ff502008-06-06 12:12:01 +0000[diff] [blame]241
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame^]242
243<hr>
244<div class="" align="center">
245<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="temporal-service-dependency_files/feed-icon-32x32.png" align="absmiddle" border="0"><sup><img class="rendericon" src="temporal-service-dependency_files/linkext7.gif" alt="" align="absmiddle" border="0" width="7" height="7"></sup></a></span></p></div>
246
247<script type="text/javascript">
248var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www.");
249document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E"));
250</script><script src="temporal-service-dependency_files/ga.js" type="text/javascript"></script>
251<script type="text/javascript">
252var pageTracker = _gat._getTracker("UA-1518442-4");
253pageTracker._trackPageview();
254</script>
255</td></tr></tbody></table>
256 </div>
257 </body></html>