Start line:  
End line:  

Snippet Preview

Snippet HTML Code

Stack Overflow Questions
  /*
   * This file is part of the DiffX library.
   *
   * For licensing information please see the file license.txt included in the release.
   * A copy of this licence can also be found at
   *   http://www.opensource.org/licenses/artistic-license-2.0.php
   */
  package com.topologi.diffx.xml;
  
Defines a writer for XML data.

This interface provides simple methods to write XML data onto a writer.

Most implementation should wrap a writer or an output stream. Implementations can be focused on performance, reliability, error reporting, etc...

For improved performance, the most efficient solution will generally to have an implementation write on a buffered writer since the memory usage will generally be restricted little more than the size of the buffer, and this will keep the I/O operation to a minimum.

Other implementations might want to wrap a SAX content handler.

Author(s):
Christophe Lauret (Allette Systems)
Version:
11 December 2011
 
 public interface XMLWriter {
 
   // Initialisation methods
   // ----------------------------------------------------------------------------------------------
 
  
Writes the XML declaration.

Always:

   <?xml version="1.0" encoding="encoding"?>
 

It is followed by a new line character if the indentation is turned on.

Throws:
java.io.IOException If an I/O exception is thrown by the underlying writer.
java.lang.IllegalStateException If this method is called after the writer has started writing elements nodes.
 
   void xmlDecl() throws IOException;

  
Sets the string to use for indentation.

The string must be only composed of valid spaces characters.

If the string is null then the indentation is turned off.

Parameters:
spaces The indentation string to use.
Throws:
java.lang.IllegalArgumentException If the indent string is not made of spaces.
java.lang.IllegalStateException If the writer has already been used.
See also:
java.lang.Character.isSpaceChar(char)
 
   void setIndentChars(String spaces);
 
   // Text methods
   // ----------------------------------------------------------------------------------------------
 
  
Writes the given character correctly for the encoding of this document.

Parameters:
c The character to write.
Throws:
java.io.IOException If an I/O exception is thrown by the underlying writer.
 
   void writeText(char cthrows IOException;

  
Writes the given text correctly for the encoding of this document.

Does nothing if the text is null.

Parameters:
text The text to write
Throws:
java.io.IOException If an I/O exception is thrown by the underlying writer.
 
   void writeText(String textthrows IOException;

  
Write the given text correctly for the encoding of this document.

Parameters:
text The text to write.
off The offset where we should start writing the string.
len The length of the character subarray to write.
Throws:
java.io.IOException If an I/O exception is thrown by the underlying writer.
 
  void writeText(char[] textint offint lenthrows IOException;

  
Writes the given text as a CDATA section.

Does nothing if the text is null.

Parameters:
data The data to write inside the CDATA section.
Throws:
java.io.IOException If an I/O exception is thrown by the underlying writer.
java.lang.IllegalArgumentException If the implementation does not support CDATA nesting
  void writeCDATA(String datathrows IOException;
  // XML methods
  // ----------------------------------------------------------------------------------------------

  
Writes the given XML data.

The text is appended as is, therefore it should be escaped properly for the encoding used by the underlying stream writer.

Does nothing if the text is null.

Parameters:
text The text to write.
Throws:
java.io.IOException If an I/O exception is thrown by the underlying writer.
  void writeXML(String textthrows IOException;

  
Write the given XML data.

The text is appended as is, therefore it should be escaped properly for the encoding used by the underlying stream writer.

Parameters:
text The text to write.
off The offset where we should start writing the string.
len The length of the character subarray to write.
Throws:
java.io.IOException If an I/O exception is thrown by the underlying writer.
  void writeXML(char[] textint offint lenthrows IOException;
  // Comments and PIs
  // ----------------------------------------------------------------------------------------------

  
Writes an XML comment.

An XML comment is:

   <!-- comment -->
 

Comments are not indented.

Does not write anything if the comment if null.

Parameters:
comment The comment to be written
Throws:
java.io.IOException If thrown by the wrapped writer.
java.lang.IllegalArgumentException If the comment contains "--".
  void writeComment(String commentthrows IOException;

  
Writes an XML processing instruction.

An XML processing intruction is:

   <?target data?>
 

Parameters:
target The PI's target.
data The PI's data.
Throws:
java.io.IOException If an I/O exception occurs.
  void writePI(String targetString datathrows IOException;
  // Open/close elements
  // ----------------------------------------------------------------------------------------------

  
Writes a start element tag correctly indented.

It is the same as openElement(name, false)

Parameters:
name the name of the element
Throws:
java.io.IOException If an I/O exception occurs.
See also:
openElement(java.lang.String,boolean)
  void openElement(String namethrows IOException;

  
Writes a start element tag correctly indented.

Use the hasChildren parameter to specify whether this element is terminal node or not, note: this affects the indenting. To produce correctly indented XML, you should use the same value for this flag when closing the element.

The name can contain attributes and should be a valid xml name.

Parameters:
name The name of the element
hasChildren true if this element has children
Throws:
java.io.IOException If an I/O exception occurs.
  void openElement(String nameboolean hasChildrenthrows IOException;

  
Writes a start element tag correctly indented.

Use the hasChildren parameter to specify whether this element is terminal node or not, note: this affects the indenting. To produce correctly indented XML, you should use the same value for this flag when closing the element.

The name can contain attributes and should be a valid xml name.

Parameters:
uri The namespace URI of the element.
name The name of the element.
hasChildren true if this element has children.
Throws:
java.io.IOException If an I/O exception occurs.
java.lang.UnsupportedOperationException If the implementing class does not handle namespace.
  void openElement(String uriString nameboolean hasChildrenthrows IOException;

  
Close the element automatically.

The element is closed symmetrically to the openElement(java.lang.String,java.lang.String,boolean) method if the XML writer is namespace aware or the openElement(java.lang.String,boolean)method.

Throws:
java.io.IOException If an I/O exception occurs.
  void closeElement() throws IOException;
  // Element shortcuts
  // ----------------------------------------------------------------------------------------------

  
Opens element, inserts text node and closes.

This method should behave like:

   this.openElement(name, false);
   this.writeText(text);
   this.closeElement();
 

Parameters:
name The name of the element.
text The text of the element.
Throws:
java.io.IOException If thrown by the wrapped writer.
  void element(String nameString textthrows IOException;

  
Writes an empty element.

It is possible for the element to contain attributes, however, since there is no character escaping, great care must be taken not to introduce invalid characters. For example:

    <example test="yes"/>
 

Parameters:
element the name of the element
Throws:
java.io.IOException If an I/O exception occurs.
java.lang.UnsupportedOperationException If the implementing class does not handle namespace.
  void emptyElement(String elementthrows IOException;

  
Writes an empty element.

It is possible for the element to contain attributes, however, since there is no character escaping, great care must be taken not to introduce invalid characters. For example:

    <example test="yes"/>
 

Parameters:
uri The namespace URI of the element.
element The name of the element.
Throws:
java.io.IOException If an I/O exception occurs.
java.lang.UnsupportedOperationException If the implementing class does not handle namespace.
  void emptyElement(String uriString elementthrows IOException;
  // Attributes
  // ----------------------------------------------------------------------------------------------

  
Writes an attribute.

Parameters:
name The name of the attribute.
value The value of the attribute.
Throws:
java.io.IOException If thrown by the wrapped writer.
java.lang.IllegalStateException If there is no open element or text has been written.
  void attribute(String nameString valuethrows IOException;

  
Writes an attribute.

This method for number does not require escaping.

Parameters:
name The name of the attribute.
value The value of the attribute.
Throws:
java.io.IOException If thrown by the wrapped writer.
java.lang.IllegalStateException If there is no open element or text has been written.
  void attribute(String nameint valuethrows IOException;

  
Writes an attribute.

Parameters:
uri The uri of the attribute.
name The name of the attribute.
value The value of the attribute.
Throws:
java.io.IOException If thrown by the wrapped writer.
java.lang.IllegalStateException If there is no open element or text has been written.
java.lang.UnsupportedOperationException If the implementing class does not handle namespace.
  void attribute(String uriString nameString valuethrows IOException;

  
Writes an attribute.

This method for number does not require escaping.

Parameters:
uri The uri of the attribute.
name The name of the attribute.
value The value of the attribute.
Throws:
java.io.IOException If thrown by the wrapped writer.
java.lang.IllegalStateException If there is no open element or text has been written.
java.lang.UnsupportedOperationException If the implementing class does not handle namespace.
  void attribute(String uriString nameint valuethrows IOException;
  // Namespace handling
  // ----------------------------------------------------------------------------------------------

  
Sets a prefix mapping.

Parameters:
uri The namespace URI.
prefix The new prefix for the namespace URI.
Throws:
java.lang.UnsupportedOperationException If the implementing class does not handle namespace.
  void setPrefixMapping(String uriString prefix);
  // Direct access to the writer
  // ----------------------------------------------------------------------------------------------

  
Flush the writer.

Throws:
java.io.IOException If thrown by the wrapped writer.
  void flush() throws IOException;

  
Close the writer.

Throws:
java.io.IOException If thrown by the wrapped writer.
UnclosedElementException If there is still an open element.
  void close() throws IOException;
New to GrepCode? Check out our FAQ X