com.sleepycat.dbxml
Class XmlEventWriter

java.lang.Object
  com.sleepycat.dbxml.XmlEventWriter

public class XmlEventWriter
extends Object

Used to create XML content as events rather than serialized text. You can obtain an instance of this object using one of XmlContainer.putDocumentAsEventWriter(com.sleepycat.dbxml.XmlDocument) or XmlDocument.getContentAsEventWriter(com.sleepycat.dbxml.XmlEventWriter). It can also be used by XmlEventReaderToWriter.
Once you acquire an instance of this class, use its methods to write content, and when the document has been completed, call the close() method to finish putting the document in the container. Some methods will do this implicitly. All text written must be encoded as UTF-8 or a subset.

Documents created in this manner are not subject to validation. This class allows applications to directly create content without involving a parser. It also allows use of an external parser to generate events that are pushed into BDB XML content

Constructor Summary

XmlEventWriter()

Method Summary

void	close() Complete the XmlContainer.putDocumentAsEventWriter(com.sleepycat.dbxml.XmlDocument) operation, and free the resources associated with this object.
void	writeAttribute(String localName, String prefix, String uri, String value, boolean isSpecified) Write an attribute to the event stream.
void	writeDTD(String dtd) Write a DTD (internal subset).
void	writeDTD(String dtd, int length) Write a DTD (internal subset).
void	writeEndDocument() Write the EndDocument event.
void	writeEndElement(String localName, String prefix, String uri) Write an EndElement event.
void	writeEndEntity(String name) Write an event indicating the end of content expanded by an entity reference.
void	writeProcessingInstruction(String target, String data) Write a ProcessingInstruction event.
void	writeStartDocument(String version, String encoding, String standalone) Write the StartDocument event.
void	writeStartElement(String localName, String prefix, String uri, int numAttributes, boolean isEmpty) Write a StartElement event.
void	writeStartEntity(String name, boolean expandedInfoFollows) Write an event indicating the start of an entity reference.
void	writeText(int type, String text) Write a text event.
void	writeText(int type, String text, int length) Write a text event.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

XmlEventWriter

public XmlEventWriter()

Method Detail

close

public void close()
           throws XmlException

Complete the XmlContainer.putDocumentAsEventWriter(com.sleepycat.dbxml.XmlDocument) operation, and free the resources associated with this object. This call must be made when you are done with this object.

Throws:

XmlException

writeAttribute

public void writeAttribute(String localName,
                           String prefix,
                           String uri,
                           String value,
                           boolean isSpecified)
                    throws XmlException

Write an attribute to the event stream. If state of the object is not able to accept an attribute, an exception is thrown.

Parameters:

localName - The localName of the attribute.

prefix - The namespace prefix of the attribute.

uri - The namespace uri of the attribute.

value - The value of the attribute.

isSpecified - A boolean indicating whether the attribute is specified. in the document (vs defaulted)

Throws:

XmlException

writeText

public void writeText(int type,
                      String text)
               throws XmlException

Write a text event. If state of the object is not able to accept a text event, an exception is thrown. This method is used for several event types, including Characters, CDATA, Comment, and Whitespace

Parameters:

type - The event type of the text. Must be one of XmlEventReader.Characters, XmlEventReader.CDATA, XmlEventReader.Comment, or XmlEventReader.Whitespace.

text - The text string itself.

Throws:

XmlException

writeText

public void writeText(int type,
                      String text,
                      int length)
               throws XmlException

Write a text event. If state of the object is not able to accept a text event, an exception is thrown. This method is used for several event types, including Characters, CDATA, Comment, and Whitespace

Parameters:

type - The event type of the text. Must be one of XmlEventReader.Characters, XmlEventReader.CDATA, XmlEventReader.Comment, or XmlEventReader.Whitespace.

text - The text string itself.

length - The length of the text string, in UTF-8 bytes.

Throws:

XmlException

writeProcessingInstruction

public void writeProcessingInstruction(String target,
                                       String data)
                                throws XmlException

Write a ProcessingInstruction event. If state of the object is not able to accept a ProcessingInstruction event, an exception is thrown.

Parameters:

target - The ProcessingInstruction target.

data - The ProcessingInstruction data.

Throws:

XmlException

writeStartElement

public void writeStartElement(String localName,
                              String prefix,
                              String uri,
                              int numAttributes,
                              boolean isEmpty)
                       throws XmlException

Write a StartElement event. If state of the object is not able to accept a StartElement event, an exception is thrown.

Parameters:

localName - The localName of the element.

prefix - The namespace prefix of the element.

uri - The namespace uri of the element.

numAttributes - The number of attributes the element has. This number is used to determine whether or not to accept calls to writeAttribute(java.lang.String, java.lang.String, java.lang.String, java.lang.String, boolean).

isEmpty - This is true if the element is empty (has neither child elements nor text content). If an element is noted as empty, the caller must not make a corresponding call to writeEndElement(java.lang.String, java.lang.String, java.lang.String).

Throws:

XmlException

writeEndElement

public void writeEndElement(String localName,
                            String prefix,
                            String uri)
                     throws XmlException

Write an EndElement event. If state of the object is not able to accept a EndElement event, an exception is thrown. This call must not be made for empty elements, as determined by the isEmpty parameter to writeStartElement(java.lang.String, java.lang.String, java.lang.String, int, boolean)

Parameters:

localName - The localName of the element.

prefix - The namespace prefix of the element.

uri - The namespace uri of the element.

Throws:

XmlException

writeDTD

public void writeDTD(String dtd)
              throws XmlException

Write a DTD (internal subset). If state of the object is not able to accept a DTD event, an exception is thrown. Note: the DTD is not parsed or used in any way by the system. It is stored as pure text in order to return it if the document is returned at a later time.

Parameters:

dtd - The DTD text.

Throws:

XmlException

writeDTD

public void writeDTD(String dtd,
                     int length)
              throws XmlException

Write a DTD (internal subset). If state of the object is not able to accept a DTD event, an exception is thrown. Note: the DTD is not parsed or used in any way by the system. It is stored as pure text in order to return it if the document is returned at a later time.

Parameters:

dtd - The DTD text.

length - The length of the text string, in UTF-8 bytes.

Throws:

XmlException

writeStartDocument

public void writeStartDocument(String version,
                               String encoding,
                               String standalone)
                        throws XmlException

Write the StartDocument event. If the state of the object is not able to accept a StartDocument event, an exception is thrown. This must be the first event written. All parameters are optional and may be null, in which case, default values are assumed. If they are set, they will be returned in the document when it is retrieved.

Parameters:

version - The XML version string ('1.0' or '1.1' typically).

encoding - The encoding used by the document. This must be UTF-8 or a compatible subset, as all content is treated as UTF-8.

standalone - Set to the desired value of 'yes' or 'no', or null.

Throws:

XmlException

writeEndDocument

public void writeEndDocument()
                      throws XmlException

Write the EndDocument event. If the state of the object is not able to accept a EndDocument event, an exception is thrown. This must be the last event written.

Throws:

XmlException

writeStartEntity

public void writeStartEntity(String name,
                             boolean expandedInfoFollows)
                      throws XmlException

Write an event indicating the start of an entity reference. If the state of the object is not able to accept a writeStartEntity event, an exception is thrown.

Most applications will not use this method. In most cases, a caller will already have expanded entity content, and may not know that it came from an entity reference. In such cases, this event will never be written. If an application does know when expanded content starts and ends, BDB XML will accept that information, and maintain it, so that a document can be serialized back to its unexpanded form (just the entity reference itself). This event is used to note such information, and is used with writeEndEntity(java.lang.String) to track when entities start and end.

Parameters:

name - The entity reference text. E.g. if the entity reference is "&foo;" this value should be "foo"

expandedInfoFollows - If the expanded entity text will follow as further events, set this boolean to true. This allows the writing of the entity reference alone, without the expanded content.

Throws:

XmlException

writeEndEntity

public void writeEndEntity(String name)
                    throws XmlException

Write an event indicating the end of content expanded by an entity reference. If the state of the object is not able to accept a writeEndEntity event, an exception is thrown.

Most applications will not use this method. See the notes in writeStartEntity(java.lang.String, boolean) for details.

Parameters:

name - The entity reference text. E.g. if the entity reference is "&foo;" this value should be "foo"

Throws:

XmlException