Jump to: navigation, search

Difference between revisions of "EclipseLink/Release/2.4.0/JAXB RI Extensions/Character Escape Handler"

 
(19 intermediate revisions by the same user not shown)
Line 1: Line 1:
 
<div style="margin:5px;float:right;border:1px solid #000000;padding:5px">__TOC__</div>
 
<div style="margin:5px;float:right;border:1px solid #000000;padding:5px">__TOC__</div>
  
= Design Documentation: CharacterEscapeHandler =
+
= Character Escape Handler =
  
[http://bugs.eclipse.org/370589 ER 370589]
+
In the current JAXB RI, developed by Sun, there is a series of "proprietary" JAXB extensions which provide advanced functionality outside of the JAXB specification (these extension classes and properties reside in the '''com.sun.xml.bind''' package).
 
+
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.
 
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.
 
 
 
= Requirements =
 
 
* 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.
 
  
  
Line 21: Line 11:
  
 
If a custom '''CharacterEscapeHandler''' is set, then that class will be responsible for all character escaping during marshal operations.
 
If a custom '''CharacterEscapeHandler''' is set, then that class will be responsible for all character escaping during marshal operations.
 +
 +
Custom escape handling is not supported when marshalling to the following targets:
 +
 +
* javax.xml.stream.XMLStreamWriter
 +
* javax.xml.stream.XMLEventWriter
 +
* org.xml.sax.ContentHandler
 +
* org.w3c.dom.Node
  
  
 
= Configuration =  
 
= Configuration =  
  
A custom '''CharacterEscapeHandler''' can be specified on a '''Marshaller''' using the <tt>addProperty()</tt> method:
+
Your custom handler should be an implementation of the '''org.eclipse.persistence.oxm.CharacterEscapeHandler''' interface.
 +
 
 +
A custom '''CharacterEscapeHandler''' can be specified on a '''Marshaller''' using the <tt>setProperty()</tt> method:
  
 
<div style="width:850px">
 
<div style="width:850px">
Line 32: Line 31:
 
JAXBContext ctx = ...
 
JAXBContext ctx = ...
 
Marshaller m = ctx.createMarshaller();
 
Marshaller m = ctx.createMarshaller();
m.setProperty(org.eclipse.persistence.jaxb.JAXBMarshaller.CHARACTER_ESCAPE_HANDLER, new MyEscapeHandler());
+
m.setProperty(MarshallerProperties.CHARACTER_ESCAPE_HANDLER, new MyHandler());
 
...
 
...
 
</source>
 
</source>
 
</div>
 
</div>
  
'''Note:''' EclipseLink also supports Sun's indentString property names:
+
'''Note:''' EclipseLink also supports Sun's CharacterEscapeHandler property names:
  
 
<div style="width:850px">
 
<div style="width:850px">
 
<source lang="java">
 
<source lang="java">
m.setProperty("com.sun.xml.bind.marshaller.CharacterEscapeHandler", new MyEscapeHandler());
+
m.setProperty("com.sun.xml.bind.marshaller.CharacterEscapeHandler", new MyHandler());
m.setProperty("com.sun.xml.internal.bind.marshaller.CharacterEscapeHandler", new MyEscapeHandler());
+
m.setProperty("com.sun.xml.internal.bind.marshaller.CharacterEscapeHandler", new MyHandler());
 +
</source>
 +
</div>
 +
 
 +
 
 +
= Appendix A - Example CharacterEscapeHandler =
 +
 
 +
<div style="width:900px">
 +
<source lang="java">
 +
package example;
 +
 
 +
import java.io.IOException;
 +
import java.io.Writer;
 +
 
 +
import org.eclipse.persistence.oxm.CharacterEscapeHandler;
 +
 
 +
public class MyHandler implements CharacterEscapeHandler {
 +
 
 +
    /**
 +
    * Escape characters inside the buffer and send the output to the Writer.
 +
    *
 +
    * @exception IOException
 +
    *                In an error condition, 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];
 +
 
 +
            if (ch == '&') {
 +
                out.write("&amp;");
 +
                continue;
 +
            }
 +
 
 +
            if (ch == '"' && isAttValue) {
 +
                out.write("&quot;");
 +
                continue;
 +
            }
 +
            if (ch == '\'' && isAttValue) {
 +
                out.write("&apos;");
 +
                continue;
 +
            }
 +
 
 +
            // you should handle other characters like < or >
 +
            // ...
 +
 
 +
            if (ch > 0x7F) {
 +
                // escape everything above ASCII to &#xXXXX;
 +
                out.write("&#x");
 +
                out.write(Integer.toHexString(ch));
 +
                out.write(";");
 +
                continue;
 +
            }
 +
 
 +
            // otherwise print normally
 +
            out.write(ch);
 +
        }
 +
    }
 +
}
 
</source>
 
</source>
 
</div>
 
</div>

Latest revision as of 11:36, 18 June 2012

Character Escape Handler

In the current JAXB RI, developed by Sun, there is a series of "proprietary" JAXB extensions which provide advanced functionality outside of the JAXB specification (these extension classes and properties 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.


Behaviour

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

Custom escape handling is not supported when marshalling to the following targets:

  • javax.xml.stream.XMLStreamWriter
  • javax.xml.stream.XMLEventWriter
  • org.xml.sax.ContentHandler
  • org.w3c.dom.Node


Configuration

Your custom handler should be an implementation of the org.eclipse.persistence.oxm.CharacterEscapeHandler interface.

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

...
JAXBContext ctx = ...
Marshaller m = ctx.createMarshaller();
m.setProperty(MarshallerProperties.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

package example;
 
import java.io.IOException;
import java.io.Writer;
 
import org.eclipse.persistence.oxm.CharacterEscapeHandler;
 
public class MyHandler implements CharacterEscapeHandler {
 
    /**
     * Escape characters inside the buffer and send the output to the Writer.
     * 
     * @exception IOException
     *                In an error condition, 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];
 
            if (ch == '&') {
                out.write("&amp;");
                continue;
            }
 
            if (ch == '"' && isAttValue) {
                out.write("&quot;");
                continue;
            }
            if (ch == '\'' && isAttValue) {
                out.write("&apos;");
                continue;
            }
 
            // you should handle other characters like < or >
            // ...
 
            if (ch > 0x7F) {
                // escape everything above ASCII to &#xXXXX;
                out.write("&#x");
                out.write(Integer.toHexString(ch));
                out.write(";");
                continue;
            }
 
            // otherwise print normally
            out.write(ch);
        }
    }
}