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.
Property name: | com.sun.xml.bind.namespacePrefixMapper |
Type: | com.sun.xml.bind.marshaller.NamespacePrefixMapper |
Default value: | null |
The JAXB RI now provides a mechanism for mapping namespace URIs to prefixes. This is the general procedure:
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; }
Property name: | com.sun.xml.bind.indentString |
Type: | java.lang.String |
Default value: | " " (four whitespaces) |
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.
Property name: | com.sun.xml.bind.characterEscapeHandler |
Type: | com.sun.xml.bind.marshaller.CharacterEscapeHandler |
Default value: | null |
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:
com.sun.xml.bind.marshaller.CharacterEscapeHandler
interface.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.
Property name: | com.sun.xml.bind.xmlDeclaration |
Type: | java.lang.Boolean |
Default value: | java.lang.Boolean.TRUE |
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 );
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
.