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.

iPOJO architecture commands

Installation¶

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

Gogo¶

The Gogo commands are the following:

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

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:

arch => displays instances name & state (equivalent to arch -instances)
arch -instance $instancename => displays complete information about the instance $instancename
arch -factories => display the list of available factories
arch -factory $factoryname => display complete information about the factory $factoryname
arch -handlers => list available handlers

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:

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.

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