Java^TM Architecture for XML Binding
JAXB RI Vendor Extensions
Runtime Properties

Marshaller Properties

The JAXB RI provides additional Marshaller properties that are not defined by the JAXB specification. These properties allow you to better control the marshalling process, but they only work with the JAXB RI; they may not work with other JAXB providers.

Index of Marshaller Properties

• Namespace Prefix Mapping
• Indentation
• Character Escaping Control
• XML Declaration Control

Namespace Prefix Mapping

The JAXB RI now provides a mechanism for mapping namespace URIs to prefixes. This is the general procedure:

1. The application developer provides an implementation of com.sun.xml.bind.marshaller.NamespacePrefixMapper.
2. This class is then set on the marshaller via the RI specific property com.sun.xml.bind.namespacePrefixMapper.
3. Each time the marshaller sees a URI, it performs a callback on the mapper: "What prefix do you want for this namespace URI?"
4. If the mapper returns something, the marshaller will try to use it.

The com.sun.xml.bind.marshaller.NamespacePrefixMapper class has the following method that you need to implement:

public abstract class NamespacePrefixMapper {
    /**
     * Returns a preferred prefix for the given namespace URI.
     * 
     * This method is intended to be overrided by a derived class.
     * 
     * @param namespaceUri
     *      The namespace URI for which the prefix needs to be found.
     *      Never be null. "" is used to denote the default namespace.
     * @param suggestion
     *      When the content tree has a suggestion for the prefix
     *      to the given namespaceUri, that suggestion is passed as a
     *      parameter. Typically this value comes from QName.getPrefix()
     *      to show the preference of the content tree. This parameter
     *      may be null, and this parameter may represent an already
     *      occupied prefix. 
     * @param requirePrefix
     *      If this method is expected to return non-empty prefix.
     *      When this flag is true, it means that the given namespace URI
     *      cannot be set as the default namespace.
     * 
     * @return
     *      null if there's no preferred prefix for the namespace URI.
     *      In this case, the system will generate a prefix for you.
     * 
     *      Otherwise the system will try to use the returned prefix,
     *      but generally there's no guarantee if the prefix will be
     *      actually used or not.
     * 
     *      return "" to map this namespace URI to the default namespace.
     *      Again, there's no guarantee that this preference will be
     *      honored.
     * 
     *      If this method returns "" when requirePrefix=true, the return
     *      value will be ignored and the system will generate one.
     */
    public abstract String getPreferredPrefix(String namespaceUri, String suggestion, boolean requirePrefix);
}

See the namespace-prefix sample application for a detailed example.

When this property is null, the following default implementation will be used.

    public String getPreferredPrefix(String namespaceUri, String suggestion, boolean requirePrefix) {
        return suggestion;
    }

Indentation

This property controls the string used for the indentation of XML. An element of depth k will be indented by printing this string k times. Note that the "jaxb.formatted.output" property needs to be set to "true" for the formatting/indentation of the output to occur. See the API documentation for javax.xml.bind.Marshaller interface for details of this property.

Character Escaping Control

By default, the marshaller implementation of the JAXB RI tries to escape characters so they can be safely represented in the output encoding (by using Unicode numeric character references of the form &#dddd;)

Unfortunately, due to various technical reasons, the default behavior may not meet your expectations. If you need to handle escaping more adroitly than the default manner, you can do so by doing the following:

1. Write a class that implements the com.sun.xml.bind.marshaller.CharacterEscapeHandler interface.
2. Create a new instance of it.
3. Set that instance to the Marshaller by using this property.

The default character escaping behavior is sensitive to the J2SE SDK version. If you are running J2SE SDK version 1.3 or earlier and are dissatisfied with the escaping it does, try J2SE SDK version 1.4 or later.

See the character-escape sample application for more details.

XML Declaration Control

When set to true, the marshaller will print out the XML declaration (you'll see <?xml version='1.0' encoding='encoding' standalone='yes' ?> in the output.) When set to false, the marshaller will not write this declaration.

Turning this option to false could be useful if you are inserting the output of the XML into another XML.

Also, this option can be used when you need to print out things like DOCTYPE declarations or XML stylesheet processing instructions. See the following code for example.

PrintWriter out = ...;

// print out the prolog part by ourselves
out.println("<xml version='1.0'?>");
out.println("<!DOCTYPE foo SYSTEM 'dummy.dtd'>");

marshaller.setProperty("com.sun.xml.bind.xmlDeclaration",Boolean.FALSE);
marshaller.marshal( jaxbObject, out );

Limitations

DOM and SAX are not capable of representing the XML declaration. As a result, when marshalling to DOM Node or SAX ContentHandler, this setting will not take effect. In other words, this setting takes effect only when you are marshalling to Writer or OutputStream.