Skip to main content
Jump to: navigation, search

EclipseLink/Release/2.4.0/JAXB RI Extensions/Character Escape Handler

Design Documentation: CharacterEscapeHandler

ER 370589

In the current JAXB RI, developed by Sun, there are a series of "proprietary" JAXB extensions that are available to provide advanced JAXB functionality outside of the JAXB spec (these extension classes reside in the com.sun.xml.bind package).

The CharacterEscapeHandler interface provided in the Sun JAXB implementation allows users to write their own character escaping code, to be used when marshalling.

This document will outline the design for an EclipseLink equivalent to this extension.


  • Provide an interface that the user can implement, and use this implementation when escaping characters during marshal.
  • Provide drop-in-replacement support, so that users already using the Sun implementation will not need to change their code when switching to EclipseLink.


If a custom CharacterEscapeHandler is set, then that class will be responsible for all character escaping during marshal operations.


A custom CharacterEscapeHandler can be specified on a Marshaller using the addProperty() method:

JAXBContext ctx = ...
Marshaller m = ctx.createMarshaller();
m.setProperty(org.eclipse.persistence.jaxb.JAXBMarshaller.CHARACTER_ESCAPE_HANDLER, new MyHandler());

Note: EclipseLink also supports Sun's CharacterEscapeHandler property names:

m.setProperty("com.sun.xml.bind.marshaller.CharacterEscapeHandler", new MyHandler());
m.setProperty("com.sun.xml.internal.bind.marshaller.CharacterEscapeHandler", new MyHandler());

Appendix A - Example CharacterEscapeHandler

public class EclipseLinkCustomCharacterEscapeHandler implements CharacterEscapeHandler {
     * Escape characters inside the buffer and send the output to the writer.
     * @exception IOException
     *    if something goes wrong, IOException can be thrown to stop the
     *    marshalling process.
    public void escape( char[] buf, int start, int len, boolean isAttValue, Writer out ) throws IOException {
        for( int i=start; i<start+len; i++ ) {
            char ch = buf[i];
            // you are supposed to do the standard XML character escapes
            // like & ... &amp;   < ... &lt;  etc
            if( ch=='&' ) {
            if( ch=='"' && isAttValue ) {
                // isAttValue is set to true when the marshaller is processing
                // attribute values. Inside attribute values, there are more
                // things you need to escape, usually.
            if( ch=='\'' && isAttValue ) {
            // you should handle other characters like < or >
            if( ch>0x7F ) {
                // escape everything above ASCII to &#xXXXX;
                out.write( Integer.toHexString(ch) );
            // otherwise print normally

Document History

Date Author Version Description & Notes
120222 Rick Barkhouse 1.00 : First draft

Back to the top