Class SourceReader


  • public class SourceReader
    extends java.lang.Object
    Convenience class to manipulate XML Sources. Methods are provided to do the useful things you might want done with from a Source. Depending on the type of the input source this may involve an XML transformation or it may not; such a transformation is not performed if it is not required.

    The transformer object used in the case that transformations are required may be accessed or set to permit some customisation of the way the transformation is done. Some convenience methods are provided for doing these settings as well.

    Author:
    Mark Taylor (Starlink)
    • Constructor Summary

      Constructors 
      Constructor Description
      SourceReader()  
    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      org.w3c.dom.Node getDOM​(javax.xml.transform.Source src)
      Returns a DOM Node representing the given source.
      org.w3c.dom.Element getElement​(javax.xml.transform.Source src)
      Returns a DOM Element representing the given source.
      javax.xml.transform.Transformer getTransformer()
      Returns a reference to the Transformer object used for transformations used by this object.
      java.io.InputStream getXMLStream​(javax.xml.transform.Source src)
      Returns an input stream from which the serialised XML text corresponding to a given Source can be read.
      SourceReader setIncludeDeclaration​(boolean flag)
      Sets whether the writeSource methods will output an XML declaration at the start of the XML output.
      SourceReader setIndent​(int indent)
      Tries to set the indent level used by the writeSource methods.
      void setTransformer​(javax.xml.transform.Transformer trans)
      Sets the transformer object used for transformations.
      void writeSource​(javax.xml.transform.Source src, java.io.OutputStream ostrm)
      Writes the contents of a given Source into a given OutputStream.
      void writeSource​(javax.xml.transform.Source src, java.io.Writer wr)
      Writes the contents of a given Source into a given Writer.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Constructor Detail

      • SourceReader

        public SourceReader()
    • Method Detail

      • getTransformer

        public javax.xml.transform.Transformer getTransformer()
        Returns a reference to the Transformer object used for transformations used by this object. Its characteristics may be changed if required. Note that in the case a transformation is not required (e.g. in the case of getting a DOM node from a source which is already a DOMSource) this transformer will not be used.
        Returns:
        the transformer object used when transformation is necessary
      • setTransformer

        public void setTransformer​(javax.xml.transform.Transformer trans)
        Sets the transformer object used for transformations. Note that in the case a transformation is not required (e.g. in the case of getting a DOM node from a source which is already a DOMSource) this transformer will not be used.
        Parameters:
        trans - the transformer object to be used when transformation is necessary. If null is supplied, a default transformer will be used.
      • getDOM

        public org.w3c.dom.Node getDOM​(javax.xml.transform.Source src)
                                throws javax.xml.transform.TransformerException
        Returns a DOM Node representing the given source. Transformation errors are handled by this object's Transformer, whose behaviour is in turn determined by its ErrorListener. By default, this SourceReader is installed as the ErrorListener.
        Parameters:
        src - the Source for which the DOM is required
        Returns:
        a DOM node (typically an Element) representing the XML data in src
        Throws:
        javax.xml.transform.TransformerException - if some error occurs in transformation or I/O
      • getElement

        public org.w3c.dom.Element getElement​(javax.xml.transform.Source src)
                                       throws javax.xml.transform.TransformerException
        Returns a DOM Element representing the given source. This convenience method invokes getDOM(javax.xml.transform.Source) and then finds an element in the result - if the result is an element that is returned, but if it is a Document then the top-level document element is returned. Anything else throws an IllegalArgumentException.
        Parameters:
        src - the Source for which the DOM is required
        Returns:
        an Element representing the XML data in src
        Throws:
        javax.xml.transform.TransformerException - if some error occurs in transformation or I/O
        java.lang.IllegalArgumentException - if src does not represent a Document or Element
      • writeSource

        public void writeSource​(javax.xml.transform.Source src,
                                java.io.Writer wr)
                         throws javax.xml.transform.TransformerException
        Writes the contents of a given Source into a given Writer. Additional buffering will be performed on the writer if necessary. The writer will be flushed, but not closed.

        Hmm, not sure if the encoding is handled correctly here for SAXSources...

        Parameters:
        src - the Source to be written
        wr - the destination for the content of src
        Throws:
        javax.xml.transform.TransformerException - if some error occurs in transformation or I/O
      • writeSource

        public void writeSource​(javax.xml.transform.Source src,
                                java.io.OutputStream ostrm)
                         throws javax.xml.transform.TransformerException
        Writes the contents of a given Source into a given OutputStream. Additional buffering will be performed on the stream if necessary. The stream will be flushed, but not closed.
        Parameters:
        src - the Source to be written
        ostrm - the destination for the content of src
        Throws:
        javax.xml.transform.TransformerException - if some error occurs in transformation or I/O
      • getXMLStream

        public java.io.InputStream getXMLStream​(javax.xml.transform.Source src)
        Returns an input stream from which the serialised XML text corresponding to a given Source can be read.
        Parameters:
        src - the Source to be read
        Returns:
        an InputStream which will supply the XML serialisation of src
      • setIndent

        public SourceReader setIndent​(int indent)
        Tries to set the indent level used by the writeSource methods. This method modifies the output properties of the the current transformer to affect the way it does the transformation (so will be undone by a subsequent setTransformer). If the supplied indent value is >=0 then the transformer may add whitespace when producing the XML output; it will be encouraged to prettyprint the XML using indent spaces to indicate element nesting, though whether this is actually done depends on which parser is actually being used by JAXP. If indent<0 then no whitespace will be added when outputting XML.

        By default, no whitespace is added.

        For convenience the method returns this SourceReader is returned.

        Parameters:
        indent - indicates if and how whitespace should be added by writeSource methods
        Returns:
        this SourceReader
      • setIncludeDeclaration

        public SourceReader setIncludeDeclaration​(boolean flag)
        Sets whether the writeSource methods will output an XML declaration at the start of the XML output. This method modifies the output properties of the the current transformer to affect the way it does the transformation (so will be undone by a subsequent setTransformer).

        By default, the declaration is included

        For convenience the method returns this SourceReader is returned.

        Parameters:
        flag - true if the writeSource methods are to output an XML declaration, false if they are not to
        Returns:
        this SourceReader