I use the EscapeXmlReference (ReferenceInsertionEventHandler implementation) in our projects to produce valid XHTML.
But I works not as expected in some situations:
Given the reference $test as 'Me & Co. Ltd' (for example from context) will output as
Me & Co. Ltd
correctly after the EscapeXmlReference.
But if we enrich the $test reference with some other string before output (#set($test = "* $test *")) we got
- Me & Co. Ltd *
and not * Me & Co. Ltd * as output!
This is because the EscapeReference handler was called two times. First on the (internal) set directive (Me & Co. Ltd
> Me & Co. Ltd), second on the real output of $test to the stream (* Me & Co. Ltd *> * Me & Co. Ltd *).
The javadoc of ReferenceInsertionEventHandler says "Reference 'Stream insertion' event handler. Called with object that will be inserted into stream via value.toString()."
"inserted into stream" means to me into the real output stream of the template merge, not into internal substreams. So I believe it's a bug or a least an unexpected behaviour because it produce unpredictable results on string operations.
So the ReferenceInsertionEventHandler needs the possibility to know if the current insertation is an internal or an real output insertation to be able to react on situations as descripted above.