001/*
002// This software is subject to the terms of the Eclipse Public License v1.0
003// Agreement, available at the following URL:
004// http://www.eclipse.org/legal/epl-v10.html.
005// You must accept the terms of that agreement to use this software.
006//
007// Copyright (C) 2003-2005 Julian Hyde
008// Copyright (C) 2005-2010 Pentaho
009// All Rights Reserved.
010*/
011package mondrian.xmla;
012
013/**
014 * <code>SaxWriter</code> is similar to a SAX {@link org.xml.sax.ContentHandler}
015 * which, perversely, converts its events into an output document.
016 *
017 * @author jhyde
018 * @author Gang Chen
019 * @since 27 April, 2003
020 */
021public interface SaxWriter {
022
023    public void startDocument();
024
025    public void endDocument();
026
027    public void startElement(String name);
028
029    public void startElement(String name, Object... attrs);
030
031    public void endElement();
032
033    public void element(String name, Object... attrs);
034
035    public void characters(String data);
036
037    /**
038     * Informs the writer that a sequence of elements of the same name is
039     * starting.
040     *
041     * <p>For XML, is equivalent to {@code startElement(name)}.
042     *
043     * <p>For JSON, initiates the array construct:
044     *
045     * <blockquote><code>"name" : [<br/>
046     * &nbsp;&nbsp;{ ... },<br/>
047     * &nbsp;&nbsp;{ ... }<br/>
048     * ]</br></code></blockquote>
049     *
050     * @param name Element name
051     * @param subName Child element name
052     */
053    public void startSequence(String name, String subName);
054
055    /**
056     * Informs the writer that a sequence of elements of the same name has
057     * ended.
058     */
059    public void endSequence();
060
061    /**
062     * Generates a text-only element, {@code &lt;name&gt;data&lt;/name&gt;}.
063     *
064     * <p>For XML, this is equivalent to
065     *
066     * <blockquote><code>startElement(name);<br/>
067     * characters(data);<br/>
068     * endElement();</code></blockquote>
069     *
070     * but for JSON, generates {@code "name": "data"}.
071     *
072     * @param name Name of element
073     * @param data Text content of element
074     */
075    public void textElement(String name, Object data);
076
077    public void completeBeforeElement(String tagName);
078
079    /**
080     * Sends a piece of text verbatim through the writer. It must be a piece
081     * of well-formed XML.
082     */
083    public void verbatim(String text);
084
085    /**
086     * Flushes any unwritten output.
087     */
088    public void flush();
089}
090
091// End SaxWriter.java