org.codehaus.plexus.util.xml.pull.XmlSerializer Maven / Gradle / Ivy
/* -*- 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;
}