JAXB standard Marshaller properties

jaxb.encoding, Marshaller.JAXB_ENCODING

As we have already seen, this property specifies the encoding used by the Marshaller, if applicable. The encoding is used to determine

• when a character will be escaped using the notation &#ddd; and
• if the method marshal(Object, OutputStream) is used, how the character is converted into bytes

For example, if we have the encoding ISO-8859-1 (also known as Latin-1), which is mainly used in the U.S. and western europe (Great Britain, France, Germany, ...) then the Marshaller knows, that no other characters that the character set should be limited to the Unicode points 0..255. In other words, all other characters will be escaped. The Latin-1 characters, however, will be passed through to the Writer, or OutputStream, because they are immediately mapped to the corresponding bytes.

jaxb.formatted.output, Marshaller.JAXB_FORMATTED_OUTPUT

By default, any Marshaller will create formatted output, when marshalling to an OutputStream or Writer. In other words, the created output will look roughly like the following:

<Person>
  <FullName>
    <FirstName>Jochen</FirstName>
    <SurName>Wiedmann</SurName>
  </FullName>
</Person>

	        

As opposed to unformatted output:

<Person><FullName><FirstName>Jochen</FirstName><SurName>Wiedmann</SurName></FullName></Person>

	        

The following example turns off the default handling and creates a String containing unformatted XML:

Example 2.7. Creating unformatted XML

    public String asUnformattedString(
                                JAXBContext pContext, 
                                Object pObject, 
                                String pFileName)
                                    throws 
                                        JAXBException {
                                        
        java.io.StringWriter sw = new StringWriter();
        
        Marshaller marshaller = pContext.createMarshaller();
        marshaller.setProperty(Marshaller.JAXB_ENCODING, "UTF-8");
        marshaller.setProperty(Marshaller.JAXB_FORMATTED_OUTPUT, Boolean.FALSE);
        marshaller.marshal(pObject, sw);
        
        return sw.toString();
    }
                

JaxMe specific Marshallerproperties

jaxme.datatype.converter, JMControllerImpl.JAXME_DATATYPE_CONVERTER

The javax.xml.bind.DatatypeConverterInterface is used by JAXB implementations to convert various data types into strings and vice versa. For example, there is a method parseInt(String), converting the given string into a primitive integer. Likewise, there is a reverse method printInt(int), converting the same integer back into a string. The various "parse" methods are used by the Unmarshaller and the "print" methods are used by the Marshaller.

The datatype converter is accessible for two reasons: First of all, you need one when writing custom parse and print methods (as specified by the jaxb:property/jaxb:conversion tags in the schema). In that case you can use a datatype converter by invoking the static methods of the class DatatypeConverter, which is internally using a single, global instance of DatatypeConverterInterface.

In the special case of JaxMe, however, you are by no means restricted to the global instance. In contrary, any JaxMe Marshaller or Unmarshaller holds an internal instance, by default the global instance from DatatypeConverter.

The advantage is, that you may customize how documents marshalled by JaxMe may look like. As an example, we'll show how to customize the look of the data type xs:datetime. The XML Schema specification requests, that timestamps are marshalled as yyyy-MM-ddThh:mm:ss, which only few people will like. Additionally the specification requires that timestamps are given in UTC time, not local time.

The specification does so for good reason: Timezone and Locale issues are eliminated. If your XML instances conform to the XML Schema format, it is most likely that you won't have interoperability problems with foreign software. Fact is, however, that not all of us are working in a multinational environment and prefer human readable formats and local time.

Example 2.8. Using a custom datatype converter

    // Create a subclass of the JaxMe datatype converter, overriding its parseDateTime() and
    // printDateTime() methods.
    public class MyDatatypeConverter extends org.apache.ws.jaxme.impl.DatatypeConverterImpl {

        public Calendar parseDateTime(String arg0) {
        
            DateFormat df = DateFormat.getDateTimeInstance();
            Calendar cal = Calendar.getInstance();
            try {
            
                cal.setTime(df.parse(arg0));
                
            } catch (ParseException e) {
            
                if (df instanceof SimpleDateFormat) {
                
                    SimpleDateFormat sdf = (SimpleDateFormat) df;
                    throw new IllegalArgumentException(
                        "Failed to parse dateTime " + arg0 +
                        " with pattern " + sdf.toPattern());
                } else {
            
                    throw new IllegalArgumentException("Failed to parse dateTime " + arg0);
                }
            }
            return cal;
        }
        
        public String printDateTime(Calendar arg0) {
        
            return DateFormat.getDateTimeInstance().format(arg0.getTime());
        }
    }


    // Convert a JaxMe object into a String, using the above converter
    public String asString(JAXBContext pContext, Object pObject)
                                throws JAXBException {
                                                
        java.io.StringWriter sw = new StringWriter();
        
        Marshaller marshaller = pContext.createMarshaller();
        marshaller.setProperty(Marshaller.JAXB_ENCODING, "UTF-8");
        marshaller.setProperty(
                                JMControllerImpl.JAXME_DATATYPE_CONVERTER, 
                                new MyDatatypeConverter());
        marshaller.marshal(pObject, sw);
        
        return sw.toString();
    }
                

Warning

The above example may cause problems, because it depends on a suitable implementation of the local date format. For example, in some asiatic locales, the default format will contain local characters. The effect is, that you'll need to specify a proper encoding. UTF-8 is always the recommended choice.

jaxme.indentation.separator, JMMarshallerImpl.JAXME_INDENTATION_SEPARATOR

This property is used in conjunction with formatted output. If formatted output is turned on, it contains the string which is used as a line terminator. The property is ignored, if formatted output is turned off or marshalling to a DOM tree or SAX ContentHander occurs.

The default property value is Line Feed (ASCII 10, or \n), which is the standard on Linux or Unix. On Windows the standard is Carriage Return, followed by a Line Feed (ASCII 13 and 10, or \r\n). Rumours are, they are even using a single Carriage Return on some Apple Macintosh boxes.

If you want to see the problem live, just take a file with Unix line terminators and open it in the Windows application Notepad. No matter, which version of Windows you choose, it remains the same after 20 years of development: You'll see a text file containing a single line and where you'd expect the lines being splitted, the editor will show you black boxes only. But rumbling doesn't help, we've got to live with it.

The following example shows how to turn on Windows line terminators:

Example 2.9. Turning on Windows line terminators

    public String asUnformattedString(
                                        JAXBContext pContext, 
                                        Object pObject, 
                                        String pFileName)
                                            throws JAXBException {
                                            
        java.io.StringWriter sw = new StringWriter();
        
        Marshaller marshaller = pContext.createMarshaller();
        marshaller.setProperty(Marshaller.JAXB_ENCODING, "UTF-8");
        marshaller.setProperty(JMMarshallerImpl.JAXME_INDENTATION_STRING, "\r\n");
        marshaller.marshal(pObject, sw);
        
        return sw.toString();
    }
                

jaxme.indentation.string, JMMarshallerImpl.JAXME_INDENTATION_STRING

This property is used in conjunction with formatted output. If formatted output is turned on, it contains the string which is used to indent one element: By default " " (two blanks). The property is ignored, if formatted output is turned off or when marshalling to a DOM tree or SAX ContentHandler occurs.

To demonstrate the effect, we'll show two example documents. First an instance with default indentation:

<Person>
  <FullName>
    <FirstName>Jochen</FirstName>
    <SurName>Wiedmann</SurName>
  </FullName>
</Person>

                

If we set the indentation string to " " (four blanks), we'll get

<Person>
    <FullName>
        <FirstName>Jochen</FirstName>
        <SurName>Wiedmann</SurName>
    </FullName>
</Person>

                

jaxme.private., JMControllerImpl.JAXME_PRIVATE_

When writing custom code for formatting or parsing element or attribute values, you will most probably find at any time, that you wish to access data, which isn't available by default. In most cases you have the data, when invoking the Marshaller but not inside the formatter or parser. A typical example might be, that you want to localize the resulting XML document by using a resource bundle.

The JaxMe Marshaller allows to set arbitrary, application specific properties, but only if they are prefixed with jaxme.private.. The idea is that an unknown property name is most probably just a typo or a similar problem and it is better to throw an exception to let the programmer know that there's something wrong. However, if the property name is prefixed with jaxme.private., the JaxMe user advises, that "this unknown property is fine".

Warning

Custom property values are arbitrary. However, you should not attempt to distinguish the between the cases null and missing, because the JAXB specification has nothing like a collections method contains(Object).

jaxme.xml.declaration, JMMarshallerImpl.JAXME_XML_DECLARATION

When writing to an OutputStream or Writer, it is likely that you want your resulting XML document to have an XML declaration like

    <?xml version="1.0" encoding="UTF-8"?>
                

By default JaxMe does not create such a declaration, because that would make it difficult to embed the resulting XML into a larger document.

An XML declaration is particularly important, if you use another encoding than UTF-8. In that case you should consider a declaration as mandatory.

The property has no effect, when marshalling to DOM trees, or SAX handlers.

Example 2.10. Enabling an XML declaration

    // Convert a JaxMe object into a String, using the above converter
    public String asString(JAXBContext pContext, Object pObject)
                                                throws JAXBException {
                                                
        java.io.StringWriter sw = new StringWriter();
        
        Marshaller marshaller = pContext.createMarshaller();
        marshaller.setProperty(Marshaller.JAXB_ENCODING, "UTF-8");
        marshaller.setProperty(JMMarshallerImpl.JAXME_XML_DECLARATION, Boolean.TRUE);
        marshaller.marshal(pObject, sw);
        
        return sw.toString();
    }
                

jaxme.xml.writer, JMMarshallerImpl.JAXME_XML_WRITER

If the above properties still don't satisfy your needs, this property is your friend. It allows to take complete control on the created XML document, when marshalling to an OutputStream or Writer. (It takes no effect otherwise.)

The property value is an instance of java.lang.Class implementing org.apache.ws.jaxme.XMLWriter, which is in turn extending org.xml.sax.ContentHandler. That means, that you can do arbitrary things, including use of an XSLT stylesheet and stuff like that.

JaxMe comes with three ready-to-use implementations:

org.apache.ws.jaxme.impl.XMLWriterImpl

This is the default implementation, suitable for any encoding and Java platform. It is very simple: It is in fact using the US-ASCII encoding, escaping all Unicode points above 126.

org.apache.ws.jaxme.impl.CharSetXMLWriter

This implementation is used, whenever you are running Java 1.4 or newer. It is internally using the class java.nio.charset.CharsetEncoder to determine the Unicode points being escaped.

org.apache.ws.jaxme.impl.PassThroughXMLWriter

This implementation does no escaping at all.

As an example, we'll write and use and XMLWriter which is escaping the german Umlauts, but no other characters.

Example 2.11. Implementation of an XMLWriter escaping german Umlauts

    public class UmlautXMLWriter extends org.apache.ws.jaxme.impl.XMLWriterImpl {
      protected boolean canEncode(char c) {
        switch (c) {
          case 228:
          case 246:
          case 252:
          case 196:
          case 214:
          case 220:
          case 223:
            return false;
          default:
            return true;
        }
      }
    }

    // Convert a JaxMe object into a String, using the above XMLWriter
    public String asString(JAXBContext pContext, Object pObject)
                                                        throws JAXBException {
                                                        
        java.io.StringWriter sw = new StringWriter();
        
        Marshaller marshaller = pContext.createMarshaller();
        marshaller.setProperty(Marshaller.JAXB_ENCODING, "UTF-8");
        marshaller.setProperty(JMMarshallerImpl.JAXME_XML_WRITER, UmlautXMLWriter.class);
        marshaller.marshal(pObject, sw);
        
        return sw.toString();
    }