/*
 * @author Ranides Atterwim {@literal <ranides@gmail.com>}
 * @copyright Ranides Atterwim
 * @license WTFPL
 * @url http://ranides.net/projects/assira
 */

package net.ranides.assira.xml;

import java.io.File;
import java.io.IOException;
import java.io.OutputStream;
import java.io.Writer;

/**
 * XMLWriter is associated with some XMLElement and can be use to configure serialization options.
 *
 * Most of the time, writer is created using {@link XMLElement#writer()}.
 * So you have to create XML document in memory first, and then you can create writer associated with them.
 *
 * @author Ranides Atterwim {@literal <ranides@gmail.com>}
 */
public interface XMLWriter {

    /**
     * Serializes associated document into provided file
     *
     * @param file file
     * @return this
     * @throws IOException on error
     */
    XMLWriter save(File file) throws IOException;

    /**
     * Serializes associated document into provided stream
     *
     * @param ostream ostream
     * @return this
     * @throws IOException on error
     */
    XMLWriter save(OutputStream ostream) throws IOException;

    /**
     * Serializes associated document into provided writer
     *
     * @param writer writer
     * @return this
     * @throws IOException on error
     */
    XMLWriter save(Writer writer) throws IOException;

    /**
     * Serializes associated document and returns it as String
     *
     * @return String
     */
    @Override
    String toString();

    /**
     * Defines configuration property used by XML Parser generating output document.
     *
     * @param param param
     * @param value value
     * @return this
     */
    XMLWriter param(XMLOptions param, String value);

    /**
     * Defines configuration property used by XML Parser generating output document.
     *
     * @param param param
     * @param value value
     * @return this
     */
    XMLWriter param(String param, String value);

    /**
     * Enables pretty printing for this writer if provided size is greater than zero.
     * Disables indentation otherwise.
     *
     * @param size size
     * @return this
     */
    XMLWriter indent(int size);

}
