Introduction

This page summarizes the planned changes for the next major release, i.e. Axiom 1.3. Note that it is not intended as a wish list for new features, but identifies a set of changes that break backward compatibility and therefore need to be postponed to the 1.3 release.

The overall goals for the 1.3 are:

  • Upgrade the API to Java 5, i.e. make use of generics.
  • Eliminate deprecated APIs and utility classes.
  • Eliminate remaining API inconsistencies.
  • Make the API more compact by clarifying the separation between the public API and implementation classes and moving implementation classes out of axiom-api.

API inconsistencies to be eliminated

Usage of Object instead of DataHandler

There are several APIs that use Object although they expect or return a DataHandler. This is probably a legacy of Axis 1.x where the Activation API was an optional dependency. Today this no longer makes sense:

  • The Activation API is included in Java 6.
  • It is unlikely that Axiom actually works if Activation is not in the class path because there is nothing in the build that enforces or tests that and there are no known downstream projects that use Axiom without also depending on the Activation API.

The following APIs will be changed to use DataHandler directly:

  • OMText#getDataHandler()
  • OMFactory#createOMText(Object, boolean)

Methods declared by the wrong interface in the node type hierarchy

Some methods are declared at the wrong level in the node type hierarchy so that they may be called on nodes for which they are not meaningful:

  • The serialize and serializeAndConsume methods that take an OutputStream or Writer object are only meaningful for OMContainer objects. However, they are declared by OMNode. Note that already in 1.2.x, these methods are deprecated.
  • OMContainer declares several methods that return child elements by name: getChildrenWithLocalName, getChildrenWithName, getChildrenWithNamespaceURI and getFirstChildWithName. Since the document element is unique, these methods are not meaningful for OMDocument and they should be declared by OMElement instead.

Removal of unnecessary or irrelevant APIs

This section identifies APIs that have become unnecessary or irrelevant. Note that APIs that have already been deprecated in 1.2.x (and will be removed in 1.3 anyway) are not listed here.

org.apache.axiom.om.OMAttachmentAccessor

In Axiom versions prior to 1.2.9, the sequence of events produced by the XMLStreamReader returned by getXMLStreamReaderWithoutCaching was inconsistent if the underlying stream is XOP encoded (see AXIOM-255). This made it necessary for application code to (partially) handle the XOP processing itself. That is the reason why the XMLStreamReader instance (which is an OMStAXWrapper) implements OMAttachmentAccessor: it allowed the application code to retrieve the binary content for undecoded xop:Include elements.

Starting with Axiom 1.2.9 the sequence of events produced by the XMLStreamReader is always the same (i.e. XOP is always completely decoded) and all binary content is reported through the DataHandlerReader extension, making the OMAttachmentAccessor API unnecessary in that context.

The interface is used in several other contexts as well, but it is actually unnecessary in each of them:

  • The Attachments class implements OMAttachmentAccessor. However, it is not possible to substitute an Attachments object by an arbitrary OMAttachmentAccessor instance (e.g. when parsing an XOP/MTOM message). This would actually be a useful feature, but in that particular context, there is an overlap with the MimePartProvider interface and that API would be better suited.
  • The OMAttachmentAccessor API is required in conjunction with the setInlineMTOM method defined by OMXMLStreamReader. However, that method is deprecated.
  • The XOPBuilder interface extends OMAttachmentAccessor. However, as explained below, that API will be removed in Axiom 1.3.

org.apache.axiom.om.impl.builder.BuilderAwareReader

This API can't be preserved as is in Axiom 1.3. There are two reasons for this:

  • The only method defined by the BuilderAwareReader interface has a parameter of type StAXBuilder, but that class will be removed from axiom-api (see below). The parameter type would have to be changed to OMXMLParserWrapper.
  • It the interface is considered a public API, then it is placed in the wrong package.

TODO: analyze the use cases for this API to see if we still need it

org.apache.axiom.om.impl.builder.XOPBuilder

The XOPBuilder interface is implemented by XOPAwareStAXOMBuilder and MTOMStAXSOAPModelBuilder. With the changes in r1164997 and r1207662, it is no longer used internally by Axiom. The interface declares methods that give access to the Attachments object that was used to create the builder. That is undesirable for two reasons:

  • For XOP/MTOM encoded messages, optimized binary data should always be accessed through the OMText API and not by accessing MIME parts directly through the Attachments API.
  • The existence of the XOPBuilder API (and in particular the getAttachments method defined by that interface) implies that an XOP/MTOM builder is necessarily created from an Attachments object. However, it may be desirable to support other ways to supply the MIME parts to the builder (e.g. using an implementation of the MimePartProvider API).

Therefore the XOPBuilder API will be removed in Axiom 1.3.

Classes to be moved from axiom-api to axiom-common-impl

Up to version 1.2.12, the core Axiom code was organized in three modules, namely axiom-api, axiom-impl and axiom-dom, where axiom-api contains both the public API as well as implementation classes shared by LLOM and DOOM. Unfortunately the distinction between the public API and these shared implementation classes has become somewhat blurred over time. In Axiom 1.2.13 a new module axiom-common-impl was introduced with the specific goal of separating the shared implementation classes from the public API. However, in Axiom 1.2.x this only applies to new code because in most cases it is not possible to move classes from axiom-api to axiom-common-impl without the risk of breaking existing code.

A new major release gives us the opportunity to move the existing shared classes to axiom-common-impl as well, so that in Axiom 1.3, axiom-api will only contain Axiom's public API. This is one of the important goals for Axiom 1.3 because it has multiple benefits:

  • The more compact the public API is, the easier it is for users to understand the API and to locate the features they are looking for.
  • By definition, anything that is not part of the public API can be modified without the risk of breaking application code. Clarifying the distinction between the public API and internal implementation classes therefore gives the project more flexibility to implement changes.
  • Having a well defined abstract API allows to create alternative implementations of that API.

This section identifies the classes and internal APIs that will be removed from axiom-api.

Builder implementations

In Axiom 1.2.13, the OMXMLBuilderFactory API allows to create any type of object model builder (plain XML, SOAP, XOP and MTOM). The API also defines two interfaces representing a builder: OMXMLParserWrapper and SOAPModelBuilder. This means that application code should no longer reference the builder implementation classes directly, but only OMXMLBuilderFactory, OMXMLParserWrapper and SOAPModelBuilder. In Axiom 1.3 the implementation classes can therefore be moved to axiom-common-impl. They are:

  • org.apache.axiom.om.impl.builder.StAXBuilder
  • org.apache.axiom.om.impl.builder.StAXOMBuilder
  • org.apache.axiom.om.impl.builder.XOPAwareStAXOMBuilder
  • org.apache.axiom.soap.impl.builder.StAXSOAPModelBuilder
  • org.apache.axiom.soap.impl.builder.MTOMStAXSOAPModelBuilder

TODO: there is one API that still references StAXBuilder, namely BuilderAwareReader; it needs to be changed (or removed)

Together with these classes, the following interfaces and helper classes should also be moved to axiom-common-impl:

  • TODO

Public APIs that need to be moved to another package

Some interfaces are part of the public API although they are placed in an impl package. These interfaces need to be moved to another package to make it clear that they are not internal or implementation specific interfaces:

  • org.apache.axiom.om.impl.builder.CustomBuilder

APIs that need to be overhauled

Attachment lifecycle manager

The LifecycleManager API has a couple of issues that can't be fixed without breaking backward compatibility:

  • There is some overlap with the AttachmentCacheMonitor class. There should be a single API to manage the lifecycle of buffered attachments.
  • LifecycleManager is an abstract API (interface), but refers to FileAccessor which is placed in an impl package.
  • FileAccessor uses the MessagingException class from JavaMail, although Axiom no longer relies on this API to parse or create MIME messages.