Section 2.11 of [XML] specifies that an “XML processor must behave as if it normalized all line breaks in external parsed entities (including the document entity) on input, before parsing, by translating both the two-character sequence #xD #xA and any #xD that is not followed by #xA to a single #xA character.” This implies that when a Windows style line ending, i.e. a CR-LF character sequence is serialized literally into an XML document, the CR character will be lost during deserialization. Depending on the use case this may or may not be desirable.

The only way to strictly preserve CR characters is to serialize them as character entities, i.e. 
. This is the default behavior of Woodstox. This can be easily checked using the following Java snippet:

OMFactory factory = OMAbstractFactory.getOMFactory();
OMElement element = factory.createOMElement("root", null);
element.setText("Test\r\nwith CRLF");
element.serialize(System.out);

This code produces the following output:

<root>Test&#xd;
with CRLF</root>

In some cases this behavior may be undesirable^[1]. Fortunately Woodstox allows to modify this behavior by changing the value of the com.ctc.wstx.outputEscapeCr property on the XMLOutputFactory. If Axiom is used (and in particular StAXUtils) than this can be achieved by adding a XMLOutputFactory.properties file with the following content to the classpath (in the default package):

com.ctc.wstx.outputEscapeCr=false

Now the output of the Java snippet shown above will be:

<root>Test
with CRLF</root>

By default, StAXUtils creates StAX parsers in coaelescing mode. In this mode, the parser will never return two character data events in sequence, while in non coaelescing mode, the parser is allowed to break up character data into smaller chunks and to return multiple consecutive character events, which may improve throughput for documents containing large text nodes. It should be noted that StAXUtils overrides the default settings mandated by the StAX specification, which specifies that by default, a StAX parser must be in non coalescing mode. The primary reason is compatibility: older versions of Woodstox had coalescing switched on by default.

A side effect of the default settings chosen by Axiom is that by default, CDATA sections are not reported by parser created by StAXUtils. The reason is that in coalescing mode, the parser will not only coaelsce adjacent text nodes, but also CDATA sections. Applications that require correct reporting of CDATA sections should therefore disable coalescing. This can be achieved by creating a XMLInputFactory.properties file with the following content:

javax.xml.stream.isCoalescing=false

Prior to Axiom 1.2.9, OMAbstractFactory used system properties as defined in the following table to determine the factory implementations to use:

This in principle allowed to mix default factory implementations from different implementations of the Axiom API (e.g. an OMFactory from the LLOM implementation and SOAP factories from DOOM). This however doesn't make sense. The system properties as described above are no longer supported in 1.2.9 and the default Axiom implementation is chosen using the new org.apache.axiom.om.OMMetaFactory system property. For LLOM, you should set:

org.apache.axiom.om.OMMetaFactory=org.apache.axiom.om.impl.llom.factory.OMLinkedListMetaFactory

This is the default and is equivalent to the defaults in 1.2.8. For DOOM, you should set:

org.apache.axiom.om.OMMetaFactory=org.apache.axiom.om.impl.dom.factory.OMDOMMetaFactory

In versions prior to 1.2.9, the XMLInputFactory and XMLOutputFactory instances returned by StAXUtils were mutable, i.e. it was possible to change the properties of these factories. This is obviously an issue since the factory instances are cached and can be shared among several thread. To avoid programming errors, starting from 1.2.9, the factories are immutable and any attempt to change their state will result in an IllegalStateException.

Note that the possibility to change the properties of these factories could be used to apply application wide settings. Starting with 1.2.9, Axiom has a proper mechanism to allow this. This feature is described in the section called “Changing the default StAX factory settings”.

In Axiom 1.2.8, XMLStreamReader instances provided by Axiom could belong to one of three different categories:

As explained in AXIOM-255 and AXIOM-122, 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).

In release 1.2.9 the behavior of Axiom was changed such that it never delivers XOP encoded data unless explicitly requested to do so. By default, any XMLStreamReader provided by Axiom now represents plain XML data and optionally implements the DataHandlerReader extension to retrieve optimized binary data. An XOP encoded stream can be requested from the getXOPEncodedStream method in XOPUtils.

Historically, org.apache.axiom.om.impl.llom.factory.OMXMLBuilderFactory was used to create Axiom trees from XML documents. Unfortunately, this class is located in the wrong package and JAR (it is implementation independent but belongs to LLOM). In Axiom 1.2.10, the standard way to create an Axiom tree was therefore to instantiate StAXOMBuilder or one of its subclasses directly. However, this is not optimal for two reasons:

Therefore, in Axiom 1.2.11, a new abstract API for creating builder instances was introduced. It is again called OMXMLBuilderFactory, but located in the org.apache.axiom.om package. The methods defined by this new API are similar to the ones in the original (now deprecated) OMXMLBuilderFactory, so that migration should be easy.

In Axiom 1.2.10 and previous versions, iterators returned by methods such as OMIterator#getChildren() internally stayed one step ahead of the node returned by the next() method. This meant that sometimes, using such an iterator had the side effect of building elements that were not intended to be built. In Axiom 1.2.11 this behavior was changed such that next() no longer builds the nodes it returns. In a few cases, this change may cause issues in existing code. One known instance is the following construct (which was used internally by Axiom itself):

while (children.hasNext()) { 
    OMNodeEx omNode = (OMNodeEx) children.next(); 
    omNode.internalSerializeAndConsume(writer); 
}

One would expect that the effect of this code is to consume the child nodes. However, in Axiom 1.2.10 this is not the case because next() actually builds the node. Note that the code actually doesn't make sense because once a child node has been consumed, it is no longer possible to retrieve the next sibling. Since in Axiom 1.2.11 the call to next() no longer builds the child node, this code will indeed trigger an exception.

Another example is the following piece of code which removes all child elements with a given name:

Iterator iterator = element.getChildrenWithName(qname);
while (iterator.hasNext()) {
    OMElement child = (OMElement)iterator.next();
    child.detach();
}

In Axiom 1.2.10 this works as expected. Indeed, since the iterator stays one node ahead, the current node can be safely removed using the detach() method. In Axiom 1.2.11, this is no longer the case and the following code (which also works with previous versions) should be used instead:

Iterator iterator = element.getChildrenWithName(qname);
while (iterator.hasNext()) {
    iterator.next();
    iterator.remove();
}

Note that this is actually compatible with the behavior of the Java 2 collection framework, where a ConcurrentModificationException may be thrown if a thread modifies a collection directly while it is iterating over the collection with an iterator.

In Axiom 1.2.12, the iterator implementations have been further improved to detect this situation and to throw a ConcurrentModificationException. This enables early detection of problematic usages of iterators.

Both XML 1.0 and XML 1.1 forbid binding a namespace prefix to the empty namespace name. Only the default namespace can have an empty namespace name. In XML 1.0, prefixed namespace bindings may not be empty, as explained in section 5 of [XMLNS]:

In Axiom 1.2.12, the declareNamespace methods in OMElement 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.

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 "undeclares" the prefix, as explained in section 5 of [XMLNS11]:

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 undeclarePrefix has been added to OMElement in Axiom 1.2.13.

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.

Methods that return an OMNamespace object may in principle use two different ways to represent the absence of a namespace: as a null value or as an OMNamespace instance that has both prefix and namespaceURI properties set to the empty string. This applies in particular to OMElement#getNamespace(), OMElement#getDefaultNamespace() and OMAttriute#getNamespace(). The API of Axiom 1.2.12 didn't clearly specify which representation was used, although in most cases a null value was used. As a consequence application code had to take into account the possibility that such methods returned OMNamespace instances with an empty prefix and namespace URI.

In Axiom 1.2.13 the situation has been clarified and the aforementioned APIs now always return null to indicate the absence of a namespace. Note that this may have an impact on flawed application code that doesn't handle null in the same way as an OMNamespace instance with an empty prefix and namespace URI. Such application code needs to be fixed to work correctly with Axiom 1.2.13.

Axiom 1.2.13 introduces a couple of new abstract APIs which give implementations of the Axiom API the freedom to do additional optimizations. Application code should be migrated to take advantage of these new APIs:

Note that some of the superseded APIs may disappear in Axiom 1.3.

Starting with version 1.2.13, Axiom uses Apache James Mime4J as MIME parser implementation instead of its own custom parser implementation. The public API as defined by the Attachments class remains unchanged, with the following exceptions:

Several internal classes related to the old MIME parsing code have been removed, are no longer public or have been changed in an incompatible way:

Although these classes were public, they are not considered part of the public API. Application code that depends on these classes needs to be rewritten before upgrading to Axiom 1.2.13.

When upgrading to 1.2.13, projects that use Axiom's XOP/MTOM features must make sure that Apache James Mime4J is added to the dependencies. For projects that use Maven (or tools that support Maven repositories and metadata) this happens automatically. Projects that use other build tools must explicity add the apache-mime4j-core library to the list of dependencies.

Axiom 1.2.13 has support for MIME part streaming. Pre-existing APIs continue to work as documented, but there are some minor changes in behavior that may be visible to code that makes assumptions that are not covered by the API contract: