KnowHowLab

OSGi universal shell implementation 1.1.0 released

2011-05-20T16:36:00.000+02:00

There is a new 1.1.0 version of OSGi universal shell adapters available.

Changes:
* Added support of defining commands services with Declarative Services

Command service registration with DS:

<?xml version="1.0" encoding="UTF-8"?>
<component name="shell_test.component">
    <implementation class="...ShellTestService"/>

    <service>
        <provide interface="...ShellTestService"/>
    </service>

    <property name="org.knowhowlab.osgi.shell.group.id" type="String" value="test_group_id"/>
    <property name="org.knowhowlab.osgi.shell.group.name" type="String" value="Test commands"/>
    <property name="org.knowhowlab.osgi.shell.commands" type="String">
        bndinfo#bndinfo <bundleId> - Print information for bundle with <bundleId>
        bndsinfo#bndsinfo - Print information for all bundles
    </property>
...
</component>

Maven artifacts:

<dependency>
    <groupId>org.knowhowlab.osgi.shell</groupId>
    <artifactId>equinox</artifactId>
    <version>1.1.0</version>
</dependency>

<dependency>
    <groupId>org.knowhowlab.osgi.shell</groupId>
    <artifactId>felix</artifactId>
    <version>1.1.0</version>
</dependency>

<dependency>
    <groupId>org.knowhowlab.osgi.shell</groupId>
    <artifactId>felix-gogo</artifactId>
    <version>1.1.0</version>
</dependency>

<dependency>
    <groupId>org.knowhowlab.osgi.shell</groupId>
    <artifactId>knopflerfish</artifactId>
    <version>1.1.0</version>
</dependency>

Cheers,
Dmytro

OSGi universal shell implementation 1.0.1 released

2011-04-02T10:44:00.000+02:00

Hi, There is a new 1.0.1 version of OSGi universal shell adapters available.

Changes:
* Changed package to org.knowhowlab.osgi.shell
* Changed maven groupId to org.knowhowlab.osgi.shell
* Added Apache Felix GoGo Universal Shell Adapter

Maven artifacts:

<dependency>
    <groupId>org.knowhowlab.osgi.shell</groupId>
    <artifactId>equinox</artifactId>
    <version>1.0.1</version>
</dependency>

<dependency>
    <groupId>org.knowhowlab.osgi.shell</groupId>
    <artifactId>felix</artifactId>
    <version>1.0.1</version>
</dependency>

<dependency>
    <groupId>org.knowhowlab.osgi.shell</groupId>
    <artifactId>felix-gogo</artifactId>
    <version>1.0.1</version>
</dependency>

<dependency>
    <groupId>org.knowhowlab.osgi.shell</groupId>
    <artifactId>knopflerfish</artifactId>
    <version>1.0.1</version>
</dependency>

Cheers,
Dmytro

OSGi Tutorial: 4 ways to activate code in OSGi bundle

2010-10-30T15:33:00.002+02:00

Hello everybody!

I would like to present a tutorial in which I show 4 ways how to activate/start code inside your OSGi bundle. All those ways are part of OSGi 4.2 specifications. The goal of the tutorial is to explain in a short form some OSGi specifications chapters with samples. I do not like to make any deep comparison of activation ways, just overview with workable examples. All sources you can find here.

Contents:

Requirements
Use Case details
Bundle Activator
Declarative Services
Blueprint Services
Web Application Bundle
How to run examples
References

Requirements. There are minimum requirements:
- Apache Maven 2.x or 3.0.x
- Your IDE with Maven support.
- Basic knowledge of OSGi specification
- Basic knowledge of PAX tools (Pax Runner). You can get some brief information also here
Use Case details. The tutorial use case is very simple:
- There is interface org.knowhowlab.osgi.tips.activation.core.Echo
```
                public interface Echo {
                    String ECHO_TYPE_PROP = "echo_type";

                    String echo(String str);
                }
            
```
  This interface exported by core bundle.
- This interface should be implemented
- Implementation should be registered as OSGi service only when org.osgi.service.prefs.PreferencesService service is available in OSGi registry

Bundle Activator. This is the simplest and oldest way to activate code in your bundle.
There are some details of this activation way:

There is only one BundleActivator per bundle
Any class could implement org.osgi.framework.BundleActivator interface
This class should have empty constructor
This class should be provided with MANIFEST OSGi header Bundle-Activator to be called on OSGi bundle STARTING stage
The best way to use it (from my own experience) in low-level bundles (e.g. implementation of any OSGi API) or when you like to control everything yourself
This way could be also used when your code does not have a lot of dependencies to external services. org.osgi.util.tracker.ServiceTracker could be used to track external services. As many external services you track as more logic code you have to write to cover all cases.

Here is code of my BundleActivator that implements required tutorial use case:

        public class Activator implements BundleActivator, Echo {
            // ServiceTracker for PreferencesServices
            private ServiceTracker serviceTracker;
            // BundleContext
            private BundleContext bc;
            // Registration of Echo service
            private ServiceRegistration registration;

            // activation
            public void start(BundleContext context) throws Exception {
                bc = context;
                // init and start ServiceTracker to track PreferencesService
                serviceTracker = new ServiceTracker(context, PreferencesService.class.getName(), new Customizer());
                serviceTracker.open();
            }

            // deactivation
            public void stop(BundleContext context) throws Exception {
                // stop ServiceTracker to track PreferencesService
                serviceTracker.close();
                serviceTracker = null;
            }

            public String echo(String str) {
                return str;
            }

            // customizer that handles tracked service registration/modification/unregistration events
            private class Customizer implements ServiceTrackerCustomizer {
                public Object addingService(ServiceReference reference) {
                    System.out.println("PreferencesService is linked");
                    // register Echo service
                    Dictionary<String, String> props = new Hashtable<String, String>();
                    props.put(ECHO_TYPE_PROP, "BundleActivator");
                    registration = bc.registerService(Echo.class.getName(), Activator.this, props);

                    return bc.getService(reference);
                }

                public void modifiedService(ServiceReference reference, Object service) {
                }

                public void removedService(ServiceReference reference, Object service) {
                    // unregister Echo service
                    registration.unregister();
                    System.out.println("PreferencesService is unlinked");
                }
            }
        }

Bundle MANIFEST.MF:

        Manifest-Version: 1.0
        Bundle-Name: KnowHowLab Tips&Tricks: Bundle Activation - Activator
        Bundle-Version: 1.0.0.SNAPSHOT
        Bundle-ManifestVersion: 2
        Bundle-Activator: org.knowhowlab.osgi.tips.activation.activator.Activa
         tor
        Bundle-Description: KnowHowLab Tips and Tricks: Bundle Activation - Ac
         tivator
        Import-Package: org.knowhowlab.osgi.tips.activation.core,org.osgi.fram
         ework;version="1.5",org.osgi.service.prefs;version="1.1",org.osgi.uti
         l.tracker;version="1.4"
        Bundle-SymbolicName: org.knowhowlab.osgi.tips.activation.activator

Declarative Services. Declarative Services specification is the next higher-level way of activation your code in bundle. It helps developer to concentate on application logic and takes responsibility for almost all OSGi aspects of tracking and registering services.
There are some details of this activation way:

Declarative Services do not work with bundle as atomic item (as in BundleActivator way). Service Component model is used instead of Bundle model
OSGi bundle can contain any count of Service Components
Every component should have Component Description - XML file with declaration of component
Every Component Description should be listed in MANIFEST OSGi header Service-Component to be available for Service Component Runtime, that manages components and their life cycle

Here is code of my EchoComponent:

        public class EchoComponent implements Echo {
            // Reference to PreferencesService
            private PreferencesService preferencesService;

            public String echo(String str) {
                return str;
            }

            // Called to bind PreferencesService
            public void bindPreferencesService(PreferencesService preferencesService) {
                System.out.println("PreferencesService is linked");
                this.preferencesService = preferencesService;
            }

            // Called to unbind PreferencesService
            public void unbindPreferencesService(PreferencesService preferencesService) {
                this.preferencesService = null;
                System.out.println("PreferencesService is unlinked");
            }
        }

Here is Component Description:

        <?xml version="1.0" encoding="UTF-8"?>
        <components xmlns:scr="http://www.osgi.org/xmlns/scr/v1.0.0">
            <!-- Echo Component -->
            <scr:component enabled="true" immediate="true" name="Echo">
                <!--Component Class name-->
                <implementation class="org.knowhowlab.osgi.tips.activation.ds.EchoComponent"/>
                <!-- Echo Service description -->
                <service servicefactory="false">
                    <provide interface="org.knowhowlab.osgi.tips.activation.core.Echo"/>
                </service>
                <!-- Service registration properties -->
                <property name="echo_type" type="String" value="Declarative Services"/>
                <property name="service.pid" value="Echo"/>
                <!-- PreferencesService dependency description -->
                <reference name="preferencesService" 
                           interface="org.osgi.service.prefs.PreferencesService" 
                           cardinality="1..1"
                           policy="static" 
                           bind="bindPreferencesService" 
                           unbind="unbindPreferencesService"/>
            </scr:component>
        </components>

Bundle MANIFEST.MF:

        Manifest-Version: 1.0
        Service-Component: OSGI-INF/serviceComponents.xml
        Export-Package: org.knowhowlab.osgi.tips.activation.ds;uses:="org.know
         howlab.osgi.tips.activation.core,org.osgi.service.prefs"
        Bundle-Name: KnowHowLab Tips&Tricks: Bundle Activation - DS
        Bundle-Version: 1.0.0.SNAPSHOT
        Bundle-ManifestVersion: 2
        Import-Package: org.knowhowlab.osgi.tips.activation.core,org.osgi.serv
         ice.prefs;version="1.1"
        Bundle-SymbolicName: org.knowhowlab.osgi.tips.activation.ds

There is Component Descrition annotations library that generate Component Description during OSGi bundle build and makes development of Service Components easier. Here is code with annotations:

        // Component description
        @Component(name = "Echo", immediate = true)
        // Service description
        @Service(value = Echo.class)
        // Service properties
        @Property(name = Echo.ECHO_TYPE_PROP, value = "Declarative Services")
        public class EchoComponent implements Echo {
            // Reference to PreferencesService
            @Reference(name = "preferencesService", referenceInterface = PreferencesService.class,
                    cardinality = ReferenceCardinality.MANDATORY_UNARY, policy = ReferencePolicy.STATIC)
            private PreferencesService preferencesService;

            public String echo(String str) {
                return str;
            }

            // Called to bind PreferencesService
            public void bindPreferencesService(PreferencesService preferencesService) {
                System.out.println("PreferencesService is linked");
                this.preferencesService = preferencesService;
            }

            // Called to unbind PreferencesService
            public void unbindPreferencesService(PreferencesService preferencesService) {
                this.preferencesService = null;
                System.out.println("PreferencesService is unlinked");
            }
        }

Blueprint Services. Blueprint Services specification is derived from Spint Dynamic Modules specification and very similar to Declarative Services specification (developer concentrates more on application-specific code).
There are some details of this activation way:

Blueprint Services do not work with bundle as atomic item (as in BundleActivator way). Component/Bean model is used instead of Bundle model
OSGi bundle can contain any count of Components/Beans
Every component/bean should have Component Definition - XML file with definition
All Component/Bean Definitions should be stored in OSGI-INF/blueprint directory

Here is code of my EchoBean:

        public class EchoBean implements Echo {
            // Reference to PreferencesService
            private PreferencesService preferencesService;

            public String echo(String str) {
                return str;
            }

            // Called to bind PreferencesService
            public void bindPreferencesService(PreferencesService preferencesService, Map props) {
                this.preferencesService = preferencesService;
                System.out.println("PreferencesService is linked");
            }

            // Called to unbind PreferencesService
            public void unbindPreferencesService(PreferencesService preferencesService, Map props) {
                this.preferencesService = null;
                System.out.println("PreferencesService is unlinked");
            }
        }

Here is Bean Definition (OSGI-INF/blueprint/echo.xml):

        <?xml version="1.0" encoding="UTF-8" standalone="no"?>
        <blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0">
            <!-- Bean definition -->
            <bean id="echoservice" class="org.knowhowlab.osgi.tips.activation.blueprint.EchoBean"/>
            <!-- Service definition -->
            <service ref="echoservice" interface="org.knowhowlab.osgi.tips.activation.core.Echo"
                     depends-on="preferencesService">
                <service-properties>
                    <entry key="ECHO_TYPE_PROP" value="Blueprint"/>
                </service-properties>
            </service>
            <!-- PreferencesService reference definition -->
            <reference id="preferencesService" interface="org.osgi.service.prefs.PreferencesService"
                       availability="mandatory">
                <reference-listener bind-method="bindPreferencesService" unbind-method="unbindPreferencesService">
                    <ref component-id="echoservice"/>
                </reference-listener>
            </reference>
        </blueprint>

I found very nice project BlueprintAnnotation under Apache Aries project. It provides runtime annotations for Blueprint beans that replaces Component/Bean Definition files. Here is EchoBean with Blueprint Annotations:

        // Bean definition
        @Bean(id = "echoservice")
        // Service definition
        @Service(interfaces = Echo.class,
                serviceProperties = @ServiceProperty(key = Echo.ECHO_TYPE_PROP, value = "Blueprint-Annotations"))
        @ReferenceListener
        public class EchoBean implements Echo {
            // Reference definition 
            @Reference(availability = "mandatory", referenceListeners = @ReferenceListener(ref = "echoservice"))
            private PreferencesService preferencesService;

            public String echo(String str) {
                return str;
            }

            @Bind
            public void bindPreferencesService(PreferencesService preferencesService, Map props) {
                this.preferencesService = preferencesService;
                System.out.println("PreferencesService is linked");
            }

            @Unbind
            public void unbindPreferencesService(PreferencesService preferencesService, Map props) {
                this.preferencesService = null;
                System.out.println("PreferencesService is unlinked");
            }
        }

Web Application Bundle. Web Application Bundle (WAB) was introduced in OSGi Enterprise 4.2 Specification. WAB is a combination of JEE Web Application and OSGi bundle.
There are some details of this activation way:

WAB has the same structure as standard WAR + OSGi MANIFEST.MF
WAB uses the same life cycle and class/resource loading rules as standard OSGi bundle
WAB context path should be described in MANIFEST OSGi header Web-ContextPath
/classes and all JARs/ZIPs in /lib folder should be listed in MANIFEST OSGi header Bundle-Classpath
OSGi BundleContext is provided to WAB as ServletContext attribute "osgi-bundlecontext". It is available for Servlets/JSPs/Listeners/Filters.

Here is code of my ContextListener:

        public class ContextListener implements ServletContextListener, Echo {
            private ServiceTracker serviceTracker;
            private BundleContext bc;
            private ServiceRegistration registration;

            public void contextInitialized(ServletContextEvent sce) {
                bc = (BundleContext) sce.getServletContext().getAttribute("osgi-bundlecontext");
                serviceTracker = new ServiceTracker(bc, PreferencesService.class.getName(), new Customizer());
                serviceTracker.open();
            }

            public void contextDestroyed(ServletContextEvent sce) {
                serviceTracker.close();
                serviceTracker = null;
            }

            public String echo(String str) {
                return str;
            }

            private class Customizer implements ServiceTrackerCustomizer {

                public Object addingService(ServiceReference reference) {
                    System.out.println("PreferencesService is linked");

                    Dictionary<String, String> props = new Hashtable<String, String>();
                    props.put(ECHO_TYPE_PROP, "WAB");
                    registration = bc.registerService(Echo.class.getName(), ContextListener.this, props);

                    return bc.getService(reference);
                }

                public void modifiedService(ServiceReference reference, Object service) {
                }

                public void removedService(ServiceReference reference, Object service) {
                    registration.unregister();
                    System.out.println("PreferencesService is unlinked");
                }
            }
        }

Here is web.xml:

        <web-app xmlns="http://java.sun.com/xml/ns/javaee"
                 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                 metadata-complete="true"
                 version="2.5">
            <listener>
                <listener-class>org.knowhowlab.osgi.tips.activation.wab.ContextListener</listener-class>
            </listener>

            <!-- welcome file mapping -->
            <welcome-file-list>
                <welcome-file>index.htm</welcome-file>
            </welcome-file-list>
        </web-app>

Here is MANIFEST.MF:

        Manifest-Version: 1.0
        Export-Package: org.knowhowlab.osgi.tips.activation.wab;uses:="org.kno
         whowlab.osgi.tips.activation.core,org.osgi.util.tracker,org.osgi.fram
         ework,javax.servlet,org.osgi.service.prefs";version="1.0.0.SNAPSHOT"
        Bundle-Classpath: WEB-INF/classes
        Bundle-Name: KnowHowLab Tips&Tricks: Bundle Activation - WAB
        Web-ContextPath: /
        Bundle-Version: 1.0.0.SNAPSHOT
        Bundle-ManifestVersion: 2
        Import-Package: javax.servlet,org.knowhowlab.osgi.tips.activation.core
         ,org.osgi.framework;version="1.5",org.osgi.service.prefs;version="1.1
         ",org.osgi.util.tracker;version="1.4"
        Bundle-SymbolicName: org.knowhowlab.osgi.tips.activation.wab

How to run examples

Download samples from here
Compile with Maven command
```
mvn clean install
```
Run BundleActivator sample
```
mvn -f run.xml -P activator
```
Run Declarative Services sample
```
mvn -f run.xml -P ds
```
Run Blueprint Services sample
```
mvn -f run.xml -P blueprint
```
Run Blueprint Annotations sample
```
mvn -f run.xml -P blueprint-annotations
```
Note: It does not work for me (even Aries BlueprintAnnotation sample). I'll try with the next version.
Run WAB sample
```
mvn -f run.xml -P wab
```

Run All sample

mvn -f run.xml -P all

Framework started:

id      State       Bundle
0       ACTIVE      org.eclipse.osgi_3.6.0.v20100517
1       ACTIVE      org.eclipse.osgi.services_3.2.100.v20100503
2       ACTIVE      org.eclipse.equinox.common_3.6.0.v20100503
3       ACTIVE      org.eclipse.equinox.preferences_3.3.0.v20100503
4       ACTIVE      org.eclipse.equinox.cm_1.0.200.v20100520
5       ACTIVE      org.eclipse.equinox.util_1.0.200.v20100503
6       ACTIVE      org.eclipse.equinox.ds_1.2.0.v20100507
7       ACTIVE      org.apache.geronimo.specs.geronimo-servlet_2.5_spec_1.2.0
8       ACTIVE      org.apache.geronimo.specs.geronimo-jaspic_1.0_spec_1.1.0
9       ACTIVE      org.eclipse.jetty.aggregate.jetty-all-server_7.2.0.v20101020
10      ACTIVE      org.eclipse.jetty.osgi.boot_7.2.0.v20101020
11      ACTIVE      slf4j.api_1.6.1
                    Fragments=12
12      RESOLVED    slf4j.jdk14_1.6.1
                    Master=11
13      ACTIVE      org.apache.aries.blueprint_0.2.0.incubating
14      ACTIVE      org.knowhowlab.osgi.tips.activation.core_1.0.0.SNAPSHOT
15      ACTIVE      org.knowhowlab.osgi.tips.activation.activator_1.0.0.SNAPSHOT
16      ACTIVE      org.knowhowlab.osgi.tips.activation.ds_1.0.0.SNAPSHOT
17      ACTIVE      org.knowhowlab.osgi.tips.activation.blueprint_1.0.0.SNAPSHOT
18      ACTIVE      org.knowhowlab.osgi.tips.activation.wab_1.0.0.SNAPSHOT

All Echo services registered:

osgi> services (objectClass=org.knowhowlab.osgi.tips.activation.core.Echo)
{org.knowhowlab.osgi.tips.activation.core.Echo}={echo_type=BundleActivator, service.id=41}
  Registered by bundle: org.knowhowlab.osgi.tips.activation.activator_1.0.0.SNAPSHOT [15]
  No bundles using service.
{org.knowhowlab.osgi.tips.activation.core.Echo}={service.pid=Echo, echo_type=Declarative Services, component.name=Echo, component.id=0, service.id=42}
  Registered by bundle: org.knowhowlab.osgi.tips.activation.ds_1.0.0.SNAPSHOT [16]
  No bundles using service.
{org.knowhowlab.osgi.tips.activation.core.Echo}={osgi.service.blueprint.compname=echoservice, ECHO_TYPE_PROP=Blueprint, service.id=46}
  Registered by bundle: org.knowhowlab.osgi.tips.activation.blueprint_1.0.0.SNAPSHOT [17]
  No bundles using service.
{org.knowhowlab.osgi.tips.activation.core.Echo}={echo_type=WAB, service.id=49}
  Registered by bundle: org.knowhowlab.osgi.tips.activation.wab_1.0.0.SNAPSHOT [18]
  No bundles using service.

Stop PersistenceService bundle, all Echo services are unregistered:

osgi> stop 3
PreferencesService is unlinked
PreferencesService is unlinked
PreferencesService is unlinked
PreferencesService is unlinked

osgi> services (objectClass=org.knowhowlab.osgi.tips.activation.core.Echo)
No registered services.

References:
1. OSGi specifications
2. OSGi API
3. Bnd tool - tool to help you diagnose and create OSGi bundles
4. maven-bundle-plugin - Maven plugin for Bnd tool
5. maven-scr-plugin - Maven plugin to ease the development of OSGi component and services
6. SCR annotations - How to use annotations for OSGi components
7. Aries Blueprint - Blueprint "Hello World" tutorial
8. Aries BlueprintAnnotations - BlueprintAnnotation tutorial
9. Pax Runner - tool to provision OSGi bundles in all major open source OSGi framework implementations (Felix, Equinox, Knopflerfish, Concierge)

Your comments are welcome.
Thank you.
Dmytro

OSGi MonitorAdmin Implementation: Release 1.0.2

2010-07-28T23:55:00.000+02:00

Hello,

I'd like to announce a new release of MonitorAdmin bundle 1.0.2. The major change - support of security permissions.

Changes:
* change POM packaging to JAR
* embed org.osgi.service.monitor package
* refactor package to org.knowhowlab.osgi.monitoradmin
* change groupId to org.knowhowlab.osgi
* change license to Apache License 2.0
* add support of security permissions
* add local permissions file

Maven artifact:

<dependency>
    <groupId>org.knowhowlab.osgi</groupId>
    <artifactId>monitoradmin</artifactId>
    <version>1.0.2</version>
</dependency>

Cheers,
Dmytro

JMX Management Model Implementation: Release 1.0.2

2010-07-09T17:56:00.000+02:00

Hi,

I'd like to announce a new minor release of JMX bundle 1.0.2.

Changes:
* refactor package to org.knowhowlab.osgi.jmx
* change groupId to org.knowhowlab.osgi
* change license to Apache License 2.0
* add support of MonitorAdmin event to notify through JMX
* handle errors on bundle start and unregister registered MBeans
* embed org.osgi.jmx package

Maven artifact:

<dependency>
    <groupId>org.knowhowlab.osgi</groupId>
    <artifactId>jmx</artifactId>
    <version>1.0.2</version>
</dependency>

Cheers,
Dmytro

Blog update

2010-07-01T17:33:00.000+02:00

Hello,

I've just moved blog from http://www.osgilab.org to http://blog.knowhowlab.org. It could be unavailable for couple of days. Hope to solve all problems with host change as soon as possible.

Sorry for inconvenience.

Best regards,
Dmytro

How to replace standard Equinox shell with Apache Felix GoGo

2010-06-28T23:09:00.002+02:00

Hello,

I've just spent some time to figure out how to integrate Apache Felix GoGo shell into Eclipse Equinox. I found two steps that should be done for this:

Disable standard Equinox shell and activate GoGo shell as default. Actually, it was not so complicated. One problem, that Equinox shell is a part of system bundle and you cannot just throw it away and replace with another implementation as you can do it with Knopflerfish. Equinox has runtime options to enable and disable console (-console, -noConsole). Then, to enable GoGo we have to install and start 3 GoGo bundles with runtime, shell and commands functionality. Fine! Now we can register shell commands based on GoGo API. Known issue: I could not replace shell when Equinox is started via Eclipse Launcher.
The second and also very important step is how to integrate Equinox shell commands into GoGo shell. I wrote some Equinox->GoGo adapter bundle that tracks Equinox shell services and registers GoGo shell service. This adapter can redirect calls from GoGo to Equinox. It can also add some usage help to Equinox commands if this help is provided by Equinox shell service.

When above steps are finished (except support of Eclipse Launcher) we can add new shell commands with GoGo and Equinox shell APIs.

Below you can find some logs from my console and the way how you can run this on your computer.

Standard Equinox Console:

osgi> help
---Controlling the OSGi framework---
 launch - start the OSGi Framework
 shutdown - shutdown the OSGi Framework
 close - shutdown and exit
 exit - exit immediately (System.exit)
 init - uninstall all bundles
 setprop = - set the OSGi property
.......

Now Equinox with GoGo console and support of Equinox shell commands

g! help
equinox:b
equinox:bundle
equinox:bundles
equinox:classSpaces
equinox:close
equinox:diag
equinox:disableBundle
equinox:disabledBundles
equinox:enableBundle
equinox:exec
equinox:exit
equinox:fork
.....
felix:start
felix:stop
felix:uninstall
felix:update
felix:which
gogo:cat
gogo:each
gogo:echo
gogo:format
gogo:getopt
gogo:gosh
......

g! help ss
ss - [-s []  []] - display installed bundles (short status)
   scope: equinox
   parameters:
      CommandSession
      String[]

g! ss -s ACTIVE
Framework is launched.
id      State       Bundle
0       ACTIVE      org.eclipse.osgi_3.6.0.v20100517
1       ACTIVE      org.apache.felix.gogo.runtime_0.6.0
2       ACTIVE      org.apache.felix.gogo.shell_0.6.0
3       ACTIVE      org.apache.felix.gogo.command_0.6.0
4       ACTIVE      org.knowhowlab.osgi.experiments.gogo.equinox_1.0.0

This solution was an experiment to integrate Apache Felix GoGo into Eclipse Equinox with support of all Equinox shell commands.
If you like to make some tests on you computer you have to download Maven project and platform definition. To start OSGi framework use command:

mvn -f demo-pom.xml

Hope, that code helps you.

Have a nice day,
Dmytro

Eclipse Equinox Helios 3.6 is out!

2010-06-23T19:01:00.000+02:00

Hello,

now we have very nice time to test our bundles and applications with 3 the most popular OSGi R4 v.4.2 frameworks: Felix, Equinox and Knopflerfish. The Equinox 3.6 was released just a few hours ago.
I've composed platform definition for Eclipse Equinox 3.6 for Pax Runned and Pax Exam.
You can download it from here or you can use it directly from POM:

<plugin>
    <groupId>org.ops4j</groupId>
    <artifactId>maven-pax-plugin</artifactId>
    <version>1.4</version>
    <configuration>
        <runner>1.4.0</runner>
        <framework>equinox</framework>
        <provision>
            <param>--log=debug</param>
            <param>--workingDirectory=target/runner</param>
            <param>--ee=J2SE-1.5</param>
            <param>--definitionURL=http://osgilab.googlecode.com/svn/trunk/org.osgilab.tips/pax-platforms/platform-equinox-3.6.0.xml</param>
        </provision>
    </configuration>
</plugin>

or from Pax Exam Unit test:

public class PaxExamTest {
   .......................
   @Configuration
    public static Option[] configurePlatform() {
        return options(
                equinox(),
                rawPaxRunnerOption("--definitionURL", "http://osgilab.googlecode.com/svn/trunk/org.osgilab.tips/pax-platforms/platform-equinox-3.6.0.xml")
        );
    }
   .......................
}

Have a nice OSGi development and testing.
Dmitriy

Knopflerfish 3.0.0 Released

2010-06-22T07:53:00.001+02:00

Hi,

This month is very rich for new OSGi framework versions. Apache Felix 3.0.0 was released a week ago and now Knopflerfish OSGi framework 3.0.0 with R4 V4.2 support is released.

What is inside:

Core specifications: Security, Module Layer, Service Layer, Life Cycle Layer - fully implemented
Framework Services: Package Admin with multihost fragments support, Start Level, Conditional Permission Admin, Permission Admin, URL Handler, Service Hooks
Service Compendium: Log, HTTP, Device Access, Configuration Admin, Meta Type, Preferences, User Admin, IO Connector, Declarative Services, Event Admin, Service and Bundle Trackers, XML Parser Service, Position, Measurement and State

A nice bunch of R4 V4.2 services :)

I've composed platform definition for Knopflerfish 3.0.0 for Pax Runned and Pax Exam.
You can download it from here or you can use it directly from POM:

<plugin>
    <groupId>org.ops4j</groupId>
    <artifactId>maven-pax-plugin</artifactId>
    <version>1.4</version>
    <configuration>
        <runner>1.4.0</runner>
        <framework>knopflerfish</framework>
        <provision>
            <param>--log=debug</param>
            <param>--workingDirectory=target/runner</param>
            <param>--ee=J2SE-1.5</param>
            <param>--definitionURL=http://osgilab.googlecode.com/svn/trunk/org.osgilab.tips/pax-platforms/platform-knopflerfish-3.0.0.xml</param>
        </provision>
    </configuration>
</plugin>

or from Pax Exam Unit test:

public class PaxExamTest {
   .......................
   @Configuration
    public static Option[] configurePlatform() {
        return options(
                knopflerfish(),
                rawPaxRunnerOption("--definitionURL", "http://osgilab.googlecode.com/svn/trunk/org.osgilab.tips/pax-platforms/platform-knopflerfish-3.0.0.xml")
        );
    }
   .......................
}

Waiting for Eclipse Helios release just to have all 3 OSGi R4 V4.2 framework implementations.

Have a nice day,
Dmitriy

Pax Runner/Exam: Felix 3.0.0 + Gogo support

2010-06-16T14:21:00.001+02:00

Hello,

I've just created Pax Runner/Exam platform definition for just released Felix 3.0.0 and Felix Gogo 0.6.0 (RFC147 implementation).

You can download it from here or you can use it directly from POM:

<plugin>
    <groupId>org.ops4j</groupId>
    <artifactId>maven-pax-plugin</artifactId>
    <version>1.4</version>
    <configuration>
        <runner>1.4.0</runner>
        <framework>felix</framework>
        <provision>
            <param>--log=debug</param>
            <param>--workingDirectory=target/runner</param>
            <param>--ee=J2SE-1.5</param>
            <param>--definitionURL=http://osgilab.googlecode.com/svn/trunk/org.osgilab.tips/pax-platforms/platform-felix-3.0.0.xml</param>
        </provision>
    </configuration>
</plugin>

or from Pax Exam Unit test:

public class PaxExamTest {
   .......................
   @Configuration
    public static Option[] configurePlatform() {
        return options(
                felix(),
                rawPaxRunnerOption("--definitionURL", "http://osgilab.googlecode.com/svn/trunk/org.osgilab.tips/pax-platforms/platform-felix-3.0.0.xml")
        );
    }
   .......................
}

Best regards, Dmitriy

OSGi Tutorial: From project structure to release

2010-06-12T20:49:00.003+02:00

Hello everybody!

This is a small OSGi tutorial where I tried to explain all main steps in OSGi bundle development. The tutorial is based on my own experience with MonitorAdmin API implementation. All sources you can find here.

Contents:

Tools
Maven POM file
Development tips
Unit tests with mocks
Integration tests inside OSGi framework
Provisioning and manual testing
Release to Central Maven repository
References

Let's start!

Tools. First of all, we have to prepare tools:
- Apache Maven 2.x
- Your IDE with Maven support.

Create Maven POM file for your OSGi bundle. The goal of this step is a configuration how to package your bundle: which classes are included and add OSGi specific entries to JAR manifest file.

POM OSGi module configuration:

<project>
    <modelVersion>4.0.0</modelVersion>
    <!-- OSGi bundle group, artifact and version -->
    <groupId>org.osgilab.bundles</groupId>
    <artifactId>monitoradmin</artifactId>
    <version>1.0.2-SNAPSHOT</version>
    <!-- module packaging [1] -->
    <packaging>bundle</packaging>

    <!-- module dependencies [2] -->
    <dependencies>
        <dependency>
            <groupId>org.osgi</groupId>
            <artifactId>org.osgi.core</artifactId>
            <version>4.1.0</version>
        </dependency>
        <dependency>
            <groupId>org.osgi</groupId>
            <artifactId>org.osgi.compendium</artifactId>
            <version>4.1.0</version>
        </dependency>
    </dependencies>
    <build>
        <plugins>
            <!-- maven-bundle-plugin [3] -->
            <plugin>
                <groupId>org.apache.felix</groupId>
                <artifactId>maven-bundle-plugin</artifactId>
                <version>2.0.1</version>
                <extensions>true</extensions>
                <!-- maven-bundle-plugin configuration [4] -->
                <configuration>
                    <instructions>
                        <Export-Package/>
                        <Import-Package>
                            org.osgi*
                        </Import-Package>
                        <Bundle-Activator>
                            org.osgilab.bundles.monitoradmin.Activator
                        </Bundle-Activator>
                        <Bundle-SymbolicName>
                            ${project.groupId}.${project.artifactId};singleton:=true
                        </Bundle-SymbolicName>
                        <Bundle-RequiredExecutionEnvironment>
                            J2SE-1.5
                        </Bundle-RequiredExecutionEnvironment>
                    </instructions>
                </configuration>
            </plugin>
            <!-- other plugins ... -->
        </plugins>
    </build>
</project>

[1] - bundle packaging is a custom packaging type that is supported by maven-bundle-plugin
[2] - module dependencies. By default, OSGi Core and Compendium API are used.
[3] - maven-bundle-plugin. This plugin is based on Bnd tool and helps to generate OSGi bundle manifest
[4] - maven-bundle-plugin configuration with OSGi specific instructions

Alternative 1: use jar packaging. In this case you have to configure maven-bundle-plugin to generate manifest file and maven-jar-plugin to include the generated MANIFEST.MF into OSGi JAR file.

<project>
    <!-- module packaging -->
    <packaging>jar</packaging>
    <build>
        <plugins>
            <!-- maven-bundle-plugin -->
            <plugin>
                <groupId>org.apache.felix</groupId>
                <artifactId>maven-bundle-plugin</artifactId>
                <version>2.0.1</version>
                <extensions>true</extensions>
                <!-- configure plugin to generate MANIFEST.MF -->
                <executions>
                    <execution>
                        <id>bundle-manifest</id>
                        <phase>process-classes</phase>
                        <goals>
                            <goal>manifest</goal>
                        </goals>
                    </execution>
                </executions>
                <configuration>
                    <!-- configure plugin to support jar packaging -->
                    <supportedProjectTypes>
                        <supportedProjectType>jar</supportedProjectType>
                    </supportedProjectTypes>
                    <instructions>
                        <!-- OSGi specific instruction -->
                    </instructions>
                </configuration>
            </plugin>
            <!-- maven-jar-plugin -->
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-jar-plugin</artifactId>
                <configuration>
                    <archive>
                        <!-- configure plugin to use MANIFEST.MF
                        generated by maven-bundle-plugin -->
                        <manifestFile>
                            ${project.build.outputDirectory}/META-INF/MANIFEST.MF
                        </manifestFile>
                    </archive>
                </configuration>
            </plugin>
            <!-- other plugins ... -->
        </plugins>
    </build>
</project>

Alternative 2: move maven-bundle-plugin OSGi specific configuration from POM to separate file. You can use Bnd native style configuration file with OSGi instructions. You can define OSGi instructions in POM and in Bnd configuration file.

<project>
    <build>
        <plugins>
            <!-- maven-bundle-plugin -->
            <plugin>
                <groupId>org.apache.felix</groupId>
                <artifactId>maven-bundle-plugin</artifactId>
                <version>2.0.1</version>
                <extensions>true</extensions>
                <configuration>
                    <!-- OSGi specific instruction -->
                    <instructions>
                        <Bundle-SymbolicName>
                            ${project.groupId}.${project.artifactId};singleton:=true
                        </Bundle-SymbolicName>
                        <!-- include instructions from 
                        Bnd native style file osgi.bnd -->
                        <_include>-osgi.bnd</_include>
                    </instructions>
                </configuration>
            </plugin>
            <!-- other plugins ... -->
        </plugins>
    </build>
</project>

osgi.bnd - file with Bnd instructions.

Export-Package:
Import-Package: org.osgi*
Bundle-Activator: org.osgilab.bundles.monitoradmin.Activator

Alternative 3: use manually created MANIFEST.MF (not recommended). You can create OSGi specific MANIFEST.MF without any help from maven-bundle-plugin.

Development tips. This is the simplest section in my tutorial - just use standard OO approach and patterns to provide the best quality.
I can give several tips that you can use during OSGi bundle development More details here:
- select the most suitable way to activate your bundle. OSGi specification offers several ways:
  - BundleActivator - I use this way during development of low-level components
  - Declarative Services - a very good way to concentrate on the application logic of your code.
  - Blueprint Services - this way was firstly implemented in Spring OSGi and then included into OSGi 4.2 specification. You can use this way instead of the Declarative Services if you have the experience with Spring technologies.
  - Web Application Bundle - this is a new bundle type that was introduced in OSGi Enterprise Specification 4.2.
  You have to decide which way suits your bundle design more.
- try to decouple your functionality from OSGi specific APIs as much as possible. It helps you to test your functionality with standard unit tests and simple mocks and avoids to move all functionality testing to integration tests.
- OSGi best practices:
  - avoid Require-Bundle. Use Import-Package instead of.
  - Only import packages that are used or needed. Avoid DynamicImport-Package: *;
  - Dont forget that OSGi is dynamic environment where new bundles/services could (dis)appear any moment. Use BundleListener/BundleTracker to track bundles, ServiceListener/ServiceTracker (or better Declarative Services/Blueprint Services) to track services, avoid any hard links to services.

Unit tests and OSGi mocks. Unit tests should cover as much as possible of your functionality. Of course, it depends on your bundle design. If you detach your functionality from OSGi API you can easily test it. You can also develop simple OSGi specific tests with OSGi API mock classes that are provided by Spring OSGi project. You just need to add dependency to you POM file:

<dependency>
    <groupId>org.springframework.osgi</groupId>
    <artifactId>spring-osgi-mock</artifactId>
    <version>1.2.1</version>
    <scope>test</scope>
</dependency>

An example from MonitorAdmin implementation. I do not use OSGi BundleContext methods directly in cases when I try to find some services in OSGi registry. I added a simple interface OsgiVisitor with application-specific methods and implementation of the interface just calls BundleContext methods:

/**
 * MonitorAdmin implementation
 */
public class MonitorAdminImpl implements MonitorAdmin, MonitorListener, MonitoringJobVisitor {
    /**
    /**
     * Initialize MonitorAdmin implementation instance
     *
     * @param osgiVisitor osgi functionality visitor
     * @param logVisitor loggers visitor
     */
    public MonitorAdminImpl(OsgiVisitor osgiVisitor, LogVisitor logVisitor) {
        this.osgiVisitor = osgiVisitor;
        this.logVisitor = logVisitor;
    }
}

public interface OsgiVisitor {
    /**
     * Get Monitorable service by ServiceReference
     * @param reference ServiceReference
     * @return Monitorable service
     */
    Monitorable getService(ServiceReference reference);

    /**
     * Get list of Monitorable ServiceReference by monitorableId
     * @param monitorableId monitorable Id
     * @return Array of ServiceReferences or null
     */
    ServiceReference[] findMonitorableReferences(String monitorableId);

    /**
     * Post Event via EventAdmin
     * @param event event
     */
    void postEvent(Event event);
}

With such design I can create a mock of OsgiVisitor interface and test MonitorAdmin implementation with standard unit tests.
This is a sample unit test with OSGi mocks from MonitorAdmin implementation:

@Test
public void testGetMonitorableNames_MonitorableAvailable() throws Exception {
    MockOsgiVisitor osgiVisitor = new MockOsgiVisitor();
    HashMap<ServiceReference, Monitorable> map = new HashMap<ServiceReference, Monitorable>();
    map.put(new MonitorableMockServiceReference("com.acme.pid2"), new MockMonitorable());
    map.put(new MonitorableMockServiceReference("com.acme.pid3"), new MockMonitorable());
    map.put(new MonitorableMockServiceReference("com.acme.pid1"), new MockMonitorable());
    osgiVisitor.setReferences(map);

    MonitorAdmin monitorAdmin = new MonitorAdminImpl(osgiVisitor, new MockLogVisitor());

    String[] monitorableNames = monitorAdmin.getMonitorableNames();
    Assert.assertNotNull(monitorableNames);
    Assert.assertEquals(3, monitorableNames.length);
    Assert.assertEquals("com.acme.pid1", monitorableNames[0]);
    Assert.assertEquals("com.acme.pid2", monitorableNames[1]);
    Assert.assertEquals("com.acme.pid3", monitorableNames[2]);
}

Integration tests inside OSGi framework. Integration tests are very important because your OSGi bundle has been testing in real OSGi environment. Usually, integrations tests are placed in separate Maven module. Here is a sample POM for integration tests:

<project>
    <modelVersion>4.0.0</modelVersion>

    <groupId>org.osgilab.bundles</groupId>
    <artifactId>it</artifactId>
    <version>1.0-SNAPSHOT</version>

    <!-- dependencies -->
    <dependencies>
        <dependency>
            <groupId>org.osgi</groupId>
            <artifactId>org.osgi.core</artifactId>
            <version>4.2.0</version>
        </dependency>
        <dependency>
            <groupId>org.osgi</groupId>
            <artifactId>org.osgi.compendium</artifactId>
            <version>4.2.0</version>
        </dependency>
        <dependency>
            <groupId>org.osgilab.testing</groupId>
            <artifactId>commons</artifactId>
            <version>1.0.0</version>
        </dependency>
        <dependency>
            <groupId>junit</groupId>
            <artifactId>junit</artifactId>
            <version>4.8.1</version>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>org.ops4j.pax.exam</groupId>
            <artifactId>pax-exam</artifactId>
            <version>1.2.0</version>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>org.ops4j.pax.exam</groupId>
            <artifactId>pax-exam-junit</artifactId>
            <version>1.2.0</version>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>org.ops4j.pax.exam</groupId>
            <artifactId>pax-exam-container-default</artifactId>
            <version>1.2.0</version>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>org.osgilab.bundles</groupId>
            <artifactId>monitoradmin</artifactId>
            <version>1.0.2-SNAPSHOT</version>
            <scope>test</scope>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <!-- pax exam Maven plugin -->
            <plugin>
                <groupId>org.ops4j.pax.exam</groupId>
                <artifactId>maven-paxexam-plugin</artifactId>
                <version>1.2.0</version>
                <executions>
                    <execution>
                        <id>generate-config</id>
                        <goals>
                            <goal>generate-depends-file</goal>
                            <goal>generate-config</goal>
                        </goals>
                    </execution>
                </executions>
                <configuration>
                    <options>
                        <workingDirectory>${project.build.directory}/paxexam</workingDirectory>
                    </options>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>

To run JUnit tests inside OSGi framework I use Pax Exam testing tool. In the POM Pax Exam Maven plugin is configured.

The next step - create JUnit test.

@RunWith(JUnit4TestRunner.class) // -- [1] --
public class MonitorAdminTest {
    // OSGi framework test configutation
    @Configuration // -- [2] --
    public static Option[] configuration() {
        return options(
                // list of frameworks to test // -- [3] --
                frameworks(equinox(), felix(), knopflerfish().version("3.0.0")),
                // list of bundles that should be installed // -- [4] --
                provision(
                        mavenBundle().groupId("org.osgi").artifactId("org.osgi.compendium").version("4.1.0"),
                        mavenBundle().groupId("org.apache.felix").artifactId("org.apache.felix.eventadmin").version("1.2.2"),
                        mavenBundle().groupId("org.apache.felix").artifactId("org.apache.felix.log").version("1.0.0"),
                        // add OSGi assertions // -- [5] --
                        mavenBundle().groupId("org.osgilab.testing").artifactId("commons").version("1.0.0"),
                        // install module to test // -- [6] --
                        mavenBundle().groupId("org.osgilab.bundles").artifactId("monitoradmin").version("1.0.2-SNAPSHOT")
                )
        );
    }

    // injected BundleContext // -- [7] --
    @Inject
    private BundleContext bc;

    // initialize OSGi assertions // -- [8] --
    @Before
    public void initAsserts() {
        OSGiAssert.init(bc);
    }
}

[1] - use custom JUnit runner from Pax Exam
[2] - Configure OSGi framework for integration tests
[3] - define the list of OSGi frameworks for tests
[4] - define the list of bundles that should be installed during tests
[5] - add support of OSGi assertions
[6] - install the bundle with functionality you like to test
[7] - define BundleContext field to inject value during tests
[8] - initialize OSGi assertions

A test sample to show what and how you can test your functionality during integration tests:

@Test
public void testServices() throws BundleException {
    // assert MonitorAdmin Service
    ServiceAssert.assertServiceAvailable(MonitorAdmin.class);

    // assert MonitorListener Service
    ServiceAssert.assertServiceAvailable(MonitorListener.class);

    // get MonitorAdmin service
    MonitorAdmin monitorAdmin = ServiceUtils.getService(bc, MonitorAdmin.class);

    // get list of Monitorable names
    String[] monitorableNames = monitorAdmin.getMonitorableNames();
    Assert.assertNotNull(monitorableNames);
    Assert.assertEquals(0, monitorableNames.length);

    // get list of running Monitoring jobs
    MonitoringJob[] runningJobs = monitorAdmin.getRunningJobs();
    Assert.assertNotNull(runningJobs);
    Assert.assertEquals(0, runningJobs.length);

    // get bundle
    Bundle bundle = BundleUtils.findBundle(bc, "org.osgilab.bundles.monitoradmin");
    bundle.stop();

    // assert MonitorAdmin Service
    ServiceAssert.assertServiceUnavailable(MonitorAdmin.class);

    // assert MonitorListener Service
    ServiceAssert.assertServiceUnavailable(MonitorListener.class);
}

Provisioning and manual testing. If you like to do some manual tests for your OSGi bundle you can use Pax Runner to prepare and start OSGi framework with bundles to test.
The simplest way is to add additional Maven profile to your POM.

<profile>
    <!-- profile name -->
    <id>manual-test</id>
    <build>
        <!-- default profile goal -->
        <defaultGoal>pax:provision</defaultGoal>
        <plugins>
            <plugin>
                <!-- Pax Runner Maven plugin -->
                <groupId>org.ops4j</groupId>
                <artifactId>maven-pax-plugin</artifactId>
                <version>1.4</version>
                <configuration>
                    <!-- Pax Runner version -->
                    <runner>1.4.0</runner>
                    <!-- OSGi framework type (equinox, felix, knopflerfish) -->
                    <framework>equinox</framework>
                    <provision>
                        <param>--log=debug</param>
                        <param>--workingDirectory=target/runner</param>
                        <!-- bundles that should be installed -->
                        <param>mvn:org.osgi/org.osgi.compendium/4.1.0@2</param>
                        <param>mvn:org.apache.felix/org.apache.felix.eventadmin/1.2.2@3</param>
                        <param>mvn:org.apache.felix/org.apache.felix.log/1.0.0@3</param>
                        <param>mvn:org.osgilab.bundles/monitoradmin/1.0.2-SNAPSHOT@4</param>
                    </provision>
                </configuration>
            </plugin>
        </plugins>
    </build>
</profile>

Use Maven command to run this profile:

mvn -P manual-test

Alternative 1: If you like to share this OSGi framework configuration you can create a ZIP-package with such command:
```
mvn -P manual-test -Dexecutor=zip
```

Alternative 2: If you like to use custom OSGi framework configuration or version that is not supported by the last Pax Runner you can describe this configuration with Pax Runner platform configuration file (platform.xml):

<platform>
    <name>Equinox 3.5.2</name>
    <system>
        http://mirror.netcologne.de/eclipse/equinox/drops/R-3.5.2-201002111343/org.eclipse.osgi_3.5.2.R35x_v20100126.jar
    </system>
    <profile name="minimal" default="true">
        <bundle>
            <name>OSGi Services</name>
            <url>
                http://mirror.netcologne.de/eclipse/equinox/drops/R-3.5.2-201002111343/org.eclipse.osgi.services_3.2.0.v20090520-1800.jar
            </url>
        </bundle>
    </profile>
</platform>

To activate this platform configuration use Maven command:

mvn -P manual-test -DdefinitionURL=file:platform.xml

Release to Central Maven repository
You can release your OSGi module to Maven central repository with Sonatype Repository Hosting service

References:
1. OSGi specifications
2. OSGi API
3. Bnd tool - tool to help you diagnose and create OSGi bundles
4. maven-bundle-plugin - Maven plugin for Bnd tool
5. Spring OSGi - Blueprint Services RI and OSGi mocks project
6. Pax Exam - OSGi integration testing tool
7. Pax Runner - tool to provision OSGi bundles in all major open source OSGi framework implementations (Felix, Equinox, Knopflerfish, Concierge)
8. Sonatype Repository Service - Maven repositories that helps to synchronize artifacts with central Maven repository

That's all. Thank you.

OSGi Testing: OSGi Assertions and Utils for integraton and functional tests

2010-06-06T12:42:00.000+02:00

Hello everybody.

Testing of OSGi specific code is not so trivial task as standard JUnit test. You can test your OSGi code by 3 simple ways:

Decouple your functionality and OSGi API (like I implemented in MonitorAdmin RI). In this case, you can test your functionality with standard unit tests.
Use OSGi API mocks (provided by Spring OSGi project). In this case, all OSGi behavior could not be reproduced, but some simple OSGi tests could be implemented.
Test your code inside OSGi framework (provided by Pax Exam and Spring OSGi).

Implementation of your tests depends, of course, on your functionality, but some common patters are used:

check some bundle state;
check some bundle type (fragment or not)
check some service availability;
create service filters;
etc.

Standard JUnit API does not provide any OSGi-specific assertions and you have to test your functionality using low-level JUnit assertions. In this case, you have to implement a lot of low-level OSGi code to access your bundles or services and the test implementation looks very complex. Like this:

ServiceTracker packageAdminTracker = new ServiceTracker(bc, PackageAdmin.class.getName(), null);
packageAdminTracker.open();
PackageAdmin packageAdmin = (PackageAdmin) packageAdminTracker.getService();
Assert.assertNotNull(packageAdmin);
packageAdminTracker.close();
Bundle[] bundles = packageAdmin.getBundles("org.osgilab.testing.it.commons.test.bundle", null);
// asserts that test bundle is installed
Assert.assertNotNull(bundles);
Assert.assertTrue(bundles.length > 0);
// gets bundle instance
Bundle bundle = bundles[0];
// asserts that test bundle is resolved
Assert.assertEquals(Bundle.RESOLVED, bundle.getState());

To simplify OSGi tests I provide OSGi assertions and utilities library that could be easily integrated into Pax Exam and Spring OSGi tests. There are classes (assertions and utilities) that help you to write more clean and understandable OSGi tests and concentrate more on your functionality.

The code from above can be easily replaced with OSGi assertions:

// asserts that test bundle is installed
assertBundleAvailable("org.osgilab.testing.it.commons.test.bundle");
// asserts that test bundle is resolved
assertBundleState(Bundle.RESOLVED, "org.osgilab.testing.it.commons.test.bundle");
// gets bundle instance
Bundle bundle = findBundle(bc, "org.osgilab.testing.it.commons.test.bundle");

You can find comparison of "standard" OSGi test and test with OSGi assertions below:

@Test
public void test_Without_OSGiAssertions() throws BundleException, InterruptedException, InvalidSyntaxException {
ServiceTracker packageAdminTracker = new ServiceTracker(bc, PackageAdmin.class.getName(), null);
packageAdminTracker.open();
PackageAdmin packageAdmin = (PackageAdmin) packageAdminTracker.getService();
Assert.assertNotNull(packageAdmin);
packageAdminTracker.close();
Bundle[] bundles = packageAdmin.getBundles("org.osgilab.testing.it.commons.test.bundle", null);
// asserts that test bundle is installed
Assert.assertNotNull(bundles);
Assert.assertTrue(bundles.length > 0);
// gets bundle instance
Bundle bundle = bundles[0];
// asserts that test bundle is resolved
Assert.assertEquals(Bundle.RESOLVED, bundle.getState());
ServiceTracker serviceTracker1 = new ServiceTracker(bc, "org.osgi.testing.it.commons.testbundle.service.Echo", null);
serviceTracker1.open();
Assert.assertEquals(0, serviceTracker1.size());
// start bundle
bundle.start();
// asserts that test bundle is active
Assert.assertEquals(Bundle.ACTIVE, bundle.getState());
// asserts that test service is available within 2 seconds
Assert.assertNotNull(serviceTracker1.waitForService(2000));
// asserts that test service with custom properties is available
ServiceTracker serviceTracker2 = new ServiceTracker(bc, FrameworkUtil.createFilter(
                "(&(" + Constants.OBJECTCLASS + "=org.osgi.testing.it.commons.testbundle.service.Echo)" +
                        "(testkey=testvalue))"), null);
serviceTracker2.open();
Assert.assertTrue(serviceTracker2.size() > 0);
// gets service by class and filter
Echo echo = (Echo) serviceTracker2.getService();
// asserts service method call
Assert.assertEquals("test", echo.echo("test"));
// stops bundle
bundle.stop();
// asserts that test bundle is resolved
Assert.assertEquals(Bundle.RESOLVED, bundle.getState());
// asserts that test service is unregistered
Assert.assertEquals(0, serviceTracker1.size());
}

@Test
public void test_With_OSGiAssertions() throws BundleException, InvalidSyntaxException {
// asserts that test bundle is installed
assertBundleAvailable("org.osgilab.testing.it.commons.test.bundle");
// asserts that test bundle is resolved
assertBundleState(Bundle.RESOLVED, "org.osgilab.testing.it.commons.test.bundle");
// gets bundle instance
Bundle bundle = findBundle(bc, "org.osgilab.testing.it.commons.test.bundle");
// asserts that test service is unavailable
assertServiceUnavailable("org.osgi.testing.it.commons.testbundle.service.Echo");
// start bundle
bundle.start();
// asserts that test bundle is active
assertBundleState(Bundle.ACTIVE, "org.osgilab.testing.it.commons.test.bundle");
// asserts that test service is available within 2 seconds
assertServiceAvailable("org.osgi.testing.it.commons.testbundle.service.Echo", 2, TimeUnit.SECONDS);
// asserts that test service with custom properties is available
assertServiceAvailable(and(create(Echo.class), eq("testkey", "testvalue")));
// gets service by class and filter
Echo echo = ServiceUtils.getService(bc, Echo.class, eq("testkey", "testvalue"));
// asserts service method call
Assert.assertEquals("test", echo.echo("test"));
// stops bundle
bundle.stop();
// asserts that test bundle is resolved
assertBundleState(Bundle.RESOLVED, "org.osgilab.testing.it.commons.test.bundle");
// asserts that test service is unregistered
assertServiceUnavailable(Echo.class);
}

Thank you for your attention. Your feedback is welcome as usual.

Best Regards.

OSGi 4.3 Core Early Draft 1 is available

2010-05-07T23:43:00.002+02:00

Hello,

yesterday OSGi Service Platform Release 4 Core Version 4.3 Early Draft 1 was published on OSGi Alliance site. Here the list of new RFCs that are included into this draft version:

RFC-0138 - Multiple Frameworks in one JVM
RFC-0151 - Framework Update. Changed in OSGi API to take advantage of Java 5 generics language feature etc.
RFC-0154 - Generic Capabilities & Requirements

OSGi Service Platform Release 4 Residential Version 4.2 Early Draft 3 is also available. RFCs that are included into:

RFC-0140 - Residential Management Tree
RFC-0141 - DTM Admin Extension
RFC-0144 - Configuration Admin Extension
RFC-0145 - Home Gateway Administration
RFC-0149 - TR-069 Protocol Implementation Guideline

Best Regards

OSGi universal shell implementation

2010-05-06T18:14:00.001+02:00

Hello OSGi-people,

everybody, who provides their bundles and components for various OSGi frameworks with shell commands, wants to implement shell commands with some universal API, that will be supported by all frameworks. Such API (RFC132) was a part of OSGi 4.2 Early Draft specification, but it was not included by some reasons into the release.

Today the most popular OSGi frameworks (Eclipse Equinox, Apache Felix and Knopflerfish) provide their own shell API to add new commands. Bundle developer should import framework specific packages and add new shell commands using framework specific API. It's not so easy to maintain if multiple versions of the same API should be supported (e.g. Knopflerfish Console API 2.0.1 (Knopflerfish 2.x.x) and 2.1.0 (Knopflerfish 3.0.x)).

My idea is very simple:

provide the way to add a new shell command without any third-party or framework specific API dependencies;
support of various OSGi frameworks is out of bundle developer tasks list;
command definition should be very simple;
support of command groups.

There are two simple steps that should be done by bundle developer to add a new shell command:

Add commands definitions to class. Every command is defined as public method with such signature:
```
public void <command_name>(java.io.PrintWriter out, java.lang.String[] args);
```

out - command output stream
args - command arguments list

service property "org.osgilab.tips.shell.group.id" (mandatory, java.lang.String) - unique commands group id. Used by some framework specific shell API that support command groups;
service property "org.osgilab.tips.shell.group.name" (mandatory, java.lang.String) - commands group name. Used by some framework specific shell API that support command groups;
service property "org.osgilab.tips.shell.commands" (mandatory, java.lang.String[][]) - commands definition "command_name" -> "command_help";
service object class - could be used any value. It's very useful when commands are included into interface implementation.

Here is a sample of new commands:

Commands implementation

public class ShellTestService {
................
    public void bndinfo(PrintWriter out, String... args) {
        if (args == null || args.length != 1) {
            out.println("Bundle id argument is missed");
            return;
        }
        try {
            int bundleId = Integer.parseInt(args[0]);
            Bundle bundle = bc.getBundle(bundleId);
            if (bundle == null) {
                out.println("Bundle id is invalid: " + bundleId);
                return;
            }
            printBundleInfo(bundle, out);
        } catch (NumberFormatException e) {
            out.println("Bundle id has wrong format: " + args[0]);
        }
    }

    public void bndsinfo(PrintWriter out, String... args) {
        Bundle[] bundles = bc.getBundles();
        for (Bundle bundle : bundles) {
            printBundleInfo(bundle, out);
        }
    }
......................
}

Command service registration.

ShellTestService shellTestService = ....;
Dictionary<String, Object> props = new Hashtable<String, Object>();
props.put("org.osgilab.tips.shell.group.id", "test_group_id");
props.put("org.osgilab.tips.shell.group.name", "Test commands");
String[][] commandsArray = new String[2][2];
commandsArray[0] = new String[]{"bndinfo", "bndinfo <bundleId> - Print information for bundle with <bundleId>"};
commandsArray[1] = new String[]{"bndsinfo", "bndsinfo - Print information for all bundles"};
props.put("org.osgilab.tips.shell.commands", commandsArray);
bc.registerService(ShellTestService.class.getName(), shellTestService, props);

There are 3 OSGi frameworks supported: Eclipse Equinox, Apache Felix and Knopflerfish.
Bundles are available in Central Maven Repository:

<dependency>
    <groupId>org.osgilab.bundles.shell</groupId>
    <artifactId>equinox</artifactId>
    <version>1.0.0</version>
</dependency>
<dependency>
    <groupId>org.osgilab.bundles.shell</groupId>
    <artifactId>felix</artifactId>
    <version>1.0.0</version>
</dependency>
<dependency>
    <groupId>org.osgilab.bundles.shell</groupId>
    <artifactId>knopflerfish</artifactId>
    <version>1.0.0</version>
</dependency>

or from project downloads page.

Thank you.

Pax Runner and Exam: new OSGi framework support

2010-05-05T20:49:00.001+02:00

Hello,

There are many people that use Pax Runner and Pax Exam as main OSGi development tools for integration and manual testing of their bundles and configurations. The last released versions of Pax tools do not support the last snapshot versions of popular OSGi frameworks (e.g. Eclipse Equinox 3.6M7, Apache Felix 2.0.5, Knopflerfish 3.0.0.beta-4). There is a simple way to add such support. Pax Runner provides very flexible configuration for Platform-Extender module. Any custom OSGi platform could be described with platform definition XML file and could be used for testing.

To set a new platform definition for Pax Runner Maven configuration use such configuration:

<plugin>
    <groupId>org.ops4j</groupId>
    <artifactId>maven-pax-plugin</artifactId>
    <version>1.4</version>
    </executions>
    <configuration>
        <runner>1.4.0</runner>
        <framework>equinox</framework>
        <provision>
            .............
            <param>--definitionURL=file:platform-equinox-3.6M7.xml</param>
            .............
        </provision>
    </configuration>
</plugin>

To set a new platform definition for Pax Exam use such configuration:

public class PaxExamTest {
   .......................
   @Configuration
    public static Option[] configurePlatform() {
        return options(
                equinox(),
                rawPaxRunnerOption("--definitionURL", "file:platform-equinox-3.6M7.xml")
        );
    }
   .......................
}

There is a sample of Eclipse Equinox 3.6M7 platform definition file.

<platform>
    <!-- Platform name -->
    <name>Eclipse Equinox 3.6M7</name>
    <!-- URL to system bundle -->
    <system>http://mirror.netcologne.de/eclipse//equinox/drops/S-3.6M7-201004291549/org.eclipse.osgi_3.6.0.v20100422-1745.jar</system>

    <!-- List of bundles -->
    <profile name="minimal" default="true">
        <bundle>
            <name>OSGi Services</name>
            <url>http://mirror.netcologne.de/eclipse//equinox/drops/S-3.6M7-201004291549/org.eclipse.osgi.services_3.2.100.v20100108.jar</url>
        </bundle>
        <bundle>
            <name>Equinox Util</name>
            <url>http://mirror.netcologne.de/eclipse//equinox/drops/S-3.6M7-201004291549/org.eclipse.equinox.util_1.0.100.v20090520-1800.jar</url>
        </bundle>
        <bundle>
            <name>Equinox Common</name>
            <url>http://mirror.netcologne.de/eclipse//equinox/drops/S-3.6M7-201004291549/org.eclipse.equinox.common_3.6.0.v20100315.jar</url>
        </bundle>
    </profile>
</platform>

Regards.

OSGi MonitorAdmin and JMX bundles minor update

2010-04-27T17:20:00.001+02:00

Hello,

There are some minor updates available:

OSGi MonitorAdmin 1.0.1 version is available. Changes:

recompile with J2SE5
use OSGi specification 4.1.0 dependencies

OSGi JMX Management Model 1.0.1 version is available. Changes:

fix NoClassDefFoundException for Compendium service
fix NPEs

Artifacts are available in Central Maven repository:

<dependency>
     <groupId>org.osgilab.bundles</groupId>
     <artifactId>monitoradmin</artifactId>
     <version>1.0.1</version>
</dependency>
<dependency>
     <groupId>org.osgilab.bundles</groupId>
     <artifactId>jmx</artifactId>
     <version>1.0.1</version>
</dependency>

Your feedback is welcome.

JMX Management Model Implementation: Release 1.0.0

2010-04-19T06:00:00.001+02:00

Hello Everybody.

I'd like to inform you that I've released yesterday the first version of OSGi Enterprise JMX Management Model Implementation version 1.0.0.

All details are available on project site.

Have a nice day.

MonitorAdmin Implementation: Release 1.0.0

2010-04-09T16:38:00.001+02:00

Hello Everybody.

I'd like to inform you that I've released today the first version of OSGi MonitorAdmin Implementation version 1.0.0.

All details are available on project site.

Have a nice day.

OSGi Tips&Tricks: Logging. JUL to OSGi. Forward java.util.logging to OSGi logs

2010-03-24T19:08:00.001+01:00

Hello everybody,

There is another small tip regarding OSGi logging - how to forward log records from java.util.logging (JUL) to OSGi LogService.
Steps that you have to do:

Register java.util.logging.Handler implementation to handle LogRecords
Get org.osgi.service.log.LogService from OSGi registry
Implement Handler method public void publish(LogRecord record) to forward Java LogRecord to OSGi LogService.

I've added some customization to this very simple flow.

You can enable/disable buffer for published LogRecords when LogService is not available in the OSGi registry. A system property "org.osgilab.tips.logs.jul2osgi.bufferSize" should be used to activate buffer functionality. Available values:

1 < value < Integer.MAX_VALUE - buffer is enabled with defined size
value <= 0 - buffer is disabled

You can filter LogRecords by Log Level with a system property "org.osgilab.tips.logs.jul2osgi.logsLevel". Available values are the same as levels defined in JUL API. Default level is Level.ALL
You can filter LogRecords by logger names with a system property "org.osgilab.tips.logs.jul2osgi.loggerNames". Logger names should be listed with ';' separator (e.g. "org.osgilab.tips.logs.jul2osgi.loggerNames=logger1;com.acme.logger2;com.foo.logger3"). Root logger is used by default.

See my reference implementation here.

Have a nice day!

OSGi Tips&Tricks: Logging. OSGi to JUL. Forward OSGi logs to java.util.logging

2010-03-12T08:11:00.002+01:00

Morning everybody,

There is a small tip - how to forward log entries from OSGi LogService to java.util.logging (JUL).
Steps that you have to do:

Get org.osgi.service.log.LogReaderService from OSGi registry
Add your implementation of org.osgi.service.log.LogListener interface to LogReaderService
Initialize/get Java util Logger instance
Implement LogListener method public void logged(LogEntry) to map OSGi LogEntry instance to Java LogRecord and publish it with Logger.

public void logged(LogEntry logEntry) {
    LOG.log(mapLogEntry(logEntry));
}

You can configure name on Java Logger with system property "org.osgilab.tips.logs.osgi2jul.loggerName" with my reference implementation.

Have a nice day!

OSGi Tips&Tricks: OSGi profiling (YourKit, VisualVM, JProfiler, JProbe) and NoClassDefFoundError

2010-03-07T11:26:00.001+01:00

Hello OSGi-people,

There are some OSGi profiling configuration tricks to avoid NoClassDefFoundError on bundles start. I've tested four Java Profiler tools and prepared configuration settings for them.

YourKit (http://www.yourkit.com/) v.8.0.x

-agentpath:${yourkit.root.folder}\bin\win32\yjpagent.dll -Dorg.osgi.framework.bootdelegation=com.yourkit.*

Sun VisualVM (https://visualvm.dev.java.net/) v.1.2.2

-Xbootclasspath:${visualvm.root.folder}\profiler3\lib\jfluid-server.jar -Dorg.osgi.framework.bootdelegation=org.netbeans.lib.profiler.*

JProfiler (http://www.ej-technologies.com/products/jprofiler/overview.html) v.6.0.x

-agentpath:${jprofiler.root.folder}\bin\windows\jprofilerti.dll -Xbootclasspath/a:${jprofiler.root.folder}\bin\agent.jar -Dorg.osgi.framework.bootdelegation=com.jprofiler.*

JProbe (http://www.quest.com/jprobe/) v.8.3

-agentpath:${jprobe.root.folder}\bin\ia32\jprobe.dll=${profile.jpl.file} -Dorg.osgi.framework.bootdelegation=com.jprobe.*

Here you can find Apache Maven POM file with profiles for OSGi frameworks (Eclipse Equinox, Apache Felix and Knopflerfish) and Java Profile Tools configurations.

E.g. run this command to run Equinox Framework with YourKit Profiler configuration:

mvn -f profile.xml -P equinox,yourkit

Update 2011/10/01: The last tests with YourKit Profiler 10.0 with OSGi + Declarative Services still require -Dorg.osgi.framework.bootdelegation=com.yourkit.* settings.

Have a nice OSGi profiling!

MonitorAdmin Implementation (Preparing steps)

2009-12-16T19:51:00.002+01:00

Hello OSGi-People!

As the first experiment, I'd like to implement OSGi MonitorAdmin Service (r4.cmpn.pdf, Chapter 119).

There is a list of development iterations that I've prepared:

Maintenance iteration. Create Maven project structure with modules and settings.
"Getters" iteration. Implementation of MonitorAdmin get-methods (e.g., getMonitorableNames() etc.). Cover functionality with unit tests with mocks and integration tests for various OSGi frameworks.
"Jobs" iteration. Implementation of MonitorAdmin jobs-related methods (e.g., startJob(), switchEvents() etc.) and related interfaces: MonitorListener and MonitoringJob. All new functionality should be covered with unit and integration tests.
"Security" iteration. Add support of MonitorPermission with unit and integration tests.
"Maven release" iteration. The last iteration to release artifact and make it available through maven repository.

I'll try to explain all development nuances in every iteration-related post.

Let's get started! Your comments are welcome.

Tools box or project receipt ingredients

2009-11-19T10:48:00.000+01:00

Hello,

Today I'd like to list the tools, utils and libraries I use for OSGi Lab projects. These ingredients are indispensable pieces of the project.

Foundation. I use Google code service for the project. It provides almost everything I need: version control - Subversion, embedded issue tracker, embedded wiki engine, downloads page. One thing that I missed is build server. I'll try to find one somewhere. Before that I'll use my own PC for nightly builds.
Main ingredient. I'll base project structure on Apache Maven. This structure is very popular in open source projects and I like to follow it. Except common Maven plug-ins I'll use OSGi specific plug-in to generate bundle manifest - Maven Bundle Plug-in. This plug-in is based on very popular OSGi tool BND from Peter Kriens. It helps to create bundle jars, create and validate manifest files, resolve bundle class-path dependencies etc.
Main tool. As the project structure is based on Maven we can use any editor for sources, even vi. I suggest to select one from high-end Java IDEs: Eclipse, JetBrains IDEA Community Edition or NetBeans. I personally like IDEA, but I don't like to start any "IDE holy wars". I think that all three IDE cover all project requirements, it's just a matter of habit.
Testing tools. To provide upscale and reliable code it should be covered with tests. During OSGi bundle development we have 2 types of tests: OSGi specific (or integration tests) and non-OSGi specific (e.g. unit tests). For unit tests I'll use JUnit and for integration tests (inside OSGi framework) I'll use JUnit with Pax Exam - OSGi test framework.
Spices. Additional useful tools and libraries: Mockito - mocking framework and Pax Runner - OSGi bundles provisioning tool

So, let's start to cook!

Welcome

2009-11-16T12:52:00.000+01:00

Hello OSGi-people. Welcome to my blog where I'd like to share some OSGi experience from my previous and current projects.
For the last few years OSGi technology gets more and more popular. There are many components and tools that are based on OSGi frameworks like Eclipse IDE or JEE servers. The last version of OSGi specification brought many new APIs, but only few of them have reference implementations.
I'd like to develop some of APIs that, I think, will be helpfull for you, OSGi-community. I'll describe all developement steps and tools I use and share sources here OSGi Lab project.

This is non-profit blog and project. "OSGi" trademark belongs to OSGi Alliance.

Your comments and ideas are welcome.