javax.xml.stream.XMLEventWriter Maven / Gradle / Ivy

Go to download

Show more of this group Show more artifacts with this name
Show all versions of stax-api

StAX is a standard XML processing API that allows you to stream XML data from and to your application.

There is a newer version: 1.0-2

package javax.xml.stream;

import javax.xml.stream.events.*;
import javax.xml.stream.util.XMLEventConsumer;
import javax.xml.namespace.NamespaceContext;

/**
 *
 * This is the top level interface for writing XML documents.
 *
 * Instances of this interface are not required to validate the 
 * form of the XML.  
 *
 * @version 1.0
 * @author Copyright (c) 2003 by BEA Systems. All Rights Reserved.
 * @see XMLEventReader
 * @see javax.xml.stream.events.XMLEvent
 * @see javax.xml.stream.events.Characters
 * @see javax.xml.stream.events.ProcessingInstruction
 * @see javax.xml.stream.events.StartElement
 * @see javax.xml.stream.events.EndElement
 */
public interface XMLEventWriter extends XMLEventConsumer {

  /**
   * Writes any cached events to the underlying output mechanism
   * @throws XMLStreamException
   */
  public void flush() throws XMLStreamException;

  /**
   * Frees any resources associated with this stream
   * @throws XMLStreamException
   */
  public void close() throws XMLStreamException;

  /**
   * Add an event to the output stream
   * Adding a START_ELEMENT will open a new namespace scope that 
   * will be closed when the corresponding END_ELEMENT is written.
   * 
   *   
   *     
   *       
   *     
   *   
   *   
   *     
   *       
   *       
   *       
   *       
   *     
   *     
   *       
   *       
   *       
   *       
   *     
   *     
   *       
   *       
   *       
   *       
   *     
   *     
   *       
   *       
   *       
   *       
   *     
   *     
   *       
   *       
   *       
   *       
   *     
   *     
   *       
   *       
   *       
   *       
   *     
   *     
   *       
   *       
   *       
   *       
   *     
   *     
   *       
   *       
   *       
   *       
   *     
   *     
   *       
   *       
   *       
   *       
   *     
   *     
   *       
   *       
   *       
   *       
   *     
   *   
   * 
   *         Required and optional fields for events added to the writer 
   *       
Event Type Required Fields Optional Fields Required Behavior
 START_ELEMENT   QName name  namespaces , attributes  A START_ELEMENT will be written by writing the name, 
   *       namespaces, and attributes of the event in XML 1.0 valid
   *       syntax for START_ELEMENTs.  
   *       The name is written by looking up the prefix for
   *       the namespace uri.  The writer can be configured to 
   *       respect prefixes of QNames.  If the writer is respecting
   *       prefixes it must use the prefix set on the QName.  The
   *       default behavior is to lookup the value for the prefix
   *       on the EventWriter's internal namespace context.   
   *       Each attribute (if any)
   *       is written using the behavior specified in the attribute
   *       section of this table.  Each namespace (if any) is written
   *       using the behavior specified in the namespace section of this
   *       table. 
   *       
 END_ELEMENT   Qname name   None  A well formed END_ELEMENT tag is written.
   *       The name is written by looking up the prefix for
   *       the namespace uri.  The writer can be configured to 
   *       respect prefixes of QNames.  If the writer is respecting
   *       prefixes it must use the prefix set on the QName.  The
   *       default behavior is to lookup the value for the prefix
   *       on the EventWriter's internal namespace context. 
   *       If the END_ELEMENT name does not match the START_ELEMENT
   *       name an XMLStreamException is thrown.
   *       
 ATTRIBUTE   QName name , String value  QName type  An attribute is written using the same algorithm
   *            to find the lexical form as used in START_ELEMENT.
   *            The default is to use double quotes to wrap attribute
   *            values and to escape any double quotes found in the
   *            value.  The type value is ignored.
   *       
 NAMESPACE   String prefix, String namespaceURI, 
   *            boolean isDefaultNamespaceDeclaration
   *       None   A namespace declaration is written.  If the 
   *            namespace is a default namespace declaration
   *            (isDefault is true) then xmlns="$namespaceURI"
   *            is written and the prefix is optional.  If 
   *            isDefault is false, the prefix must be declared
   *            and the writer must prepend xmlns to the prefix 
   *            and write out a standard prefix declaration.
   *      
 PROCESSING_INSTRUCTION     None    String target, String data    The data does not need to be present and may be
   *              null.  Target is required and many not be null.  
   *              The writer
   *              will write data section 
   *              directly after the target, 
   *              enclosed in appropriate XML 1.0 syntax
   *      
 COMMENT   None   String comment   If the comment is present (not null) it is written, otherwise an
   *            an empty comment is written
   *      
 START_DOCUMENT   None   String encoding , boolean standalone, String version   A START_DOCUMENT event is not required to be written to the
   *             stream.  If present the attributes are written inside
   *             the appropriate XML declaration syntax
   *      
 END_DOCUMENT   None  None   Nothing is written to the output  
 DTD   String DocumentTypeDefinition   None   The DocumentTypeDefinition is written to the output  
   * @param event the event to be added
   * @throws XMLStreamException
   */
  public void add(XMLEvent event) throws XMLStreamException;

  /**
   * Adds an entire stream to an output stream, 
   * calls next() on the inputStream argument until hasNext() returns false
   * This should be treated as a convenience method that will
   * perform the following loop over all the events in an
   * event reader and call add on each event.
   *
   * @param reader the event stream to add to the output
   * @throws XMLStreamException
   */

  public void add(XMLEventReader reader) throws XMLStreamException;

  /**
   * Gets the prefix the uri is bound to
   * @param uri the uri to look up
   * @throws XMLStreamException
   */
  public String getPrefix(String uri) throws XMLStreamException;

  /**
   * Sets the prefix the uri is bound to.  This prefix is bound
   * in the scope of the current START_ELEMENT / END_ELEMENT pair.
   * If this method is called before a START_ELEMENT has been written
   * the prefix is bound in the root scope.
   * @param prefix the prefix to bind to the uri
   * @param uri the uri to bind to the prefix
   * @throws XMLStreamException
   */
  public void setPrefix(String prefix, String uri) throws XMLStreamException;

  /**
   * Binds a URI to the default namespace
   * This URI is bound
   * in the scope of the current START_ELEMENT / END_ELEMENT pair.
   * If this method is called before a START_ELEMENT has been written
   * the uri is bound in the root scope.
   * @param uri the uri to bind to the default namespace
   * @throws XMLStreamException
   */
  public void setDefaultNamespace(String uri) throws XMLStreamException;

  /**
   * Sets the current namespace context for prefix and uri bindings.
   * This context becomes the root namespace context for writing and
   * will replace the current root namespace context.  Subsequent calls
   * to setPrefix and setDefaultNamespace will bind namespaces using
   * the context passed to the method as the root context for resolving
   * namespaces.
   * @param context the namespace context to use for this writer
   * @throws XMLStreamException
   */
  public void setNamespaceContext(NamespaceContext context)
    throws XMLStreamException;

  /**
   * Returns the current namespace context.
   * @return the current namespace context
   */
  public NamespaceContext getNamespaceContext();

  
}

* Required and optional fields for events added to the writer *
Event Type	Required Fields	Optional Fields	Required Behavior
START_ELEMENT	QName name	namespaces , attributes	A START_ELEMENT will be written by writing the name, * namespaces, and attributes of the event in XML 1.0 valid * syntax for START_ELEMENTs. * The name is written by looking up the prefix for * the namespace uri. The writer can be configured to * respect prefixes of QNames. If the writer is respecting * prefixes it must use the prefix set on the QName. The * default behavior is to lookup the value for the prefix * on the EventWriter's internal namespace context. * Each attribute (if any) * is written using the behavior specified in the attribute * section of this table. Each namespace (if any) is written * using the behavior specified in the namespace section of this * table. *
END_ELEMENT	Qname name	None	A well formed END_ELEMENT tag is written. * The name is written by looking up the prefix for * the namespace uri. The writer can be configured to * respect prefixes of QNames. If the writer is respecting * prefixes it must use the prefix set on the QName. The * default behavior is to lookup the value for the prefix * on the EventWriter's internal namespace context. * If the END_ELEMENT name does not match the START_ELEMENT * name an XMLStreamException is thrown. *
ATTRIBUTE	QName name , String value	QName type	An attribute is written using the same algorithm * to find the lexical form as used in START_ELEMENT. * The default is to use double quotes to wrap attribute * values and to escape any double quotes found in the * value. The type value is ignored. *
NAMESPACE	String prefix, String namespaceURI, * boolean isDefaultNamespaceDeclaration *	None	A namespace declaration is written. If the * namespace is a default namespace declaration * (isDefault is true) then xmlns="$namespaceURI" * is written and the prefix is optional. If * isDefault is false, the prefix must be declared * and the writer must prepend xmlns to the prefix * and write out a standard prefix declaration. *
PROCESSING_INSTRUCTION	None	String target, String data	The data does not need to be present and may be * null. Target is required and many not be null. * The writer * will write data section * directly after the target, * enclosed in appropriate XML 1.0 syntax *
COMMENT	None	String comment	If the comment is present (not null) it is written, otherwise an * an empty comment is written *
START_DOCUMENT	None	String encoding , boolean standalone, String version	A START_DOCUMENT event is not required to be written to the * stream. If present the attributes are written inside * the appropriate XML declaration syntax *
END_DOCUMENT	None	None	Nothing is written to the output
DTD	String DocumentTypeDefinition	None	The DocumentTypeDefinition is written to the output