/* -*-             c-basic-offset: 4; indent-tabs-mode: nil; -*-  //------100-columns-wide------>|*/
   // for license please see accompanying LICENSE.txt file (available also at http://www.xmlpull.org/)
   
   package org.codehaus.plexus.util.xml.pull;
   
   import java.io.IOException;
   import java.io.OutputStream;
   import java.io.Writer;
   
  /**
   * Define an interface to serialization of XML Infoset. This interface abstracts away if serialized XML is XML 1.0
   * compatible text or other formats of XML 1.0 serializations (such as binary XML for example with WBXML).
   * <p>
   * <b>PLEASE NOTE:</b> This interface will be part of XmlPull 1.2 API. It is included as basis for discussion. It may
   * change in any way.
   * <p>
   * Exceptions that may be thrown are: IOException or runtime exception (more runtime exceptions can be thrown but are
   * not declared and as such have no semantics defined for this interface):
   * <ul>
   * <li><em>IllegalArgumentException</em> - for almost all methods to signal that argument is illegal
   * <li><em>IllegalStateException</em> - to signal that call has good arguments but is not expected here (violation of
   * contract) and for features/properties when requesting setting unimplemented feature/property
   * (UnsupportedOperationException would be better but it is not in MIDP)
   * </ul>
   * <p>
   * <b>NOTE:</b> writing CDSECT, ENTITY_REF, IGNORABLE_WHITESPACE, PROCESSING_INSTRUCTION, COMMENT, and DOCDECL in some
   * implementations may not be supported (for example when serializing to WBXML). In such case IllegalStateException will
   * be thrown and it is recommended to use an optional feature to signal that implementation is not supporting this kind
   * of output.
   */
  public interface XmlSerializer {
  
      /**
       * Set feature identified by name (recommended to be URI for uniqueness). Some well known optional features are
       * defined in <a href="http://www.xmlpull.org/v1/doc/features.html">
       * http://www.xmlpull.org/v1/doc/features.html</a>. If feature is not recognized or can not be set then
       * IllegalStateException MUST be thrown.
       * @param name feature name
       * @param state feature state
       * @exception IllegalStateException If the feature is not supported or can not be set
       */
      void setFeature(String name, boolean state) throws IllegalArgumentException, IllegalStateException;
  
      /**
       * Return the current value of the feature with given name.
       * <p>
       * <strong>NOTE:</strong> unknown properties are <strong>always</strong> returned as null
       *
       * @param name The name of feature to be retrieved.
       * @return The value of named feature.
       * @exception IllegalArgumentException if feature string is null
       */
      boolean getFeature(String name);
  
      /**
       * Set the value of a property. (the property name is recommended to be URI for uniqueness). Some well known
       * optional properties are defined in <a href="http://www.xmlpull.org/v1/doc/properties.html">
       * http://www.xmlpull.org/v1/doc/properties.html</a>. If property is not recognized or can not be set then
       * IllegalStateException MUST be thrown.
       * @param name property name
       * @param value property value
       * @exception IllegalStateException if the property is not supported or can not be set
       */
      void setProperty(String name, Object value) throws IllegalArgumentException, IllegalStateException;
  
      /**
       * Look up the value of a property. The property name is any fully-qualified URI. I
       * <p>
       * <strong>NOTE:</strong> unknown properties are <strong>always</strong> returned as null
       *
       * @param name The name of property to be retrieved.
       * @return The value of named property.
       */
      Object getProperty(String name);
  
      /**
       * Set to use binary output stream with given encoding.
       * @param os out
       * @param encoding encoding
       * @throws IOException io
       * @throws IllegalArgumentException if null
       * @throws IllegalStateException illegal use
       */
      void setOutput(OutputStream os, String encoding)
              throws IOException, IllegalArgumentException, IllegalStateException;
  
      /**
       * @param writer Set the output to the given writer.
       * <p>
       * <b>WARNING</b> no information about encoding is available!
       * @throws IOException io
       * @throws IllegalArgumentException if null
       * @throws IllegalStateException illegal use
       */
      void setOutput(Writer writer) throws IOException, IllegalArgumentException, IllegalStateException;
  
      /**
       * Write &lt;&#63;xml declaration with encoding (if encoding not null) and standalone flag (if standalone not null)
       * This method can only be called just after setOutput.
      * @param encoding document encoding
      * @param standalone standalone flag value
      * @throws IOException io
      * @throws IllegalArgumentException if null
      * @throws IllegalStateException illegal use
      */
     void startDocument(String encoding, Boolean standalone)
             throws IOException, IllegalArgumentException, IllegalStateException;
 
     /**
      * Finish writing. All unclosed start tags will be closed and output will be flushed. After calling this method no
      * more output can be serialized until next call to setOutput()
      * @throws IOException io
      * @throws IllegalArgumentException if null
      * @throws IllegalStateException illegal use
      */
     void endDocument() throws IOException, IllegalArgumentException, IllegalStateException;
 
     /**
      * Binds the given prefix to the given namespace. This call is valid for the next element including child elements.
      * The prefix and namespace MUST be always declared even if prefix is not used in element (startTag() or
      * attribute()) - for XML 1.0 it must result in declaring <code>xmlns:prefix='namespace'</code> (or
      * <code>xmlns:prefix="namespace"</code> depending what character is used to quote attribute value).
      * <p>
      * <b>NOTE:</b> this method MUST be called directly before startTag() and if anything but startTag() or setPrefix()
      * is called next there will be exception.
      * <p>
      * <b>NOTE:</b> prefixes "xml" and "xmlns" are already bound and can not be redefined see:
      * <a href="http://www.w3.org/XML/xml-names-19990114-errata#NE05">Namespaces in XML Errata</a>.
      * <p>
      * <b>NOTE:</b> to set default namespace use as prefix empty string.
      *
      * @param prefix must be not null (or IllegalArgumentException is thrown)
      * @param namespace must be not null
      * @throws IOException io
      * @throws IllegalArgumentException if null
      * @throws IllegalStateException illegal use
      */
     void setPrefix(String prefix, String namespace) throws IOException, IllegalArgumentException, IllegalStateException;
 
     /**
      * @return namespace that corresponds to given prefix If there is no prefix bound to this namespace return null but
      * if generatePrefix is false then return generated prefix.
      * <p>
      * <b>NOTE:</b> if the prefix is empty string "" and default namespace is bound to this prefix then empty string
      * ("") is returned.
      * <p>
      * <b>NOTE:</b> prefixes "xml" and "xmlns" are already bound will have values as defined
      * <a href="http://www.w3.org/TR/REC-xml-names/">Namespaces in XML specification</a>
      * @param namespace the namespace
      * @param generatePrefix to generate the missing prefix
      * @throws IllegalArgumentException if null
      */
     String getPrefix(String namespace, boolean generatePrefix) throws IllegalArgumentException;
 
     /**
      * @return the current depth of the element. Outside the root element, the depth is 0. The depth is incremented by 1
      * when startTag() is called. The depth is decremented after the call to endTag() event was observed.
      *
      * <pre>
      * &lt;!-- outside --&gt;     0
      * &lt;root&gt;               1
      *   sometext                 1
      *     &lt;foobar&gt;         2
      *     &lt;/foobar&gt;        2
      * &lt;/root&gt;              1
      * &lt;!-- outside --&gt;     0
      * </pre>
      */
     int getDepth();
 
     /**
      * Returns the namespace URI of the current element as set by startTag().
      * <p>
      * <b>NOTE:</b> that means in particular that:
      * <ul>
      * <li>if there was startTag("", ...) then getNamespace() returns ""
      * <li>if there was startTag(null, ...) then getNamespace() returns null
      * </ul>
      *
      * @return namespace set by startTag() that is currently in scope
      */
     String getNamespace();
 
     /**
      * Returns the name of the current element as set by startTag(). It can only be null before first call to startTag()
      * or when last endTag() is called to close first startTag().
      *
      * @return namespace set by startTag() that is currently in scope
      */
     String getName();
 
     /**
      * Writes a start tag with the given namespace and name. If there is no prefix defined for the given namespace, a
      * prefix will be defined automatically. The explicit prefixes for namespaces can be established by calling
      * setPrefix() immediately before this method. If namespace is null no namespace prefix is printed but just name. If
      * namespace is empty string then serializer will make sure that default empty namespace is declared (in XML 1.0
      * xmlns='') or throw IllegalStateException if default namespace is already bound to non-empty string.
      * @param namespace ns
      * @param name tag name
      * @return XmlSerializer
      * @throws IOException io
      * @throws IllegalArgumentException if null
      * @throws IllegalStateException illegal use
      */
     XmlSerializer startTag(String namespace, String name)
             throws IOException, IllegalArgumentException, IllegalStateException;
 
     /**
      * Write an attribute. Calls to attribute() MUST follow a call to startTag() immediately. If there is no prefix
      * defined for the given namespace, a prefix will be defined automatically. If namespace is null or empty string no
      * namespace prefix is printed but just name.
      * @param name attribute name
      * @param value attribute value
      * @param namespace namespace to use
      * @return XmlSerializer
      * @throws IOException io
      * @throws IllegalArgumentException if null
      * @throws IllegalStateException illegal use
      */
     XmlSerializer attribute(String namespace, String name, String value)
             throws IOException, IllegalArgumentException, IllegalStateException;
 
     /**
      * Write end tag. Repetition of namespace and name is just for avoiding errors.
      * <b>Background:</b> in kXML endTag had no arguments, and non matching tags were very difficult to find... If
      * namespace is null no namespace prefix is printed but just name. If namespace is empty string then serializer will
      * make sure that default empty namespace is declared (in XML 1.0 xmlns='').
      * @param namespace ns
      * @param name tag name
      * @return XmlSerializer
      * @throws IOException io
      * @throws IllegalArgumentException if null
      * @throws IllegalStateException illegal use
      */
     XmlSerializer endTag(String namespace, String name)
             throws IOException, IllegalArgumentException, IllegalStateException;
 
     // /**
     // * Writes a start tag with the given namespace and name.
     // * <br />If there is no prefix defined (prefix == null) for the given namespace,
     // * a prefix will be defined automatically.
     // * <br />If explicit prefixes is passed (prefix != null) then it will be used
     // *and namespace declared if not already declared or
     // * throw IllegalStateException the same prefix was already set on this
     // * element (setPrefix()) and was bound to different namespace.
     // * <br />If namespace is null then prefix must be null too or IllegalStateException is thrown.
     // * <br />If namespace is null then no namespace prefix is printed but just name.
     // * <br />If namespace is empty string then serializer will make sure that
     // * default empty namespace is declared (in XML 1.0 xmlns='')
     // * or throw IllegalStateException if default namespace is already bound
     // * to non-empty string.
     // */
     // XmlSerializer startTag (String prefix, String namespace, String name)
     // throws IOException, IllegalArgumentException, IllegalStateException;
     //
     // /**
     // * Write an attribute. Calls to attribute() MUST follow a call to
     // * startTag() immediately.
     // * <br />If there is no prefix defined (prefix == null) for the given namespace,
     // * a prefix will be defined automatically.
     // * <br />If explicit prefixes is passed (prefix != null) then it will be used
     // * and namespace declared if not already declared or
     // * throw IllegalStateException the same prefix was already set on this
     // * element (setPrefix()) and was bound to different namespace.
     // * <br />If namespace is null then prefix must be null too or IllegalStateException is thrown.
     // * <br />If namespace is null then no namespace prefix is printed but just name.
     // * <br />If namespace is empty string then serializer will make sure that
     // * default empty namespace is declared (in XML 1.0 xmlns='')
     // * or throw IllegalStateException if default namespace is already bound
     // * to non-empty string.
     // */
     // XmlSerializer attribute (String prefix, String namespace, String name, String value)
     // throws IOException, IllegalArgumentException, IllegalStateException;
     //
     // /**
     // * Write end tag. Repetition of namespace, prefix, and name is just for avoiding errors.
     // * <br />If namespace or name arguments are different from corresponding startTag call
     // * then IllegalArgumentException is thrown, if prefix argument is not null and is different
     // * from corresponding starTag then IllegalArgumentException is thrown.
     // * <br />If namespace is null then prefix must be null too or IllegalStateException is thrown.
     // * <br />If namespace is null then no namespace prefix is printed but just name.
     // * <br />If namespace is empty string then serializer will make sure that
     // * default empty namespace is declared (in XML 1.0 xmlns='').
     // * <p><b>Background:</b> in kXML endTag had no arguments, and non matching tags were
     // * very difficult to find...</p>
     // */
     // ALEK: This is really optional as prefix in end tag MUST correspond to start tag but good for error checking
     // XmlSerializer endTag (String prefix, String namespace, String name)
     // throws IOException, IllegalArgumentException, IllegalStateException;
 
     /**
      * @param text Writes text, where special XML chars are escaped automatically
      * @return XmlSerializer
      * @throws IOException io
      * @throws IllegalArgumentException if null
      * @throws IllegalStateException illegal use
      */
     XmlSerializer text(String text) throws IOException, IllegalArgumentException, IllegalStateException;
 
     /**
      * Writes text, where special XML chars are escaped automatically
      * @param buf characters
      * @param len lenght
      * @param start start
      * @return XmlSerializer
      * @throws IOException io
      * @throws IllegalArgumentException if null
      * @throws IllegalStateException illegal use
      */
     XmlSerializer text(char[] buf, int start, int len)
             throws IOException, IllegalArgumentException, IllegalStateException;
 
     void cdsect(String text) throws IOException, IllegalArgumentException, IllegalStateException;
 
     void entityRef(String text) throws IOException, IllegalArgumentException, IllegalStateException;
 
     void processingInstruction(String text) throws IOException, IllegalArgumentException, IllegalStateException;
 
     void comment(String text) throws IOException, IllegalArgumentException, IllegalStateException;
 
     void docdecl(String text) throws IOException, IllegalArgumentException, IllegalStateException;
 
     void ignorableWhitespace(String text) throws IOException, IllegalArgumentException, IllegalStateException;
 
     /**
      * Write all pending output to the stream. If method startTag() or attribute() was called then start tag is closed
      * (final &gt;) before flush() is called on underlying output stream.
      * <p>
      * <b>NOTE:</b> if there is need to close start tag (so no more attribute() calls are allowed) but without flushing
      * output call method text() with empty string (text("")).
      * @throws IOException io
      */
     void flush() throws IOException;
 }