iPOJO architecture commands

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 architecture commands allows getting these data from the Felix Shell, from the Equinox shell and Gogo.

Installation

According to your shell, download the adequate bundles from the Felix download page

Gogo

The Gogo commands are the following:

For example:

$ instances
Instance ArchCommand -> valid
Instance spell.english.EnglishDictionary-0 -> valid
Instance spell.checker.SpellCheck-0 -> valid
Instance spell.gui.SpellCheckerGui-0 -> valid

$ 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"

Equinox and Felix Shells

On Equinox and Felix (old) shell, the command is named arch:

Examples

-> arch
Instance ArchCommand -> valid
Instance spell.english.EnglishDictionary-0 -> valid
Instance spell.checker.SpellCheck-0 -> valid
Instance spell.gui.SpellCheckerGui-0 -> valid

-> 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"

Reading instance architecture:

Instance architecture is organized as follows:

As an example, the following snippet dumps the architecture of an instance:

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"

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:

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"

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).

List available factories

You can access factory list using the factories gogo command or the arch -factories on Felix's shell. For every available (public) factories,the name and the state are displayed. A factory is valid if and only if all required handlers are available.

-> arch -factories
Factory spell.checker.SpellCheck (VALID)
Factory spell.gui.SpellCheckerGui (VALID)
Factory spell.english.EnglishDictionary (VALID)
-> arch -factory spell.english.EnglishDictionary
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]"

On Gogo:

$factories
Factory spell.checker.SpellCheck (VALID)
Factory spell.gui.SpellCheckerGui (VALID)
Factory spell.english.EnglishDictionary (VALID)
$factory spell.english.EnglishDictionary
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]"

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.

List available handlers

Like listing factories, you can get the list of handlers.

-> 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)

On 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)

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).