Package io.sf.carte.doc.dom

Class DOMWriter

java.lang.Object
io.sf.carte.doc.dom.DOMWriter
public class DOMWriter extends Object
Serializes a node and its subtree.

To pretty-print a document (or any node), uses heuristics that take into account the default values of the display CSS property for the elements, according to a reference style sheet (by default, the user agent's style sheet). And when serializing a Text node, also allows to replace a specified subset of codepoints with the proper entity references.

This class could be subclassed to customize the printing.

  • Constructor Summary

    Constructors
    Constructor
    Description
    DOMWriter()
    Construct a DOMWriter with default settings.
    DOMWriter(CSSStyleSheet<? extends CSSRule> refSheet)
    Construct a DOMWriter with a reference style sheet for formatting heuristics.

  • Method Summary

    Modifier and Type
    Method
    Description
    protected boolean
    afterStartTag(DOMElement element, io.sf.carte.util.SimpleWriter wri)
    Take decisions after serializing the start tag of an element.
    protected void
    deepenIndent()
    Deepen the indenting level.
    protected void
    endIndentedNode(Node node, io.sf.carte.util.SimpleWriter wri)
     
    protected void
    endIndentedNodeList(Node listParent, io.sf.carte.util.SimpleWriter wri)
     
    protected String
    getDisplayProperty(Element element)
    Get the value of the display CSS property as specified in the user agent style sheet for that element.
    protected boolean
    isRawTextElement(DOMElement element)
     
    protected String
    replaceByEntities(String line)
    Verify if the given line contains characters for which there is the mandate to replace by entity references.
    String
    serializeToString(Node root)
    Serializes root into a String using the configurable serialization provided by this class.
    int
    setEntityCodepoints(DocumentType docType, int[] entities)
    Configure the writer to replace the given codePoints by entity references (if the document type allows it).
    void
    setEntityResolver(EntityResolver2 resolver)
    Sets the entity resolver to be used to read the DTD.
    void
    setIndentingUnit(int whitespaceCount)
    Sets a whitespace string of the whitespaceCount length as the level indenting unit (that is, every indenting depth shall be whitespaceCount larger).
    protected void
    startIndentedNode(Node node, io.sf.carte.util.SimpleWriter wri)
     
    protected void
    startIndentedNodeList(Node parent, io.sf.carte.util.SimpleWriter wri)
     
    protected void
    updateIndent(Node node)
    Update the indenting level to the parent of the given node.
    protected void
    writeAttribute(Attr attr, io.sf.carte.util.SimpleWriter wri)
    Serialize an element attribute.
    protected void
    writeAttributes(AttributeNamedNodeMap nodeMap, io.sf.carte.util.SimpleWriter wri)
    Serialize the attributes of an element.
    protected void
    writeCDataSection(CDATASection data, io.sf.carte.util.SimpleWriter wri)
    Serialize a CDATA section.
    protected void
    writeChildNodes(Node parent, io.sf.carte.util.SimpleWriter wri, boolean indented)
    Serialize a list of (child) nodes.
    protected void
    writeComment(Comment comment, io.sf.carte.util.SimpleWriter wri, boolean indented)
    Serialize a comment.
    protected void
    writeDocumentType(DocumentType docType, io.sf.carte.util.SimpleWriter wri)
    Serialize a DOCTYPE node.
    protected void
    writeElement(DOMElement element, io.sf.carte.util.SimpleWriter wri, boolean indented)
    Serialize the given element and descendants, with an initial indenting context.
    protected void
    writeElementContentWhitespace(Text text, io.sf.carte.util.SimpleWriter wri)
    Serialize element content whitespace.
    protected void
    writeEntityReference(Node node, io.sf.carte.util.SimpleWriter wri)
     
    protected void
    writeFullIndent(io.sf.carte.util.SimpleWriter wri)
    Write a full indent to the writer.
    void
    writeNode(Node root, io.sf.carte.util.SimpleWriter writer)
    Serialize the given node and descendants.
    protected void
    writeNode(Node node, io.sf.carte.util.SimpleWriter wri, boolean indented)
    Serialize the given node and descendants, with an initial indenting context.
    protected void
    writeNonRawText(Text text, io.sf.carte.util.SimpleWriter wri, boolean indented)
    Serialize a Text node that is not the child of a raw text element (that is, a normal Text node).
    protected void
    writeProcessingInstruction(ProcessingInstruction pi, io.sf.carte.util.SimpleWriter wri)
    Serialize a ProcessingInstruction node.
    protected void
    writeRawText(Text text, String parentLocalName, io.sf.carte.util.SimpleWriter wri)
    Serialize a Text node that is child of a raw text element.
    protected void
    writeText(Text text, io.sf.carte.util.SimpleWriter wri, boolean indented)
    Serialize a Text node.
    protected void
    writeTextLine(String line, io.sf.carte.util.SimpleWriter wri)
    Serialize a line of a normal Text node.
    static void
    writeTree(Node root, io.sf.carte.util.SimpleWriter writer)
    Create a DOMWriter object, use it to serialize the given node and descendants.

    Methods inherited from class java.lang.Object

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

  • Constructor Details

    • DOMWriter

      public DOMWriter()
      Construct a DOMWriter with default settings.

    • DOMWriter

      public DOMWriter(CSSStyleSheet<? extends CSSRule> refSheet)
      Construct a DOMWriter with a reference style sheet for formatting heuristics.

      Use this constructor when you know that the user agent's sheet is not adequate for the nodes that you are going to print (or that you'll be using always the same reference sheet, and you want to spare the retrieval of the UA sheet for each writeNode(Node, SimpleWriter) call).

      Parameters:
      refSheet - the reference sheet.

  • Method Details

    • setEntityCodepoints

      public int setEntityCodepoints(DocumentType docType, int[] entities) throws SAXException, IOException
      Configure the writer to replace the given codePoints by entity references (if the document type allows it).

      If you want to use a specific EntityResolver2 in the process, be sure to call setEntityResolver(EntityResolver2) first.

      Parameters:
      docType - the document type.
      entities - the codePoints that should be replaced by entity references.
      Returns:
      the number of requested entities that could be found.
      Throws:
      IOException - if an I/O problem occurred reading the DTD.
      SAXException - if a DTD-related error happened.
      NullPointerException - if either docType or entities are null.

    • setEntityResolver

      public void setEntityResolver(EntityResolver2 resolver)
      Sets the entity resolver to be used to read the DTD.

      If no entity resolver is set, this library's default resolver will be used.

      Parameters:
      resolver - the entity resolver.

    • setIndentingUnit

      public void setIndentingUnit(int whitespaceCount)
      Sets a whitespace string of the whitespaceCount length as the level indenting unit (that is, every indenting depth shall be whitespaceCount larger).
      Parameters:
      whitespaceCount - the length of the indenting unit.
      Throws:
      IllegalArgumentException - if the whitespaceCount is negative.

    • writeTree

      public static void writeTree(Node root, io.sf.carte.util.SimpleWriter writer) throws DOMException, IOException
      Create a DOMWriter object, use it to serialize the given node and descendants.

      Example: 

       Document document = ...
 BufferSimpleWriter writer = new BufferSimpleWriter();
 DOMWriter.writeTree(document, writer);
 System.out.println(writer.toString());
      Parameters:
      root - the root node.
      writer - the writer.
      Throws:
      DOMException - NAMESPACE_ERR if there is a DOM namespace inconsistency preventing a satisfactory serialization.
      IOException - if an I/O problem occurred while writing.

    • serializeToString

      public String serializeToString(Node root) throws DOMException
      Serializes root into a String using the configurable serialization provided by this class.

      Named for similarity with W3C's XMLSerializer interface.

      Parameters:
      root - the root node.
      Returns:
      the serialization.
      Throws:
      DOMException - NAMESPACE_ERR if there is a DOM namespace inconsistency preventing a satisfactory serialization.

    • writeNode

      public void writeNode(Node root, io.sf.carte.util.SimpleWriter writer) throws DOMException, IOException
      Serialize the given node and descendants.

      Example: 

       Document document = ...
 BufferSimpleWriter writer = new BufferSimpleWriter();
 DOMWriter domwriter = new DOMWriter(document);
 domwriter.writeNode(document, writer);
 System.out.println(writer.toString());
      Parameters:
      root - the node.
      writer - the writer.
      Throws:
      DOMException - NAMESPACE_ERR if there is a DOM namespace inconsistency preventing a satisfactory serialization.
      IOException - if an I/O problem occurred while writing.

    • writeNode

      protected void writeNode(Node node, io.sf.carte.util.SimpleWriter wri, boolean indented) throws DOMException, IOException
      Serialize the given node and descendants, with an initial indenting context.
      Parameters:
      node - the node.
      wri - the writer.
      indented - true if the current behaviour (specified by parent or by direct method call) is to put each child node on its own line and indent it.
      Throws:
      DOMException - NAMESPACE_ERR if there is a DOM namespace inconsistency preventing a satisfactory serialization.
      IOException - if an I/O problem occurred while writing.

    • writeElement

      protected void writeElement(DOMElement element, io.sf.carte.util.SimpleWriter wri, boolean indented) throws DOMException, IOException
      Serialize the given element and descendants, with an initial indenting context.
      Parameters:
      element - the element.
      wri - the writer.
      indented - true if the current behaviour (specified by parent or by direct method call) is to put each child node on its own line and indent it.
      Throws:
      DOMException - NAMESPACE_ERR if there is a DOM namespace inconsistency preventing a satisfactory serialization.
      IOException - if an I/O problem occurred while writing.

    • writeAttributes

      protected void writeAttributes(AttributeNamedNodeMap nodeMap, io.sf.carte.util.SimpleWriter wri) throws IOException
      Serialize the attributes of an element.

      Only explicitly specified attributes are serialized.

      Parameters:
      nodeMap - the attribute map.
      wri - the writer.
      Throws:
      IOException - if an I/O problem occurred while writing.

    • writeAttribute

      protected void writeAttribute(Attr attr, io.sf.carte.util.SimpleWriter wri) throws IOException
      Serialize an element attribute.
      Parameters:
      attr - the attribute.
      wri - the writer.
      Throws:
      IOException - if an I/O problem occurred while writing.

    • writeChildNodes

      protected void writeChildNodes(Node parent, io.sf.carte.util.SimpleWriter wri, boolean indented) throws DOMException, IOException
      Serialize a list of (child) nodes.
      Parameters:
      parent - the parent node.
      wri - the writer.
      indented - true if the current behaviour (specified by parent or by direct method call) is to put each child node on its own line and indent it.
      Throws:
      DOMException - if there is a DOM inconsistency preventing a satisfactory serialization.
      IOException - if an I/O problem occurred while writing.

    • writeText

      protected void writeText(Text text, io.sf.carte.util.SimpleWriter wri, boolean indented) throws IOException
      Serialize a Text node.
      Parameters:
      text - the text node.
      wri - the writer.
      indented - true if the current behaviour (specified by parent or by direct method call) is to put each child node on its own line and indent it.
      Throws:
      IOException - if an I/O problem occurred while writing.

    • isRawTextElement

      protected boolean isRawTextElement(DOMElement element)

    • writeRawText

      protected void writeRawText(Text text, String parentLocalName, io.sf.carte.util.SimpleWriter wri) throws IOException
      Serialize a Text node that is child of a raw text element.

      See Raw text elements and also escapable raw text elements.

      Parameters:
      text - the text node to be serialized as raw text.
      wri - the writer.
      Throws:
      IOException - if an I/O problem occurred while writing.

    • writeNonRawText

      protected void writeNonRawText(Text text, io.sf.carte.util.SimpleWriter wri, boolean indented) throws IOException
      Serialize a Text node that is not the child of a raw text element (that is, a normal Text node).
      Parameters:
      text - the text node to be serialized as normal text.
      wri - the writer.
      indented - true if the current behaviour (specified by parent or by direct method call) is to put each child node on its own line and indent it.
      Throws:
      IOException - if an I/O problem occurred while writing.

    • writeTextLine

      protected void writeTextLine(String line, io.sf.carte.util.SimpleWriter wri) throws IOException
      Serialize a line of a normal Text node.

      If there is the mandate to replace characters by entity references, call replaceByEntities(String) before writing.

      Parameters:
      line - the line to write.
      wri - the writer.
      Throws:
      IOException - if an I/O problem occurred while writing.

    • replaceByEntities

      protected String replaceByEntities(String line) throws SAXException, IOException
      Verify if the given line contains characters for which there is the mandate to replace by entity references.
      Parameters:
      line - the line where the characters should be replaced.
      Returns:
      the line, with the relevant characters replaced by entity references.
      Throws:
      SAXException - if there was a non-I/O problem handling the DTD.
      IOException - if an I/O problem occurred while reading a DTD or serializing.

    • writeElementContentWhitespace

      protected void writeElementContentWhitespace(Text text, io.sf.carte.util.SimpleWriter wri) throws IOException
      Serialize element content whitespace.
      Parameters:
      text - the text node.
      wri - the writer.
      Throws:
      IOException - if an I/O problem occurred while writing.

    • writeCDataSection

      protected void writeCDataSection(CDATASection data, io.sf.carte.util.SimpleWriter wri) throws IOException
      Serialize a CDATA section.
      Parameters:
      data - the CDATA section.
      wri - the writer.
      Throws:
      IOException - if an I/O problem occurred while writing.

    • writeComment

      protected void writeComment(Comment comment, io.sf.carte.util.SimpleWriter wri, boolean indented) throws IOException
      Serialize a comment.
      Parameters:
      comment - the comment node.
      wri - the writer.
      indented - true if the current behaviour (specified by parent or by direct method call) is to put each child node on its own line and indent it.
      Throws:
      IOException - if an I/O problem occurred while writing.

    • writeDocumentType

      protected void writeDocumentType(DocumentType docType, io.sf.carte.util.SimpleWriter wri) throws IOException
      Serialize a DOCTYPE node.
      Parameters:
      docType - the DocumentType node.
      wri - the writer.
      Throws:
      IOException - if an I/O problem occurred while writing.

    • writeProcessingInstruction

      protected void writeProcessingInstruction(ProcessingInstruction pi, io.sf.carte.util.SimpleWriter wri) throws IOException
      Serialize a ProcessingInstruction node.
      Parameters:
      pi - the ProcessingInstruction node.
      wri - the writer.
      Throws:
      IOException - if an I/O problem occurred while writing.

    • writeEntityReference

      protected void writeEntityReference(Node node, io.sf.carte.util.SimpleWriter wri) throws IOException
      Throws:
      IOException

    • startIndentedNodeList

      protected void startIndentedNodeList(Node parent, io.sf.carte.util.SimpleWriter wri) throws IOException
      Throws:
      IOException

    • startIndentedNode

      protected void startIndentedNode(Node node, io.sf.carte.util.SimpleWriter wri) throws IOException
      Throws:
      IOException

    • endIndentedNode

      protected void endIndentedNode(Node node, io.sf.carte.util.SimpleWriter wri) throws IOException
      Throws:
      IOException

    • endIndentedNodeList

      protected void endIndentedNodeList(Node listParent, io.sf.carte.util.SimpleWriter wri) throws IOException
      Throws:
      IOException

    • afterStartTag

      protected boolean afterStartTag(DOMElement element, io.sf.carte.util.SimpleWriter wri) throws IOException
      Take decisions after serializing the start tag of an element.
      Parameters:
      element - the element whose start tag was serialized.
      wri - the writer.
      Returns:
      true if children of the given element should be serialized indented.
      Throws:
      IOException - if an I/O problem occurred while writing.

    • getDisplayProperty

      protected String getDisplayProperty(Element element)
      Get the value of the display CSS property as specified in the user agent style sheet for that element.
      Parameters:
      element - the element.
      Returns:
      the value of the display property, or null if no rule with that type selector defining that property was found.

    • deepenIndent

      protected void deepenIndent()
      Deepen the indenting level.

    • updateIndent

      protected void updateIndent(Node node)
      Update the indenting level to the parent of the given node.
      Parameters:
      node - the current parent node.

    • writeFullIndent

      protected void writeFullIndent(io.sf.carte.util.SimpleWriter wri) throws IOException
      Write a full indent to the writer.
      Parameters:
      wri - the writer.
      Throws:
      IOException - if an I/O problem occurred while writing.