org.codehaus.plexus.util.xml.pull
public interface XmlSerializer
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):
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.
Method Summary | |
---|---|
XmlSerializer | attribute(String namespace, String name, String value)
Write an attribute. |
void | cdsect(String text) |
void | comment(String text) |
void | docdecl(String text) |
void | endDocument()
Finish writing. |
XmlSerializer | endTag(String namespace, String name)
Write end tag. |
void | entityRef(String text) |
void | flush()
Write all pending output to the stream.
|
int | getDepth()
Returns the current depth of the element.
|
boolean | getFeature(String name)
Return the current value of the feature with given name.
|
String | getName()
Returns the name of the current element as set by startTag().
|
String | getNamespace()
Returns the namespace URI of the current element as set by startTag().
|
String | getPrefix(String namespace, boolean generatePrefix)
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.
|
Object | getProperty(String name)
Look up the value of a property.
|
void | ignorableWhitespace(String text) |
void | processingInstruction(String text) |
void | setFeature(String name, boolean state)
Set feature identified by name (recommended to be URI for uniqueness).
|
void | setOutput(OutputStream os, String encoding)
Set to use binary output stream with given encoding. |
void | setOutput(Writer writer)
Set the output to the given writer.
|
void | setPrefix(String prefix, String namespace)
Binds the given prefix to the given namespace.
|
void | setProperty(String name, Object value)
Set the value of a property.
(the property name is recommended to be URI for uniqueness).
|
void | startDocument(String encoding, Boolean standalone)
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. |
XmlSerializer | startTag(String namespace, String name)
Writes a start tag with the given namespace and name.
|
XmlSerializer | text(String text)
Writes text, where special XML chars are escaped automatically |
XmlSerializer | text(char[] buf, int start, int len)
Writes text, where special XML chars are escaped automatically |
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='').
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("")).
<!-- outside --> 0 <root> 1 sometext 1 <foobar> 2 </foobar> 2 </root> 1 <!-- outside --> 0
NOTE: unknown properties are always returned as null
Parameters: name The name of feature to be retrieved.
Returns: The value of named feature.
Throws: IllegalArgumentException if feature string is null
Returns: namespace set by startTag() that is currently in scope
NOTE: that means in particular that:
Returns: namespace set by startTag() that is currently in scope
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
NOTE: unknown properties are Parameters: name The name of property to be retrieved. Returns: The value of named property.
Throws: IllegalStateException If the feature is not supported or can not be set
WARNING no information about encoding is available!
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.
Parameters: prefix must be not null (or IllegalArgumentException is thrown) namespace must be not null
Throws: IllegalStateException if the property is not supported or can not be set