Writer represents a simplified interface to an XML
* writer that is used for the XML persistence mechanism.
*
* Its sole purpose is to allow multiple backends which may remove * the need to have certain APIs in the classpath. Eg. it is possible * to write a stripped down XML Writer that does not rely on SAX, StAX * or DOM APIs.
* *The caller may assume that every action is done immediately. However * it is possible that the underlying implementation uses buffering streams. * To make sure the data is written call the {@link flush} method.
* *The Writer implementation should care about the formatting
* of the XML stream making it possible to generate three types of formats using
* a special method invocation chain.
Write
*
* <element/>
*
* by issuing write("element", true) (or any of the other
* write-variants that allows specifying the isEmpty argument)
* and writeEnd(true).
Write
*
* <element>body</element>
*
* by issuing writeNoChildren("element", "body") and writeNoChildrenEnd().
* Write
*
* <element>
* <child1/>
* <child2/>
* ...
* <element/>
*
* by issuing write("element", false) (or any of the other
* write-variants that allows specifying the isEmpty argument)
* and writeEnd(false).
Note: It is important that the values of isEmpty and
* wasEmpty match. Otherwise strange things might happen to
* the layout.
If your tag has not generated any body text or child
* elements provide true as the argument to generate
* more space efficient variant of the tag.>/p>
*
* @param wasEmpty Whether the tag was empty or not.
*/
void writeEnd(boolean wasEmpty);
/** Writes an XML tag without any attributes.
*
* @param tagName The name of the tag to write.
* @param empty Whether the element has child elements.
*/
void write(String tagName, boolean empty);
/** Writes an XML tag with one attribute name and value.
*
* @param tagName The name of the tag to write.
* @param attributeName The name of attribute.
* @param attributeValue The attribute's value.
* @param empty Whether the element has child elements.
*/
void write(String tagName, String attributeName, String attributeValue, boolean empty);
/** Writes an XML tag with multiple attributes and a body text.
*
* @param tagName The name of the tag to write.
* @param value The element's body content.
* @param attributeNames A set of attribute names.
* @param attributeValues A set of attribute values.
* @param empty Whether the element has child elements.
*/
void write(String tagName, String value, String[] attributeNames,
String[] attributeValues, boolean empty);
/** Writes an XML tag with multiple attributes without a body text.
*
* @param tagName The name of the tag to write.
* @param attributeNames A set of attribute names.
* @param attributeValues A set of attribute values.
* @param empty Whether the element has child elements.
*/
void write(String tagName, String[] attributeNames, String[] attributeValues, boolean empty);
/** Writes an XML tag with no attributes but with a body text
* that may have child elements.
*
* @param tagName The name of the tag to write.
* @param value The element's body content.
*/
void write(String tagName, String value);
/** Writes an XML tag with no attributes but with a body text
* that does not have child elements.
*
* @param tagName The name of the tag to write.
* @param value The element's body content.
*/
void writeNoChildren(String tagName, String value);
/** Writes the end of an XML tag that has no child elements.
*
*
Must be used in combination with {@link writeNoChildren} only.
*/ void writeEndNoChildren(); /** Forces the implementation to write some data. */ void flush(); /** Closes the writer. */ void close(); }