Author: veithen
Date: Sat Dec 3 19:04:56 2011
New Revision: 1209981
URL: http://svn.apache.org/viewvc?rev=1209981&view=rev
Log:
Clarified the relation between Axiom and StAX. Technically, nothing requires an
implementation of the Axiom API to use a StAX parser. The only constraints are
that the implementation must use a pull parser (otherwise it wouldn't be able
to support deferred building) and it must be able to expose the event stream
using the StAX API.
Modified:
webservices/commons/trunk/modules/axiom/src/docbkx/userguide.xml
webservices/commons/trunk/modules/axiom/src/site/apt/index.apt
Modified: webservices/commons/trunk/modules/axiom/src/docbkx/userguide.xml
URL:
http://svn.apache.org/viewvc/webservices/commons/trunk/modules/axiom/src/docbkx/userguide.xml?rev=1209981&r1=1209980&r2=1209981&view=diff
==============================================================================
--- webservices/commons/trunk/modules/axiom/src/docbkx/userguide.xml (original)
+++ webservices/commons/trunk/modules/axiom/src/docbkx/userguide.xml Sat Dec 3
19:04:56 2011
@@ -124,9 +124,8 @@
<section>
<title>Features of Axiom</title>
<para>
- Axiom is a lightweight, deferred built XML infoset
representation based on
- StAX (<ulink url="http://www.jcp.org/en/jsr/detail?id=173";>JSR
173</ulink>), which
- is the standard streaming pull parser API. The object model
can be
+ Axiom is a lightweight XML infoset representation that
supports deferred building
+ That means that the object model can be
manipulated as flexibly as any other object model (Such as
<ulink url="http://www.jdom.org/";>JDOM</ulink>), but
underneath, the objects will be
created only when they are absolutely required. This leads to
much less
@@ -152,19 +151,10 @@
<listitem>
<para>
<emphasis role="bold">Pull based</emphasis>: For a
deferred building mechanism a pull
- based parser is required. Axiom is based on
- <ulink
url="http://today.java.net/pub/a/today/2006/07/20/introduction-to-stax.html";>StAX</ulink>,
- the standard pull parser API.
+ based parser is required.
</para>
</listitem>
</itemizedlist>
- <important>
- <para>
- Axiom is tightly bound to StAX API. To work with Axiom
- a StAX compliant parser and the API
<emphasis>must</emphasis> be present in the
- classpath.
- </para>
- </important>
<para>
The Following image shows how Axiom API is viewed by the user
</para>
@@ -176,10 +166,17 @@
</imageobject>
</mediaobject>
</figure>
+ </section>
+ <section>
+ <title>Relation with StAX</title>
<para>
- OM Builder wraps the raw xml character stream through the StAX
reader API.
- Hence, the complexities of the pull event stream is
transparent to the
- user.
+ <ulink
url="http://today.java.net/pub/a/today/2006/07/20/introduction-to-stax.html";>StAX</ulink>
+ (<ulink url="http://www.jcp.org/en/jsr/detail?id=173";>JSR
173</ulink>) is the standard pull parser API for Java.
+ Axiom makes use of the StAX API to allow application code to
access the object model in streaming mode, which means
+ that application code can request an
<classname>XMLStreamReader</classname> for any document or element information
item.
+ In addition, support for deferred building relies on the usage
of a pull parser. The two standard implementations
+ of the Axiom API (LLOM and DOOM) both use the StAX API for
that. To work with these implementations, a StAX compliant
+ parser <emphasis>must</emphasis> be present in the classpath.
</para>
</section>
<section>
Modified: webservices/commons/trunk/modules/axiom/src/site/apt/index.apt
URL:
http://svn.apache.org/viewvc/webservices/commons/trunk/modules/axiom/src/site/apt/index.apt?rev=1209981&r1=1209980&r2=1209981&view=diff
==============================================================================
--- webservices/commons/trunk/modules/axiom/src/site/apt/index.apt (original)
+++ webservices/commons/trunk/modules/axiom/src/site/apt/index.apt Sat Dec 3
19:04:56 2011
@@ -21,10 +21,10 @@
Welcome to Apache Axiom
- The Apache Axiom\u2122 library provides a StAX-based, XML Infoset compliant
object model
+ The Apache Axiom\u2122 library provides an XML Infoset compliant object model
implementation which supports on-demand building
of the object tree. It supports a novel "pull-through" model which allows
one to turn off the tree
- building and directly access the underlying pull event stream. It also has
built in support for XML
+ building and directly access the underlying pull event stream using the StAX
API. It also has built in support for XML
Optimized Packaging (XOP) and MTOM, the combination of which allows XML to
carry binary data
efficiently and in a transparent manner. The combination of these is an easy
to use API with a very
high performant architecture!
