You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@aries.apache.org by bu...@apache.org on 2012/08/29 11:44:22 UTC
svn commit: r830436 - in /websites/staging/aries/trunk/content: ./
modules/spi-fly.html
Author: buildbot
Date: Wed Aug 29 09:44:22 2012
New Revision: 830436
Log:
Staging update by buildbot for aries
Modified:
websites/staging/aries/trunk/content/ (props changed)
websites/staging/aries/trunk/content/modules/spi-fly.html
Propchange: websites/staging/aries/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Wed Aug 29 09:44:22 2012
@@ -1 +1 @@
-1364951
+1378489
Modified: websites/staging/aries/trunk/content/modules/spi-fly.html
==============================================================================
--- websites/staging/aries/trunk/content/modules/spi-fly.html (original)
+++ websites/staging/aries/trunk/content/modules/spi-fly.html Wed Aug 29 09:44:22 2012
@@ -271,6 +271,8 @@
The SPI Fly component is aimed at providing general support for the JRE SPI
mechanism, including the usage of <tt>java.util.ServiceLoader</tt>,
<tt>META-INF/services</tt> and similar methods in OSGi.</p>
+<p>SPI Fly is the Reference Implementation of the OSGi ServiceLoader Mediator specification, chapter 133 in the <a href="http://www.osgi.org/Download/Release5" title="OSGi Enterprise Specification">OSGi
+Enterprise Specification</a>, available from version 5.</p>
<h2 id="the-problem">The Problem</h2>
<p><tt>java.util.ServiceLoader.load()</tt> and other similar methods such as
<tt>sun.misc.Service.providers()</tt>, but also other static finder methods such as the
@@ -291,7 +293,59 @@ resources in the META-INF/services direc
<p>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.</p>
-<h3 id="providers">Providers</h3>
+<p>SPI Fly supports two modes of operation:</p>
+<ul>
+<li>OSGi Specification compliant configuration. This is based on OSGi generic requirements and capabilities and
+provides portability across implementations of this specification, but only covers <tt>java.util.ServiceLoader</tt>. <a href="#specconf">Find it here</a>.</li>
+<li>If you need to handle cases other than <tt>java.util.ServiceLoader</tt>, such as the various FactoryFinders,
+<tt>javax.imageio.spi.ServiceRegistry</tt>, <tt>javax.sound.sampled.AudioSystem</tt> or others that use the TCCL
+to find an implementation, you can use the <a href="#specificconf">SPI Fly-specific configuration</a>.</li>
+</ul>
+<p>Additionally, services found in the META-INF/services location in opted-in bundles will be registered in the OSGi Service
+Registry so that OSGi-aware consumers can simply find them there.</p>
+<h2 id="getting-spi-fly">Getting SPI Fly</h2>
+<h3 id="releases">Releases</h3>
+<p>There are no releases of SPI-Fly at this point in time, but when
+once released releases will be available from Maven Central.</p>
+<h3 id="building-the-code">Building the code</h3>
+<p>The code can be found in
+<a href="http://svn.apache.org/repos/asf/aries/trunk/spi-fly">http://svn.apache.org/repos/asf/aries/trunk/spi-fly</a>.</p>
+<p>To build, use Maven 3.x and run 'mvn install'</p>
+<h1 id="wzxhzdk13configuration-osgi-spec-compliant"><a id="specconf"/>Configuration: OSGi Spec-compliant</h1>
+<p>All the details surrounding this type of configuration are covered in the
+<a href="http://www.osgi.org/Download/Release5" title="OSGi Enterprise Specification">OSGi Enterprise Specification</a> (from version 5) chapter 133. This section provides a short overview.</p>
+<h2 id="providers">Providers</h2>
+<p>SPI provider bundles opt in to being processed by specifying a requirement on the
+<tt>osgi.serviceloader.registrar</tt> extender. This is done by adding the following Bundle Manifest header. Without this they will not be considered by SPI Fly:</p>
+<p><tt> Require-Capability: osgi.extender; filter:="(osgi.extender=osgi.serviceloader.registrar)"</tt></p>
+<p>Additionally, they need to provide capabilities for all the APIs that are exposed through this mechanism, for example:</p>
+<p><tt> Provide-Capability: osgi.serviceloader; osgi.serviceloader=org.apache.aries.spifly.mysvc.MySPIProvider</tt></p>
+<p>While this example omits it, it is advisable to use <tt>uses</tt> constraints on the Provide-Capability header, to
+ensure consistent class spaces.</p>
+<p>See the <tt>spi-fly-example-provider2-bundle</tt> for an example of a spec-compliant provider.</p>
+<h2 id="consumers">Consumers</h2>
+<p>A SPI consumer (i.e. a bundle using the <tt>java.util.ServiceLoader.load()</tt> API) needs to specify required capabilities
+in the Required-Capability Manifest header. Two different types of requirements must be specified:</p>
+<ul>
+<li>A requirement on the SPI Fly mechanism. This is stated as follows<br/>
+<tt> osgi.extender; filter:="(osgi.extender=osgi.serviceloader.processor)"</tt><br/>
+without this requirement the bundle will not be considered for processing.</li>
+<li>A requirement on the SPI that needs to be provided through this mechanism, for example<br/>
+<tt> osgi.serviceloader; filter:="(osgi.serviceloader=org.apache.aries.spifly.mysvc.MySPIProvider)";cardinality:=multiple</tt><br/>
+Note that the <tt>cardinality</tt> directive is specified to allow multiple bundles to provide the requested capability, allowing
+provided services to come from more than one provider bundle. However at this time of writing some OSGi frameworks ignore
+the cardinality directive.</li>
+</ul>
+<p>All requirements are combined into a single Require-Capability header:</p>
+<p><tt> Require-Capability: osgi.serviceloader; filter:="(osgi.serviceloader=org.apache.aries.spifly.mysvc.MySPIProvider)";cardinality:=multiple,osgi.extender; filter:="(osgi.extender=osgi.serviceloader.processor)"</tt></p>
+<p>See the <tt>spi-fly-example-client2-bundle</tt> for an example of a spec-compliant consumer.</p>
+<h1 id="wzxhzdk36configuration-spi-fly-specific"><a id="specificconf"/>Configuration: SPI Fly-specific</h1>
+<p>This section describes how to use SPI Fly's proprietary configuration
+mechanism. It provides more features, but doesn't provide the
+portability that spec-compliance configuration gives. If you
+are only using SPI Fly with java.util.ServiceLoader then consider
+using the <a href="#specconf">spec-compliant</a> configuration for portability.</p>
+<h2 id="providers_1">Providers</h2>
<p>First for all, SPI Fly needs to be made aware of any bundles that provide the services.
These bundles are made visible through the TCCL for the duration of the <tt>ServiceLoader.load()</tt>
(or similar) call.</p>
@@ -308,7 +362,7 @@ property.</p>
<p>The <tt>SPI-Provider</tt> header can either be set in the providing bundle itself or in a wrapper bundle
that holds the original unmodified jar containing the provider internally as a
on the <tt>Bundle-ClassPath</tt>.</p>
-<h3 id="consumers">Consumers</h3>
+<h2 id="consumers_1">Consumers</h2>
<p>Service consumers also need to opt-in to the process. </p>
<p>To specify a consumer, add the <tt>SPI-Consumer</tt> manifest header to the client bundle. This header
will opt-in the bundle to the weaving process where for the duration of the specified call
@@ -325,12 +379,29 @@ call <tt>DocumentBuilderFactory.newInsta
<li><strong>org.foo.Foo#someMthd(),org.bar.Bar#myMethod()</strong> weave calls to <tt>Foo.someMthd()</tt> and
<tt>Bar.myMethod()</tt>. </li>
</ul>
-<p>There are currently standardization efforts ongoing in the OSGi Alliance for which the SPI Fly project is the Reference Implementation.
-For more information, see RFC 167 in the OSGi Enterprise 5 EA draft:
-<a href="http://www.osgi.org/download/osgi-early-draft-2011-09.pdf">http://www.osgi.org/download/osgi-early-draft-2011-09.pdf</a></p>
-<p>The code can be found in
-<a href="http://svn.apache.org/repos/asf/aries/trunk/spi-fly">http://svn.apache.org/repos/asf/aries/trunk/spi-fly</a>.</p>
-<h2 id="how-to-use">How to use</h2>
+<h3 id="special-cases">Special Cases</h3>
+<p>SPI Fly can be used for most SPI provider/lookup systems that use the TCCL pattern to obtain
+implementations. However, some cases some <em>special treatment</em> is needed. This special treatment is often needed when the API itself does not
+match the name of the resources in META-INF/services, java.util.ServiceLoader is such a case, however SPI-Fly has built-in knowledge of ServiceLoader.
+Other APIs that require special treatment are listed below:</p>
+<ul>
+<li><strong>javax.imageio.spi.ServiceRegistry</strong>: 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:
+<tt>SPI-Provider: javax.imageio.spi.ServiceRegistry</tt> on the client
+side you can use <tt>SPI-Consumer: javax.imageio.spi.ServiceRegistry#lookupProviders(java.lang.Class)</tt>
+ or <tt>SPI-Consumer: javax.imageio.spi.ServiceRegistry#lookupProviders</tt></li>
+<li><strong>javax.sound.sampled.AudioSystem</strong>: This class uses sun.misc.Service under the covers (via com.sun.media.sound.JDK13Services)
+which is a predecessor to java.util.ServiceLoader. There is no special treatment for sun.misc.Service
+in SPI Fly (yet), but the AudioSystem.getAudioInputStream() API can be made to work by explicitly listing it in the provider bundle
+(the one that contains the relevant META-INF/services resources):
+<tt>SPI-Provider: javax.sound.sampled.AudioSystem</tt> on the consumer side you can use
+<tt>SPI-Consumer: javax.sound.sampled.AudioSystem#getAudioInputStream
+</tt></li>
+</ul>
+<h1 id="usage">Usage</h1>
<p>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. </p>
<p>If you have an pre-4.3 OSGi framework or don't want to use bytecode weaving at runtime you
@@ -376,28 +447,6 @@ 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</pre></p>
<p>Then install and start the statically woven bundle into the system.</p>
-<h2 id="special-cases">Special Cases</h2>
-<p>SPI Fly can be used for most SPI provider/lookup systems that use the TCCL pattern to obtain
-implementations. However, some cases some <em>special treatment</em> is needed. This special treatment is often needed when the API itself does not
-match the name of the resources in META-INF/services, java.util.ServiceLoader is such a case, however SPI-Fly has built-in knowledge of ServiceLoader.
-Other APIs that require special treatment are listed below:</p>
-<ul>
-<li><strong>javax.imageio.spi.ServiceRegistry</strong>: 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:
-<tt>SPI-Provider: javax.imageio.spi.ServiceRegistry</tt> on the client
-side you can use <tt>SPI-Consumer: javax.imageio.spi.ServiceRegistry#lookupProviders(java.lang.Class)</tt>
- or <tt>SPI-Consumer: javax.imageio.spi.ServiceRegistry#lookupProviders</tt></li>
-<li><strong>javax.sound.sampled.AudioSystem</strong>: This class uses sun.misc.Service under the covers (via com.sun.media.sound.JDK13Services)
-which is a predecessor to java.util.ServiceLoader. There is no special treatment for sun.misc.Service
-in SPI Fly (yet), but the AudioSystem.getAudioInputStream() API can be made to work by explicitly listing it in the provider bundle
-(the one that contains the relevant META-INF/services resources):
-<tt>SPI-Provider: javax.sound.sampled.AudioSystem</tt> on the consumer side you can use
-<tt>SPI-Consumer: javax.sound.sampled.AudioSystem#getAudioInputStream
-</tt></li>
-</ul>
<h2 id="examples">Examples</h2>
<p>The <tt>spi-fly-examples</tt> directory contains a number of example bundles that can be
used for testing or experimenting.</p>