ws-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From veit...@apache.org
Subject svn commit: r1719800 - in /webservices/axiom/trunk: devguide/src/docbkx/devguide.xml src/site/markdown/design/ src/site/markdown/design/index.md src/site/markdown/design/osgi-integration.md src/site/site.xml
Date Sun, 13 Dec 2015 14:06:03 GMT
Author: veithen
Date: Sun Dec 13 14:06:03 2015
New Revision: 1719800

URL: http://svn.apache.org/viewvc?rev=1719800&view=rev
Log:
Migrate the OSGi integration design documentation to Markdown.

Added:
    webservices/axiom/trunk/src/site/markdown/design/
    webservices/axiom/trunk/src/site/markdown/design/index.md
    webservices/axiom/trunk/src/site/markdown/design/osgi-integration.md
Modified:
    webservices/axiom/trunk/devguide/src/docbkx/devguide.xml
    webservices/axiom/trunk/src/site/site.xml

Modified: webservices/axiom/trunk/devguide/src/docbkx/devguide.xml
URL: http://svn.apache.org/viewvc/webservices/axiom/trunk/devguide/src/docbkx/devguide.xml?rev=1719800&r1=1719799&r2=1719800&view=diff
==============================================================================
--- webservices/axiom/trunk/devguide/src/docbkx/devguide.xml (original)
+++ webservices/axiom/trunk/devguide/src/docbkx/devguide.xml Sun Dec 13 14:06:03 2015
@@ -226,588 +226,6 @@ javax.xml.stream.XMLOutputFactory=com.be
                 declaration may be skipped when that API is used.
             </para>
         </section>
-        <section>
-            <title>OSGi integration and separation between API and implementation</title>
-            <section>
-                <title>Introduction</title>
-                <para>
-                    This section addresses two related architectural questions:
-                </para>
-                <itemizedlist>
-                    <listitem>
-                        <para>
-                            OSGi support was originally introduced in Axiom 1.2.9, but the implementation had
-                            a couple of flaws. This section discusses the rationale behind the new OSGi
-                            support introduced in Axiom 1.2.13.
-                        </para>
-                    </listitem>
-                    <listitem>
-                        <para>
-                            Axiom is designed as a set of abstract APIs for which two implementations are
-                            provided: LLOM and DOOM. It is important to make a clear distinction between what
-                            is part of the public API and what should be considered implementation classes that
-                            must not be used by application code directly. This also implies that Axiom must
-                            provide the necessary APIs to allow application code to access all features without
-                            the need to access implementation classes directly. This section in particular
-                            discusses the question how application code can request factories that support DOM
-                            without the need to refer directly to DOOM.
-                        </para>
-                    </listitem>
-                </itemizedlist>
-                <para>
-                    These two questions are closely related because OSGi allows to enforce the distinction
-                    between public API and implementation classes by carefully selecting the packages
-                    exported by the different bundles: only classes belonging to the public API
-                    should be exported, while implementation classes should be private to the bundles
-                    containing them. This in turn has implications for the packaging of these artifacts.
-                </para>
-            </section>
-            <section>
-                <title>Requirements</title>
-                <formalpara xml:id="osgi-req-no-separate-bundles">
-                    <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 xml: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>
-                <note>
-                    <para>
-                        This requirement was already satisfied by the OSGi support introduced in Axiom 1.2.9.
-                        It therefore also ensures that the transition to the new OSGi support in Axiom 1.2.13
-                        is transparent for applications that already use Axiom in an OSGi container.
-                    </para>
-                </note>
-                <formalpara xml: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>
-                <formalpara xml:id="osgi-ref-impl-not-exported">
-                    <title>Requirement 4</title>
-                    <para>
-                        Only classes belonging to the public API should be exported by the OSGi bundles.
-                        Implementation classes should not be exported. In particular,
-                        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.
-                        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, it requires
-                        changes to downstreams project to make this actually work:
-                    </para>
-                    <itemizedlist>
-                        <listitem>
-                            <para>
-                                As explained in <link xlink:href="https://issues.apache.org/jira/browse/AXIS2-4902">AXIS2-4902</link>,
-                                there used to be many places in Axis2 that still referred directly to Axiom implementation classes.
-                                The same was true for Rampart and Sandesha2. This has now been fixed and all three projects
-                                use <literal>axiom-impl</literal> and <literal>axiom-dom</literal> as dependencies in scope
-                                <literal>runtime</literal>.
-                            </para>
-                        </listitem>
-                        <listitem>
-                            <para>
-                                Abdera extends the LLOM implementation. Probably, some <literal>maven-shade-plugin</literal>
-                                magic will be required here to create Abdera OSGi bundles that work properly with
-                                the Axiom bundles.
-                            </para>
-                        </listitem>
-                        <listitem>
-                            <para>
-                                For Spring Web Services this issue is addressed by
-                                <link xlink:href="https://jira.springsource.org/browse/SWS-822">SWS-822</link>.
-                            </para>
-                        </listitem>
-                    </itemizedlist>
-                </note>
-                <formalpara xml:id="osgi-req-dropin">
-                    <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 a custom bundles for Axiom. However, this bundle only seem to exist to
-                                support their own custom Abdera bundle, which is basically an incorrect repackaging of the
-                                original Abdera code. See
-                                <link xlink:href="https://issues.apache.org/jira/browse/SMX4-877">SMX4-877</link> for more details.
-                            </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 xml:id="osgi-reg-no-framework">
-                    <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 xml: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 xml:id="osgi-req-best-practices">
-                    <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 simply 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>
-                <formalpara>
-                    <title>Non-Requirement 1</title>
-                    <para>
-                        APIs such as JAXP and JAXB have been designed from the start for inclusion into the JRE.
-                        They need to support scenarios where an application bundles its own implementation
-                        (e.g. an application may package a version of Apache Xerces, which would then be
-                        instantiated by the <methodname>newInstance</methodname> method in
-                        <classname>DocumentBuilderFactory</classname>). That implies that the selected implementation
-                        depends on the thread context class loader. It is assumed that there is no such requirement
-                        for Axiom, which means that in a non OSGi environment, the Axiom implementations are always loaded from the same
-                        class loader as the <literal>axiom-api</literal> JAR.
-                    </para>
-                </formalpara>
-                <note>
-                    <para>
-                        This (non-)requirement is actually not directly relevant for the OSGi support, but it
-                        nevertheless has some importance because of <xref linkend="osgi-req-same-impl-selection"/>
-                        (which implies that the OSGi support needs to be designed in parallel with the implementation
-                        discovery strategy applicable in a non OSGi environment).
-                    </para>
-                </note>
-            </section>
-            <section>
-                <title>Analysis of the Geronimo JAXB bundles</title>
-                <para>
-                    As noted in <xref linkend="osgi-req-best-practices"/> the Apache Geronimo has successfully
-                    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.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, 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 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>
-                    <listitem>
-                        <para>
-                            The registry bundle creates a <classname>BundleTracker</classname> that looks for
-                            the <literal>SPI-Provider</literal> attribute in active bundles. For each bundle
-                            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 for the present discussion).
-                        </para>
-                    </listitem>
-                    <listitem>
-                        <para>
-                            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>
-                <para>
-                    This is an example of a particularly elegant way to satisfy <xref linkend="osgi-req-no-separate-bundles"/>,
-                    <xref linkend="osgi-req-same-api"/> and <xref linkend="osgi-req-same-impl-selection"/>, especially because
-                    it relies on the same metadata (the <filename>META-INF/services/javax.xml.bind.JAXBContext</filename> resources)
-                    in OSGi and non OSGi environments.
-                </para>
-                <para>
-                    Obviously, Axiom could reuse the registry and locator bundles developed by Geronimo. This however would
-                    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>
-                <title>New abstract APIs</title>
-                <para>
-                    Application code rarely uses DOOM as the default Axiom implementation. Several downstream projects
-                    (e.g. the Axis2/Rampart combination) use both the default (LLOM) implementation and DOOM. They select
-                    the implementation based on the particular context. As of Axiom 1.2.12, the only way to create an object
-                    model instance with the DOOM implementation is to use the <classname>DOOMAbstractFactory</classname> API
-                    or to instantiate one of the factory classes (<classname>OMDOMMetaFactory</classname>, <classname>OMDOMFactory</classname>
-                    or one of the subclasses of <classname>DOMSOAPFactory</classname>). All these classes are part of
-                    the <literal>axiom-dom</literal> artifact. This is clearly in contradiction with <xref linkend="osgi-ref-impl-not-exported"/>
-                    and <xref linkend="osgi-req-dropin"/>.
-                </para>
-                <para>
-                    To overcome this problem the Axiom API must be enhanced to make it possible to select an Axiom
-                    implementation based on capabilities/features requested by the application code. E.g. in the case
-                    of DOOM, the application code would request a factory that implements the DOM API. It is then up
-                    to the Axiom API classes to locate an appropriate implementation, which may be DOOM or another
-                    drop-in replacement, as per <xref linkend="osgi-req-dropin"/>.
-                </para>
-                <para>
-                    If multiple Axiom implementations are available (on the class path in non OSGi environment or
-                    deployed as bundles in an OSGi environment), then the Axiom API must also be able to select an
-                    appropriate default implementation if no specific feature is requested by the application code.
-                    This can be easily implemented by defining a special feature called "default" that would be
-                    declared by any Axiom implementation that is suitable as a default implementation.
-                </para>
-                <note>
-                    <para>
-                        DOOM is generally not considered suitable as a default implementation because it doesn't
-                        implement the complete Axiom API (e.g. it doesn't support <classname>OMSourcedElement</classname>).
-                        In addition, in earlier versions of Axiom, the factory classes for DOOM were not stateless
-                        (see <link xlink:href="https://issues.apache.org/jira/browse/AXIOM-412">AXIOM-412</link>).
-                    </para>
-                </note>
-                <para>
-                    Finally, to make the selection algorithm deterministic, there should also be a concept
-                    of priority: if multiple Axiom implementations are found for the same feature, then the Axiom API
-                    would select the one with the highest priority.
-                </para>
-                <para>
-                    This leads to the following design:
-                </para>
-                <orderedlist>
-                    <listitem>
-                        <para>
-                            Every Axiom implementation declares a set of features that it supports. A feature is
-                            simply identified by a string. Two features are predefined by the Axiom API:
-                        </para>
-                        <itemizedlist>
-                            <listitem>
-                                <para>
-                                    <literal>default</literal>: indicates that the implementation is a complete
-                                    implementation of the Axiom API and may be used as a default implementation.
-                                </para>
-                            </listitem>
-                            <listitem>
-                                <para>
-                                    <literal>dom</literal>: indicates that the implementation supports DOM
-                                    in addition to the Axiom API.
-                                </para>
-                            </listitem>
-                        </itemizedlist>
-                        <para>
-                            For every feature it declares, the Axiom implementation specifies a priority,
-                            which is a positive integer.
-                        </para>
-                    </listitem>
-                    <listitem>
-                        <para>
-                            The relevant Axiom APIs are enhanced so that they take an optional argument
-                            specifying the feature requested by the application code. If no explicit feature
-                            is requested, then Axiom will use the <literal>default</literal> feature.
-                        </para>
-                    </listitem>
-                    <listitem>
-                        <para>
-                            To determine the <classname>OMMetaFactory</classname> to be used, Axiom locates
-                            the implementations declaring the requested feature and selects the one that
-                            has the highest priority for that feature.
-                        </para>
-                    </listitem>
-                </orderedlist>
-                <para>
-                    A remaining question is how the implementation declares the feature/priority information.
-                    There are two options:
-                </para>
-                <itemizedlist>
-                    <listitem>
-                        <para>
-                            Add a method to <classname>OMMetaFactory</classname> that allows the Axiom API
-                            to query the feature/priority information from the implementation (i.e. the
-                            features and priorities are hardcoded in the implementation).
-                        </para>
-                    </listitem>
-                    <listitem>
-                        <para>
-                            Let the implementation provide this information declaratively in its metadata
-                            (either in the manifest or in a separate resource with a well defined name).
-                            Note that in a non OSGi environment, such a metadata resource must be used anyway
-                            to enable the Axiom API to locate the <classname>OMMetaFactory</classname> implementations.
-                            Therefore this would be a natural place to declare the features as well.
-                        </para>
-                    </listitem>
-                </itemizedlist>
-                <para>
-                    The second option has the advantage to make it easier for users to debug and tweak
-                    the implementation discovery process (e.g. there may be a need to
-                    customize the features and priorities declared by the different implementations to ensure
-                    that the right implementation is chosen in a particular use case).
-                </para>
-                <para>
-                    This leads to the following design decision:
-                    the features and priorities (together with the class name of the <classname>OMMetaFactory</classname>
-                    implementation) will be defined in an XML descriptor with resource name <filename>META-INF/axiom.xml</filename>.
-                    The format of that descriptor must take into account that a single JAR may contain several
-                    Axiom implementations (e.g. if the JAR is an uber-JAR repackaged from the standard Axiom JARs).
-                </para>
-            </section>
-            <section>
-                <title>Common implementation classes</title>
-                <para>
-                    Obviously the LLOM and DOOM implementations share some amount of common code. Historically,
-                    implementation classes reusable between LLOM and DOOM were placed in <literal>axiom-api</literal>.
-                    This however tends to blur the distinction between the public API and implementation classes.
-                    Starting with Axiom 1.2.13 such classes are placed into a separate module called
-                    <literal>axiom-common-impl</literal>. However, <literal>axiom-common-impl</literal> cannot simply
-                    be a dependency of <literal>axiom-impl</literal> and <literal>axiom-dom</literal>.
-                    The reason is that in an OSGi environment, the <literal>axiom-common-impl</literal> bundle
-                    would have to export these shared classes, which is in contradiction with <xref linkend="osgi-ref-impl-not-exported"/>.
-                    Therefore the code from <literal>axiom-common-impl</literal> needs to be packaged into
-                    <literal>axiom-impl</literal> and <literal>axiom-dom</literal> by the build process so that
-                    the <literal>axiom-common-impl</literal> artifact is not required at runtime.
-                    <xref linkend="osgi-req-no-separate-bundles"/> forbids using embedded JARs to achieve this.
-                    Instead <literal>maven-shade-plugin</literal> is used to include the classes
-                    from <literal>axiom-common-impl</literal> into <literal>axiom-impl</literal> and <literal>axiom-dom</literal>
-                    (and to modify the POMs to remove the dependencies on <literal>axiom-common-impl</literal>).
-                </para>
-                <para>
-                    This raises the question whether <literal>maven-shade-plugin</literal> should be configured to
-                    simply copy the classes or to relocate them (i.e. to change their package names). There are a couple
-                    of arguments in favor of relocating them:
-                </para>
-                <itemizedlist>
-                    <listitem>
-                        <para>
-                            According to <xref linkend="osgi-req-no-separate-bundles"/>, the Axiom artifacts should be
-                            usable both as normal JARs and as OSGi bundles. Obviously the expectation is that from the
-                            point of view of application code, they should work in the same in OSGi and non OSGi environments.
-                            Relocation is required if one wants to strictly satisfy this requirement even if different versions
-                            of <literal>axiom-impl</literal> and <literal>axiom-dom</literal> are mixed.
-                            Since the container creates separate class loaders for the <literal>axiom-impl</literal> and <literal>axiom-dom</literal> bundles,
-                            it is always possible to do that in an OSGi environment: even if the shared classes
-                            included in <literal>axiom-impl</literal> and <literal>axiom-dom</literal> are
-                            not relocated, but have the same names, this will not result in conflicts.
-                            The situation is different in a non OSGi environment where the classes in <literal>axiom-impl</literal>
-                            and <literal>axiom-dom</literal> are loaded by the same class loader. If the shared classes
-                            are not relocated, then there may be a conflict if the versions don't match.
-                        </para>
-                        <para>
-                            However, in practice it is unlikely that there are valid use case where one would use
-                            <literal>axiom-impl</literal> and <literal>axiom-dom</literal> artifacts from different Axiom versions.
-                        </para>
-                    </listitem>
-                    <listitem>
-                        <para>
-                            Relocation allows to preserve compatibility when duplicate code from
-                            <literal>axiom-impl</literal> and <literal>axiom-dom</literal> is merged and moved
-                            to <literal>axiom-common-impl</literal>. The <classname>OMNamespaceImpl</classname>,
-                            <classname>OMNavigator</classname> and <classname>OMStAXWrapper</classname> classes
-                            from <literal>axiom-impl</literal> and the <classname>NamespaceImpl</classname>,
-                            <classname>DOMNavigator</classname> and <classname>DOMStAXWrapper</classname>
-                            classes from <literal>axiom-dom</literal> that existed in earlier versions of Axiom
-                            are examples of this. The classes in <literal>axiom-dom</literal> were almost identical
-                            to the corresponding classes in <literal>axiom-impl</literal>. These classes have been
-                            merged and moved to <literal>axiom-common-impl</literal>. Relocation then allows them
-                            to retain their original name (including the original package name) in the
-                            <literal>axiom-impl</literal> and <literal>axiom-dom</literal> artifacts.
-                        </para>
-                        <para>
-                            However, this is only a concern if one wants to preserve compatibility with existing
-                            code that directly uses these implementation specific classes (which is something that is
-                            strongly discouraged). One example where this was relevant was the SAAJ implementation
-                            in Axis2 which used to be very strongly coupled to the DOOM implementation. This however
-                            has been fixed now.
-                        </para>
-                    </listitem>
-                </itemizedlist>
-                <para>
-                    Using relocation also has some serious disadvantages:
-                </para>
-                <itemizedlist>
-                    <listitem>
-                        <para>
-                            Stack traces may contain class names that don't match class names in the Axiom source
-                            code, making debugging harder.
-                        </para>
-                    </listitem>
-                    <listitem>
-                        <para>
-                            Axiom now uses JaCoCo to produce code coverage reports. However these reports are
-                            incomplete if relocation is used. This doesn't affect test cases executed in
-                            the <literal>axiom-impl</literal> and <literal>axiom-dom</literal> modules
-                            (because they are executed with the original classes), but tests in separate modules
-                            (such as integration tests). There are actually two issues:
-                        </para>
-                        <itemizedlist>
-                            <listitem>
-                                <para>
-                                    For the relocated classes, JaCoCo is unable to find the corresponding source code.
-                                    This means that the reported code coverage is inaccurate for classes in
-                                    <literal>axiom-common-impl</literal>.
-                                </para>
-                            </listitem>
-                            <listitem>
-                                <para>
-                                    Relocation not only modifies the classes in <literal>axiom-common-impl</literal>, but
-                                    also the classes in <literal>axiom-impl</literal> and <literal>axiom-dom</literal>
-                                    that use them. JaCoCo <link xlink:href="https://github.com/jacoco/jacoco/issues/51">detects this</link>
-                                    and excludes the data from the coverage analysis. This means that the
-                                    reported code coverage will also be inaccurate for classes in
-                                    <literal>axiom-impl</literal> and <literal>axiom-dom</literal>.
-                                </para>
-                            </listitem>
-                        </itemizedlist>
-                    </listitem>
-                </itemizedlist>
-                <para>
-                    In Axiom 1.2.14 relocation was used, but this has been changed in Axiom 1.2.15 because the disadvantages
-                    outweigh the advantages.
-                </para>
-            </section>
-        </section>
     
         <section>
             <title><classname>LifecycleManager</classname> design (Axiom 1.3)</title>

Added: webservices/axiom/trunk/src/site/markdown/design/index.md
URL: http://svn.apache.org/viewvc/webservices/axiom/trunk/src/site/markdown/design/index.md?rev=1719800&view=auto
==============================================================================
--- webservices/axiom/trunk/src/site/markdown/design/index.md (added)
+++ webservices/axiom/trunk/src/site/markdown/design/index.md Sun Dec 13 14:06:03 2015
@@ -0,0 +1,25 @@
+<!--
+  ~ Licensed to the Apache Software Foundation (ASF) under one
+  ~ or more contributor license agreements. See the NOTICE file
+  ~ distributed with this work for additional information
+  ~ regarding copyright ownership. The ASF licenses this file
+  ~ to you under the Apache License, Version 2.0 (the
+  ~ "License"); you may not use this file except in compliance
+  ~ with the License. You may obtain a copy of the License at
+  ~
+  ~ http://www.apache.org/licenses/LICENSE-2.0
+  ~
+  ~ Unless required by applicable law or agreed to in writing,
+  ~ software distributed under the License is distributed on an
+  ~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+  ~ KIND, either express or implied. See the License for the
+  ~ specific language governing permissions and limitations
+  ~ under the License.
+  -->
+
+Design documents
+================
+
+| Title/link | Status |
+| ---------- | ------ |
+| [OSGi integration and separation between API and implementation](osgi-integration.html) | Implemented |

Added: webservices/axiom/trunk/src/site/markdown/design/osgi-integration.md
URL: http://svn.apache.org/viewvc/webservices/axiom/trunk/src/site/markdown/design/osgi-integration.md?rev=1719800&view=auto
==============================================================================
--- webservices/axiom/trunk/src/site/markdown/design/osgi-integration.md (added)
+++ webservices/axiom/trunk/src/site/markdown/design/osgi-integration.md Sun Dec 13 14:06:03 2015
@@ -0,0 +1,408 @@
+<!--
+  ~ Licensed to the Apache Software Foundation (ASF) under one
+  ~ or more contributor license agreements. See the NOTICE file
+  ~ distributed with this work for additional information
+  ~ regarding copyright ownership. The ASF licenses this file
+  ~ to you under the Apache License, Version 2.0 (the
+  ~ "License"); you may not use this file except in compliance
+  ~ with the License. You may obtain a copy of the License at
+  ~
+  ~ http://www.apache.org/licenses/LICENSE-2.0
+  ~
+  ~ Unless required by applicable law or agreed to in writing,
+  ~ software distributed under the License is distributed on an
+  ~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+  ~ KIND, either express or implied. See the License for the
+  ~ specific language governing permissions and limitations
+  ~ under the License.
+  -->
+
+OSGi integration and separation between API and implementation
+==============================================================
+
+## Introduction
+
+This section addresses two related architectural questions:
+
+*   OSGi support was originally introduced in Axiom 1.2.9, but the implementation had
+    a couple of flaws. This section discusses the rationale behind the new OSGi
+    support introduced in Axiom 1.2.13.
+
+*   Axiom is designed as a set of abstract APIs for which two implementations are
+    provided: LLOM and DOOM. It is important to make a clear distinction between what
+    is part of the public API and what should be considered implementation classes that
+    must not be used by application code directly. This also implies that Axiom must
+    provide the necessary APIs to allow application code to access all features without
+    the need to access implementation classes directly. This section in particular
+    discusses the question how application code can request factories that support DOM
+    without the need to refer directly to DOOM.
+
+These two questions are closely related because OSGi allows to enforce the distinction
+between public API and implementation classes by carefully selecting the packages
+exported by the different bundles: only classes belonging to the public API
+should be exported, while implementation classes should be private to the bundles
+containing them. This in turn has implications for the packaging of these artifacts.
+
+## Requirements
+
+<a name="req1"/>
+
+**Requirement 1**: *The Axiom artifacts SHOULD be usable both as normal JAR files and as OSGi bundles.*
+
+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.
+
+<a name="req2"/>
+
+**Requirement 2**: *All APIs defined by the `axiom-api` module, and in particular the
+`OMAbstractFactory` API MUST continue to work as expected in an OSGi environment, so that code
+in downstream projects doesn't need to be rewritten.*
+
+This requirement was already satisfied by the OSGi support introduced in Axiom 1.2.9.
+It therefore also ensures that the transition to the new OSGi support in Axiom 1.2.13
+is transparent for applications that already use Axiom in an OSGi container.
+
+<a name="req3"/>
+
+**Requirement 3**: *`OMAbstractFactory` 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 `OMMetaFactory`
+implementation: in an OSGi environment, selecting an implementation class using
+a system property is not meaningful.*
+
+<a name="req4"/>
+
+**Requirement 4**: *Only classes belonging to the public API should be exported by the OSGi bundles.
+Implementation classes should not be exported. In particular,
+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.
+An exception MAY be made for factory classes related to foreign APIs, such as the
+`DocumentBuilderFactory` implementation for an Axiom implementation
+supporting DOM.*
+
+When the Axiom artifacts are used as normal JAR files in a Maven build, this requirement implies that
+they should be used in scope `runtime`.
+
+Although this requirement is easy to implement for the Axiom project, it requires
+changes to downstreams project to make this actually work:
+
+*   As explained in [AXIS2-4902](https://issues.apache.org/jira/browse/AXIS2-4902),
+    there used to be many places in Axis2 that still referred directly to Axiom implementation classes.
+    The same was true for Rampart and Sandesha2. This has now been fixed and all three projects
+    use `axiom-impl` and `axiom-dom` as dependencies in scope
+    `runtime`.
+
+*   Abdera extends the LLOM implementation. Probably, some `maven-shade-plugin`
+    magic will be required here to create Abdera OSGi bundles that work properly with
+    the Axiom bundles.
+
+*   For Spring Web Services this issue is addressed by
+    [SWS-822](https://jira.springsource.org/browse/SWS-822).
+
+<a name="req5"/>
+
+**Requirement 5**: *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 `axiom-impl`
+and `axiom-dom` bundles. It MUST be possible to replace `axiom-impl`
+(resp. `axiom-dom`) 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.*
+
+This requirement has several important implications:
+
+*   It restricts the allowable exceptions to [Requirement 4](#req4).
+
+*   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.
+
+*   In accordance with [Requirement 2](#req2) and [Requirement 3](#req3)
+    this requirement not only applies to an OSGi environment, but extends to non OSGi environments as well.
+
+**Requirement 6**: *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.*
+
+Currently there are at least two projects that create their own modified Axiom bundles:
+
+*   Apache Geronimo has a custom Axiom bundle to support the Axis2 integration.
+
+*   ServiceMix also has a custom bundles for Axiom. However, this bundle only seem to exist to
+    support their own custom Abdera bundle, which is basically an incorrect repackaging of the
+    original Abdera code. See
+    [SMX4-877](https://issues.apache.org/jira/browse/SMX4-877) for more details.
+
+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 [Requirement 4](#req4).
+Nevertheless, Axiom must provide the necessary APIs and features to meet the needs
+of these projects.
+
+<a name="req7"/>
+
+**Requirement 7**: *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).*
+
+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 [Requirement 8](#req8) is satisfied.
+
+<a name="req8"/>
+
+**Requirement 8**: *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.*
+
+<a name="req9"/>
+
+**Requirement 9**: *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.*
+
+Axiom is designed around an abstract API and allows for the existence of multiple
+independent implementations. A factory (`OMAbstractFactory`) is used to
+locate and instantiate the desired implementation. This is similar to APIs such as
+JAXP (`DocumentBuilderFactory`, etc.) and JAXB (`JAXBContext`).
+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.
+
+It should be noted that because of the way the Axiom API is designed and taking into account
+[Requirement 2](#req2), 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 simply expose itself as an OSGi service (of type `OMMetaFactory` 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 [Requirement 2](#req2).
+
+**Non-Requirement 1**: *APIs such as JAXP and JAXB have been designed from the start for inclusion into the JRE.
+They need to support scenarios where an application bundles its own implementation
+(e.g. an application may package a version of Apache Xerces, which would then be
+instantiated by the `newInstance` method in
+`DocumentBuilderFactory`). That implies that the selected implementation
+depends on the thread context class loader. It is assumed that there is no such requirement
+for Axiom, which means that in a non OSGi environment, the Axiom implementations are always loaded from the same
+class loader as the `axiom-api` JAR.*
+
+This (non-)requirement is actually not directly relevant for the OSGi support, but it
+nevertheless has some importance because of [Requirement 3](#req3)
+(which implies that the OSGi support needs to be designed in parallel with the implementation
+discovery strategy applicable in a non OSGi environment).
+
+## Analysis of the Geronimo JAXB bundles
+
+As noted in [Requirement 9](#req9) the Apache Geronimo has successfully
+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: 
+`org.apache.geronimo.specs:geronimo-jaxb_2.2_spec:1.0.1` (called the "API bundle" hereafter),
+`org.apache.geronimo.bundles:jaxb-impl:2.2.3-1_1` (the "implementation bundle"),
+`org.apache.geronimo.specs:geronimo-osgi-locator:1.0` (the "locator bundle") and
+`org.apache.geronimo.specs:geronimo-osgi-registry:1.0` (the "registry bundle"):
+
+*   The implementation bundle retains the `META-INF/services/javax.xml.bind.JAXBContext`
+    resource from the original artifact (`com.sun.xml.bind:jaxb-impl`).
+    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 [Requirement 1](#req1).
+
+*   The manifest of the implementation bundle has an attribute `SPI-Provider: true` that indicates
+    that it contains provider implementations that are discovered using the JDK 1.3 service discovery.
+
+*   The registry bundle creates a `BundleTracker` that looks for
+    the `SPI-Provider` attribute in active bundles. For each bundle
+    that has this attribute set to `true`, it will scan the content of
+    `META-INF/services` 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 for the present discussion).
+
+*   The `ContextFinder` class (the interface of which is defined by
+    the JAXB specification and that is used by the `newInstance`
+    method in `JAXBContext`) in the API bundle delegates the discovery
+    of the SPI implementation to a static method of the `ProviderLocator`
+    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.
+
+    The build is configured (using a `Private-Package` instruction)
+    such that the classes of the locator bundle are actually included into the API bundle, thus
+    avoiding an additional dependency.
+
+*   The `ProviderLocator` 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 `ProviderLocator`
+    class using a bundle activator.
+
+*   Finally, it should also be noted that the API bundle is configured with `singleton=true`.
+    There is indeed no meaningful way how providers could be matched with different versions of the same API
+    bundle.
+
+This is an example of a particularly elegant way to satisfy [Requirement 1](#req1),
+[Requirement 2](#req2) and [Requirement 3](#req3), especially because
+it relies on the same metadata (the `META-INF/services/javax.xml.bind.JAXBContext` resources)
+in OSGi and non OSGi environments.
+
+Obviously, Axiom could reuse the registry and locator bundles developed by Geronimo. This however would
+contradict [Requirement 7](#req7). 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.
+
+## New abstract APIs
+
+Application code rarely uses DOOM as the default Axiom implementation. Several downstream projects
+(e.g. the Axis2/Rampart combination) use both the default (LLOM) implementation and DOOM. They select
+the implementation based on the particular context. As of Axiom 1.2.12, the only way to create an object
+model instance with the DOOM implementation is to use the `DOOMAbstractFactory` API
+or to instantiate one of the factory classes (`OMDOMMetaFactory`, `OMDOMFactory`
+or one of the subclasses of `DOMSOAPFactory`). All these classes are part of
+the `axiom-dom` artifact. This is clearly in contradiction with [Requirement 4](#req4)
+and [Requirement 5](#req5).
+
+To overcome this problem the Axiom API must be enhanced to make it possible to select an Axiom
+implementation based on capabilities/features requested by the application code. E.g. in the case
+of DOOM, the application code would request a factory that implements the DOM API. It is then up
+to the Axiom API classes to locate an appropriate implementation, which may be DOOM or another
+drop-in replacement, as per [Requirement 5](#req5).
+
+If multiple Axiom implementations are available (on the class path in non OSGi environment or
+deployed as bundles in an OSGi environment), then the Axiom API must also be able to select an
+appropriate default implementation if no specific feature is requested by the application code.
+This can be easily implemented by defining a special feature called "default" that would be
+declared by any Axiom implementation that is suitable as a default implementation.
+
+**Note:** DOOM is generally not considered suitable as a default implementation because it doesn't
+implement the complete Axiom API (e.g. it doesn't support `OMSourcedElement`).
+In addition, in earlier versions of Axiom, the factory classes for DOOM were not stateless
+(see [AXIOM-412](https://issues.apache.org/jira/browse/AXIOM-412)).
+
+Finally, to make the selection algorithm deterministic, there should also be a concept
+of priority: if multiple Axiom implementations are found for the same feature, then the Axiom API
+would select the one with the highest priority.
+
+This leads to the following design:
+
+1.  Every Axiom implementation declares a set of features that it supports. A feature is
+    simply identified by a string. Two features are predefined by the Axiom API:
+
+    *   `default`: indicates that the implementation is a complete
+        implementation of the Axiom API and may be used as a default implementation.
+    *   `dom`: indicates that the implementation supports DOM
+        in addition to the Axiom API.
+
+    For every feature it declares, the Axiom implementation specifies a priority,
+    which is a positive integer.
+
+2.  The relevant Axiom APIs are enhanced so that they take an optional argument
+    specifying the feature requested by the application code. If no explicit feature
+    is requested, then Axiom will use the `default` feature.
+
+3.  To determine the `OMMetaFactory` to be used, Axiom locates
+    the implementations declaring the requested feature and selects the one that
+    has the highest priority for that feature.
+
+A remaining question is how the implementation declares the feature/priority information.
+There are two options:
+
+*   Add a method to `OMMetaFactory` that allows the Axiom API
+    to query the feature/priority information from the implementation (i.e. the
+    features and priorities are hardcoded in the implementation).
+
+*   Let the implementation provide this information declaratively in its metadata
+    (either in the manifest or in a separate resource with a well defined name).
+    Note that in a non OSGi environment, such a metadata resource must be used anyway
+    to enable the Axiom API to locate the `OMMetaFactory` implementations.
+    Therefore this would be a natural place to declare the features as well.
+
+The second option has the advantage to make it easier for users to debug and tweak
+the implementation discovery process (e.g. there may be a need to
+customize the features and priorities declared by the different implementations to ensure
+that the right implementation is chosen in a particular use case).
+
+This leads to the following design decision:
+the features and priorities (together with the class name of the `OMMetaFactory`
+implementation) will be defined in an XML descriptor with resource name `META-INF/axiom.xml`.
+The format of that descriptor must take into account that a single JAR may contain several
+Axiom implementations (e.g. if the JAR is an uber-JAR repackaged from the standard Axiom JARs).
+
+## Common implementation classes
+
+Obviously the LLOM and DOOM implementations share some amount of common code. Historically,
+implementation classes reusable between LLOM and DOOM were placed in `axiom-api`.
+This however tends to blur the distinction between the public API and implementation classes.
+Starting with Axiom 1.2.13 such classes are placed into a separate module called
+`axiom-common-impl`. However, `axiom-common-impl` cannot simply
+be a dependency of `axiom-impl` and `axiom-dom`.
+The reason is that in an OSGi environment, the `axiom-common-impl` bundle
+would have to export these shared classes, which is in contradiction with [Requirement 4](#req4).
+Therefore the code from `axiom-common-impl` needs to be packaged into
+`axiom-impl` and `axiom-dom` by the build process so that
+the `axiom-common-impl` artifact is not required at runtime.
+[Requirement 1](#req1) forbids using embedded JARs to achieve this.
+Instead `maven-shade-plugin` is used to include the classes
+from `axiom-common-impl` into `axiom-impl` and `axiom-dom`
+(and to modify the POMs to remove the dependencies on `axiom-common-impl`).
+
+This raises the question whether `maven-shade-plugin` should be configured to
+simply copy the classes or to relocate them (i.e. to change their package names). There are a couple
+of arguments in favor of relocating them:
+
+*   According to [Requirement 1](#req1), the Axiom artifacts should be
+    usable both as normal JARs and as OSGi bundles. Obviously the expectation is that from the
+    point of view of application code, they should work in the same in OSGi and non OSGi environments.
+    Relocation is required if one wants to strictly satisfy this requirement even if different versions
+    of `axiom-impl` and `axiom-dom` are mixed.
+    Since the container creates separate class loaders for the `axiom-impl` and `axiom-dom` bundles,
+    it is always possible to do that in an OSGi environment: even if the shared classes
+    included in `axiom-impl` and `axiom-dom` are
+    not relocated, but have the same names, this will not result in conflicts.
+    The situation is different in a non OSGi environment where the classes in `axiom-impl`
+    and `axiom-dom` are loaded by the same class loader. If the shared classes
+    are not relocated, then there may be a conflict if the versions don't match.
+
+    However, in practice it is unlikely that there are valid use case where one would use
+    `axiom-impl` and `axiom-dom` artifacts from different Axiom versions.
+
+*   Relocation allows to preserve compatibility when duplicate code from
+    `axiom-impl` and `axiom-dom` is merged and moved
+    to `axiom-common-impl`. The `OMNamespaceImpl`,
+    `OMNavigator` and `OMStAXWrapper` classes
+    from `axiom-impl` and the `NamespaceImpl`,
+    `DOMNavigator` and `DOMStAXWrapper`
+    classes from `axiom-dom` that existed in earlier versions of Axiom
+    are examples of this. The classes in `axiom-dom` were almost identical
+    to the corresponding classes in `axiom-impl`. These classes have been
+    merged and moved to `axiom-common-impl`. Relocation then allows them
+    to retain their original name (including the original package name) in the
+    `axiom-impl` and `axiom-dom` artifacts.
+
+    However, this is only a concern if one wants to preserve compatibility with existing
+    code that directly uses these implementation specific classes (which is something that is
+    strongly discouraged). One example where this was relevant was the SAAJ implementation
+    in Axis2 which used to be very strongly coupled to the DOOM implementation. This however
+    has been fixed now.
+
+Using relocation also has some serious disadvantages:
+
+*   Stack traces may contain class names that don't match class names in the Axiom source
+    code, making debugging harder.
+
+*   Axiom now uses JaCoCo to produce code coverage reports. However these reports are
+    incomplete if relocation is used. This doesn't affect test cases executed in
+    the `axiom-impl` and `axiom-dom` modules
+    (because they are executed with the original classes), but tests in separate modules
+    (such as integration tests). There are actually two issues:
+
+    *   For the relocated classes, JaCoCo is unable to find the corresponding source code.
+        This means that the reported code coverage is inaccurate for classes in
+        `axiom-common-impl`.
+    *   Relocation not only modifies the classes in `axiom-common-impl`, but
+        also the classes in `axiom-impl` and `axiom-dom`
+        that use them. JaCoCo [detects this](https://github.com/jacoco/jacoco/issues/51)
+        and excludes the data from the coverage analysis. This means that the
+        reported code coverage will also be inaccurate for classes in
+        `axiom-impl` and `axiom-dom`.
+
+In Axiom 1.2.14 relocation was used, but this has been changed in Axiom 1.2.15 because the disadvantages
+outweigh the advantages.

Modified: webservices/axiom/trunk/src/site/site.xml
URL: http://svn.apache.org/viewvc/webservices/axiom/trunk/src/site/site.xml?rev=1719800&r1=1719799&r2=1719800&view=diff
==============================================================================
--- webservices/axiom/trunk/src/site/site.xml (original)
+++ webservices/axiom/trunk/src/site/site.xml Sun Dec 13 14:06:03 2015
@@ -58,6 +58,9 @@
             <item name="Quick start samples" href="quickstart-samples.html"/>
             <item name="User guide" href="userguide/userguide.html"/>
             <item name="Developer guide" href="devguide/devguide.html"/>
+            <item name="Design documents" collapse="true" href="design/index.html">
+                <item name="OSGi integration" href="design/osgi-integration.html"/>
+            </item>
             <item name="Articles" href="articles.html"/>
             <item name="Javadocs" href="/apidocs/index.html"/>
             <item name="FAQ" href="faq.html"/>



Mime
View raw message