Gitiles
Code Review Sign In
gerrit.onosproject.org / onos-felix / 65b51e9292ef69c7827fa60b28ae4f6178f7e7c4 / . / ipojo / arch / doc / ipojo-arch-command.html
blob: a2e6a021a6ad90c5d21039e951903bd3442f071b [file] [log] [blame]
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000[diff] [blame]1<!DOCTYPE HTML PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
2<html><head>
3
4
5
6 <title>Apache Felix - iPOJO-Arch-Command</title>
7 <link rel="stylesheet" href="ipojo-arch-command_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="ipojo-arch-command_files/logo.png" border="0"></a></div><div class="header"><a href="http://www.apache.org/"><img alt="Apache" src="ipojo-arch-command_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="ipojo-arch-command_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="ipojo-arch-command_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="ipojo-arch-command_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="ipojo-arch-command_files/linkext7.gif" alt="" align="absmiddle" border="0" width="7" height="7"></sup></a></span>
22<!-- ApacheCon Ad -->
23<iframe src="ipojo-arch-command_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="iPOJO-Arch-Command-iPOJO{{Arch}}command"></a>iPOJO <tt>Arch</tt> command</h1>
31<p>Architecture introspection is required when the system doesn't work
32as expected. In this case, having a quick access to instances states
33and interconnection is a stringent requirement. The <tt>arch</tt> command allows getting these data from the Felix Shell and from the Equinox shell.</p>
34
35<h2><a name="iPOJO-Arch-Command-Download"></a>Download</h2>
36<p>The Felix command is available from the <a href="http://felix.apache.org/site/download.html" title="Download">download</a> page and in the <tt>arch</tt> folder of the iPOJO trunk <span class="nobr"><a href="http://svn.apache.org/viewvc/felix/trunk/ipojo/arch" title="Visit page outside Confluence" rel="nofollow">http://svn.apache.org/repos/asf/felix/trunk/ipojo/arch/<sup><img class="rendericon" src="ipojo-arch-command_files/linkext7.gif" alt="" align="absmiddle" border="0" width="7" height="7"></sup></a></span>.<br>
37The Equinox command sources are available <span class="nobr"><a href="http://svn.apache.org/viewvc/felix/sandbox/clement/ipojo-utils/arch-equinox/" title="Visit page outside Confluence" rel="nofollow">http://svn.apache.org/repos/asf/felix/sandbox/clement/ipojo-utils/arch-equinox/<sup><img class="rendericon" src="ipojo-arch-command_files/linkext7.gif" alt="" align="absmiddle" border="0" width="7" height="7"></sup></a></span>. To compile sources, just launch the <tt>mvn clean install</tt>.</p>
38
39<h2><a name="iPOJO-Arch-Command-Usage"></a>Usage</h2>
40<p>Once you get the bundle, just install and start it in the OSGi Framework shell:</p>
41<div class="code"><div class="codeHeader"><b>Felix</b></div><div class="codeContent">
42<pre class="code-none">start file:/BUNDLE_URL.jar</pre>
43</div></div>
44<div class="code"><div class="codeHeader"><b>Equinox</b></div><div class="codeContent">
45<pre class="code-none">install file:/BUNDLE_URL.jar
46Bundle X installed
47start X</pre>
48</div></div>
49<p>Then, you can use it to introspect the system by launching the <tt>arch</tt> command.</p>
50<div class="code"><div class="codeContent">
51<pre class="code-java">arch =&gt; displays instances name &amp; state (equivalent to arch \-instances)
52arch -instance $instance_name =&gt; displays complete information about the instance $instance_name
53arch -factories =&gt; display the list of available factories
54arch -factory $factory_name =&gt; display complete information about the factory $factory_name
55arch -handlers =&gt; list available handlers</pre>
56</div></div>
57<h2><a name="iPOJO-Arch-Command-Readinginstancearchitecture"></a>Reading instance architecture </h2>
58<p>When you launch the <tt>arch</tt> command, the list of created instances (enabling architecture introspection) is displayed.</p>
59<div class="code"><div class="codeContent">
60<pre class="code-java">-&gt; arch
61Instance ArchCommand -&gt; valid
62Instance spell.english.EnglishDictionary-0 -&gt; valid
63Instance spell.checker.SpellCheck-0 -&gt; valid
64Instance spell.gui.SpellCheckerGui-0 -&gt; valid</pre>
65</div></div>
66<p>To get more information on an instance, launch <tt>arch -instance the_instance_name</tt></p>
67<div class="code"><div class="codeContent">
68<pre class="code-java">-&gt; arch -instance spell.checker.SpellCheck-0
69instance component.type=<span class="code-quote">"spell.checker.SpellCheck"</span> state=<span class="code-quote">"valid"</span> bundle=<span class="code-quote">"8"</span> name=<span class="code-quote">"spell.checker.SpellCheck-0"</span>
70 handler state=<span class="code-quote">"valid"</span> name=<span class="code-quote">"org.apache.felix.ipojo.handlers.dependency.DependencyHandler"</span>
71 requires optional=<span class="code-quote">"<span class="code-keyword">false</span>"</span> aggregate=<span class="code-quote">"<span class="code-keyword">false</span>"</span> state=<span class="code-quote">"resolved"</span> binding-policy=<span class="code-quote">"dynamic"</span> specification=<span class="code-quote">"spell.services.DictionaryService"</span>
72 handler state=<span class="code-quote">"valid"</span> name=<span class="code-quote">"org.apache.felix.ipojo.handlers.providedservice.ProvidedServiceHandler"</span>
73 provides service.id=<span class="code-quote">"36"</span> state=<span class="code-quote">"registered"</span> specifications=<span class="code-quote">"[spell.services.SpellChecker]"</span>
74 property value=<span class="code-quote">"spell.checker.SpellCheck"</span> name=<span class="code-quote">"factory.name"</span>
75 property value=<span class="code-quote">"spell.checker.SpellCheck-0"</span> name=<span class="code-quote">"instance.name"</span>
76 handler state=<span class="code-quote">"valid"</span> name=<span class="code-quote">"org.apache.felix.ipojo.handlers.architecture.ArchitectureHandler"</span>
77-&gt;</pre>
78</div></div>
79<p>Instance architecture is organized as follows:<br>
80On the first line, are displayed the component type (i.e. factory), the instance state (<tt>valid</tt> or <tt>invalid</tt>), the bundle from which the instance is created, and the instance name.<br>
81Then, the information is organized handler by handler (a piece of
82container). For each handler plugged on the instance can participate to
83the instance architecture. For each handler its name (such as {{
84org.apache.felix.ipojo.handlers.dependency.DependencyHandler}} for
85iPOJO service dependencies, {{
86org.apache.felix.ipojo.handlers.providedservice.ProvidedServiceHandler}}
87for iPOJO service providing...) and the state (either <tt>valid</tt> or <tt>invalid</tt> are displayed. Remember that an instance is valid only and only if all plugged handlers are valid. <br>
88The <tt>org.apache.felix.ipojo.handlers.dependency.DependencyHandler</tt>
89provides data on service dependencies and more precisely on the state
90of service dependencies. In the previous example, the dependency on {{
91spell.services.DictionaryService}} was resolved. On the following
92example, the same dependency is no more resolved:</p>
93<div class="code"><div class="codeContent">
94<pre class="code-java">instance component.type=<span class="code-quote">"spell.checker.SpellCheck"</span> state=<span class="code-quote">"invalid"</span> bundle=<span class="code-quote">"8"</span> name=<span class="code-quote">"spell.checker.SpellCheck-0"</span>
95 handler state=<span class="code-quote">"invalid"</span> name=<span class="code-quote">"org.apache.felix.ipojo.handlers.dependency.DependencyHandler"</span>
96 requires optional=<span class="code-quote">"<span class="code-keyword">false</span>"</span> aggregate=<span class="code-quote">"<span class="code-keyword">false</span>"</span> state=<span class="code-quote">"unresolved"</span> binding-policy=<span class="code-quote">"dynamic"</span> specification=<span class="code-quote">"spell.services.DictionaryService"</span>
97 handler state=<span class="code-quote">"valid"</span> name=<span class="code-quote">"org.apache.felix.ipojo.handlers.providedservice.ProvidedServiceHandler"</span>
98 provides state=<span class="code-quote">"unregistered"</span> specifications=<span class="code-quote">"[spell.services.SpellChecker]"</span>
99 property value=<span class="code-quote">"spell.checker.SpellCheck"</span> name=<span class="code-quote">"factory.name"</span>
100 property value=<span class="code-quote">"spell.checker.SpellCheck-0"</span> name=<span class="code-quote">"instance.name"</span>
101 handler state=<span class="code-quote">"valid"</span> name=<span class="code-quote">"org.apache.felix.ipojo.handlers.architecture.ArchitectureHandler"</span></pre>
102</div></div>
103<p>Notes that, the instance also becomes invalid and that the provided service is unregistered.<br>
104If the provider comes back, the dependency becomes <tt>resolved</tt> and the instance becomes <tt>valid</tt><br>
105If an instance begins to use a service, the bound providers are described in the instance architecture:</p>
106<div class="code"><div class="codeContent">
107<pre class="code-java">-&gt; arch -instance spell.checker.SpellCheck-0
108instance component.type=<span class="code-quote">"spell.checker.SpellCheck"</span> state=<span class="code-quote">"valid"</span> bundle=<span class="code-quote">"8"</span> name=<span class="code-quote">"spell.checker.SpellCheck-0"</span>
109 object name=<span class="code-quote">"spell.checker.SpellCheck@e222eb"</span>
110 handler state=<span class="code-quote">"valid"</span> name=<span class="code-quote">"org.apache.felix.ipojo.handlers.dependency.DependencyHandler"</span>
111 requires optional=<span class="code-quote">"<span class="code-keyword">false</span>"</span> aggregate=<span class="code-quote">"<span class="code-keyword">false</span>"</span> state=<span class="code-quote">"resolved"</span> binding-policy=<span class="code-quote">"dynamic"</span> specification=<span class="code-quote">"spell.services.DictionaryService"</span>
112 uses service.id=<span class="code-quote">"41"</span> instance.name=<span class="code-quote">"spell.english.EnglishDictionary-0"</span>
113 handler state=<span class="code-quote">"valid"</span> name=<span class="code-quote">"org.apache.felix.ipojo.handlers.providedservice.ProvidedServiceHandler"</span>
114 provides service.id=<span class="code-quote">"42"</span> state=<span class="code-quote">"registered"</span> specifications=<span class="code-quote">"[spell.services.SpellChecker]"</span>
115 property value=<span class="code-quote">"spell.checker.SpellCheck"</span> name=<span class="code-quote">"factory.name"</span>
116 property value=<span class="code-quote">"spell.checker.SpellCheck-0"</span> name=<span class="code-quote">"instance.name"</span>
117 handler state=<span class="code-quote">"valid"</span> name=<span class="code-quote">"org.apache.felix.ipojo.handlers.architecture.ArchitectureHandler"</span></pre>
118</div></div>
119<p>In the previous case, the dependency on {{
120spell.services.DictionaryService}} use the service 41 from the iPOJO
121instance named {{ spell.english.EnglishDictionary-0}}<br>
122You can also check created POJO objects (implementation class objet). Here, only one object was created (<tt>spell.checker.SpellCheck@e222eb</tt>).</p>
123<h2><a name="iPOJO-Arch-Command-Listavailablefactories"></a>List available factories</h2>
124<p>To list available factories (i.e. component types), launch the <tt>arch -factories</tt> command:</p>
125<div class="code"><div class="codeContent">
126<pre class="code-java">-&gt; arch -factories
127Factory spell.checker.SpellCheck (VALID)
128Factory spell.gui.SpellCheckerGui (VALID)
129Factory spell.english.EnglishDictionary (VALID)</pre>
130</div></div>
131<p>For each available (public) factories,the name and the sate are
132displayed. A factory is valid if and only if all required handlers are
133available. To get more information on a factory launch the <tt>arch -factory factory_name</tt> command:</p>
134<div class="code"><div class="codeContent">
135<pre class="code-java">factory implementation-class=<span class="code-quote">"spell.english.EnglishDictionary"</span> state=<span class="code-quote">"valid"</span> bundle=<span class="code-quote">"7"</span> name=<span class="code-quote">"spell.english.EnglishDictionary"</span>
136 provides specification=<span class="code-quote">"spell.services.DictionaryService"</span>
137 missinghandlers list=<span class="code-quote">"[]"</span>
138 requiredhandlers list=<span class="code-quote">"[org.apache.felix.ipojo:provides, org.apache.felix.ipojo:architecture]"</span></pre>
139</div></div>
140<p>On the first line, you get the implementation class of the type, the
141state of the factory, the bundle declaring the type and the name of the
142type. Then you get the list of required and missing handlers.</p>
143<h2><a name="iPOJO-Arch-Command-Listavailablehandlers"></a>List available handlers</h2>
144<p>You can also list available handlers with the <tt>arch -handlers</tt> command.</p>
145<div class="code"><div class="codeContent">
146<pre class="code-java">-&gt; arch -handlers
147Handler org.apache.felix.ipojo:controller (VALID)
148Handler org.apache.felix.ipojo:callback (VALID)
149Handler org.apache.felix.ipojo:requires (VALID)
150Handler org.apache.felix.ipojo:provides (VALID)
151Handler org.apache.felix.ipojo:properties (VALID)
152Handler org.apache.felix.ipojo:architecture (VALID)
153Handler org.apache.felix.ipojo.white-board-pattern:wbp (VALID)</pre>
154</div></div>
155<p>Handlers with the <tt>org.apache.felix.ipojo</tt> namespace (section before <tt>:</tt>) are core handlers (provided by the iPOJO bundle). Others are external handlers (provided by others bundles).</p>
156</td>
157<td class="confluenceTd" valign="top" width="20%">
158<h6><a name="iPOJO-Arch-Command-Overview"></a><b>Overview</b></h6>
159<ul>
160 <li><a href="http://felix.apache.org/site/apache-felix-ipojo.html" title="Apache Felix iPOJO">Home Page</a></li>
161 <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>
162 <li><a href="http://felix.apache.org/site/download.html" title="Download">Download &amp; Install </a></li>
163</ul>
164
165
166<h6><a name="iPOJO-Arch-Command-GettingStarted"></a><b>Getting Started</b></h6>
167<ul>
168 <li><a href="http://felix.apache.org/site/ipojo-in-10-minutes.html" title="iPOJO in 10 minutes">iPOJO in 10 minutes</a></li>
169 <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>
170 <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>
171 <li><a href="http://felix.apache.org/site/ipojo-advanced-tutorial.html" title="iPOJO Advanced Tutorial">iPOJO Advanced Tutorial</a></li>
172 <li><a href="http://felix.apache.org/site/ipojo-composition-tutorial.html" title="iPOJO Composition Tutorial">iPOJO Composition Tutorial</a></li>
173</ul>
174
175
176<h6><a name="iPOJO-Arch-Command-UserGuide"></a><b>User Guide</b></h6>
177<ul>
178 <li><a href="http://felix.apache.org/site/describing-components.html" title="Describing components">Describing components (handler list) </a></li>
179 <li><a href="http://felix.apache.org/site/using-xml-schemas.html" title="Using XML Schemas">Using XML Schemas</a></li>
180 <li><a href="http://felix.apache.org/site/apache-felix-ipojo-testing-components.html" title="apache-felix-ipojo-testing-components">Testing components</a></li>
181 <li><a href="http://felix.apache.org/site/ipojo-advanced-topics.html" title="iPOJO Advanced Topics">Advanced Topics</a></li>
182 <li><a href="http://felix.apache.org/site/ipojo-faq.html" title="iPOJO FAQ">FAQ</a></li>
183 <li><a href="http://felix.apache.org/site/ipojo-reference-card.html" title="iPOJO-Reference-Card">iPOJO Reference Card</a></li>
184</ul>
185
186
187<h6><a name="iPOJO-Arch-Command-Tools"></a><b>Tools</b></h6>
188<ul>
189 <li><a href="http://felix.apache.org/site/ipojo-eclipse-plug-in.html" title="iPOJO Eclipse Plug-in">iPOJO Eclipse Plug-in</a></li>
190 <li><a href="http://felix.apache.org/site/ipojo-ant-task.html" title="iPOJO Ant Task">iPOJO Ant Task</a></li>
191 <li><a href="http://felix.apache.org/site/ipojo-maven-plug-in.html" title="iPOJO Maven Plug-in">iPOJO Maven Plug-in</a></li>
192 <li><a href="" title="iPOJO-Arch-Command">iPOJO Arch Command</a></li>
193 <li><a href="http://felix.apache.org/site/apache-felix-ipojo-junit4osgi.html" title="apache-felix-ipojo-junit4osgi">Junit4OSGi</a></li>
194 <li><a href="http://felix.apache.org/site/ipojo-concepts-overview.html" title="iPOJO Concepts Overview">iPOJO concepts overview</a></li>
195</ul>
196
197
198<h6><a name="iPOJO-Arch-Command-DeveloperGuide"></a><b>Developer Guide</b></h6>
199<ul>
200 <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="ipojo-arch-command_files/linkext7.gif" alt="" align="absmiddle" border="0" width="7" height="7"></sup></a></span></li>
201 <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>
202 <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>
203 <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>
204</ul>
205
206
207<h6><a name="iPOJO-Arch-Command-Misc&amp;Contact"></a><b>Misc &amp; Contact</b></h6>
208<ul>
209 <li><a href="http://felix.apache.org/site/apache-felix-ipojo-issuestracker.html" title="apache-felix-ipojo-issuestracker">Issues Tracker</a></li>
210 <li><a href="http://felix.apache.org/site/apache-felix-ipojo-supportedvms.html" title="apache-felix-ipojo-supportedVMs">Supported JVMs</a></li>
211 <li><a href="http://felix.apache.org/site/apache-felix-ipojo-supportedosgi.html" title="apache-felix-ipojo-supportedOSGi">Supported OSGi Implementations</a></li>
212 <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="ipojo-arch-command_files/linkext7.gif" alt="" align="absmiddle" border="0" width="7" height="7"></sup></a></span></li>
213 <li><a href="http://felix.apache.org/site/future-ideas.html" title="Future Ideas">Future Ideas</a></li>
214 <li><a href="http://felix.apache.org/site/contact.html" title="Contact">Contact</a></li>
215 <li><a href="http://felix.apache.org/site/related-works.html" title="Related Works">Related Works</a></li>
216 <li><a href="http://felix.apache.org/site/article-presentations.html" title="Article &amp; Presentations">Article &amp; Presentations</a></li>
217</ul>
218
219
220<hr>
221<div class="" align="center">
222<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="ipojo-arch-command_files/feed-icon-32x32.png" align="absmiddle" border="0"><sup><img class="rendericon" src="ipojo-arch-command_files/linkext7.gif" alt="" align="absmiddle" border="0" width="7" height="7"></sup></a></span></p></div>
223
224<script type="text/javascript">
225var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www.");
226document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E"));
227</script><script src="ipojo-arch-command_files/ga.js" type="text/javascript"></script>
228<script type="text/javascript">
229var pageTracker = _gat._getTracker("UA-1518442-4");
230pageTracker._trackPageview();
231</script>
232</td></tr></tbody></table>
233
234 </div>
235 </body></html>