All Downloads are FREE. Search and download functionalities are using the official Maven repository.

org.codehaus.plexus.util.xml.pull.XmlSerializer Maven / Gradle / Ivy

There is a newer version: 3.0.0-alpha-3
Show newest version
/* -*-             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).
 * 

* PLEASE NOTE: This interface will be part of XmlPull 1.2 API. It is included as basis for discussion. It may * change in any way. *

* 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): *

    *
  • IllegalArgumentException - for almost all methods to signal that argument is illegal *
  • IllegalStateException - 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) *
*

* NOTE: 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 * http://www.xmlpull.org/v1/doc/features.html. 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. *

* NOTE: unknown properties are always 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 * http://www.xmlpull.org/v1/doc/properties.html. 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 *

* NOTE: unknown properties are always 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. *

* WARNING 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 <?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 xmlns:prefix='namespace' (or * xmlns:prefix="namespace" depending what character is used to quote attribute value). *

* NOTE: this method MUST be called directly before startTag() and if anything but startTag() or setPrefix() * is called next there will be exception. *

* NOTE: prefixes "xml" and "xmlns" are already bound and can not be redefined see: * Namespaces in XML Errata. *

* NOTE: 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. *

* NOTE: if the prefix is empty string "" and default namespace is bound to this prefix then empty string * ("") is returned. *

* NOTE: prefixes "xml" and "xmlns" are already bound will have values as defined * Namespaces in XML specification * @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. * *

     * <!-- outside -->     0
     * <root>               1
     *   sometext                 1
     *     <foobar>         2
     *     </foobar>        2
     * </root>              1
     * <!-- outside -->     0
     * 
*/ int getDepth(); /** * Returns the namespace URI of the current element as set by startTag(). *

* NOTE: that means in particular that: *

    *
  • if there was startTag("", ...) then getNamespace() returns "" *
  • if there was startTag(null, ...) then getNamespace() returns null *
* * @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. * Background: 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. // *
If there is no prefix defined (prefix == null) for the given namespace, // * a prefix will be defined automatically. // *
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. // *
If namespace is null then prefix must be null too or IllegalStateException is thrown. // *
If namespace is null then 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 prefix, 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 (prefix == null) for the given namespace, // * a prefix will be defined automatically. // *
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. // *
If namespace is null then prefix must be null too or IllegalStateException is thrown. // *
If namespace is null then 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 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. // *
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. // *
If namespace is null then prefix must be null too or IllegalStateException is thrown. // *
If namespace is null then 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=''). // *

Background: in kXML endTag had no arguments, and non matching tags were // * very difficult to find...

// */ // 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 >) before flush() is called on underlying output stream. *

* NOTE: 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; }





© 2015 - 2024 Weber Informatics LLC | Privacy Policy