Page History

...

This page presents how to use the iPOJO runtime and its associated service component model. The concepts of the service component model are introduced, followed by a simple example that demonstrates the features of iPOJO. This tutorial uses XML to describe components, however. However, iPOJO also supports annotations and provides an a Java API for this purpose.

Introduction

iPOJO aims to simplify service-oriented programming on OSGi frameworks; the name iPOJO is an abbreviation for injected POJO. iPOJO provides a new way to develop OSGi service components with the main goal being to simplify , simplifying service component implementation by transparently managing the dynamics of the environment as well as other non-functional requirements. The iPOJO framework allows developers to more clearly separate functional code (i.e., the POJOPOJOs) from the non-functional code (i.e., dependency management, service provision, configuration, etc.). At run time, iPOJO combines the functional and non-functional aspects at run time. To achieve this, iPOJO provides a simple and extensible service component model based on POJOs.

The POJO concept

"POJO" is just an acronym for Plain Old Java Object, but it embodies a concept that the simpler and less intrusive the design of a given framework, the better. The name is used to emphasize that a given object is not somehow special, but is an ordinary Java Object. Martin Fowler, Rebecca Parsons and Josh Mackenzie coined the term POJO in September 2000: "We wondered why people were so against using regular objects in their systems and concluded that it was because simple objects lacked a fancy name. So we gave them one, and it's caught on very nicely." From the a developer's perspective, the iPOJO framework strives as much as possible to only require POJOs in as much as it is possible.

iPOJO service component overview

A service component is able to provide and/or require services, where a service is an object that implements a given service interface embodied as a Java interface. In addition, iPOJO introduces a callback concept to notify a component about various state changes.

The component is the a central concept in iPOJO. In the core iPOJO model, a component describes service dependencies, provided services, and callbacks; this information is recorded in the component's metadata. ThenAfter components, the second next most important concept in iPOJO is the component instancesinstance. A component instances instance is a special version of the a component. By merging component metadata and instance configuration, the iPOJO runtime is able to manage the component, i.e., manage its life cycle, discover and inject required services, publish provided services, discover needed servicesand manage the component's life cycle.

A simple example

In this tutorial we will present how to:

...

package spell.services;
/**
 * A simple service interface that defines a dictionary service.
 * A dictionary service simply verifies the existence of a word.
**/
public interface DictionaryService {
    /**
     * Check for the existence of a word.
     * @param word the word to be checked.
     * @return true if the word is in the dictionary,
     *         false otherwise.
     **/
    public boolean checkWord(String word);
}

Then, create the file "src/spell/services/SpellChecker.java" for the following Spell Checker service interface:

...

Once created, you can build the project by launching Ant from the project directory.

$ ant
Buildfile: build.xml
clean:
compile:
    [mkdir] Created dir: d:\clement\workspaces\sandbox\ipojo\examples\tutorial-ant\
            spell.services\output
    [mkdir] Created dir: d:\clement\workspaces\sandbox\ipojo\examples\tutorial-ant\
            spell.services\output\classes
    [javac] Compiling 2 source files to d:\clement\workspaces\sandbox\ipojo\examples\
            tutorial-ant\spell.services\output\classes
package:
      [bnd] spell.services 2
BUILD SUCCESSFUL
Total time: 0 seconds

...

Then, we are able to create the bundle. In the spell.english directory launch the ant command:

$ ant
Buildfile: build.xml
clean:
   [delete] Deleting directory d:\clement\workspaces\sandbox\ipojo\examples\
            tutorial-ant\spell.english\output\classes
   [delete] Deleting directory d:\clement\workspaces\sandbox\ipojo\examples\
            tutorial-ant\spell.english\output
buildclasspath:
compile:
    [mkdir] Created dir: d:\clement\workspaces\sandbox\ipojo\examples\
            tutorial-ant\spell.english\output
    [mkdir] Created dir: d:\clement\workspaces\sandbox\ipojo\examples\
            tutorial-ant\spell.english\output\classes
    [javac] Compiling 1 source file to d:\clement\workspaces\sandbox\ipojo\examples\
            tutorial-ant\spell.english\output\classes
package:
      [bnd] spell.english 1
    [ipojo] Input Bundle File : d:\clement\workspaces\sandbox\ipojo\examples\
            tutorial-ant\spell.english\output\spell.english.jar
    [ipojo] Metadata File : d:\clement\workspaces\sandbox\ipojo\examples\
            tutorial-ant\spell.english\metadata.xml
    [ipojo] Start bundle manipulation
    [ipojo] Bundle manipulation - SUCCESS
    [ipojo] Output File : d:\clement\workspaces\sandbox\ipojo\examples\
            tutorial-ant\spell.english\output\spell.english.jar
BUILD SUCCESSFUL
Total time: 1 second

The created bundle is inside the output directory (spell.english.jar). The build process is based on BND and on the iPOJO Ant task. The manifest of the bundle is described in the spell.english.bnd file.

The spell.checker project: Requiring an OSGi service

...

To run the example, start Felix. A distribution of Felix is provided in the felix directory. This version is configured to launch iPOJO automatically. From the Felix directory, launch the following command to start the framework. Then enter a profile name.

java -jar bin/felix.jar

You can check installed bundles by using the 'ps' command:

-> ps
START LEVEL 1
   ID   State        Level  Name
[   0] [Active     ] [    0] System Bundle (12.40.15)
[   1] [Active     ] [    1] Apache Felix ShellBundle ServiceRepository (1.04.23)
[   2] [Active     ] [    1] Apache Felix Shell TUIiPOJO (1.6.0.2)
[   3] [Active     ] [    1] Apache Felix iPOJO BundleArch RepositoryCommand (1.26.10)
[   4] [Active     ] [    1] Apache Felix iPOJOShell Service (1.4.2.0)
[   5] [Active     ] [    1] Apache Felix iPOJOShell ArchTUI Command (1.24.01)
->

iPOJO runtime is the bundle 4. Once started, install the four created bundles as above:

start file:../spell.services/output/spell.services.jar
start file:../spell.english/output/spell.english.jar
start file:../spell.checker/output/spell.checker.jar
start file:../spell.checker.gui/output/spell.checker.gui.jar

When starting the GUI bundle, the user interface appears. Indeed, the Check Speller service is provided. You can interact with this service by entering a passage and clicking on the check button:

Then, stop the Dictionary service provider (with the stop 7) command. The GUI disappears. Indeed, Spell Checker service cannot be provided as it depends on the Dictionary service.

Then, restart the Dictionary service provider with the start 7 command. The GUI reappears immediately. You can try to stop the check speller service provider without stopping the dictionary service provider with the stop 8 command. As for the last manipulation, the GUI disappears.

To go further in the exploration, modify the spell.cheker checker implementation. For example, add a simple trace, printing wrong words:

...

iPOJO provides a lot of others features that you can try in the others available tutorials. Subscribe to the Felix users mailing list by sending a message to users-subscribe@felix.apache.org; after subscribing, email questions or feedback to users@felix.apache.org.