You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@ws.apache.org by ve...@apache.org on 2011/10/03 23:50:56 UTC
svn commit: r1178597 -
/webservices/commons/trunk/modules/axiom/src/docbkx/devguide.xml
Author: veithen
Date: Mon Oct 3 21:50:56 2011
New Revision: 1178597
URL: http://svn.apache.org/viewvc?rev=1178597&view=rev
Log:
Started to define a set of requirements for a redesign of the OSGi support in Axiom.
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=1178597&r1=1178596&r2=1178597&view=diff
==============================================================================
--- webservices/commons/trunk/modules/axiom/src/docbkx/devguide.xml (original)
+++ webservices/commons/trunk/modules/axiom/src/docbkx/devguide.xml Mon Oct 3 21:50:56 2011
@@ -158,6 +158,226 @@ javax.xml.stream.XMLOutputFactory=com.be
</chapter>
<chapter>
+ <title>OSGi integration</title>
+ <section>
+ <title>Requirements</title>
+ <formalpara>
+ <title>Requirement 1</title>
+ <para>
+ The Axiom artifacts SHOULD be usable both as normal JAR files and as OSGi bundles.
+ </para>
+ </formalpara>
+ <note>
+ <para>
+ The alternative would be to produce two sets of artifacts during the build. This
+ should be avoided in order to keep the build process as simple as possible.
+ It should also be noted that the Geronimo Spec artifacts also meet this requirement.
+ </para>
+ </note>
+ <formalpara id="osgi-req-same-api">
+ <title>Requirement 2</title>
+ <para>
+ All APIs defined by the <literal>axiom-api</literal> module, and in particular the
+ <classname>OMAbstractFactory</classname> API MUST continue to work
+ as expected in an OSGi environment, so that code in downstream projects
+ doesn't need to be rewritten.
+ </para>
+ </formalpara>
+ <formalpara id="osgi-req-same-impl-selection">
+ <title>Requirement 3</title>
+ <para>
+ <classname>OMAbstractFactory</classname> MUST select the same implementation
+ regardless of the type of container (OSGi or non OSGi). The only exception is
+ related to the usage of system properties to specify the default <classname>OMMetaFactory</classname>
+ implementation: in an OSGi environment, selecting an implementation class using
+ a system property is not meaningful.
+ </para>
+ </formalpara>
+ <note>
+ <para>
+ This is currently not the case. In a non OSGi environment, recent versions of Axiom
+ use JDK 1.3 service discovery to locate the default implementation and fall back to
+ LLOM if none is found. DOOM will never be selected as the default implementation.
+ On the other hand, the current OSGi integration will select any Axiom implementation
+ as default implementation, but gives priority to LLOM.
+ </para>
+ </note>
+ <formalpara id="osgi-ref-impl-not-exported">
+ <title>Requirement 4</title>
+ <para>
+ The bundles for the LLOM and DOOM implementations MUST NOT export any packages.
+ This is required to keep a clean separation between the public API and implementation
+ specific classes and to make sure that the implementations can be modified without the
+ risk of breaking existing code.
+ </para>
+ <para>
+ An exception MAY be made for factory classes related to foreign APIs, such as the
+ <classname>DocumentBuilderFactory</classname> implementation for an Axiom implementation
+ supporting DOM.
+ </para>
+ </formalpara>
+ <note>
+ <para>
+ When the Axiom artifacts are used as normal JAR files in a Maven build, this requirement implies that
+ they should be used in scope <literal>runtime</literal>.
+ </para>
+ <para>
+ Although this requirement is easy to implement for the Axiom project, there are
+ currently a couple of issues in the downstreams project that need to be addressed
+ to make this work:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ As explained in <ulink url="https://issues.apache.org/jira/browse/AXIS2-4902">AXIS2-4902</ulink>,
+ there are many places in Axis2 that still refer directly to Axiom implementation classes.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The <literal>axis2-saaj</literal> module is tightly coupled to <literal>axiom-dom</literal>.
+ Making this work will probably require using <literal>maven-shade-plugin</literal> to
+ include (a relocated copy of) the DOOM classes into <literal>axis2-saaj</literal>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Abdera extends the LLOM implementation. Probably, some <literal>maven-shade-plugin</literal>
+ magic will be required here as well to create Abdera OSGi bundles that work properly with
+ the Axiom bundles.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </note>
+ <formalpara>
+ <title>Requirement 5</title>
+ <para>
+ It MUST be possible to use a non standard (third party) Axiom implementation as a drop-in replacement
+ for the standard LLOM and DOOM implementation, i.e. the <literal>axiom-impl</literal>
+ and <literal>axiom-dom</literal> bundles. It MUST be possible to replace <literal>axiom-impl</literal>
+ (resp. <literal>axiom-dom</literal>) by any Axiom implementation that supports the full Axiom API
+ (resp. that supports DOM in addition to the Axiom API), without the need to change any application code.
+ </para>
+ </formalpara>
+ <note>
+ <para>
+ This requirement has several important implications:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ It restricts the allowable exceptions to <xref linkend="osgi-ref-impl-not-exported"/>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ It implies that there must be an API that allows application code to select an Axiom
+ implementation based on its capabilities (e.g. DOM support) without introducing a
+ hard dependency on a particular Axiom implementation.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ In accordance with <xref linkend="osgi-req-same-api"/> and <xref linkend="osgi-req-same-impl-selection"/>
+ this requirement not only applies to an OSGi environment, but extends to non OSGi environments as well.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </note>
+ <formalpara>
+ <title>Requirement 6</title>
+ <para>
+ The OSGi integration SHOULD remove the necessity for downstreams projects
+ to produce their own custom OSGi bundles for Axiom. There SHOULD be one
+ and only one set of OSGi bundles for Axiom, namely the ones released by the Axiom project.
+ </para>
+ </formalpara>
+ <note>
+ <para>
+ Currently there are at least two projects that create their own modified Axiom bundles:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Apache Geronimo has a custom Axiom bundle to support the Axis2 integration.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ ServiceMix also has custom bundles to support Abdera; see
+ <ulink url="https://issues.apache.org/jira/browse/SMX4-877">SMX4-877</ulink>.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ Note that this requirement can't be satisfied directly by Axiom. It requires that
+ the above mentioned projects (Geronimo, Axis2 and Abdera) use Axiom in a way that is
+ compatible with its design, and in particular with <xref linkend="osgi-ref-impl-not-exported"/>.
+ Nevertheless, Axiom must provide the necessary APIs and features to meet the needs
+ of these projects.
+ </para>
+ </note>
+ <formalpara>
+ <title>Requirement 7</title>
+ <para>
+ The Axiom OSGi integration SHOULD NOT rely on any particular OSGi framework such
+ as Felix SCR (Declarative Services). When deployed in an OSGi environment, Axiom should have the same
+ runtime dependencies as in a non OSGi environment (i.e. StAX, Activation and JavaMail).
+ </para>
+ </formalpara>
+ <note>
+ <para>
+ Axiom 1.2.12 relies on Felix SCR. Although there is no real issue with that, getting rid
+ of this extra dependency is seen as a nice to have. One of the reasons for using Felix SCR
+ was to avoid introducing OSGi specific code into Axiom. However, there is no issue with
+ having such code, provided that <xref linkend="osgi-req-no-osgi-dep"/> is satisfied.
+ </para>
+ </note>
+ <formalpara id="osgi-req-no-osgi-dep">
+ <title>Requirement 8</title>
+ <para>
+ In a non OSGi environment, Axiom MUST NOT have any OSGi related dependencies. That means
+ that the OSGi integration must be written in such a way that no OSGi specific classes are
+ ever loaded in a non OSGi environment.
+ </para>
+ </formalpara>
+ <formalpara>
+ <title>Requirement 9</title>
+ <para>
+ The OSGi integration MUST follow established best practices. It SHOULD be inspired by
+ what has been done to add OSGi integration to APIs that have a similar structure as Axiom.
+ </para>
+ </formalpara>
+ <note>
+ <para>
+ Axiom is designed around an abstract API and allows for the existence of multiple
+ independent implementations. A factory (<classname>OMAbstractFactory</classname>) is used to
+ locate and instantiate the desired implementation. This is similar to APIs such as
+ JAXP (<classname>DocumentBuilderFactory</classname>, etc.) and JAXB (<classname>JAXBContext</classname>).
+ These APIs have been successfully "OSGi-fied" e.g. by the Apache Geronimo project.
+ Instead of reinventing the wheel, we should leverage that work and adapt it to
+ Axiom's specific requirements.
+ </para>
+ <para>
+ It should be noted that because of the way the Axiom API is designed and taking into account
+ <xref linkend="osgi-req-same-api"/>, it is not possible to make Axiom entirely compatible
+ with OSGi paradigms (the same is true for JAXB). In an OSGi-only world, each Axiom
+ implementation would simple expose itself as an OSGi service (of type <classname>OMMetaFactory</classname> e.g.)
+ and code depending on Axiom would bind to one (or more) of these services depending on its needs.
+ That is not possible because it would conflict with <xref linkend="osgi-req-same-api"/>.
+ </para>
+ </note>
+ </section>
+ <section>
+ <title>New abstract APIs</title>
+ <para>
+ TODO: The existence of DOOMAbstractFactory conflicts with several of the requirements; need a new API that allows
+ to select an Axiom implementation based on capabilities/features requested by the application code
+ </para>
+ </section>
+ </chapter>
+
+ <chapter>
<title>Release process</title>
<section>
<title>Release preparation</title>