Update documentation
git-svn-id: https://svn.apache.org/repos/asf/felix/trunk@734735 13f79535-47bb-0310-9956-ffa450edef68
diff --git a/ipojo/arch/doc/ipojo-arch-command.html b/ipojo/arch/doc/ipojo-arch-command.html
new file mode 100644
index 0000000..a2e6a02
--- /dev/null
+++ b/ipojo/arch/doc/ipojo-arch-command.html
@@ -0,0 +1,235 @@
+<!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 => displays instances name & state (equivalent to arch \-instances)
+arch -instance $instance_name => displays complete information about the instance $instance_name
+arch -factories => display the list of available factories
+arch -factory $factory_name => display complete information about the factory $factory_name
+arch -handlers => 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">-> arch
+Instance ArchCommand -> valid
+Instance spell.english.EnglishDictionary-0 -> valid
+Instance spell.checker.SpellCheck-0 -> valid
+Instance spell.gui.SpellCheckerGui-0 -> 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">-> 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>
+-></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">-> 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">-> 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">-> 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 & 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&Contact"></a><b>Misc & 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 & Presentations">Article & Presentations</a></li>
+</ul>
+
+
+<hr>
+<div class="" align="center">
+<p><span class="nobr"><a href="http://cwiki.apache.org/confluence/createrssfeed.action?types=blogpost&statuses=created&statuses=modified&spaces=FELIX&labelString=iPOJO&rssType=atom&maxResults=10&timeSpan=5&publicFeed=true&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>
\ No newline at end of file