SPI Fly

+

SPI Fly

This page describes the SPI Fly component. The SPI Fly component is aimed at providing general support for the JRE SPI mechanism, including the usage of java.util.ServiceLoader, META-INF/services and similar methods in OSGi.

-

The Problem

+

The Problem

java.util.ServiceLoader.load() and other similar methods such as sun.misc.Service.providers(), but also other static finder methods such as the FactoryFinder.find() methods try to locate 'service' implementations by looking for @@ -271,7 +284,7 @@ resources in the META-INF/services direc

The SPI Fly project makes it possible to use existing code that uses ServiceLoader.load() and similar mechanisms under OSGi.

-

Making it Work

+

Making it Work

In order to make the ServiceLoader approach work under OSGi, calling code can be woven to set the TCCL to the appropriate providers very briefly, only for the duration of the call. The SPI Fly component does precisely this.

@@ -314,12 +327,12 @@ For more information, see RFC 167 in the http://www.osgi.org/download/osgi-early-draft-2011-09.pdf

The code can be found in http://svn.apache.org/repos/asf/aries/trunk/spi-fly.

-

How to use

+

How to use

There are currently two ways to use the SPI Fly component. If you have an OSGi 4.3 compliant framework that supports WeavingHooks you can use the dynamic weaving approach.

If you have an pre-4.3 OSGi framework or don't want to use bytecode weaving at runtime you can use the static weaving approach.

-

Use with Dynamic Weaving

+

Use with Dynamic Weaving

Install and start the org.apache.aries.spifly.dynamic.bundle into the system. This bundle has a dependency on org.objectweb.asm version 3.2 or newer and on the Aries Util bundle.

@@ -336,12 +349,12 @@ id State Bundle bundle (org.apache.aries.spifly.dynamic.bundle in the SPI Fly case) needs to be active before any bundles that need to be dynamically woven. OSGi Start Levels can provide a mechanism to control this.

-

Use with Static Weaving

+

Use with Static Weaving

For static use, you need to weave the client bundle before installing it into the system. The modification changes the byte code around java.util.ServiceLoader.load() calls in the bundle and inserts calls to set the correct ThreadContextClassLoader around it. Provider bundles are still handled dynamically.

-

To statically weave a bundle

+

To statically weave a bundle

The easiest way to invoke the static weaver is to take the org.apache.aries.spifly.static.tool jar with dependencies. This jar can be created by running mvn assembly:single in this maven module.

Then run the static tool on any bundle that needs processing: @@ -360,6 +373,18 @@ id State Bundle 2 ACTIVE org.apache.aries.util_0.5.0.SNAPSHOT 3 ACTIVE org.apache.aries.spifly.static.bundle_0.4.0.SNAPSHOT

Then install and start the statically woven bundle into the system.

+

Special Cases

+

SPI Fly can be used for most SPI provider/lookup systems that use the TCCL pattern to obtain +implementations. However, some cases some special treatment is needed. This section +lists the known cases.

+

javax.imageio.spi.ServiceRegistry: This class is very much like +java.util.ServiceLoader in that it can load any kind of API implementation. +While SPI Fly knows about ServiceLoader and treats it specially, the ServiceRegistry +class currently does not have special treatment. It can still be made to work +but this requires the following header in the provider bundle: +SPI-Provider: javax.imageio.spi.ServiceRegistry

Examples

The spi-fly-examples directory contains a number of example bundles that can be used for testing or experimenting.