svn commit: r1150109 - /webservices/commons/trunk/modules/axiom/src/docbkx/userguide.xml

[ve...@apache.org]

Author: veithen
Date: Sat Jul 23 14:35:39 2011
New Revision: 1150109

URL: http://svn.apache.org/viewvc?rev=1150109&view=rev
Log:
AXIOM-372: Finalized the user guide section about illegal namespace bindings.

Modified:
    webservices/commons/trunk/modules/axiom/src/docbkx/userguide.xml

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=1150109&r1=1150108&r2=1150109&view=diff
==============================================================================
--- webservices/commons/trunk/modules/axiom/src/docbkx/userguide.xml (original)
+++ webservices/commons/trunk/modules/axiom/src/docbkx/userguide.xml Sat Jul 23 14:35:39 2011
@@ -1254,8 +1254,15 @@ while (iterator.hasNext()) {
                         </para>
                     </blockquote>
                     <para>
+                        In Axiom 1.2.12, the <methodname>declareNamespace</methodname> methods in <classname>OMElement</classname>
+                        didn't enforce this constraint and namespace declarations violating this requirement were silently
+                        dropped during serialization. This behavior is problematic because it may result in subtle issues
+                        such as unbound namespace prefixes. In Axiom 1.2.13 these methods have been changed so that they
+                        throw an exception if an attempt is made to bind the empty namespace name to a prefix.
+                    </para>                     
+                    <para>
                         In XML 1.1, prefixed namespace bindings may be empty, but rather than binding the empty namespace name
-                        to a prefix, such a namespace declaration "unbinds" the prefix, as explained in section 5
+                        to a prefix, such a namespace declaration "undeclares" the prefix, as explained in section 5
                         of <xref linkend="bib.xmlns11"/>:
                     </para>
                     <blockquote>
@@ -1267,7 +1274,21 @@ while (iterator.hasNext()) {
                             value in the innermost such declaration must not be an empty string.
                         </para>
                     </blockquote>
-                    
+                    <para>
+                        Although the same syntax is used in both cases, adding a namespace declaration to bind a prefix
+                        to a (non empty) namespace URI and adding a namespace declaration to undeclare a prefix are two
+                        fundamentally different operations from the point of view of the application. Therefore, to
+                        support prefix undeclaring for XML 1.1 infosets, a new method <methodname>undeclarePrefix</methodname>
+                        has been added to <classname>OMElement</classname> in Axiom 1.2.13.
+                    </para>
+                    <para>
+                        As a corollary of the above, neither XML 1.0 nor XML 1.1 allows creating prefixed elements or
+                        attributes with an empty namespace name. In Axiom 1.2.12, when attempting to create such invalid
+                        information items, the behavior was inconsistent: in some cases,
+                        the prefix was silently dropped, in other cases the invalid information item was actually created,
+                        resulting in problems during serialization. Axiom 1.2.13 consistently throws an exception when
+                        an attempt is made to create such an invalid information item.
+                    </para>
                 </section>
                 <section>
                     <title>New abstract APIs</title>