org.ws4d.java.xmlpull.v1

Interface XmlSerializer

All Known Subinterfaces:

Ws4dXmlSerializer

All Known Implementing Classes:

DefaultWs4dXmlSerializer, MXSerializer

public interface XmlSerializer

Defines an interface for 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). Defines 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 later change.

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 the argument is illegal
• IllegalStateException - to signal that the call has the correct 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 the implementation does not support this kind of output.

Method Summary

Modifier and Type	Method and Description
XmlSerializer	attribute(java.lang.String namespace, java.lang.String name, java.lang.String value) Writes an attribute.
void	cdsect(java.lang.String text)
void	comment(java.lang.String text)
void	docdecl(java.lang.String text)
void	endDocument() Finishes writing.
XmlSerializer	endTag(java.lang.String namespace, java.lang.String name) Writes end tag.
void	entityRef(java.lang.String text)
void	flush() Writes all pending output to the stream.
int	getDepth() Returns the current depth of the element.
boolean	getFeature(java.lang.String name) Returns the current value of the feature with given name.
java.lang.String	getName() Returns the name of the current element as set by startTag().
java.lang.String	getNamespace() Returns the namespace URI of the current element as set by startTag().
java.lang.String	getPrefix(java.lang.String namespace, boolean generatePrefix) Returns prefix that corresponds to the given namespace.
java.lang.Object	getProperty(java.lang.String name) Looks up the value of a property.
void	ignorableWhitespace(java.lang.String text)
void	processingInstruction(java.lang.String text)
void	setFeature(java.lang.String name, boolean state) Sets feature identified by name (recommended to be URI for uniqueness).
void	setOutput(java.io.OutputStream os, java.lang.String encoding) Sets the use binary output stream with given encoding.
void	setOutput(java.io.Writer writer) Sets the output to the given writer.
void	setPrefix(java.lang.String prefix, java.lang.String namespace) Binds the given prefix to the given namespace.
void	setProperty(java.lang.String name, java.lang.Object value) Sets the value of a property.
void	startDocument(java.lang.String encoding, java.lang.Boolean standalone) Writes <?xml declaration with encoding (if encoding not null) and standalone flag (if standalone not null) This method can only be called just after setOutput.
XmlSerializer	startTag(java.lang.String namespace, java.lang.String name) Writes a start tag with the given namespace and name.
XmlSerializer	text(char[] buf, int start, int len) Writes text, where special XML chars are automatically escaped
XmlSerializer	text(java.lang.String text) Writes text, where special XML chars are automatically escaped

Method Detail

setFeature

void setFeature(java.lang.String name,
                boolean state)
         throws java.lang.IllegalArgumentException,
                IllegalStateException

Sets 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 this feature is not recognized or cannot be set then IllegalStateException MUST be thrown.

Throws:

IllegalStateException - If the feature is not supported or cannot be set

java.lang.IllegalArgumentException

getFeature

boolean getFeature(java.lang.String name)

Returns the current value of the feature with given name.

NOTE: unknown properties are always returned as null

Parameters:

name - The name of the feature to be retrieved.

Returns:

The value of the named feature.

Throws:

java.lang.IllegalArgumentException - if feature string is null

setProperty

void setProperty(java.lang.String name,
                 java.lang.Object value)
          throws java.lang.IllegalArgumentException,
                 IllegalStateException

Sets the value of a property. (the property name is recommened to be URI for uniqueness). Some well known optional properties are defined in http://www.xmlpull.org/v1/doc/properties.html. If the property is not recognized or cannot be set then an IllegalStateException MUST be thrown.

Throws:

IllegalStateException - if the property is not supported or cannot be set

java.lang.IllegalArgumentException

getProperty

java.lang.Object getProperty(java.lang.String name)

Looks up the value of a property. The property name is any fully-qualified URI.

NOTE: unknown properties are always returned as null

Parameters:

name - The name of the property to be retrieved.

Returns:

The value of the named property.

setOutput

void setOutput(java.io.OutputStream os,
               java.lang.String encoding)
        throws java.io.IOException,
               java.lang.IllegalArgumentException,
               IllegalStateException

Sets the use binary output stream with given encoding.

Throws:

java.io.IOException

java.lang.IllegalArgumentException

IllegalStateException

setOutput

void setOutput(java.io.Writer writer)
        throws java.io.IOException,
               java.lang.IllegalArgumentException,
               IllegalStateException

Sets the output to the given writer.

WARNING no information about encoding is available!

Throws:

java.io.IOException

java.lang.IllegalArgumentException

IllegalStateException

startDocument

void startDocument(java.lang.String encoding,
                   java.lang.Boolean standalone)
            throws java.io.IOException,
                   java.lang.IllegalArgumentException,
                   IllegalStateException

Writes <?xml declaration with encoding (if encoding not null) and standalone flag (if standalone not null) This method can only be called just after setOutput.

Throws:

java.io.IOException

java.lang.IllegalArgumentException

IllegalStateException

endDocument

void endDocument()
          throws java.io.IOException,
                 java.lang.IllegalArgumentException,
                 IllegalStateException

Finishes writing. All unclosed start tags will be closed and output will be flushed. After calling this method no more output can be serialized until the next call to setOutput()

Throws:

java.io.IOException

java.lang.IllegalArgumentException

IllegalStateException

setPrefix

void setPrefix(java.lang.String prefix,
               java.lang.String namespace)
        throws java.io.IOException,
               java.lang.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 other than startTag() or setPrefix() is called next, an exception will be thrown.

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

NOTE: to set default namespace, use as prefix empty string.

Parameters:

prefix - must be not null (or IllegalArgumentException is thrown)

namespace - must be not null

Throws:

java.io.IOException

java.lang.IllegalArgumentException

IllegalStateException

getPrefix

java.lang.String getPrefix(java.lang.String namespace,
                           boolean generatePrefix)
                    throws java.lang.IllegalArgumentException

Returns prefix that corresponds to the given namespace. If there is no prefix bound to this namespace returns null, but if generatePrefix is false, then returns generated prefix.

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

NOTE: prefixes "xml" and "xmlns" are already bound, and will have values as defined Namespaces in XML specification

Throws:

java.lang.IllegalArgumentException

getDepth

int getDepth()

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 is observed.

 <!-- outside -->     0
 <root>               1
   sometext                 1
     <foobar>         2
     </foobar>        2
 </root>              1
 <!-- outside -->     0
 

getNamespace

java.lang.String getNamespace()

Returns the namespace URI of the current element as set by startTag().

NOTE: that notably means that:

• if there was startTag("", ...) then getNamespace() returns ""
• if there was startTag(null, ...) then getNamespace() returns null

Returns:

namespace set by startTag() that is currently in scope

getName

java.lang.String getName()

Returns the name of the current element as set by startTag(). It can only be null before the first call to startTag(), or when the last endTag() is called to close the first startTag().

Returns:

namespace set by startTag() that is currently in scope

startTag

XmlSerializer startTag(java.lang.String namespace,
                       java.lang.String name)
                throws java.io.IOException,
                       java.lang.IllegalArgumentException,
                       IllegalStateException

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, only the name is. If namespace is the empty string, then the serializer will make sure that the default empty namespace is declared (in XML 1.0 xmlns='') or will throw IllegalStateException if the default namespace is already bound to the non-empty string.

Throws:

java.io.IOException

java.lang.IllegalArgumentException

IllegalStateException

attribute

XmlSerializer attribute(java.lang.String namespace,
                        java.lang.String name,
                        java.lang.String value)
                 throws java.io.IOException,
                        java.lang.IllegalArgumentException,
                        IllegalStateException

Writes an attribute. Calls to attribute() MUST immediately follow a call to startTag(). If there is no prefix defined for the given namespace, a prefix will automatically be defined . If namespace is null or empty string, no namespace prefix is printed, only the name will.

Throws:

java.io.IOException

java.lang.IllegalArgumentException

IllegalStateException

endTag

XmlSerializer endTag(java.lang.String namespace,
                     java.lang.String name)
              throws java.io.IOException,
                     java.lang.IllegalArgumentException,
                     IllegalStateException

Writes end tag. Namespace and name are repeated simply in order to 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, only the name is. If namespace is empty string then the serialzier will make sure that the default empty namespace is declared (in XML 1.0 xmlns='').

Throws:

java.io.IOException

java.lang.IllegalArgumentException

IllegalStateException

text

XmlSerializer text(java.lang.String text)
            throws java.io.IOException,
                   java.lang.IllegalArgumentException,
                   IllegalStateException

Writes text, where special XML chars are automatically escaped

Throws:

java.io.IOException

java.lang.IllegalArgumentException

IllegalStateException

text

XmlSerializer text(char[] buf,
                   int start,
                   int len)
            throws java.io.IOException,
                   java.lang.IllegalArgumentException,
                   IllegalStateException

Writes text, where special XML chars are automatically escaped

Throws:

java.io.IOException

java.lang.IllegalArgumentException

IllegalStateException

cdsect

void cdsect(java.lang.String text)
     throws java.io.IOException,
            java.lang.IllegalArgumentException,
            IllegalStateException

Throws:

java.io.IOException

java.lang.IllegalArgumentException

IllegalStateException

entityRef

void entityRef(java.lang.String text)
        throws java.io.IOException,
               java.lang.IllegalArgumentException,
               IllegalStateException

Throws:

java.io.IOException

java.lang.IllegalArgumentException

IllegalStateException

processingInstruction

void processingInstruction(java.lang.String text)
                    throws java.io.IOException,
                           java.lang.IllegalArgumentException,
                           IllegalStateException

Throws:

java.io.IOException

java.lang.IllegalArgumentException

IllegalStateException

comment

void comment(java.lang.String text)
      throws java.io.IOException,
             java.lang.IllegalArgumentException,
             IllegalStateException

Throws:

java.io.IOException

java.lang.IllegalArgumentException

IllegalStateException

docdecl

void docdecl(java.lang.String text)
      throws java.io.IOException,
             java.lang.IllegalArgumentException,
             IllegalStateException

Throws:

java.io.IOException

java.lang.IllegalArgumentException

IllegalStateException

ignorableWhitespace

void ignorableWhitespace(java.lang.String text)
                  throws java.io.IOException,
                         java.lang.IllegalArgumentException,
                         IllegalStateException

Throws:

java.io.IOException

java.lang.IllegalArgumentException

IllegalStateException

flush

void flush()
    throws java.io.IOException

Writes all pending output to the stream. If the method startTag() or attribute() was called then start tag is closed (final >) before the call to flush() on the underlying output stream.

NOTE: if there is a need to close start tag (so no more attribute() calls are allowed) but without flushing the output call method text() with empty string (text("")).

Throws:

java.io.IOException