Author: veithen
Date: Thu Oct 6 20:03:15 2011
New Revision: 1179799
URL: http://svn.apache.org/viewvc?rev=1179799&view=rev
Log:
Refined the OSGi analysis.
Modified:
webservices/commons/trunk/modules/axiom/src/docbkx/devguide.xml
Modified: webservices/commons/trunk/modules/axiom/src/docbkx/devguide.xml
URL:
http://svn.apache.org/viewvc/webservices/commons/trunk/modules/axiom/src/docbkx/devguide.xml?rev=1179799&r1=1179798&r2=1179799&view=diff
==============================================================================
--- webservices/commons/trunk/modules/axiom/src/docbkx/devguide.xml (original)
+++ webservices/commons/trunk/modules/axiom/src/docbkx/devguide.xml Thu Oct 6
20:03:15 2011
@@ -393,26 +393,26 @@ javax.xml.stream.XMLOutputFactory=com.be
<title>Analysis of the Geronimo JAXB bundles</title>
<para>
As noted in <xref linkend="osgi-req-best-practices"/> the
Apache Geronimo has successfully
- OSGi-fied the JAXB API which has a similar structure as Axiom.
This section briefly describes
+ added OSGi support to the JAXB API which has a structure
similar to the Axiom API. This section briefly describes
how this works. The analysis refers to the following Geronimo
artifacts:
-
<literal>org.apache.geronimo.bundles:jaxb-impl:2.2.3-1_1</literal>,
-
<literal>org.apache.geronimo.specs:geronimo-jaxb_2.2_spec:1.0.1</literal>,
-
<literal>org.apache.geronimo.specs:geronimo-osgi-locator:1.0</literal> and
-
<literal>org.apache.geronimo.specs:geronimo-osgi-registry:1.0</literal>:
+
<literal>org.apache.geronimo.specs:geronimo-jaxb_2.2_spec:1.0.1</literal>
(called the "API bundle" hereafter),
+
<literal>org.apache.geronimo.bundles:jaxb-impl:2.2.3-1_1</literal> (the
"implementation bundle"),
+
<literal>org.apache.geronimo.specs:geronimo-osgi-locator:1.0</literal> (the
"locator bundle") and
+
<literal>org.apache.geronimo.specs:geronimo-osgi-registry:1.0</literal> (the
"registry bundle"):
</para>
<itemizedlist>
<listitem>
<para>
The implementation bundle retains the
<filename>META-INF/services/javax.xml.bind.JAXBContext</filename>
resource from the original artifact
(<literal>com.sun.xml.bind:jaxb-impl</literal>).
- In a non OSGi environment, the
<classname>JAXBContext</classname> class of the API bundle
- will use that resource to discover the implementation
(as required by the JAXB specification).
+ In a non OSGi environment, that resource will be used
to discover the implementation, following
+ the standard JDK 1.3 service discovery algorithm will
(as required by the JAXB specification).
This is the equivalent of our <xref
linkend="osgi-req-no-separate-bundles"/>.
</para>
</listitem>
<listitem>
<para>
- The implementation bundle has an attribute
<literal>SPI-Provider: true</literal> that indicates
+ The manifest of the implementation bundle has an
attribute <literal>SPI-Provider: true</literal> that indicates
that it contains provider implementations that are
discovered using the JDK 1.3 service discovery.
</para>
</listitem>
@@ -423,13 +423,39 @@ javax.xml.stream.XMLOutputFactory=com.be
that has this attribute set to
<literal>true</literal>, it will scan the content of
<filename>META-INF/services</filename> and add the
discovered services to a registry
(Note that the registry bundle supports other ways to
declare SPI providers,
- but this is not really relevant).
+ but this is not really relevant for the present
discussion).
</para>
</listitem>
-
<listitem>
<para>
- The API bundle uses <literal>singleton=true</literal>
(may be relevant for AXIOM-371)
+ The <classname>ContextFinder</classname> class (the
interface of which is defined by
+ the JAXB specification and that is used by the
<methodname>newInstance</methodname>
+ method in <classname>JAXBContext</classname>) in the
API bundle delegates the discovery
+ of the SPI implementation to a static method of the
<classname>ProviderLocator</classname>
+ class defined by the locator bundle (which is not
specific to JAXB and is used by other
+ API bundles as well). This is true both in an OSGi
environment and in a non OSGi environment.
+ </para>
+ <para>
+ The build is configured (using a
<literal>Private-Package</literal> instruction)
+ such that the classes of the locator bundle are
actually included into the API bundle, thus
+ avoiding an additional dependency.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The <classname>ProviderLocator</classname> class and
related code provided by the locator bundle is designed
+ such that in a non OSGi environment, it will simply
use JDK 1.3 service discovery to locate
+ the SPI implementation, without ever loading any OSGi
specific class. On the other hand,
+ in an OSGi environment, it will query the registry
maintained by the registry bundle to locate
+ the provider. The reference to the registry is
injected into the <classname>ProviderLocator</classname>
+ class using a bundle activator.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Finally, it should also be noted that the API bundle
is configured with <literal>singleton=true</literal>.
+ There is indeed no meaningful way how providers could
be matched with different versions of the same API
+ bundle.
</para>
</listitem>
</itemizedlist>
@@ -441,7 +467,9 @@ javax.xml.stream.XMLOutputFactory=com.be
</para>
<para>
Obviously, Axiom could reuse the registry and locator bundles
developed by Geronimo. This however would
- contradict <xref linkend="osgi-reg-no-framework"/>.
+ contradict <xref linkend="osgi-reg-no-framework"/>. In
addition, for Axiom there is no requirement to
+ strictly follow the JDK 1.3 service discovery algorithm.
Therefore Axiom should reuse the pattern
+ developed by Geronimo, but not the actual implementation.
</para>
</section>
<section>
