| package org.xmlpull.v1; |
| |
| 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. |
| * |
| * @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. |
| * |
| * @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 <string>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. |
| */ |
| void setOutput (OutputStream os, String encoding) |
| throws IOException, IllegalArgumentException, IllegalStateException; |
| |
| /** |
| * Set the output to the given writer. |
| * <p><b>WARNING</b> no information about encoding is available! |
| */ |
| void setOutput (Writer writer) |
| throws IOException, IllegalArgumentException, IllegalStateException; |
| |
| /** |
| * Write <?xml declaration with encoding (if encoding not null) |
| * and standalone flag (if standalone not null) |
| * This method can only be called just after setOutput. |
| */ |
| 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() |
| */ |
| 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 |
| */ |
| 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> |
| */ |
| String getPrefix (String namespace, boolean generatePrefix) |
| throws IllegalArgumentException; |
| |
| /** |
| * Returns 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> |
| * <!-- outside --> 0 |
| * <root> 1 |
| * sometext 1 |
| * <foobar> 2 |
| * </foobar> 2 |
| * </root> 1 |
| * <!-- outside --> 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. |
| */ |
| 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. |
| */ |
| 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. |
| * <p><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=''). |
| */ |
| 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; |
| |
| /** |
| * Writes text, where special XML chars are escaped automatically |
| */ |
| XmlSerializer text (String text) |
| throws IOException, IllegalArgumentException, IllegalStateException; |
| |
| /** |
| * Writes text, where special XML chars are escaped automatically |
| */ |
| 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 >) |
| * 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("")). |
| * |
| */ |
| void flush () |
| throws IOException; |
| |
| } |
