org.codehaus.stax2.io.EscapingWriterFactory Maven / Gradle / Ivy

Go to download

Show more of this group Show more artifacts with this name
Show all versions of webservices-rt Show documentation

This module contains the Metro runtime code.

There is a newer version: 4.0.4

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).
 *
 * 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.
 *
 * Note about implementing escaping writers: writers need to obey normal
 * Writer semantics, and specifically they should pass calls to
 * flush() and close() 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;
}