Package uk.ac.starlink.util
Class SourceReader
java.lang.Object
uk.ac.starlink.util.SourceReader
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 -
Method Summary
Modifier and TypeMethodDescriptionReturns a DOM Node representing the given source.getElement
(Source src) Returns a DOM Element representing the given source.Returns a reference to the Transformer object used for transformations used by this object.getXMLStream
(Source src) Returns an input stream from which the serialised XML text corresponding to a given Source can be read.setIncludeDeclaration
(boolean flag) Sets whether thewriteSource
methods will output an XML declaration at the start of the XML output.setIndent
(int indent) Tries to set the indent level used by thewriteSource
methods.void
setTransformer
(Transformer trans) Sets the transformer object used for transformations.void
writeSource
(Source src, OutputStream ostrm) Writes the contents of a given Source into a given OutputStream.void
writeSource
(Source src, Writer wr) Writes the contents of a given Source into a given Writer.
-
Constructor Details
-
SourceReader
public SourceReader()
-
-
Method Details
-
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 aDOMSource
) this transformer will not be used.- Returns:
- the transformer object used when transformation is necessary
-
setTransformer
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 aDOMSource
) this transformer will not be used.- Parameters:
trans
- the transformer object to be used when transformation is necessary. Ifnull
is supplied, a default transformer will be used.
-
getDOM
Returns a DOM Node representing the given source. Transformation errors are handled by this object'sTransformer
, whose behaviour is in turn determined by itsErrorListener
. By default, thisSourceReader
is installed as theErrorListener
.- Parameters:
src
- the Source for which the DOM is required- Returns:
- a DOM node (typically an
Element
) representing the XML data insrc
- Throws:
TransformerException
- if some error occurs in transformation or I/O
-
getElement
Returns a DOM Element representing the given source. This convenience method invokesgetDOM(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:
TransformerException
- if some error occurs in transformation or I/OIllegalArgumentException
- if src does not represent a Document or Element
-
writeSource
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 writtenwr
- the destination for the content ofsrc
- Throws:
TransformerException
- if some error occurs in transformation or I/O
-
writeSource
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 writtenostrm
- the destination for the content ofsrc
- Throws:
TransformerException
- if some error occurs in transformation or I/O
-
getXMLStream
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
Tries to set the indent level used by thewriteSource
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 subsequentsetTransformer
). If the suppliedindent
value is >=0 then the transformer may add whitespace when producing the XML output; it will be encouraged to prettyprint the XML usingindent
spaces to indicate element nesting, though whether this is actually done depends on which parser is actually being used by JAXP. Ifindent<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 bywriteSource
methods- Returns:
- this
SourceReader
-
setIncludeDeclaration
Sets whether thewriteSource
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 subsequentsetTransformer
).By default, the declaration is included
For convenience the method returns this
SourceReader
is returned.- Parameters:
flag
-true
if thewriteSource
methods are to output an XML declaration,false
if they are not to- Returns:
- this
SourceReader
-