net.sf.xolite
Interface XMLSerializer

All Known Implementing Classes:

BaseXMLSerializer, ConsoleXMLSerializer, DomXMLSerializer, FlowXMLSerializer, SaxXMLSerializer, StreamXMLSerializer, StringXMLSerializer

public interface XMLSerializer

Interface of support object used to serialize XMLSerializable objects to XML.
The XMLSerializable tells what to generate to this XMLSerializer using events similar to SAX events. So, this interface is similar to the org.xml.sax.ContentHandler interface. It's simply because this interface does similar job as SAX ContentHandler but just in the other direction (serialize from java objects to a stream). Fortunately, using the event-based SAX model is very easy when you are on the provider part. So, interacting with this XMLSerializer is pretty straightforward.

You can also view this interface as a Visitor pattern specialized for XML. This object plays the "visitor" role while objects implementing the XMLSerializable interface play the role of "element" and the "accept" method is called serialize.

Method Summary

void	attribute(String localName, String value) Add an attribute to the element that was just started.
void	attribute(String namespaceUri, String localName, String value) Add an attribute to the element that was just started.
void	characters(String text) Add character content of an element.
void	charactersMultiLine(String text) Same as characters but the text (supposed to be multi-line) is formatted to be an indented text block.
void	endDocument() End the current XML document.
void	endElement(String namespaceUri, String localName) End an XML element.
Object	getCustomObject(Object key) Get back any custom object that was put in with the putCustomObject(key, value) method.
void	putCustomObject(Object key, Object value) Put a custom object in an internal Map.
void	simpleElement(String namespaceUri, String localName, String text) This is a helper method useful to add a simpleType element in one call.
void	startDocument() Start an XML document.
void	startElement(String namespaceUri, String localName) Start an XML element.
void	startPrefixMapping(String prefix, String namespaceUri) Define a prefix mapping.

Method Detail

startDocument

void startDocument()
                   throws XMLSerializeException

Start an XML document.

Throws:

XMLSerializeException

startPrefixMapping

void startPrefixMapping(String prefix,
                        String namespaceUri)
                        throws XMLSerializeException

Define a prefix mapping. This method associate the given prefix to the given namespace. So when a node of the given namespace will be serialized, the given prefix will be used to denote the namespace (and the prefix declaration will be inserted when necessary).

This method should be called for each namespace URI before the first time they are used.

If the given namespace is already associated to another prefix (or the same prefix), this method call is ignored (i.e. first association wins).

If the given prefix is already associated to an other namespace, a new prefix is generated and mapped at the place of the given one.

Parameters:

prefix - a prefix (can be "" for default prefix mapping)

namespaceUri - a namespace URI

Throws:

XMLSerializeException - if prefix or namespaceUri is null or if required action cannot be done (implementation dependent).

startElement

void startElement(String namespaceUri,
                  String localName)
                  throws XMLSerializeException

Start an XML element.

Parameters:

namespaceUri - The element namespace URI (can be null if namespace are not used)

localName - The element local name (a.k.a. NCName)

Throws:

XMLSerializeException - if required action cannot be done (implementation dependent).

attribute

void attribute(String localName,
               String value)
               throws XMLSerializeException

Add an attribute to the element that was just started. All the call to this method must immediately follow a startElement call. attribute. This attribute use no namespace.

Parameters:

localName - The attribute local name (a.k.a. NCName)

value - the attribute value (null is treated as empty string).

Throws:

XMLSerializeException - if you don't call this method just after startElement or if required action cannot be done (implementation dependent).

attribute

void attribute(String namespaceUri,
               String localName,
               String value)
               throws XMLSerializeException

Add an attribute to the element that was just started. All the call to this method must immediately follow a startElement call. attribute

Parameters:

namespaceUri - The attribute namespace URI. This URI is usually null because most of the time, attributes don't use a namespace.

localName - The attribute local name (a.k.a. NCName)

value - the attribute value (null is treated as empty string).

Throws:

XMLSerializeException - if you don't call this method just after startElement or if required action cannot be done (implementation dependent).

endElement

void endElement(String namespaceUri,
                String localName)
                throws XMLSerializeException

End an XML element.

Parameters:

namespaceUri - The element namespace URI (can be null if namespace are not used)

localName - The element local name (a.k.a. NCName)

Throws:

XMLSerializeException - if required action cannot be done (implementation dependent).

characters

void characters(String text)
                throws XMLSerializeException

Add character content of an element. This method must be called between startElement (possibly followed by attribute) and endElement. If this method is called several times for the same element, the texts are concatenated.

Parameters:

text - text of the currently started element.

Throws:

XMLSerializeException - if you don't call this method just beteween startElement and endElement or if required action cannot be done (implementation dependent).

charactersMultiLine

void charactersMultiLine(String text)
                         throws XMLSerializeException

Same as characters but the text (supposed to be multi-line) is formatted to be an indented text block.
The result will look like:

            <tag>
                some text
                spanning multiple
                lines.
            </tag>
 

While usual output would have given:

            <tag>some text
      spanning multiple
      lines.</tag>
 

The original text can be retrieved (when parsing) with the ElementText.getMultilineText(..) method. This method will automatically remove the added space.

Parameters:

text - the text to serialize in XML

Throws:

XMLSerializeException

See Also:

ElementText.getMultilineText(String, XMLEventParser)

simpleElement

void simpleElement(String namespaceUri,
                   String localName,
                   String text)
                   throws XMLSerializeException

This is a helper method useful to add a simpleType element in one call. It is strictly equivalent to the following sequence:

 startElement(namespaceUri, localName);
 characters(text);
 endElement(namespaceUri, localName);
 

Parameters:

namespaceUri - The element namespace URI (can be null if namespace are not used)

localName - The element local name (a.k.a. NCName)

text - text of the element.

Throws:

XMLSerializeException

endDocument

void endDocument()
                 throws XMLSerializeException

End the current XML document.

Throws:

XMLSerializeException

putCustomObject

void putCustomObject(Object key,
                     Object value)

Put a custom object in an internal Map.
It can be retrieved later with getCustomObject(key) method.

Parameters:

key - key of the custom object.

value - custom object.

getCustomObject

Object getCustomObject(Object key)

Get back any custom object that was put in with the putCustomObject(key, value) method.

Parameters:

key - key of the custom object.

Returns:

the custom object.