Author: veithen
Date: Tue Jun 10 16:55:43 2014
New Revision: 1601685
URL: http://svn.apache.org/r1601685
Log:
Make the user and dev guides conform to DocBook 5.
Modified:
webservices/axiom/trunk/devguide/src/docbkx/devguide.xml
webservices/axiom/trunk/userguide/src/docbkx/userguide.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=1601685&r1=1601684&r2=1601685&view=diff
==============================================================================
--- webservices/axiom/trunk/devguide/src/docbkx/devguide.xml (original)
+++ webservices/axiom/trunk/devguide/src/docbkx/devguide.xml Tue Jun 10
16:55:43 2014
@@ -19,7 +19,7 @@
~ under the License.
-->
<book>
- <bookinfo>
+ <info>
<title>Axiom Developer Guide</title>
<releaseinfo>&version;</releaseinfo>
@@ -31,7 +31,7 @@
this file except in compliance with the License. You may
obtain a copy of the License at
</para>
<para>
- <ulink url="http://www.apache.org/licenses/LICENSE-2.0"/>
+ <link xlink:href="http://www.apache.org/licenses/LICENSE-2.0"/>
</para>
<para>
Unless required by applicable law or agreed to in writing,
software distributed under the License is
@@ -40,7 +40,7 @@
License.
</para>
</legalnotice>
- </bookinfo>
+ </info>
<toc/>
@@ -67,7 +67,7 @@
was the intention to split the
<filename>axiom-tests</filename> project into several parts
and make them part of <filename>axiom-api</filename>,
<filename>axiom-impl</filename> and
<filename>axiom-dom</filename>. This reorganization is not
complete
- yet<footnote><para>See <ulink
url="https://issues.apache.org/jira/browse/AXIOM-311";>AXIOM-311</ulink>.</para></footnote>.
+ yet<footnote><para>See <link
xlink:href="https://issues.apache.org/jira/browse/AXIOM-311";>AXIOM-311</link>.</para></footnote>.
For new test cases (or when refactoring existing tests),
the following guidelines should be applied:
</para>
<orderedlist>
@@ -78,7 +78,7 @@
This primarily applies to tests that validate
utility classes in <filename>axiom-api</filename>.
</para>
</listitem>
- <listitem id="test.category.api">
+ <listitem xml:id="test.category.api">
<para>
The code of unit tests that apply to all Axiom
implementations and that check conformance
to the specifications of the Axiom API should be
added
@@ -134,7 +134,7 @@
<listitem>
<para>
The reference implementation was written by
BEA and is available as Maven artifact
- <literal>stax:stax:1.2.0</literal>. The
homepage is <ulink url="http://stax.codehaus.org/Home"/>.
+ <literal>stax:stax:1.2.0</literal>. The
homepage is <link xlink:href="http://stax.codehaus.org/Home"/>.
Note that the JAR doesn't contain the
necessary files to enable service discovery.
Geronimo's implementation of the StAX API
library will not be able to locate
the reference implementation unless the
following system properties are set:
@@ -151,12 +151,12 @@ javax.xml.stream.XMLOutputFactory=com.be
and is part of IBM's JRE/JDK v6. Note that due
to an agreement between IBM and Sun, IBM's
Java implementation for the Windows
platform is not available as a separate
download, but only bundled with another
- IBM product, e.g. <ulink
url="http://www.ibm.com/developerworks/downloads/ws/wasdevelopers/";>WebSphere
- Application Server for Developers</ulink>.
+ IBM product, e.g. <link
xlink:href="http://www.ibm.com/developerworks/downloads/ws/wasdevelopers/";>WebSphere
+ Application Server for Developers</link>.
</para>
<para>
On the other hand, the JDK for Linux can be
downloaded as a separate package from the
- <link
url="https://www.ibm.com/developerworks/java/jdk/linux/download.html";>developerWorks
+ <link
xlink:href="https://www.ibm.com/developerworks/java/jdk/linux/download.html";>developerWorks
site</link>. There are versions for 32-bit x86
(<quote>xSeries</quote>) and 64-bit AMD.
They are available as RPMs and tarballs. To
install the JDK properly on a Debian
based system (including Ubuntu), follow the
instructions given in
@@ -207,7 +207,7 @@ javax.xml.stream.XMLOutputFactory=com.be
</section>
<section>
<title>Requirements</title>
- <formalpara id="osgi-req-no-separate-bundles">
+ <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.
@@ -220,7 +220,7 @@ javax.xml.stream.XMLOutputFactory=com.be
It should also be noted that the Geronimo Spec artifacts
also meet this requirement.
</para>
</note>
- <formalpara id="osgi-req-same-api">
+ <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
@@ -236,7 +236,7 @@ javax.xml.stream.XMLOutputFactory=com.be
is transparent for applications that already use Axiom in
an OSGi container.
</para>
</note>
- <formalpara id="osgi-req-same-impl-selection">
+ <formalpara xml:id="osgi-req-same-impl-selection">
<title>Requirement 3</title>
<para>
<classname>OMAbstractFactory</classname> MUST select the
same implementation
@@ -246,7 +246,7 @@ javax.xml.stream.XMLOutputFactory=com.be
a system property is not meaningful.
</para>
</formalpara>
- <formalpara id="osgi-ref-impl-not-exported">
+ <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.
@@ -255,8 +255,6 @@ javax.xml.stream.XMLOutputFactory=com.be
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.
@@ -274,7 +272,7 @@ javax.xml.stream.XMLOutputFactory=com.be
<itemizedlist>
<listitem>
<para>
- As explained in <ulink
url="https://issues.apache.org/jira/browse/AXIS2-4902";>AXIS2-4902</ulink>,
+ 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
@@ -291,12 +289,12 @@ javax.xml.stream.XMLOutputFactory=com.be
<listitem>
<para>
For Spring Web Services this issue is addressed by
- <ulink
url="https://jira.springsource.org/browse/SWS-822";>SWS-822</ulink>.
+ <link
xlink:href="https://jira.springsource.org/browse/SWS-822";>SWS-822</link>.
</para>
</listitem>
</itemizedlist>
</note>
- <formalpara id="osgi-req-dropin">
+ <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
@@ -354,7 +352,7 @@ javax.xml.stream.XMLOutputFactory=com.be
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
- <ulink
url="https://issues.apache.org/jira/browse/SMX4-877";>SMX4-877</ulink> for more
details.
+ <link
xlink:href="https://issues.apache.org/jira/browse/SMX4-877";>SMX4-877</link> for
more details.
</para>
</listitem>
</itemizedlist>
@@ -366,7 +364,7 @@ javax.xml.stream.XMLOutputFactory=com.be
of these projects.
</para>
</note>
- <formalpara id="osgi-reg-no-framework">
+ <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
@@ -382,7 +380,7 @@ javax.xml.stream.XMLOutputFactory=com.be
having such code, provided that <xref
linkend="osgi-req-no-osgi-dep"/> is satisfied.
</para>
</note>
- <formalpara id="osgi-req-no-osgi-dep">
+ <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
@@ -390,7 +388,7 @@ javax.xml.stream.XMLOutputFactory=com.be
ever loaded in a non OSGi environment.
</para>
</formalpara>
- <formalpara id="osgi-req-best-practices">
+ <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
@@ -552,7 +550,7 @@ javax.xml.stream.XMLOutputFactory=com.be
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 <ulink
url="https://issues.apache.org/jira/browse/AXIOM-412";>AXIOM-412</ulink>).
+ (see <link
xlink:href="https://issues.apache.org/jira/browse/AXIOM-412";>AXIOM-412</link>).
</para>
</note>
<para>
@@ -738,7 +736,7 @@ javax.xml.stream.XMLOutputFactory=com.be
<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 <ulink
url="https://github.com/jacoco/jacoco/issues/51";>detects this</ulink>
+ 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>.
@@ -784,17 +782,17 @@ javax.xml.stream.XMLOutputFactory=com.be
</listitem>
<listitem>
<para>
- One of the stated design goals (see <ulink
url="https://issues.apache.org/jira/browse/AXIOM-192";>AXIOM-192</ulink>)
+ One of the stated design goals (see <link
xlink:href="https://issues.apache.org/jira/browse/AXIOM-192";>AXIOM-192</link>)
of the <classname>LifecycleManager</classname> API was
to wrap the files in <classname>FileAccessor</classname> objects to
<quote>keep track of activity that occurs on the
files</quote>. However, as pointed out in
- <ulink
url="https://issues.apache.org/jira/browse/AXIOM-185";>AXIOM-185</ulink>, since
+ <link
xlink:href="https://issues.apache.org/jira/browse/AXIOM-185";>AXIOM-185</link>,
since
<classname>FileAccessor</classname> has a method that
returns the corresponding <classname>File</classname>
object, this goal has not been reached.
</para>
</listitem>
<listitem>
<para>
- As noted in <ulink
url="https://issues.apache.org/jira/browse/AXIOM-382";>AXIOM-382</ulink>, the
fact
+ As noted in <link
xlink:href="https://issues.apache.org/jira/browse/AXIOM-382";>AXIOM-382</link>,
the fact
that <classname>LifecycleManagerImpl</classname>
registers a shutdown hook which is never unregistered
causes a class loader leak in J2EE environments.
</para>
@@ -802,7 +800,7 @@ javax.xml.stream.XMLOutputFactory=com.be
<listitem>
<para>
In an attempt to work around the issues related to
<classname>LifecycleManager</classname> (in particular
- the first item above), <ulink
url="https://issues.apache.org/jira/browse/AXIOM-185";>AXIOM-185</ulink>
+ the first item above), <link
xlink:href="https://issues.apache.org/jira/browse/AXIOM-185";>AXIOM-185</link>
introduced another class called
<classname>AttachmentCacheMonitor</classname> that implements a timer
based mechanism to clean up temporary files. However,
this change causes other issues:
</para>
@@ -825,7 +823,7 @@ javax.xml.stream.XMLOutputFactory=com.be
</itemizedlist>
<para>
Fortunately, that change was only meant as a
workaround to solve a particular issue in WebSphere
- (see APAR <ulink
url="http://www-01.ibm.com/support/docview.wss?rs=180&uid=swg1PK91497";>PK91497</ulink>),
+ (see APAR <link
xlink:href="http://www-01.ibm.com/support/docview.wss?rs=180&uid=swg1PK91497";>PK91497</link>),
and once the <classname>LifecycleManager</classname>
API is redesigned to solve that issue,
<classname>AttachmentCacheMonitor</classname> no
longer has a reason to exist.
</para>
@@ -899,7 +897,7 @@ javax.xml.stream.XMLOutputFactory=com.be
To satisfy the second condition, one may want to use
<methodname>File#deleteOnExit</methodname>.
However, this method causes a native memory leak, especially
when used with temporary files,
which are expected to have unique names (see
- <ulink
url="http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=4513817";>bug
4513817</ulink>).
+ <link
xlink:href="http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=4513817";>bug
4513817</link>).
Therefore this can only be implemented using a shutdown hook.
However, a shutdown hook will
cause a class loader leak if it is used improperly, e.g. if it
is registered by an application deployed
into a J2EE container and not unregistered when that
application is stopped. For this
@@ -950,7 +948,7 @@ javax.xml.stream.XMLOutputFactory=com.be
to contain utility classes that don't depend on higher
level APIs. More precisely,
<package>org.apache.axiom.util</package> should only
have dependencies on
<package>org.apache.axiom.ext</package>, but not e.g.
on <package>org.apache.axiom.om</package>.
- <ulink
url="http://www.hello2morrow.com/products/sonarj";>SonarJ</ulink> can be used
+ <link
xlink:href="http://www.hello2morrow.com/products/sonarj";>SonarJ</link> can be
used
to check these dependencies. The following figure
shows the expected structure:
</para>
<figure>
@@ -974,7 +972,7 @@ javax.xml.stream.XMLOutputFactory=com.be
</mediaobject>
</figure>
<para>
- The check can also be done using <ulink
url="http://mojo.codehaus.org/jdepend-maven-plugin/";>jdepend-maven-plugin</ulink>.
+ The check can also be done using <link
xlink:href="http://mojo.codehaus.org/jdepend-maven-plugin/";>jdepend-maven-plugin</link>.
To do this, execute the following command in the
<filename>axiom-api</filename> module:
</para>
<screen>mvn jdepend:generate</screen>
@@ -1008,8 +1006,8 @@ javax.xml.stream.XMLOutputFactory=com.be
<listitem>
<para>
Check that the Maven site conforms to the latest
version of the
- <ulink
url="http://apache.org/foundation/marks/pmcs";>Apache Project
- Branding Guidelines</ulink>.
+ <link
xlink:href="http://apache.org/foundation/marks/pmcs";>Apache Project
+ Branding Guidelines</link>.
</para>
</listitem>
<listitem>
@@ -1059,8 +1057,8 @@ javax.xml.stream.XMLOutputFactory=com.be
<itemizedlist>
<listitem>
<para>
- A PGP key that conforms to the <ulink
url="http://www.apache.org/dev/release-signing.html";>requirement
- for Apache release signing</ulink>. To make the
release process easier, the passphrase for the
+ A PGP key that conforms to the <link
xlink:href="http://www.apache.org/dev/release-signing.html";>requirement
+ for Apache release signing</link>. To make the release
process easier, the passphrase for the
code signing key should be configured in
<filename>${user.home}/.m2/settings.xml</filename>:
</para>
<screen><![CDATA[<settings>
@@ -1100,7 +1098,7 @@ javax.xml.stream.XMLOutputFactory=com.be
On Unix systems this will work out of the box if you
have SSH installed, a public key installed
on <literal>people.apache.org</literal> and your user
name is the same on your local system and
<literal>people.apache.org</literal>. If this is not
the case, some additional configuration will be
- required, as described in <ulink
url="http://maven.apache.org/plugins/maven-deploy-plugin/examples/deploy-ssh-external.html"/>.
+ required, as described in <link
xlink:href="http://maven.apache.org/plugins/maven-deploy-plugin/examples/deploy-ssh-external.html"/>.
</para>
</listitem>
</itemizedlist>
@@ -1152,9 +1150,9 @@ javax.xml.stream.XMLOutputFactory=com.be
</step>
<step>
<para>
- Log in to the Nexus repository (<ulink
url="https://repository.apache.org/"/>
+ Log in to the Nexus repository (<link
xlink:href="https://repository.apache.org/"/>
and close the staging repository. The name of the
staging profile is
- <literal>org.apache.ws</literal>. See <ulink
url="http://maven.apache.org/developers/release/apache-release.html"/>
+ <literal>org.apache.ws</literal>. See <link
xlink:href="http://maven.apache.org/developers/release/apache-release.html"/>
for a more thorough description of this step.
</para>
</step>
@@ -1224,7 +1222,7 @@ javax.xml.stream.XMLOutputFactory=com.be
<step>
<para>
Promote the artifacts in the staging repository. See
- <ulink
url="http://maven.apache.org/developers/release/apache-release.html"/>
+ <link
xlink:href="http://maven.apache.org/developers/release/apache-release.html"/>
for detailed instructions for this step.
</para>
</step>
@@ -1277,12 +1275,12 @@ python <replaceable>path_to_etc</replace
</listitem>
<listitem>
<para>
- the Maven site has been synchronized to <ulink
url="http://ws.apache.org/axiom/"/>;
+ the Maven site has been synchronized to <link
xlink:href="http://ws.apache.org/axiom/"/>;
</para>
</listitem>
<listitem>
<para>
- the binary and source distributions can be downloaded
from <ulink url="http://ws.apache.org/axiom/download.cgi"/>.
+ the binary and source distributions can be downloaded
from <link xlink:href="http://ws.apache.org/axiom/download.cgi"/>.
</para>
</listitem>
</itemizedlist>
@@ -1382,22 +1380,22 @@ python <replaceable>path_to_etc</replace
<itemizedlist>
<listitem>
<para>
- <ulink
url="http://www.apache.org/legal/src-headers.html";>ASF Source Header and
Copyright Notice Policy</ulink>
+ <link
xlink:href="http://www.apache.org/legal/src-headers.html";>ASF Source Header and
Copyright Notice Policy</link>
</para>
</listitem>
<listitem>
<para>
- <ulink
url="http://apache.org/foundation/marks/pmcs";>Apache Project Branding
Guidelines</ulink>
+ <link
xlink:href="http://apache.org/foundation/marks/pmcs";>Apache Project Branding
Guidelines</link>
</para>
</listitem>
<listitem>
<para>
- <ulink url="http://projects.apache.org/doap.html";>DOAP
Files</ulink>
+ <link
xlink:href="http://projects.apache.org/doap.html";>DOAP Files</link>
</para>
</listitem>
<listitem>
<para>
- <ulink
url="http://www.apache.org/dev/release-publishing.html";>Publishing
Releases</ulink>
+ <link
xlink:href="http://www.apache.org/dev/release-publishing.html";>Publishing
Releases</link>
</para>
</listitem>
</itemizedlist>
@@ -1406,7 +1404,7 @@ python <replaceable>path_to_etc</replace
<appendix>
<title>Appendix</title>
- <section id="install.ibm.jdk">
+ <section xml:id="install.ibm.jdk">
<title>Installing IBM's JDK on Debian Linux</title>
<procedure>
<step>
@@ -1419,7 +1417,7 @@ python <replaceable>path_to_etc</replace
<step>
<para>
Download the <filename>.tgz</filename> version of the
JDK from
- <ulink
url="http://www.ibm.com/developerworks/java/jdk/linux/download.html"/>.
+ <link
xlink:href="http://www.ibm.com/developerworks/java/jdk/linux/download.html"/>.
</para>
</step>
<step>
Modified: webservices/axiom/trunk/userguide/src/docbkx/userguide.xml
URL:
http://svn.apache.org/viewvc/webservices/axiom/trunk/userguide/src/docbkx/userguide.xml?rev=1601685&r1=1601684&r2=1601685&view=diff
==============================================================================
--- webservices/axiom/trunk/userguide/src/docbkx/userguide.xml (original)
+++ webservices/axiom/trunk/userguide/src/docbkx/userguide.xml Tue Jun 10
16:55:43 2014
@@ -19,7 +19,7 @@
~ under the License.
-->
<book>
- <bookinfo>
+ <info>
<title>Axiom User Guide</title>
<releaseinfo>&version;
</releaseinfo>
@@ -32,7 +32,7 @@
this file except in compliance with the License. You may
obtain a copy of the License at
</para>
<para>
- <ulink url="http://www.apache.org/licenses/LICENSE-2.0"/>
+ <link xlink:href="http://www.apache.org/licenses/LICENSE-2.0"/>
</para>
<para>
Unless required by applicable law or agreed to in writing,
software distributed under the License is
@@ -41,7 +41,7 @@
License.
</para>
</legalnotice>
- </bookinfo>
+ </info>
<toc/>
@@ -54,7 +54,7 @@
that is initially developed for Apache Axis2. XML infoset
refers to the information included inside the
XML, and for programmatic manipulation it is convenient to
have a representation of this XML infoset in
a language specific manner. For an object oriented language
the obvious choice is a model made up of
- objects. <ulink url="http://www.w3.org/DOM/";>DOM</ulink> and
<ulink url="http://www.jdom.org/";>JDOM</ulink>
+ objects. <link xlink:href="http://www.w3.org/DOM/";>DOM</link>
and <link xlink:href="http://www.jdom.org/";>JDOM</link>
are two such XML models. Axiom is conceptually similar to such
an XML model by its external behavior but
deep down it is very much different. The objective of this
tutorial is to introduce the basics of Axiom and
explain the best practices to be followed while using Axiom.
However, before diving in to the deep end of
@@ -67,8 +67,8 @@
This tutorial can be used by anyone who is interested in Axiom
and needs to
gain a deeper knowledge about the model. However, it is
assumed that the
reader has a basic understanding of the concepts of XML (such
as
- <ulink
src="http://www.w3.org/TR/REC-xml-names/";>Namespaces</ulink>) and a working
- knowledge of tools such as <ulink
href="http://ant.apache.org/";>Ant</ulink>.
+ <link
xlink:href="http://www.w3.org/TR/REC-xml-names/";>Namespaces</link>) and a
working
+ knowledge of tools such as <link
xlink:href="http://ant.apache.org/";>Ant</link>.
Knowledge in similar object models such as DOM will be quite
helpful in
understanding Axiom, mainly to highlight the differences and
similarities
between the two, but such knowledge is not assumed. Several
links are listed
@@ -81,8 +81,8 @@
<para>
Pull parsing is a recent trend in XML processing. The
previously popular XML
processing frameworks such as
- <ulink
url="http://en.wikipedia.org/wiki/Simple_API_for_XML";>SAX</ulink> and
- <ulink
url="http://en.wikipedia.org/wiki/Document_Object_Model";>DOM</ulink> were
+ <link
xlink:href="http://en.wikipedia.org/wiki/Simple_API_for_XML";>SAX</link> and
+ <link
xlink:href="http://en.wikipedia.org/wiki/Document_Object_Model";>DOM</link> were
"push-based" which means the control of the parsing was in the
hands of the
parser itself. This approach is fine and easy to use, but it
was not
efficient in handling large XML documents since a complete
memory model will
@@ -90,8 +90,8 @@
parser only proceeds at the users command. The user can decide
to store or
discard events generated from the parser. Axiom is based on
pull parsing. To
learn more about XML pull parsing see the
- <ulink
url="http://www.bearcave.com/software/java/xml/xmlpull.html";>XML pull
- parsing introduction</ulink>.
+ <link
xlink:href="http://www.bearcave.com/software/java/xml/xmlpull.html";>XML pull
+ parsing introduction</link>.
</para>
</section>
<section>
@@ -102,7 +102,7 @@
The original OM was proposed as a store for the pull parser
events for
later processing, at the Axis summit held in Colombo, Sri
Lanka, in September
2004. However, this approach was soon improved and OM was
pursued as a
- complete <ulink url="http://dret.net/glossary/xmlinfoset";>XML
infoset</ulink> model
+ complete <link
xlink:href="http://dret.net/glossary/xmlinfoset";>XML infoset</link> model
due to its flexibility. Several implementation techniques were
attempted
during the initial phases. The two most promising techniques
were the table
based technique and the link list based technique. During the
intermediate
@@ -116,7 +116,7 @@
tight integration was evident at this stage and this resulted
in having SOAP
specific interfaces as part of OM rather than a layer on top
of it. OM was
deliberately made
- <ulink
url="http://en.wikipedia.org/wiki/Application_programming_interface";>API</ulink>
+ <link
xlink:href="http://en.wikipedia.org/wiki/Application_programming_interface";>API</link>
centric. It allows the implementations to take place
independently and
swapped without affecting the program later.
</para>
@@ -127,7 +127,7 @@
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
+ <link xlink:href="http://www.jdom.org/";>JDOM</link>), but
underneath, the objects will be
created only when they are absolutely required. This leads to
much less
memory intensive programming. Following is a short feature
overview of OM.
</para>
@@ -170,8 +170,8 @@
<section>
<title>Relation with StAX</title>
<para>
- <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.
+ <link
xlink:href="http://today.java.net/pub/a/today/2006/07/20/introduction-to-stax.html";>StAX</link>
+ (<link
xlink:href="http://www.jcp.org/en/jsr/detail?id=173";>JSR 173</link>) 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
@@ -196,7 +196,7 @@
<section>
<title>Where Does SOAP Come into Play?</title>
<para>
- In a nutshell <ulink
url="http://www.w3schools.com/SOAP/soap_intro.asp";>SOAP</ulink> is an
+ In a nutshell <link
xlink:href="http://www.w3schools.com/SOAP/soap_intro.asp";>SOAP</link> is an
information exchange protocol based on XML. SOAP has a defined
set of XML
elements that should be used in messages. Since Axis2 is a
"SOAP Engine" and
Axiom is built for Axis2, a set of SOAP specific objects were
also defined along
@@ -224,7 +224,7 @@
<listitem>
<para>
A prebuilt binary distribution can be
- <ulink
url="http://ws.apache.org/axiom/download.cgi";>downloaded</ulink>
+ <link
xlink:href="http://ws.apache.org/axiom/download.cgi";>downloaded</link>
from the site. Source distributions are also
available. They can be built
using Maven 2, by executing <command>mvn
install</command> in the root
directory of the distribution.
@@ -236,7 +236,7 @@
version (trunk) or previous releases from the
Subversion repository and build it
using Maven 2. Detailed information on getting the
source code
from the Subversion repository is found
- <ulink
url="http://ws.apache.org/axiom/source-repository.html";>here</ulink>.
+ <link
xlink:href="http://ws.apache.org/axiom/source-repository.html";>here</link>.
</para>
</listitem>
</orderedlist>
@@ -261,7 +261,7 @@
The reason for this is to cater for different implementations
of the Axiom API,
as shown in <xref linkend="fig_api"/>.
</para>
- <figure id="fig_api">
+ <figure xml:id="fig_api">
<title>The Axiom API with different implementations</title>
<mediaobject>
<imageobject>
@@ -293,7 +293,7 @@
factory for plain XML. <xref linkend="list2"/> shows how this
factory is used to create
several <classname>OMElement</classname> instances.
</para>
- <example id="list2">
+ <example xml:id="list2">
<title>Creating an object model programmatically</title>
<programlisting>//create a factory
OMFactory factory = OMAbstractFactory.getOMFactory();
@@ -317,7 +317,7 @@ public void addAttribute(OMAttribute att
<xref linkend="ex-addChild"/> shows how this method is used to
assemble the three elements
created in <xref linkend="list2"/> into a tree structure.
</para>
- <example id="ex-addChild">
+ <example xml:id="ex-addChild">
<title>Usage of <methodname>addChild</methodname></title>
<programlisting>//set the children
elt11.addChild(elt21);
@@ -357,7 +357,7 @@ root.addChild(elt12);</programlisting>
This approach is still supported as well.
</para>
</note>
- <example id="list1">
+ <example xml:id="list1">
<title>Creating an object model from an input stream</title>
<programlisting>//create the input stream
InputStream in = new FileInputStream(file);
@@ -439,7 +439,7 @@ public OMNamespace findNamespace(String
<para>
The following simple code segment shows how the namespaces are
dealt in OM
</para>
- <example id="list6">
+ <example xml:id="list6">
<title>Creating an OM document with namespaces</title>
<programlisting>OMFactory factory = OMAbstractFactory.getOMFactory();
OMNamespace ns1 = factory.createOMNamespace("bar","x");
@@ -492,7 +492,7 @@ while(children.hasNext()){
</para>
</important>
</section>
- <section id="serializer">
+ <section xml:id="serializer">
<title>Serializer</title>
<para>
An Axiom tree can be serialized either as the pure object
model or the pull event
@@ -588,7 +588,7 @@ OMElement documentElement = builder.getD
//dump the out put to console with caching
System.out.println(documentElement.toStringWithConsume());</programlisting>
</section>
- <section id="StAXUtils">
+ <section xml:id="StAXUtils">
<title>Creating stream readers and writers using
<classname>StAXUtils</classname></title>
<para>
The normal way to create
<classname>XMLStreamReader</classname> and
@@ -621,7 +621,7 @@ System.out.println(documentElement.toStr
Therefore, when using Axiom versions prior to 1.2.9, you
should avoid using <classname>StAXUtils</classname>
together with a StAX implementation other than Woodstox,
especially in a highly
concurrent environment. The issue has been fixed in Axiom
1.2.9. See
- <ulink
url="https://issues.apache.org/jira/browse/AXIOM-74";>AXIOM-74</ulink>
+ <link
xlink:href="https://issues.apache.org/jira/browse/AXIOM-74";>AXIOM-74</link>
for more details.
</para>
</caution>
@@ -763,7 +763,7 @@ try {
sequence of events. Starting with Axiom 1.2.8, the object
model builder
will never attempt to read new events from a parser that
has previously reported
an I/O or parsing error. These versions of Axiom are
therefore safe; see
- <ulink
url="https://issues.apache.org/jira/browse/AXIOM-34";>AXIOM-34</ulink>
+ <link
xlink:href="https://issues.apache.org/jira/browse/AXIOM-34";>AXIOM-34</link>
for more details.
</para>
</caution>
@@ -780,7 +780,7 @@ try {
</section>
</chapter>
- <chapter id="advanced">
+ <chapter xml:id="advanced">
<title>Advanced Operations with Axiom</title>
<section>
<title>Accessing the Pull Parser</title>
@@ -819,13 +819,13 @@ try {
<chapter>
<title>Integrating Axiom into your project</title>
- <section id="using-maven2">
+ <section xml:id="using-maven2">
<title>Using Axiom in a Maven 2 project</title>
<section>
<title>Adding Axiom as a dependency</title>
<para>
If your project uses Maven 2, it is fairly easy to add
Axiom to your project.
- Simply add the following entries to the <sgmltag
class="element">dependencies</sgmltag>
+ Simply add the following entries to the <tag
class="element">dependencies</tag>
section of <filename>pom.xml</filename>:
</para>
<programlisting><![CDATA[<dependency>
@@ -840,7 +840,7 @@ try {
</dependency>]]></programlisting>
<para>
All Axiom releases are deployed to the Maven central
repository and there is no need
- to add an entry to the <sgmltag
class="element">repositories</sgmltag> section.
+ to add an entry to the <tag
class="element">repositories</tag> section.
However, if you want to work with the development
(snapshot) version of Axiom, it
is necessary to add the Apache Snapshot Repository:
</para>
@@ -865,9 +865,9 @@ try {
<para>
Axiom requires the Java Activation Framework (JAF) and the
JavaMail API to work. There are two
commonly used incarnations of these libraries: one is
Sun's reference implementation, the other
- is part of the <ulink
url="http://geronimo.apache.org/";>Geronimo</ulink> project. Axiom declares
+ is part of the <link
xlink:href="http://geronimo.apache.org/";>Geronimo</link> project. Axiom declares
dependencies on the Geronimo versions (though that might
- <ulink
url="https://issues.apache.org/jira/browse/AXIOM-319";>change</ulink> in the
future).
+ <link
xlink:href="https://issues.apache.org/jira/browse/AXIOM-319";>change</link> in
the future).
If your project uses another library that depends on JAF
and/or JavaMail, but that refers
to Sun's implementation, your project will end up with
dependencies on two different
artifacts implementing the same API.
@@ -917,7 +917,7 @@ try {
and/or property files. This is also important when using third
party applications or
libraries that depend on Axiom.
</para>
- <section id="factory.properties">
+ <section xml:id="factory.properties">
<title>Changing the default StAX factory settings</title>
<note>
<para>
@@ -964,7 +964,7 @@ try {
</para>
<para>
The only way to strictly preserve CR characters is to
serialize them as
- character entities, i.e. <sgmltag
class="genentity">#xD</sgmltag>. This is the default
+ character entities, i.e. <tag
class="genentity">#xD</tag>. This is the default
behavior of Woodstox. This can be easily checked using
the following Java snippet:
</para>
<programlisting>OMFactory factory = OMAbstractFactory.getOMFactory();
@@ -991,7 +991,7 @@ with CRLF</root>]]></screen>
</note>
<para>
In some cases this behavior may be
undesirable<footnote><para>See
- <ulink
url="http://jira.codehaus.org/browse/WSTX-94";>WSTX-94</ulink> for a discussion
+ <link
xlink:href="http://jira.codehaus.org/browse/WSTX-94";>WSTX-94</link> for a
discussion
about this.</para></footnote>. Fortunately Woodstox
allows to modify this behavior
by changing the value of the
<varname>com.ctc.wstx.outputEscapeCr</varname> property
on the <classname>XMLOutputFactory</classname>. If
Axiom is used (and in particular
@@ -1131,8 +1131,8 @@ with CRLF</root>]]></screen>
</listitem>
</orderedlist>
<para>
- As explained in <ulink
url="https://issues.apache.org/jira/browse/AXIOM-255";>AXIOM-255</ulink>
- and <ulink
url="https://issues.apache.org/jira/browse/AXIOM-122";>AXIOM-122</ulink>,
+ As explained in <link
xlink:href="https://issues.apache.org/jira/browse/AXIOM-255";>AXIOM-255</link>
+ and <link
xlink:href="https://issues.apache.org/jira/browse/AXIOM-122";>AXIOM-122</link>,
in Axiom 1.2.8, the type of stream reader provided by
the API was not always well defined.
Sometimes the type of the stream reader even depended
on the state of the Axiom tree
(i.e. whether some part of it has been accessed or
not).
@@ -1147,9 +1147,9 @@ with CRLF</root>]]></screen>
</para>
</section>
</section>
- <section id="changes-1.2.11">
+ <section xml:id="changes-1.2.11">
<title>Changes in Axiom 1.2.11</title>
- <section id="OMXMLBuilderFactory">
+ <section xml:id="OMXMLBuilderFactory">
<title>Resurrection of the
<classname>OMXMLBuilderFactory</classname> API</title>
<para>
Historically,
<classname>org.apache.axiom.om.impl.llom.factory.OMXMLBuilderFactory</classname>
was used to
@@ -1182,7 +1182,7 @@ with CRLF</root>]]></screen>
migration should be easy.
</para>
</section>
- <section id="iterator-changes">
+ <section xml:id="iterator-changes">
<title>Changes in the behavior of certain iterators</title>
<para>
In Axiom 1.2.10 and previous versions, iterators
returned by methods such as <methodname>OMIterator#getChildren()</methodname>
@@ -1235,7 +1235,7 @@ while (iterator.hasNext()) {
</para>
</section>
</section>
- <section id="changes-1.2.13">
+ <section xml:id="changes-1.2.13">
<title>Changes in Axiom 1.2.13</title>
<section>
<title>Handling of illegal namespace declarations</title>
@@ -1354,8 +1354,8 @@ while (iterator.hasNext()) {
<section>
<title>Usage of Apache James Mime4J as MIME parser</title>
<para>
- Starting with version 1.2.13, Axiom uses <ulink
url="http://james.apache.org/mime4j/";>Apache
- James Mime4J</ulink> as MIME parser implementation
instead of its own custom parser
+ Starting with version 1.2.13, Axiom uses <link
xlink:href="http://james.apache.org/mime4j/";>Apache
+ James Mime4J</link> as MIME parser implementation
instead of its own custom parser
implementation. The public API as defined by the
<classname>Attachments</classname> class
remains unchanged, with the following exceptions:
</para>
@@ -1440,7 +1440,7 @@ while (iterator.hasNext()) {
</itemizedlist>
</section>
</section>
- <section id="changes-1.2.14">
+ <section xml:id="changes-1.2.14">
<title>Changes in Axiom 1.2.14</title>
<section>
<title>Upgrade of Woodstox</title>
@@ -1464,7 +1464,7 @@ while (iterator.hasNext()) {
</para>
<para>
For more information about the new semantics, refer to
the Javadoc of <classname>DOMMetaFactory</classname>
- and to <ulink
url="https://issues.apache.org/jira/browse/AXIOM-412";>AXIOM-412</ulink>.
+ and to <link
xlink:href="https://issues.apache.org/jira/browse/AXIOM-412";>AXIOM-412</link>.
</para>
</section>
<section>
@@ -1477,7 +1477,7 @@ while (iterator.hasNext()) {
</para>
</section>
</section>
- <section id="changes-1.2.15">
+ <section xml:id="changes-1.2.15">
<title>Changes in Axiom 1.2.15</title>
<section>
<title>Removal of the JavaMail dependency</title>
@@ -1526,11 +1526,11 @@ public InputStream getInputStream() thro
<methodname>getInputStream</methodname>
<quote>destructive</quote>. Consider
the implementation shown in <xref
linkend="InputStreamDataSource"/><footnote><para>The example
shown is actually a simplified version of code that is
- <ulink
url="http://svn.apache.org/repos/asf/axis/axis2/java/core/tags/v1.5/modules/kernel/src/org/apache/axis2/builder/unknowncontent/InputStreamDataSource.java";>part
of Axis2 1.5</ulink>.</para></footnote>.
+ <link
xlink:href="http://svn.apache.org/repos/asf/axis/axis2/java/core/tags/v1.5/modules/kernel/src/org/apache/axis2/builder/unknowncontent/InputStreamDataSource.java";>part
of Axis2 1.5</link>.</para></footnote>.
It is clear that this data source can only be read once and
that any subsequent call to
<methodname>getInputStream</methodname> will return an already
closed input stream.
</para>
- <example id="InputStreamDataSource">
+ <example xml:id="InputStreamDataSource">
<title><classname>DataSource</classname> implementation that
violates the interface contract</title>
<programlisting>public class InputStreamDataSource implements DataSource {
private final InputStream is;
@@ -1566,7 +1566,7 @@ public InputStream getInputStream() thro
</para>
<para>
Imagine for example<footnote><para>For another example, see
- <ulink
url="http://markmail.org/thread/omx7umk5fnpb6dnc"/>.</para></footnote>
+ <link
xlink:href="http://markmail.org/thread/omx7umk5fnpb6dnc"/>.</para></footnote>
that the implementation shown above is used to produce an
MTOM message. At first this will work without any problems
because the data
source is read only once when serializing the message. If
later on the MTOM
@@ -1664,9 +1664,9 @@ public InputStream getInputStream() thro
<classname>XMLStreamReader</classname> provided by
<methodname>OMElement#getXMLStreamReader()</methodname>.
For example, older versions of ADB
(Axis2 Data Binding) used the following
code<footnote><para>For the complete
- code, see <ulink
url="http://svn.apache.org/repos/asf/axis/axis2/java/core/tags/v1.5/modules/adb/src/org/apache/axis2/databinding/ADBDataSource.java"/>.</para></footnote>:
+ code, see <link
xlink:href="http://svn.apache.org/repos/asf/axis/axis2/java/core/tags/v1.5/modules/adb/src/org/apache/axis2/databinding/ADBDataSource.java"/>.</para></footnote>:
</para>
- <example id="adb-getReader">
+ <example xml:id="adb-getReader">
<title><methodname>OMDataSource#getReader()</methodname>
implementation used in older ADB versions</title>
<programlisting>public XMLStreamReader getReader() throws XMLStreamException {
MTOMAwareOMBuilder mtomAwareOMBuilder = new MTOMAwareOMBuilder();
@@ -1728,7 +1728,7 @@ public InputStream getInputStream() thro
<para>
The <methodname>getReader</methodname> method also
uses an intermediary
Axiom tree<footnote><para>See e.g.
- <ulink
url="http://svn.apache.org/repos/asf/axis/axis2/java/core/tags/v1.5/modules/kernel/src/org/apache/axis2/builder/unknowncontent/UnknownContentOMDataSource.java"/>.</para></footnote>.
+ <link
xlink:href="http://svn.apache.org/repos/asf/axis/axis2/java/core/tags/v1.5/modules/kernel/src/org/apache/axis2/builder/unknowncontent/UnknownContentOMDataSource.java"/>.</para></footnote>.
In that case it doesn't make sense to use an
<classname>OMSourcedElement</classname>
in the first place! At least it doesn't make sense
if one assumes that
in general the
<classname>OMSourcedElement</classname> will either be
@@ -1754,7 +1754,7 @@ public InputStream getInputStream() thro
</section>
</chapter>
- <chapter id="appendix">
+ <chapter xml:id="appendix">
<title>Appendix</title>
<section>
<title>Program Listing for Build and Serialize</title>
@@ -1793,7 +1793,7 @@ public class TestOMBuilder {
}
}</programlisting>
</section>
- <section id="links">
+ <section xml:id="links">
<title>Links</title>
<para>
For basics in XML
@@ -1801,27 +1801,27 @@ public class TestOMBuilder {
<itemizedlist>
<listitem>
<para>
- <ulink
url="http://www-128.ibm.com/developerworks/xml/newto/index.html";>Developerworks
Introduction to XML</ulink>
+ <link
xlink:href="http://www-128.ibm.com/developerworks/xml/newto/index.html";>Developerworks
Introduction to XML</link>
</para>
</listitem>
<listitem>
<para>
- <ulink
url="http://www.bearcave.com/software/java/xml/xmlpull.html";>Introduction to
Pull parsing</ulink>
+ <link
xlink:href="http://www.bearcave.com/software/java/xml/xmlpull.html";>Introduction
to Pull parsing</link>
</para>
</listitem>
<listitem>
<para>
- <ulink
url="http://today.java.net/pub/a/today/2006/07/20/introduction-to-stax.html";>Introduction
to StAX</ulink>
+ <link
xlink:href="http://today.java.net/pub/a/today/2006/07/20/introduction-to-stax.html";>Introduction
to StAX</link>
</para>
</listitem>
<listitem>
<para>
- <ulink
url="http://www.jaxmag.com/itr/online_artikel/psecom,id,726,nodeid,147.html";>Fast
and Lightweight Object Model for XML</ulink>
+ <link
xlink:href="http://www.jaxmag.com/itr/online_artikel/psecom,id,726,nodeid,147.html";>Fast
and Lightweight Object Model for XML</link>
</para>
</listitem>
<listitem>
<para>
- <ulink
url="http://www-128.ibm.com/developerworks/library/x-axiom/";>Get the most out
of XML processing with AXIOM</ulink>
+ <link
xlink:href="http://www-128.ibm.com/developerworks/library/x-axiom/";>Get the
most out of XML processing with AXIOM</link>
</para>
</listitem>
</itemizedlist>
@@ -1832,21 +1832,21 @@ public class TestOMBuilder {
<title>References</title>
<bibliodiv>
<title>Specifications</title>
- <biblioentry id="bib.xml">
+ <biblioentry xml:id="bib.xml">
<abbrev>XML</abbrev>
- <title><ulink
url="http://www.w3.org/TR/2008/REC-xml-20081126/";>Extensible Markup Language
(XML) 1.0 (Fifth Edition)</ulink></title>
+ <title><link
xlink:href="http://www.w3.org/TR/2008/REC-xml-20081126/";>Extensible Markup
Language (XML) 1.0 (Fifth Edition)</link></title>
<publishername>W3C Recommendation</publishername>
<pubdate>26 November 2008</pubdate>
</biblioentry>
- <biblioentry id="bib.xmlns">
+ <biblioentry xml:id="bib.xmlns">
<abbrev>XMLNS</abbrev>
- <title><ulink
url="http://www.w3.org/TR/2009/REC-xml-names-20091208/";>Namespaces in XML 1.0
(Third Edition)</ulink></title>
+ <title><link
xlink:href="http://www.w3.org/TR/2009/REC-xml-names-20091208/";>Namespaces in
XML 1.0 (Third Edition)</link></title>
<publishername>W3C Recommendation</publishername>
<pubdate>8 December 2009</pubdate>
</biblioentry>
- <biblioentry id="bib.xmlns11">
+ <biblioentry xml:id="bib.xmlns11">
<abbrev>XMLNS11</abbrev>
- <title><ulink
url="http://www.w3.org/TR/2006/REC-xml-names11-20060816/";>Namespaces in XML 1.1
(Second Edition)</ulink></title>
+ <title><link
xlink:href="http://www.w3.org/TR/2006/REC-xml-names11-20060816/";>Namespaces in
XML 1.1 (Second Edition)</link></title>
<publishername>W3C Recommendation</publishername>
<pubdate>16 August 2006</pubdate>
</biblioentry>
