OSGi Helpers

The OSGi Helper project is a pretty simple library providing useful methods for OSGi integration-tests. The goal is to help the writing of OSGi tests by avoiding the burden of the regular OSGi API. For example, instead of always relying on the bundle context to get a service, the OSGi helper provides a ‘getServiceObject’ method.

The OSGi helper library does not only contain OSGi specific method, but also support iPOJO and provides an extensible mechanism to add others helpers.

Using the OSGi Helper Library with OPS4J Pax Exam

First, you need to add the OSGi helper library in your class path. For Maven, it looks like:

<dependency>
<groupId>org.ow2.chameleon.testing</groupId>
<artifactId>osgi-helpers</artifactId>
<version>0.4.0</version>
</dependency>

So, your test class should contain something like:

@Inject
private BundleContext context;
private OSGiHelper osgi;
private IPOJOHelper ipojo;
@Configuration
public static Option[] configure() throws Exception {
        Option[] opt = CoreOptions.options(
            CoreOptions.felix(),
            CoreOptions.provision(                       
              CoreOptions.mavenBundle()
                 .groupId("org.apache.felix")
                .artifactId("org.apache.felix.ipojo")
                .versionAsInProject(),
              CoreOptions.mavenBundle()
               .groupId("org.ow2.chameleon.testing")
               .artifactId("osgi-helpers")
               .versionAsInProject()
             // …
      )
       );
        return opt;
    }
    @Before
    public void setup() {
        osgi = new OSGiHelper(context);
        ipojo = new IPOJOHelper(context);
    }
    @After
    public void tearDown() {
        osgi.dispose();
        ipojo.dispose();
    }

@Test
    public void testMemWriter() throws Exception {
        // Create the instance
        Properties props = new Properties();
        props.put(FeedWriter.FEED_TITLE_PROPERTY, "a feed");
        ipojo
           .createComponentInstance(
              "org.ow2.chameleon.syndication.rome.memwriter", 
               props);
        osgi.waitForService(FeedWriter.class.getName(), null, 5000);
        
        ServiceReference ref = osgi
              .getServiceReference(FeedReader.class.getName());
        // ...
        FeedWriter writer = (FeedWriter) osgi
              .getServiceObject(FeedWriter.class.getName(), null);
       //…
    }

Available methods

The 0.4.0 version has introduced generic methods using Class objects.

OSGi helper

• boolean isServiceAvailable(String itf): checks if a service is available
• boolean isServiceAvailableByPID(String itf, String pid): checks is a service provider providing itf and having the pid service pid is available
• Object getServiceObject(String itf, String filter): gets a service object (or null if not found) based on the given interface and filter (can be null)
• Object getServiceObject(ServiceReference ref): gets the service object attached to the given service reference
• Object[] getServiceObjects(String itf, String filter): gets the service objects matching the request (filter can be null). An empty array is returned if no services match.
• ServiceReference getServiceReference(String itf, String filter): gets the service reference matching the request (filter can be null)
• ServiceReference getServiceReference(String itf): gets a service reference providing the given interface or null if not found
• ServiceReference getServiceReferenceByPID(String itf, String pid): gets a service reference providing the given interface and having the specified service.pid or null if not found
• ServiceReference[] getServiceReferences(String itf, String filter): gets the service references matching the request (filter can be null). An empty array is returned if no services match.
• PackageAdmin getPackageAdmin(): gets the package admin service
• refresh() : refresh the framework
• void waitForService(String itf, String filter, long timeout): wait for a service. This method blocks until the service become available. If the given timeout is reached, the test fails.
• Bundle installBundle(String url): installs the given bundle, fails on error.
• Bundle installBundle(String url, InputStream stream): installs the given bundle from the given input stream, fails on error.
• Bundle installAndStart(String url): installs the bundle and starts it, fails on error
• Bundle installAndStart(String url, InputStream stream): installs the given bundle from the given input stream then starts it, fails on error.
• Bundle getBundle(long bundleId): gets the bundle with the given id (null if not found).
• Bundle getBundle(String name): gets the bundle with the given symbolic name (null if not found).

iPOJO Helper

• ComponentInstance getInstanceByName(String name): gets a component instance by its name (null if not found)
• ComponentInstance createComponentInstance(String factoryName, String instanceName): creates a component instance from the specified factory. The instance name is set to the given name
• ComponentInstance createComponentInstance(String factoryName, Dictionary configuration): creates a component instance from the given factory with the given configuration
• ComponentInstance createComponentInstance(String factoryName): creates an ‘unamed’ component instance from the given factory
• ComponentInstance createComponentInstance(String factoryName, String instanceName, Dictionary configuration): creates a component instance from the given factory with the given name and the given configuration
• Factory getFactory(String factoryName): gets the specified factory, null if nto found
• HandlerFactory getHandlerFactory(String factoryName): gets the specified handler factory
• static Element getMetadata(Bundle bundle, String component): gets the metadata of a component specified in the given bundle
• static Element[] getInstanceMetadata(Bundle bundle, String component): gets the metadata of the instances specified in the given bundle. Component depicts the component type name of the instance (‘component’ attribute)
• ServiceReference getServiceReferenceByName(String itf, String name) : gets a service reference provided by the instance named ‘name’
• isServiceAvailableByName(String itf, String name) : checks a a service ‘itf’ is exposed by an instance named ‘name’

OSGi Assertions