Gitiles
Code Review Sign In
gerrit.onosproject.org / onos-felix / c5dfcd88856aca736ae0e4ce39c6badf6c31776d / . / ipojo / arch / doc / ipojo-arch-command.html
blob: a2e6a021a6ad90c5d21039e951903bd3442f071b [file] [log] [blame]
<!DOCTYPE HTML PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html><head>
<title>Apache Felix - iPOJO-Arch-Command</title>
<link rel="stylesheet" href="ipojo-arch-command_files/site.css" type="text/css" media="all">
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
</head><body>
<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>
<div class="menu">
<ul>
<li><a href="http://felix.apache.org/site/news.html" title="news">news</a></li>
<li><a href="http://felix.apache.org/site/license.html" title="license">license</a></li>
<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>
<li><a href="http://felix.apache.org/site/documentation.html" title="documentation">documentation</a></li>
<li><a href="http://felix.apache.org/site/mailinglists.html" title="mailinglists">mailing lists</a></li>
<li><a href="http://felix.apache.org/site/contributing.html" title="Contributing">contributing</a></li>
<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>
<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>
<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>
<!-- ApacheCon Ad -->
<iframe src="ipojo-arch-command_files/button.html" style="border-width: 0pt; float: left;" scrolling="no" width="135" frameborder="0" height="135"></iframe>
<p style="height: 100px;">
<!-- ApacheCon Ad -->
</p></li></ul> </div>
<div class="main">
<table class="sectionMacro" border="0" cellpadding="5" cellspacing="0" width="100%"><tbody><tr>
<td class="confluenceTd" valign="top" width="80%">
<h1><a name="iPOJO-Arch-Command-iPOJO{{Arch}}command"></a>iPOJO <tt>Arch</tt> command</h1>
<p>Architecture introspection is required when the system doesn't work
as expected. In this case, having a quick access to instances states
and interconnection is a stringent requirement. The <tt>arch</tt> command allows getting these data from the Felix Shell and from the Equinox shell.</p>
<h2><a name="iPOJO-Arch-Command-Download"></a>Download</h2>
<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>
The 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>
<h2><a name="iPOJO-Arch-Command-Usage"></a>Usage</h2>
<p>Once you get the bundle, just install and start it in the OSGi Framework shell:</p>
<div class="code"><div class="codeHeader"><b>Felix</b></div><div class="codeContent">
<pre class="code-none">start file:/BUNDLE_URL.jar</pre>
</div></div>
<div class="code"><div class="codeHeader"><b>Equinox</b></div><div class="codeContent">
<pre class="code-none">install file:/BUNDLE_URL.jar
Bundle X installed
start X</pre>
</div></div>
<p>Then, you can use it to introspect the system by launching the <tt>arch</tt> command.</p>
<div class="code"><div class="codeContent">
<pre class="code-java">arch =&gt; displays instances name &amp; state (equivalent to arch \-instances)
arch -instance $instance_name =&gt; displays complete information about the instance $instance_name
arch -factories =&gt; display the list of available factories
arch -factory $factory_name =&gt; display complete information about the factory $factory_name
arch -handlers =&gt; list available handlers</pre>
</div></div>
<h2><a name="iPOJO-Arch-Command-Readinginstancearchitecture"></a>Reading instance architecture </h2>
<p>When you launch the <tt>arch</tt> command, the list of created instances (enabling architecture introspection) is displayed.</p>
<div class="code"><div class="codeContent">
<pre class="code-java">-&gt; arch
Instance ArchCommand -&gt; valid
Instance spell.english.EnglishDictionary-0 -&gt; valid
Instance spell.checker.SpellCheck-0 -&gt; valid
Instance spell.gui.SpellCheckerGui-0 -&gt; valid</pre>
</div></div>
<p>To get more information on an instance, launch <tt>arch -instance the_instance_name</tt></p>
<div class="code"><div class="codeContent">
<pre class="code-java">-&gt; arch -instance spell.checker.SpellCheck-0
instance 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>
handler state=<span class="code-quote">"valid"</span> name=<span class="code-quote">"org.apache.felix.ipojo.handlers.dependency.DependencyHandler"</span>
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>
handler state=<span class="code-quote">"valid"</span> name=<span class="code-quote">"org.apache.felix.ipojo.handlers.providedservice.ProvidedServiceHandler"</span>
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>
property value=<span class="code-quote">"spell.checker.SpellCheck"</span> name=<span class="code-quote">"factory.name"</span>
property value=<span class="code-quote">"spell.checker.SpellCheck-0"</span> name=<span class="code-quote">"instance.name"</span>
handler state=<span class="code-quote">"valid"</span> name=<span class="code-quote">"org.apache.felix.ipojo.handlers.architecture.ArchitectureHandler"</span>
-&gt;</pre>
</div></div>
<p>Instance architecture is organized as follows:<br>
On 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>
Then, the information is organized handler by handler (a piece of
container). For each handler plugged on the instance can participate to
the instance architecture. For each handler its name (such as {{
org.apache.felix.ipojo.handlers.dependency.DependencyHandler}} for
iPOJO service dependencies, {{
org.apache.felix.ipojo.handlers.providedservice.ProvidedServiceHandler}}
for 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>
The <tt>org.apache.felix.ipojo.handlers.dependency.DependencyHandler</tt>
provides data on service dependencies and more precisely on the state
of service dependencies. In the previous example, the dependency on {{
spell.services.DictionaryService}} was resolved. On the following
example, the same dependency is no more resolved:</p>
<div class="code"><div class="codeContent">
<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>
handler state=<span class="code-quote">"invalid"</span> name=<span class="code-quote">"org.apache.felix.ipojo.handlers.dependency.DependencyHandler"</span>
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>
handler state=<span class="code-quote">"valid"</span> name=<span class="code-quote">"org.apache.felix.ipojo.handlers.providedservice.ProvidedServiceHandler"</span>
provides state=<span class="code-quote">"unregistered"</span> specifications=<span class="code-quote">"[spell.services.SpellChecker]"</span>
property value=<span class="code-quote">"spell.checker.SpellCheck"</span> name=<span class="code-quote">"factory.name"</span>
property value=<span class="code-quote">"spell.checker.SpellCheck-0"</span> name=<span class="code-quote">"instance.name"</span>
handler state=<span class="code-quote">"valid"</span> name=<span class="code-quote">"org.apache.felix.ipojo.handlers.architecture.ArchitectureHandler"</span></pre>
</div></div>
<p>Notes that, the instance also becomes invalid and that the provided service is unregistered.<br>
If the provider comes back, the dependency becomes <tt>resolved</tt> and the instance becomes <tt>valid</tt><br>
If an instance begins to use a service, the bound providers are described in the instance architecture:</p>
<div class="code"><div class="codeContent">
<pre class="code-java">-&gt; arch -instance spell.checker.SpellCheck-0
instance 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>
object name=<span class="code-quote">"spell.checker.SpellCheck@e222eb"</span>
handler state=<span class="code-quote">"valid"</span> name=<span class="code-quote">"org.apache.felix.ipojo.handlers.dependency.DependencyHandler"</span>
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>
uses service.id=<span class="code-quote">"41"</span> instance.name=<span class="code-quote">"spell.english.EnglishDictionary-0"</span>
handler state=<span class="code-quote">"valid"</span> name=<span class="code-quote">"org.apache.felix.ipojo.handlers.providedservice.ProvidedServiceHandler"</span>
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>
property value=<span class="code-quote">"spell.checker.SpellCheck"</span> name=<span class="code-quote">"factory.name"</span>
property value=<span class="code-quote">"spell.checker.SpellCheck-0"</span> name=<span class="code-quote">"instance.name"</span>
handler state=<span class="code-quote">"valid"</span> name=<span class="code-quote">"org.apache.felix.ipojo.handlers.architecture.ArchitectureHandler"</span></pre>
</div></div>
<p>In the previous case, the dependency on {{
spell.services.DictionaryService}} use the service 41 from the iPOJO
instance named {{ spell.english.EnglishDictionary-0}}<br>
You can also check created POJO objects (implementation class objet). Here, only one object was created (<tt>spell.checker.SpellCheck@e222eb</tt>).</p>
<h2><a name="iPOJO-Arch-Command-Listavailablefactories"></a>List available factories</h2>
<p>To list available factories (i.e. component types), launch the <tt>arch -factories</tt> command:</p>
<div class="code"><div class="codeContent">
<pre class="code-java">-&gt; arch -factories
Factory spell.checker.SpellCheck (VALID)
Factory spell.gui.SpellCheckerGui (VALID)
Factory spell.english.EnglishDictionary (VALID)</pre>
</div></div>
<p>For each available (public) factories,the name and the sate are
displayed. A factory is valid if and only if all required handlers are
available. To get more information on a factory launch the <tt>arch -factory factory_name</tt> command:</p>
<div class="code"><div class="codeContent">
<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>
provides specification=<span class="code-quote">"spell.services.DictionaryService"</span>
missinghandlers list=<span class="code-quote">"[]"</span>
requiredhandlers list=<span class="code-quote">"[org.apache.felix.ipojo:provides, org.apache.felix.ipojo:architecture]"</span></pre>
</div></div>
<p>On the first line, you get the implementation class of the type, the
state of the factory, the bundle declaring the type and the name of the
type. Then you get the list of required and missing handlers.</p>
<h2><a name="iPOJO-Arch-Command-Listavailablehandlers"></a>List available handlers</h2>
<p>You can also list available handlers with the <tt>arch -handlers</tt> command.</p>
<div class="code"><div class="codeContent">
<pre class="code-java">-&gt; arch -handlers
Handler org.apache.felix.ipojo:controller (VALID)
Handler org.apache.felix.ipojo:callback (VALID)
Handler org.apache.felix.ipojo:requires (VALID)
Handler org.apache.felix.ipojo:provides (VALID)
Handler org.apache.felix.ipojo:properties (VALID)
Handler org.apache.felix.ipojo:architecture (VALID)
Handler org.apache.felix.ipojo.white-board-pattern:wbp (VALID)</pre>
</div></div>
<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>
</td>
<td class="confluenceTd" valign="top" width="20%">
<h6><a name="iPOJO-Arch-Command-Overview"></a><b>Overview</b></h6>
<ul>
<li><a href="http://felix.apache.org/site/apache-felix-ipojo.html" title="Apache Felix iPOJO">Home Page</a></li>
<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>
<li><a href="http://felix.apache.org/site/download.html" title="Download">Download &amp; Install </a></li>
</ul>
<h6><a name="iPOJO-Arch-Command-GettingStarted"></a><b>Getting Started</b></h6>
<ul>
<li><a href="http://felix.apache.org/site/ipojo-in-10-minutes.html" title="iPOJO in 10 minutes">iPOJO in 10 minutes</a></li>
<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>
<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>
<li><a href="http://felix.apache.org/site/ipojo-advanced-tutorial.html" title="iPOJO Advanced Tutorial">iPOJO Advanced Tutorial</a></li>
<li><a href="http://felix.apache.org/site/ipojo-composition-tutorial.html" title="iPOJO Composition Tutorial">iPOJO Composition Tutorial</a></li>
</ul>
<h6><a name="iPOJO-Arch-Command-UserGuide"></a><b>User Guide</b></h6>
<ul>
<li><a href="http://felix.apache.org/site/describing-components.html" title="Describing components">Describing components (handler list) </a></li>
<li><a href="http://felix.apache.org/site/using-xml-schemas.html" title="Using XML Schemas">Using XML Schemas</a></li>
<li><a href="http://felix.apache.org/site/apache-felix-ipojo-testing-components.html" title="apache-felix-ipojo-testing-components">Testing components</a></li>
<li><a href="http://felix.apache.org/site/ipojo-advanced-topics.html" title="iPOJO Advanced Topics">Advanced Topics</a></li>
<li><a href="http://felix.apache.org/site/ipojo-faq.html" title="iPOJO FAQ">FAQ</a></li>
<li><a href="http://felix.apache.org/site/ipojo-reference-card.html" title="iPOJO-Reference-Card">iPOJO Reference Card</a></li>
</ul>
<h6><a name="iPOJO-Arch-Command-Tools"></a><b>Tools</b></h6>
<ul>
<li><a href="http://felix.apache.org/site/ipojo-eclipse-plug-in.html" title="iPOJO Eclipse Plug-in">iPOJO Eclipse Plug-in</a></li>
<li><a href="http://felix.apache.org/site/ipojo-ant-task.html" title="iPOJO Ant Task">iPOJO Ant Task</a></li>
<li><a href="http://felix.apache.org/site/ipojo-maven-plug-in.html" title="iPOJO Maven Plug-in">iPOJO Maven Plug-in</a></li>
<li><a href="" title="iPOJO-Arch-Command">iPOJO Arch Command</a></li>
<li><a href="http://felix.apache.org/site/apache-felix-ipojo-junit4osgi.html" title="apache-felix-ipojo-junit4osgi">Junit4OSGi</a></li>
<li><a href="http://felix.apache.org/site/ipojo-concepts-overview.html" title="iPOJO Concepts Overview">iPOJO concepts overview</a></li>
</ul>
<h6><a name="iPOJO-Arch-Command-DeveloperGuide"></a><b>Developer Guide</b></h6>
<ul>
<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>
<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>
<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>
<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>
</ul>
<h6><a name="iPOJO-Arch-Command-Misc&amp;Contact"></a><b>Misc &amp; Contact</b></h6>
<ul>
<li><a href="http://felix.apache.org/site/apache-felix-ipojo-issuestracker.html" title="apache-felix-ipojo-issuestracker">Issues Tracker</a></li>
<li><a href="http://felix.apache.org/site/apache-felix-ipojo-supportedvms.html" title="apache-felix-ipojo-supportedVMs">Supported JVMs</a></li>
<li><a href="http://felix.apache.org/site/apache-felix-ipojo-supportedosgi.html" title="apache-felix-ipojo-supportedOSGi">Supported OSGi Implementations</a></li>
<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>
<li><a href="http://felix.apache.org/site/future-ideas.html" title="Future Ideas">Future Ideas</a></li>
<li><a href="http://felix.apache.org/site/contact.html" title="Contact">Contact</a></li>
<li><a href="http://felix.apache.org/site/related-works.html" title="Related Works">Related Works</a></li>
<li><a href="http://felix.apache.org/site/article-presentations.html" title="Article &amp; Presentations">Article &amp; Presentations</a></li>
</ul>
<hr>
<div class="" align="center">
<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>
<script type="text/javascript">
var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www.");
document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E"));
</script><script src="ipojo-arch-command_files/ga.js" type="text/javascript"></script>
<script type="text/javascript">
var pageTracker = _gat._getTracker("UA-1518442-4");
pageTracker._trackPageview();
</script>
</td></tr></tbody></table>
</div>
</body></html>