When working with binary (base64) content, it is sometimes necessary to write a custom DataSource implementation to wrap binary data that is available in a different form (and for which Axiom or the Java Activation Framework has no out-of-the-box data source implementation). Data sources are also sometimes (but less frequently) used in conjunction with OMSourcedElement and OMDataSource.

The documentation of the DataSource is very clear on the expected behavior of the getInputStream method:

/**
 * This method returns an InputStream representing
 * the data and throws the appropriate exception if it can
 * not do so. Note that a new InputStream object must be
 * returned each time this method is called, and the stream must be
 * positioned at the beginning of the data.
 *
 * @return an InputStream
 */
public InputStream getInputStream() throws IOException;

A common mistake is to implement the data source in a way that makes getInputStream “destructive”. Consider the implementation shown in Example 5.1, “DataSource implementation that violates the interface contract”^[2]. It is clear that this data source can only be read once and that any subsequent call to getInputStream will return an already closed input stream.

public class InputStreamDataSource implements DataSource {
    private final InputStream is;

    public InputStreamDataSource(InputStream is) {
        this.is = is;
    }

    public String getContentType() {
        return "application/octet-stream";
    }

    public InputStream getInputStream() throws IOException {
        return is;
    }

    public String getName() {
        return null;
    }

    public OutputStream getOutputStream() throws IOException {
        throw new UnsupportedOperationException();
    }
}

What makes this mistake so vicious is that very likely it will not cause problems immediately. The reason is that Axiom is optimized to read the data only when necessary, which in most cases means only once! However, in some cases it is unavoidable to read the data several times. When that happens, the broken DataSource implementation will cause problems that may be extremely hard to debug.

Imagine for example^[3] 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 threshold feature is enabled, the broken implementation will (in the worst case) cause the corresponding MIME parts to be empty or (in the best case) trigger an I/O error because Axiom attempts to read from an already closed stream. The reason for this is that when an MTOM threshold is set, Axiom reads the data source twice: once to determine if its size exceeds the threshold^[4] and once during serialization of the message.

Quite frequently users post messages on the Axiom related mailing lists about issues that seem to disappear by “magic” when they try to debug them. The reason why this can happen is simple. As explained earlier, Axiom uses deferred building, but at the same time does its best to hide that from the user, so that he doesn't need to worry about whether the object model has already been built or not. On the other hand, when serializing the object model to XML or when requesting a pull parser (XMLStreamReader) from a node, the code paths taken may be radically different depending on whether or not the corresponding part of the tree has already been built. This is especially true when caching is disabled.

While the end result should be the same in all cases, it is also clear that in some circumstances an issue that occurs with an incompletely built tree may disappear if there is something that causes Axiom to build the rest of the object model. What is important to understand is that the “something” may be as trivial as a call to the toString method of an OMNode! The fact that adding System.out.println statements or logging instructions is a common debugging technique then explains why issues sometimes seem to “magically” disappear during debugging.

Finally, it should be noted that inspecting an OMNode in a debugger also causes a call to the toString method on that object. This means that by just clicking on something in the “Variables” window of your debugger, you may completely change the state of the process that is being debugged!