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/04 21:27:45 UTC
svn commit: r1178921 -
/webservices/commons/trunk/modules/axiom/src/docbkx/devguide.xml
Author: veithen
Date: Tue Oct 4 19:27:45 2011
New Revision: 1178921
URL: http://svn.apache.org/viewvc?rev=1178921&view=rev
Log:
More analysis around OSGi.
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=1178921&r1=1178920&r2=1178921&view=diff
==============================================================================
--- webservices/commons/trunk/modules/axiom/src/docbkx/devguide.xml (original)
+++ webservices/commons/trunk/modules/axiom/src/docbkx/devguide.xml Tue Oct 4 19:27:45 2011
@@ -249,7 +249,7 @@ javax.xml.stream.XMLOutputFactory=com.be
</listitem>
</itemizedlist>
</note>
- <formalpara>
+ <formalpara 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
@@ -362,7 +362,7 @@ javax.xml.stream.XMLOutputFactory=com.be
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.)
+ 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>
@@ -371,9 +371,106 @@ javax.xml.stream.XMLOutputFactory=com.be
<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
+ 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>)
+ and because the factory classes are not stateless.
+ </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>
</section>
</chapter>