package org.codehaus.stax2.io;
import java.io.
OutputStream;
import java.io.
UnsupportedEncodingException;
import java.io.
Writer;
/**
* Interface that defines API for the factories stream writers use for
* creating "escaping writers". These factories are used when defining
* custom escaping of text (as well as possibly used by the
* implementations for default escaping too). Escaping in this context
* refers to the process of replacing individual text/attribute content
* character with pre-defined and character entities, as per XML
* specification (2.4, Appendix D).
*<p>
* Typical escaping writers replace characters like '<' and '&',
* as well as some additional characters depending on context.
* Custom implementations may choose to escape additional characters,
* for example to make it easier to manually view or edit resulting
* serialized XML document.
*<p>
* Note about implementing escaping writers: writers need to obey normal
* Writer semantics, and specifically they should pass calls to
* <code>flush()</code> and <code>close()</code> to the underlying
* Writer.
*/
public interface
EscapingWriterFactory
{
/**
* Method called to create an instance of escaping writer that
* will output content using specified writer,
* and escaping necessary characters (depending on
* both type [attr, element text] and encoding).
*
* @param w Underlying writer that the encoding writer should
* output
* @param enc Encoding to use, as specified by the stream writer
* (based on information application has passed)
*/
public
Writer createEscapingWriterFor(
Writer w,
String enc)
throws
UnsupportedEncodingException;
/**
* Method called to create an instance of escaping writer that
* will output to the specified stream, using the specified
* encoding,
* and escaping necessary characters (depending on
* both type [attr, element text] and encoding).
*
* @param out Underlying stream that the encoding writer should
* output using
* @param enc Encoding to use, as specified by the stream writer
* (based on information application has passed)
*/
public
Writer createEscapingWriterFor(
OutputStream out,
String enc)
throws
UnsupportedEncodingException;
}