Gitiles
Code Review Sign In
gerrit.onosproject.org / onos-felix / 8350751a451c994c384b8972b67fcfd8c1c217bc / . / ipojo / handler / temporal / doc / temporal-service-dependency.html
blob: f4500c87ae3326e52a1c686b3ff7c0a2b714a7cc [file] [log] [blame]
Clement Escoffierbd7ff502008-06-06 12:12:01 +0000[diff] [blame]1
2<!DOCTYPE HTML PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3<HTML>
4
Clement Escoffier83507512008-10-13 07:33:03 +0000[diff] [blame^]5<!-- Mirrored Site: felix.apache.org. File: /site/temporal-service-dependency.html. Date: Mon, 13 Oct 2008 06:52:59 GMT -->
Clement Escoffierbd7ff502008-06-06 12:12:01 +0000[diff] [blame]6<HEAD>
7 <TITLE>Apache Felix - Temporal Service Dependency</TITLE>
Clement Escoffier83507512008-10-13 07:33:03 +0000[diff] [blame^]8 <LINK rel="stylesheet" href="media.data/site.css" type="text/css" media="all">
Clement Escoffierbd7ff502008-06-06 12:12:01 +0000[diff] [blame]9 <META http-equiv="Content-Type" content="text/html;charset=UTF-8">
10 </HEAD>
11 <BODY>
Clement Escoffier83507512008-10-13 07:33:03 +0000[diff] [blame^]12 <DIV class="title"><DIV class="logo"><A href="index.html"><IMG border="0" alt="Apache Felix" src="media.data/logo.png"></A></DIV><DIV class="header"><A href="http://www.apache.org/"><IMG border="0" alt="Apache" src="media.data/apache.png"></A></DIV></DIV>
Clement Escoffierbd7ff502008-06-06 12:12:01 +0000[diff] [blame]13 <DIV class="menu">
Clement Escoffier83507512008-10-13 07:33:03 +0000[diff] [blame^]14 <UL>
15 <LI><A href="news.html" title="news">news</A></LI>
16 <LI><A href="license.html" title="license">license</A></LI>
17 <LI><SPAN class="nobr"><A href="downloads.html" title="Visit page outside Confluence" rel="nofollow">downloads<SUP><IMG class="rendericon" src="../../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="documentation.html" title="documentation">documentation</A></LI>
19 <LI><A href="mailinglists.html" title="mailinglists">mailing lists</A></LI>
20 <LI><A href="contributing.html" title="Contributing">contributing</A></LI>
21 <LI><SPAN class="nobr"><A href="http://www.apache.org/" title="Visit page outside Confluence" rel="nofollow">asf<SUP><IMG class="rendericon" src="../../cwiki.apache.org/confluence/images/icons/linkext7.gif" height="7" width="7" align="absmiddle" alt="" border="0"></SUP></A></SPAN></LI>
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="../../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="../../cwiki.apache.org/confluence/images/icons/linkext7.gif" height="7" width="7" align="absmiddle" alt="" border="0"></SUP></A></SPAN>
Clement Escoffierbd7ff502008-06-06 12:12:01 +0000[diff] [blame]24<!-- ApacheCon Ad -->
25<IFRAME src="http://www.apache.org/ads/button.html" style="border-width:0; float: left" frameborder="0" scrolling="no" width="135" height="135"></IFRAME>
26<P style="height: 100px">
27<!-- ApacheCon Ad --></LI>
Clement Escoffier83507512008-10-13 07:33:03 +0000[diff] [blame^]28</UL>
29 </DIV>
Clement Escoffierbd7ff502008-06-06 12:12:01 +0000[diff] [blame]30 <DIV class="main">
31<TABLE class="sectionMacro" border="0" cellpadding="5" cellspacing="0" width="100%"><TBODY><TR>
32<TD class="confluenceTd" valign="top" width="80%">
33<H1><A name="TemporalServiceDependency-Thetemporaldependencyhandler"></A>The temporal dependency handler</H1>
Clement Escoffier83507512008-10-13 07:33:03 +0000[diff] [blame^]34
35<P>Regular service dependencies participate to the instance lifecycle. Moreover, the injected service object is either available or not available. A temporal dependency handler is a little different and provides a different resolution pattern. Indeed, the temporal dependency does not invalidate the instance. Moreover, if not available, the temporal dependency waits (and so blocks the current thread) for a provider. Of course, the maximum waiting time can be specified. If a timeout occurs, the handler throws a runtime exception.<BR>
36Using the handler</P>
37
Clement Escoffierbd7ff502008-06-06 12:12:01 +0000[diff] [blame]38<P>First of all, you need to configure the component type to use the handler such as:</P>
39<DIV class="code"><DIV class="codeContent">
40<PRE class="code-xml"><SPAN class="code-tag">&lt;iPOJO <SPAN class="code-keyword">xmlns:temporal</SPAN>=<SPAN class="code-quote">&quot;org.apache.felix.ipojo.handler.temporal&quot;</SPAN>&gt;</SPAN>
Clement Escoffier83507512008-10-13 07:33:03 +0000[diff] [blame^]41&lt;component
42 className=<SPAN class="code-quote">&quot;org.apache.felix.ipojo.example.Temporal&quot;</SPAN>&gt;
43
44 <SPAN class="code-tag"><SPAN class="code-comment">&lt;!-- Temporal dependency configuration --&gt;</SPAN></SPAN>
45 <SPAN class="code-tag">&lt;temporal:requires field=<SPAN class="code-quote">&quot;mytemporal&quot;</SPAN>/&gt;</SPAN>
46
47 <SPAN class="code-tag">&lt;provides/&gt;</SPAN>
48
49<SPAN class="code-tag">&lt;/component&gt;</SPAN>
Clement Escoffierbd7ff502008-06-06 12:12:01 +0000[diff] [blame]50<SPAN class="code-tag">&lt;/iPOJO&gt;</SPAN></PRE>
51</DIV></DIV>
52<P>Notice that, this handler is an external handler. So, it uses the &quot;org.apache.felix.ipojo.handler.temporal&quot; namespace.<BR>
Clement Escoffier83507512008-10-13 07:33:03 +0000[diff] [blame^]53Once described, you can implement your component. The specified field will be mapped to the temporal dependency. As for regular field injection, aggregation, targeted service specification (i.e. interface) is discovered automatically. Filter, comparator and binding policy are also supported. However, the optional attribute is not supported. In fact, this attribute is meaningless in the case of a temporal dependency.<BR>
54Using the field in your code will try to find a matching service provider. If a provider is available, the field receives the service object immediately. Else, the thread is stopped and waits for a provider. The default wait time is 3s (you can also specify this time). If no provider is available after this time, the thread throws a RuntimeException. If a provider becomes available during this time, the field receives immediately the value and the execution can continue.<BR>
55Configuration</P>
56
Clement Escoffierbd7ff502008-06-06 12:12:01 +0000[diff] [blame]57<P>The handler has only one mandatory attributes:</P>
58<UL>
59 <LI>Field: the implementation field supporting the dependency</LI>
60</UL>
61
62
63<P>The handler supports on specific optional attributes:</P>
64<UL>
Clement Escoffier83507512008-10-13 07:33:03 +0000[diff] [blame^]65 <LI>Timeout: the maximum time waited in order to find a provider (default: 3s). For an infinite timeout [New in the 0.9.0-SNAPSHOT version], the timeout value is either &quot;infinite&quot; or &quot;-1&quot;.</LI>
66 <LI>OnTimeout [New in the 0.9.0-SNAPSHOT version]: specifies the action to do when the timeout occurs. Four actions are supported: null, nullable, empty-array, default-implementation. By default, no action is specified, and an exception occurs when the timeout is reached.</LI>
Clement Escoffierbd7ff502008-06-06 12:12:01 +0000[diff] [blame]67</UL>
68
69
Clement Escoffier83507512008-10-13 07:33:03 +0000[diff] [blame^]70<P>The attributes from &quot;regular&quot; dependencies are also supported (like filter).<BR>
71OnTimeout actions</P>
72
73<P>When a timeout occurs, you can specify what the handler must do. By default, it throws a runtime exception. However, four others actions can be set in the 'onTimeout' attribute.</P>
74<UL>
75 <LI>The null action (onTimeout=&quot;null&quot;) will return &quot;null&quot; instead of the service object.</LI>
76 <LI>The &quot;nullable&quot; action (onTimeout=&quot;nullable&quot;) will return a &quot;Nullable&quot; object instead of the service object. This object is a fake but can be used a regular service object. However, invoking actions on this object will do nothing. In the case of aggregate dependency, an array containing a &quot;nullable&quot; object is returned.</LI>
77 <LI>The empty-array action is only supported for aggregate dependency (the field must be an array). In this case, an empty-array is returned.</LI>
78 <LI>The default-implementation action is a little different. Instead of specifying the action, you need to specify the default-implementation (the qualified class name) that you want to use. For example onTimeout=&quot;o.a.f.i.MyDefaultLogServiceImpl&quot;. In this case, the handler will inject an instance of this object instead of a real service object. On aggregate dependency, an array with one default-implementation object is returned.</LI>
79</UL>
80
81
Clement Escoffierbd7ff502008-06-06 12:12:01 +0000[diff] [blame]82<H2><A name="TemporalServiceDependency-Download"></A>Download</H2>
Clement Escoffier83507512008-10-13 07:33:03 +0000[diff] [blame^]83
84<P>The handler is available on the <A href="download.html" title="Download">download</A> page.<BR>
85Sources 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="../../cwiki.apache.org/confluence/images/icons/linkext7.gif" height="7" width="7" align="absmiddle" alt="" border="0"></SUP></A></SPAN></P></TD>
Clement Escoffierbd7ff502008-06-06 12:12:01 +0000[diff] [blame]86<TD class="confluenceTd" valign="top" width="20%">
87<H6><A name="TemporalServiceDependency-Overview"></A><B>Overview</B></H6>
88<UL>
Clement Escoffier83507512008-10-13 07:33:03 +0000[diff] [blame^]89 <LI><A href="apache-felix-ipojo.html" title="Apache Felix iPOJO">Home Page</A></LI>
90 <LI><A href="apache-felix-ipojo-feature-overview.html" title="Apache Felix iPOJO Feature Overview">iPOJO Feature Overview</A></LI>
91 <LI><A href="download.html" title="Download">Download &amp; Install </A></LI>
Clement Escoffierbd7ff502008-06-06 12:12:01 +0000[diff] [blame]92</UL>
93
94
95<H6><A name="TemporalServiceDependency-GettingStarted"></A><B>Getting Started</B></H6>
96<UL>
Clement Escoffier83507512008-10-13 07:33:03 +0000[diff] [blame^]97 <LI><A href="ipojo-in-10-minutes.html" title="iPOJO in 10 minutes">iPOJO in 10 minutes</A></LI>
98 <LI><A href="ipojo-hello-word-maven-based-tutorial.html" title="iPOJO Hello Word (Maven-Based) tutorial">iPOJO Hello Word &#40;Maven&#45;Based&#41; tutorial</A></LI>
99 <LI><A href="ipojo-advanced-tutorial.html" title="iPOJO Advanced Tutorial">iPOJO Advanced Tutorial</A></LI>
Clement Escoffierbd7ff502008-06-06 12:12:01 +0000[diff] [blame]100</UL>
101
102
103<H6><A name="TemporalServiceDependency-UserGuide"></A><B>User Guide</B></H6>
104<UL>
Clement Escoffier83507512008-10-13 07:33:03 +0000[diff] [blame^]105 <LI><A href="describing-components.html" title="Describing components">Describing components (handler list) </A></LI>
106 <LI><A href="how-to-use-ipojo-annotations.html" title="How to use iPOJO Annotations">How to use iPOJO Annotations</A></LI>
107 <LI><A href="using-xml-schemas.html" title="Using XML Schemas">Using XML Schemas</A></LI>
108 <LI><A href="ipojo-advanced-topics.html" title="iPOJO Advanced Topics">Advanced Topics</A></LI>
109 <LI><A href="ipojo-faq.html" title="iPOJO FAQ">FAQ</A></LI>
Clement Escoffierbd7ff502008-06-06 12:12:01 +0000[diff] [blame]110</UL>
111
112
113<H6><A name="TemporalServiceDependency-Tools"></A><B>Tools</B></H6>
114<UL>
Clement Escoffier83507512008-10-13 07:33:03 +0000[diff] [blame^]115 <LI><A href="ipojo-eclipse-plug-in.html" title="iPOJO Eclipse Plug-in">iPOJO Eclipse Plug&#45;in</A></LI>
116 <LI><A href="ipojo-ant-task.html" title="iPOJO Ant Task">iPOJO Ant Task</A></LI>
117 <LI><A href="ipojo-maven-plug-in.html" title="iPOJO Maven Plug-in">iPOJO Maven Plug&#45;in</A></LI>
118 <LI><A href="ipojo-concepts-overview.html" title="iPOJO Concepts Overview">iPOJO concepts overview</A></LI>
Clement Escoffierbd7ff502008-06-06 12:12:01 +0000[diff] [blame]119</UL>
120
121
122<H6><A name="TemporalServiceDependency-DeveloperGuide"></A><B>Developer Guide</B></H6>
123<UL>
Clement Escoffier83507512008-10-13 07:33:03 +0000[diff] [blame^]124 <LI>API: <SPAN class="nobr"><A href="http://people.apache.org/~clement/ipojo/api/0.8/" title="Visit page outside Confluence" rel="nofollow">0.8<SUP><IMG class="rendericon" src="../../cwiki.apache.org/confluence/images/icons/linkext7.gif" height="7" width="7" align="absmiddle" alt="" border="0"></SUP></A></SPAN></LI>
125 <LI><A href="how-to-write-your-own-handler.html" title="How to write your own handler">How to write your own handler</A></LI>
126 <LI><A href="how-to-use-ipojo-manipulation-metadata.html" title="How to use iPOJO Manipulation Metadata">How to use iPOJO Manipulation Metadata</A></LI>
Clement Escoffierbd7ff502008-06-06 12:12:01 +0000[diff] [blame]127</UL>
128
129
130<H6><A name="TemporalServiceDependency-Misc%26Contact"></A><B>Misc &amp; Contact</B></H6>
131<UL>
Clement Escoffier83507512008-10-13 07:33:03 +0000[diff] [blame^]132 <LI><A href="apache-felix-ipojo-issuestracker.html" title="apache-felix-ipojo-issuestracker">Issues Tracker</A></LI>
133 <LI><A href="apache-felix-ipojo-supportedvms.html" title="apache-felix-ipojo-supportedVMs">Supported JVMs</A></LI>
134 <LI><A href="apache-felix-ipojo-supportedosgi.html" title="apache-felix-ipojo-supportedOSGi">Supported OSGi Implementations</A></LI>
135 <LI><A href="future-ideas.html" title="Future Ideas">Future Ideas</A></LI>
136 <LI><A href="contact.html" title="Contact">Contact</A></LI>
137 <LI><A href="related-works.html" title="Related Works">Related Works</A></LI>
138 <LI><A href="article-presentations.html" title="Article & Presentations">Article &amp; Presentations</A></LI>
Clement Escoffierbd7ff502008-06-06 12:12:01 +0000[diff] [blame]139</UL>
140
141
142<HR>
143<DIV class="" align="center">
Clement Escoffier83507512008-10-13 07:33:03 +0000[diff] [blame^]144<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="../../cwiki.apache.org/confluence/images/icons/feed-icon-32x32.png" align="absmiddle" border="0"><SUP><IMG class="rendericon" src="../../cwiki.apache.org/confluence/images/icons/linkext7.gif" height="7" width="7" align="absmiddle" alt="" border="0"></SUP></A></SPAN></P></DIV></TD></TR></TBODY></TABLE>
Clement Escoffierbd7ff502008-06-06 12:12:01 +0000[diff] [blame]145 </DIV>
146 </BODY>
147
Clement Escoffier83507512008-10-13 07:33:03 +0000[diff] [blame^]148<!-- Mirrored Site: felix.apache.org. File: /site/temporal-service-dependency.html. Date: Mon, 13 Oct 2008 06:52:59 GMT -->
Clement Escoffierbd7ff502008-06-06 12:12:01 +0000[diff] [blame]149</HTML>