Page History

{include:apache-felix-ipojo-header}
{html}
<div class="content">
{html}
h1. iPOJO {{Arch}} command
_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 {{arch}} command allows getting these data from the Felix Shell, from the Equinox shell and Gogo._

{div:class=toc}
{toc:maxLevel=4|minLevel=2}
{div}

h2. Download
The Felix commands is available from the [download] page.
The Equinox command sources are available [http://svn.apache.org/repos/asf/felix/sandbox/clement/ipojo-utils/arch-equinox/|http://svn.apache.org/viewvc/felix/sandbox/clement/ipojo-utils/arch-equinox/]. To compile sources, just launch the {{mvn clean install}} and deploy the resulting bundle.

h2. Installation
Once you get the bundle, just install and start it in the OSGi Framework shell:
{code:xml|title=Felix}
start file:/BUNDLE_URL.jar
{code}
{code:xml|title=Equinox}
install file:/BUNDLE_URL.jar
Bundle X installed
start X
{code}
{code:xml|title=Gogo}
install file:/ARCH_GOGO_URL.jar
Bundle X installed
start X
{code}

h2. Equinox and Felix Shells

Then, you can use it to introspect the system by launching the {{arch}} command.
{code:shell}
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
{code}

h2. Gogo Shell Commands
The set of commands available from Gogo is a little bit different:
* {{ipojo:instances}} (or just {{instances}}) lists the instances and state
* {{ipojo:instance $instance_name}} (or just {{instance $instance_name}}) displays the complete information about the specified $instance_name
* {{ipojo:factories}} (or just {{factories}}) lists the available public factories
* {{ipojo:factory $factory_name}} (or just {{factory $factory_name}}) displays complete information about the factory $factory_name
* {{ipojo:handlers}} (or just {{handlers}} lists available handlers


h2. Reading instance architecture 
When you launch the {{arch}} command (or {{instances}} on Gogo), the list of created instances (enabling architecture introspection) is displayed.
{code:shell|title="Felix or Equinox"}
-> arch
Instance ArchCommand -> valid
Instance spell.english.EnglishDictionary-0 -> valid
Instance spell.checker.SpellCheck-0 -> valid
Instance spell.gui.SpellCheckerGui-0 -> valid
{code}
{code:shell|title="gogo"}
$ instances
Instance ArchCommand -> valid
Instance spell.english.EnglishDictionary-0 -> valid
Instance spell.checker.SpellCheck-0 -> valid
Instance spell.gui.SpellCheckerGui-0 -> valid
{code}
To get more information on an instance, launch {{arch -instance the_instance_name}} (or {{instance the_instance_name}} on Gogo)
{code:shell|title="Felix or Equinox"}
-> arch -instance spell.checker.SpellCheck-0                                    
instance component.type="spell.checker.SpellCheck" state="valid" bundle="8" name="spell.checker.SpellCheck-0"
	handler state="valid" name="org.apache.felix.ipojo.handlers.dependency.DependencyHandler"
		requires optional="false" aggregate="false" state="resolved" binding-policy="dynamic" specification="spell.services.DictionaryService"
	handler state="valid" name="org.apache.felix.ipojo.handlers.providedservice.ProvidedServiceHandler"
		provides service.id="36" state="registered" specifications="[spell.services.SpellChecker]"
			property value="spell.checker.SpellCheck" name="factory.name"
			property value="spell.checker.SpellCheck-0" name="instance.name"
	handler state="valid" name="org.apache.felix.ipojo.handlers.architecture.ArchitectureHandler"
{code}
{code:shell|title="Gogo"}
$ipojo:instance spell.checker.SpellCheck-0                                    
instance component.type="spell.checker.SpellCheck" state="valid" bundle="8" name="spell.checker.SpellCheck-0"
	handler state="valid" name="org.apache.felix.ipojo.handlers.dependency.DependencyHandler"
		requires optional="false" aggregate="false" state="resolved" binding-policy="dynamic" specification="spell.services.DictionaryService"
	handler state="valid" name="org.apache.felix.ipojo.handlers.providedservice.ProvidedServiceHandler"
		provides service.id="36" state="registered" specifications="[spell.services.SpellChecker]"
			property value="spell.checker.SpellCheck" name="factory.name"
			property value="spell.checker.SpellCheck-0" name="instance.name"
	handler state="valid" name="org.apache.felix.ipojo.handlers.architecture.ArchitectureHandler"
{code}

Instance architecture is organized as follows:
On the first line, are displayed the component type (i.e. factory), the instance state ({{valid}} or {{invalid}}), the bundle from which the instance is created, and the instance name.
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 {{valid}} or {{invalid}} are displayed. Remember that an instance is valid only and only if all plugged handlers are valid. 
The {{org.apache.felix.ipojo.handlers.dependency.DependencyHandler}} 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:
{code:shell}
instance component.type="spell.checker.SpellCheck" state="invalid" bundle="8" name="spell.checker.SpellCheck-0"
	handler state="invalid" name="org.apache.felix.ipojo.handlers.dependency.DependencyHandler"
		requires optional="false" aggregate="false" state="unresolved" binding-policy="dynamic" specification="spell.services.DictionaryService"
	handler state="valid" name="org.apache.felix.ipojo.handlers.providedservice.ProvidedServiceHandler"
		provides state="unregistered" specifications="[spell.services.SpellChecker]"
			property value="spell.checker.SpellCheck" name="factory.name"
			property value="spell.checker.SpellCheck-0" name="instance.name"
	handler state="valid" name="org.apache.felix.ipojo.handlers.architecture.ArchitectureHandler" 
{code}
Notes that, the instance also becomes invalid and that the provided service is unregistered.
If the provider comes back, the dependency becomes {{resolved}} and the instance becomes {{valid}}
If an instance begins to use a service, the bound providers are described in the instance architecture:
{code:shell|title="Felix or Equinox"}
-> arch -instance spell.checker.SpellCheck-0 
instance component.type="spell.checker.SpellCheck" state="valid" bundle="8" name="spell.checker.SpellCheck-0"
	object name="spell.checker.SpellCheck@e222eb"
	handler state="valid" name="org.apache.felix.ipojo.handlers.dependency.DependencyHandler"
		requires optional="false" aggregate="false" state="resolved" binding-policy="dynamic" specification="spell.services.DictionaryService"
			uses service.id="41" instance.name="spell.english.EnglishDictionary-0"
	handler state="valid" name="org.apache.felix.ipojo.handlers.providedservice.ProvidedServiceHandler"
		provides service.id="42" state="registered" specifications="[spell.services.SpellChecker]"
			property value="spell.checker.SpellCheck" name="factory.name"
			property value="spell.checker.SpellCheck-0" name="instance.name"
	handler state="valid" name="org.apache.felix.ipojo.handlers.architecture.ArchitectureHandler"
{code}

{code:shell|title="Gogo"}
$instance spell.checker.SpellCheck-0 
instance component.type="spell.checker.SpellCheck" state="valid" bundle="8" name="spell.checker.SpellCheck-0"
	object name="spell.checker.SpellCheck@e222eb"
	handler state="valid" name="org.apache.felix.ipojo.handlers.dependency.DependencyHandler"
		requires optional="false" aggregate="false" state="resolved" binding-policy="dynamic" specification="spell.services.DictionaryService"
			uses service.id="41" instance.name="spell.english.EnglishDictionary-0"
	handler state="valid" name="org.apache.felix.ipojo.handlers.providedservice.ProvidedServiceHandler"
		provides service.id="42" state="registered" specifications="[spell.services.SpellChecker]"
			property value="spell.checker.SpellCheck" name="factory.name"
			property value="spell.checker.SpellCheck-0" name="instance.name"
	handler state="valid" name="org.apache.felix.ipojo.handlers.architecture.ArchitectureHandler"
{code}
In the previous case, the dependency on {{ spell.services.DictionaryService}} use the service 41 from the iPOJO instance named {{ spell.english.EnglishDictionary-0}}
You can also check created POJO objects (implementation class objet). Here, only one object was created ({{spell.checker.SpellCheck@e222eb}}).

h2. List available factories
To list available factories (i.e. component types), launch the {{arch -factories}} command (or {{factories}} on Gogo):
{code:shell|title="Felix or Equinox"}
-> arch -factories
Factory spell.checker.SpellCheck (VALID)
Factory spell.gui.SpellCheckerGui (VALID)
Factory spell.english.EnglishDictionary (VALID)
{code}
{code:shell|title="Gogo"}
$factories
Factory spell.checker.SpellCheck (VALID)
Factory spell.gui.SpellCheckerGui (VALID)
Factory spell.english.EnglishDictionary (VALID)
{code}

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 {{arch -factory factory_name}} (or {{factory factory_name}} on Gogo) command:
{code:shell}
factory implementation-class="spell.english.EnglishDictionary" state="valid" bundle="7" name="spell.english.EnglishDictionary"
	provides specification="spell.services.DictionaryService"
	missinghandlers list="[]"
	requiredhandlers list="[org.apache.felix.ipojo:provides, org.apache.felix.ipojo:architecture]"
{code}
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. You also get the list of required and missing handlers.
h2. List available handlers
You can also list available handlers with the {{arch -handlers}} (or {{handlers}} on Gogo) command.
{code:shell|title="Felix or Equinox"}
-> 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.handler.whiteboard:wbp (VALID)
{code}
{code:shell|title="Gogo"}
$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.handler.whiteboard:wbp (VALID)
{code}
Handlers with the {{org.apache.felix.ipojo}} namespace (section before {{:}}) are core handlers (provided by the iPOJO core bundles). Others are external handlers (provided by others bundles).
\\
\\
{include:apache-felix-ipojo-footer}