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

From Eclipsepedia

Jump to: navigation, search
Line 16: Line 16:
 
* Provide an interface that the user can implement, and use this implementation when escaping characters during marshal.
 
* 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.
 
* Provide drop-in-replacement support, so that users already using the Sun implementation will not need to change their code when switching to EclipseLink.
 +
 +
 +
= Behaviour =
 +
 +
If a custom '''CharacterEscapeHandler''' is set, then that class will be responsible for all character escaping during marshal operations.
 +
 +
 +
= Configuration =
 +
 +
A custom '''CharacterEscapeHandler''' can be specified on a '''Marshaller''' using the <tt>addProperty()</tt> method:
 +
 +
<div style="width:850px">
 +
<source lang="java">
 +
...
 +
JAXBContext ctx = ...
 +
Marshaller m = ctx.createMarshaller();
 +
m.setProperty(org.eclipse.persistence.jaxb.JAXBMarshaller.CHARACTER_ESCAPE_HANDLER, new MyEscapeHandler());
 +
...
 +
</source>
 +
</div>
 +
 +
'''Note:''' EclipseLink also supports Sun's indentString property names:
 +
 +
<div style="width:850px">
 +
<source lang="java">
 +
m.setProperty("com.sun.xml.bind.marshaller.CharacterEscapeHandler", new MyEscapeHandler());
 +
m.setProperty("com.sun.xml.internal.bind.marshaller.CharacterEscapeHandler", new MyEscapeHandler());
 +
</source>
 +
</div>

Revision as of 12:19, 22 February 2012

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.


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.


Behaviour

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


Configuration

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 MyEscapeHandler());
...

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

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