aries-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From dav...@apache.org
Subject svn commit: r1378529 - /aries/site/trunk/content/modules/spi-fly.mdtext
Date Wed, 29 Aug 2012 13:09:32 GMT
Author: davidb
Date: Wed Aug 29 13:09:31 2012
New Revision: 1378529

URL: http://svn.apache.org/viewvc?rev=1378529&view=rev
Log:
SPI Fly Documentation improvements.

Modified:
    aries/site/trunk/content/modules/spi-fly.mdtext

Modified: aries/site/trunk/content/modules/spi-fly.mdtext
URL: http://svn.apache.org/viewvc/aries/site/trunk/content/modules/spi-fly.mdtext?rev=1378529&r1=1378528&r2=1378529&view=diff
==============================================================================
--- aries/site/trunk/content/modules/spi-fly.mdtext (original)
+++ aries/site/trunk/content/modules/spi-fly.mdtext Wed Aug 29 13:09:31 2012
@@ -3,23 +3,23 @@ Title: 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 <tt>java.util.ServiceLoader</tt>, 
-<tt>META-INF/services</tt> and similar methods in OSGi.
+The SPI Fly component is aimed at providing OSGi support for JRE SPI
+mechanisms, including the usage of <tt>java.util.ServiceLoader</tt>, 
+<tt>META-INF/services</tt> and similar methods.
 
 SPI Fly is the Reference Implementation of the OSGi ServiceLoader Mediator specification,
chapter 133 in the [OSGi 
 Enterprise Specification][1], available from version 5.
 
 ##The Problem##
-<tt>java.util.ServiceLoader.load()</tt> and other similar methods such as 
+Java's <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 
 <tt>FactoryFinder.find()</tt> methods try to locate 'service' implementations
by looking for 
 resources in the META-INF/services directory of all the jars visible to the 
 ***Thread Context ClassLoader*** (TCCL).
 
-There are a number of issues with this approach in OSGi:
+There are a number of issues with the above mechanisms when used in OSGi:
 
- 1. The Thread Context ClassLoader is not defined in general in an OSGi context. It can and
has to be set by the caller and OSGi cannot enforce that. 
+ 1. The Thread Context ClassLoader is not defined in general in an OSGi context. It can and
has to be set by the caller and OSGi cannot generally enforce that. 
  2. A bundle can't Import-Package META-INF/services as potentially many bundles will contain
this pseudo-package and the OSGi framework will only bind a single exporter to an importer
for a given package.
  3. Instantiating an SPI provider generally requires access to internal implementation classes,
by exporting these classes an implementing bundle would break its encapsulation. 
  4. Even if an implementation class was exported, importing this class in a consumer bundle
would bind it to the specific implementation package provided, which violates the principle
of loose coupling.
@@ -29,20 +29,21 @@ The SPI Fly project makes it possible to
 <tt>ServiceLoader.load()</tt> and similar mechanisms under OSGi.
 
 ##Making it Work##
-In order to make the ServiceLoader approach work under OSGi, calling code can be woven
+In order to make ServiceLoader (and other similar SPI or plugin mechanisms) 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.
 
-SPI Fly supports two modes of operation:
+SPI Fly supports two modes of configuration:
 
   - 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>.
[Find it here](#specconf).
+provides portability across implementations of this specification. However, it only covers
<tt>java.util.ServiceLoader</tt>. [Find it here](#specconf).
   - 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 [SPI Fly-specific configuration](#specificconf).
 
 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.
+Registry so that OSGi-aware consumers can simply find them there. This is supported in both
the spec-compliant as 
+well as the proprietary configuration modes.
 
 ##Getting SPI Fly##
 
@@ -54,13 +55,14 @@ once released releases will be available
 The code can be found in
 [http://svn.apache.org/repos/asf/aries/trunk/spi-fly][2].
 
-To build, use Maven 3.x and run 'mvn install'
+To build, use Maven 3.x and run <tt>mvn install</tt>
+
 #<a id="specconf"/>Configuration: OSGi Spec-compliant#
 All the details surrounding this type of configuration are covered in the 
 [OSGi Enterprise Specification][1] (from version 5) chapter 133. This section provides a
short overview.
 
 ##Providers##
-SPI provider bundles opt in to being processed by specifying a requirement on the 
+SPI provider bundles opt in to being registered 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:
 
 <tt>&nbsp;&nbsp;Require-Capability: osgi.extender; filter:="(osgi.extender=osgi.serviceloader.registrar)"</tt>
@@ -76,7 +78,7 @@ See the <tt>spi-fly-example-provider2-bu
 
 ##Consumers##
 
-A SPI consumer (i.e. a bundle using the <tt>java.util.ServiceLoader.load()</tt>
API) needs to specify required capabilities
+An 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:
 
   - A requirement on the SPI Fly mechanism. This is stated as follows<br/>
@@ -98,7 +100,8 @@ See the <tt>spi-fly-example-client2-bund
 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
+are only using SPI Fly with <tt>java.util.ServiceLoader</tt> or you are only
using the provided 
+services through the OSGi Service Registry, then consider
 using the [spec-compliant](#specconf) configuration for portability.
 
 ##Providers##
@@ -114,30 +117,34 @@ directory and register them.
 MySvc2.
 
 Additionally services found in META-INF/services are registered in the OSGi Service 
-Registry. Each service is registered with the *spi.provider.url* service registration
-property.
+Registry. Each service is registered with the *serviceloader.mediator* service registration
+property set.
 
 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>.
 
+See the <tt>spi-fly-example-provider1-bundle</tt> for an example of a provider
using this type of configuration.
+
 ##Consumers##
-Service consumers also need to opt-in to the process. 
+Service consumers also need to opt in to the process. 
 
 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
-the TCCL will be set to the matching provider bundle(s).
+the TCCL will be set to the matching provider bundle(s). Some example SPI-Consumer headers
are:
 
 * **SPI-Consumer: *** This is a shorthand for 
 <tt>java.util.ServiceLoader#load(java.lang.Class)</tt> and will 
 automatically weave all <tt>ServiceLoader.load(Class)</tt> calls.
-* **java.util.ServiceLoader#load(java.lang.Class[org.apache.aries.mytest.MySPI])**
+* **SPI-Consumer: java.util.ServiceLoader#load(java.lang.Class[org.apache.aries.mytest.MySPI])**
 Only process calls to <tt>ServiceLoader.load(Class)</tt> when it is called with

 <tt>MySPI.class</tt> as argument.
-* **javax.xml.parsers.DocumentBuilderFactory#newInstance()** weave clients that
+* **SPI-Consumer: javax.xml.parsers.DocumentBuilderFactory#newInstance()** weave clients
that
 call <tt>DocumentBuilderFactory.newInstance()</tt>. 
-* **org.foo.Foo#someMthd(),org.bar.Bar#myMethod()** weave calls to <tt>Foo.someMthd()</tt>
and 
-<tt>Bar.myMethod()</tt>. 
+* **SPI-Consumer: org.foo.Foo#someMthd(),org.bar.Bar#myMethod()** weave calls to <tt>Foo.someMthd()</tt>
and 
+<tt>Bar.myMethod()</tt>.
+
+See the <tt>spi-fly-example-client1-bundle/target</tt> for an example of a consumer
using this type of configuration. 
 
 ###Special Cases###
 SPI Fly can be used for most SPI provider/lookup systems that use the TCCL pattern to obtain
@@ -163,14 +170,14 @@ in SPI Fly (yet), but the AudioSystem.ge
 
 #Usage#
 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.

+4.3 (or higher) 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##
 Install and start the <tt>org.apache.aries.spifly.dynamic.bundle</tt> into the
system. This bundle 
-has a dependency on <tt>[org.objectweb.asm][3]</tt> version 3.2 or newer and
on the Aries 
+has a dependency on <tt>[org.objectweb.asm][3]</tt> version 4.0 or newer and
on the Aries 
 Util bundle.
 
 <pre>osgi> ss    
@@ -178,8 +185,8 @@ Framework is launched.    
 id	State       Bundle
 0	ACTIVE      org.eclipse.osgi_3.7.1.R37x_v20110808-1106
 1	ACTIVE      org.objectweb.asm.all_3.2.0
-2	ACTIVE      org.apache.aries.util_0.5.0.SNAPSHOT
-3	ACTIVE      org.apache.aries.spifly.dynamic.bundle_0.4.0.SNAPSHOT
+2	ACTIVE      org.apache.aries.util_1.0.0
+3	ACTIVE      org.apache.aries.spifly.dynamic.bundle_1.0.0
 </pre>
 
 Note that, as with any OSGi Bundle that uses the OSGi 4.3 WeavingHooks, the weaver
@@ -195,11 +202,11 @@ Provider bundles are still handled dynam
 
 ###To statically weave a bundle###
 The easiest way to invoke the static weaver is to take the <tt>org.apache.aries.spifly.static.tool</tt>
-jar with dependencies. This jar can be created by running <tt>mvn assembly:single</tt>
in this maven module.
+jar with dependencies.
 
 Then run the static tool on any bundle that needs processing:
 <pre>
-java -jar org.apache.aries.spifly.static.tool-0.4-with-dependencies.jar mybundle.jar
+java -jar org.apache.aries.spifly.static.tool-1.0.0-with-dependencies.jar mybundle.jar
 </pre>
 
 This will produce a second bundle with the same name with the _spifly suffix appended, so

@@ -212,8 +219,8 @@ Framework is launched.
 id	State       Bundle
 0	ACTIVE      org.eclipse.osgi_3.6.2.R36x_v20110210
 1	ACTIVE      org.eclipse.osgi.services_3.2.100.v20100503
-2	ACTIVE      org.apache.aries.util_0.5.0.SNAPSHOT
-3	ACTIVE      org.apache.aries.spifly.static.bundle_0.4.0.SNAPSHOT</pre>
+2	ACTIVE      org.apache.aries.util_1.0.0
+3	ACTIVE      org.apache.aries.spifly.static.bundle_1.0.0</pre>
 
 Then install and start the statically woven bundle into the system.
 
@@ -225,13 +232,13 @@ The following modules can be found in th
 
 * **spi-fly-example-spi-bundle** - a bundle providing an SPI interface used by the other
example bundles.
 * **spi-fly-example-provider1-jar** - a plain jar file providing an implementation of the
SPI (via <tt>META-INF/services</tt>).
-* **spi-fly-example-provider1-bundle** - a bundle that wraps the jar file from the previous
bullet and specifies it in its Bundle-ClassPath. This example represents the common case where
an existing SPI provider is wrapped as-is in an OSGi bundle.
-* **spi-fly-example-provider2-bundle** - a bundle that directly provides an SPI service (via
<tt>META-INF/services</tt>).
+* **spi-fly-example-provider1-bundle** - a bundle that wraps the jar file from the previous
bullet and specifies it in its Bundle-ClassPath. This example represents the common case where
an existing SPI provider is wrapped as-is in an OSGi bundle. This example uses the SPI Fly
proprietary configuration.
+* **spi-fly-example-provider2-bundle** - a bundle that directly provides an SPI service (via
<tt>META-INF/services</tt>). This example uses OSGi  specification compliant configuration.
 * **spi-fly-example-client1-jar** - a plain jar using java.util.ServiceLoader.load() to obtain
and invoke all services provided of a certain SPI.
-* **spi-fly-example-client1-bundle** - a bundle that wraps the jar file from the previous
bullet and lists it in its Bundle-ClassPath. This example represents the common case where
an existing SPI consumer is wrapped as-is in an OSGi bundle.
-* **spi-fly-example-client2-bundle** - a bundle that has code that invokes <tt>java.util.ServiceLoader.load()</tt>
directly.
+* **spi-fly-example-client1-bundle** - a bundle that wraps the jar file from the previous
bullet and lists it in its Bundle-ClassPath. This example represents the common case where
an existing SPI consumer is wrapped as-is in an OSGi bundle. This example uses SPI Fly proprietary
configuration.
+* **spi-fly-example-client2-bundle** - a bundle that has code that invokes <tt>java.util.ServiceLoader.load()</tt>
directly. This example uses OSGi specification compliant configuration.
 
 
   [1]: http://www.osgi.org/Download/Release5 "OSGi Enterprise Specification"
   [2]: http://svn.apache.org/repos/asf/aries/trunk/spi-fly
-  [3]: http://search.maven.org/#artifactdetails|asm|asm-all|3.2|jar
\ No newline at end of file
+  [3]: http://search.maven.org/#artifactdetails|org.ow2.asm|asm-all|4.0|jar
\ No newline at end of file



Mime
View raw message