jenkins.util.xml

Class XMLUtils

java.lang.Object

jenkins.util.xml.XMLUtils

public final class XMLUtils
extends Object

Utilities useful when working with various XML types.

Since:

1.596.1 and 1.600, unrestricted since 2.179

Constructor Summary

Constructors

Constructor and Description
XMLUtils()

Method Summary

Modifier and Type	Method and Description
static String	getValue(String xpath, Document document) The a "value" from an XML file using XPath.
static String	getValue(String xpath, File file) The a "value" from an XML file using XPath.
static String	getValue(String xpath, File file, String fileDataEncoding) The a "value" from an XML file using XPath.
static Document	parse(File file) Parse the supplied XML file data to a Document.
static Document	parse(File file, String encoding) Deprecated. use parse(File)
static Document	parse(InputStream stream) Parse the supplied XML stream data to a Document.
static Document	parse(Reader stream) Parse the supplied XML stream data to a Document.
static void	safeTransform(Source source, Result out) Transform the source to the output in a manner that is protected against XXE attacks.

Methods inherited from class java.lang.Object

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

Constructor Detail

XMLUtils

public XMLUtils()

Method Detail

safeTransform

public static void safeTransform(@NonNull
                                 Source source,
                                 @NonNull
                                 Result out)
                          throws TransformerException,
                                 SAXException

Transform the source to the output in a manner that is protected against XXE attacks. If the transform can not be completed safely then an IOException is thrown. Note - to turn off safety set the system property disableXXEPrevention to true.

Parameters:

source - The XML input to transform. - This should be a StreamSource or a SAXSource in order to be able to prevent XXE attacks.

out - The Result of transforming the source.

Throws:

TransformerException

SAXException

parse

@NonNull
public static Document parse(@NonNull
                                      InputStream stream)
                               throws SAXException,
                                      IOException

Parse the supplied XML stream data to a Document.

This function does not close the stream.

Parameters:

stream - The XML stream.

Returns:

The XML Document.

Throws:

SAXException - Error parsing the XML stream data e.g. badly formed XML.

IOException - Error reading from the steam.

Since:

TODO

parse

@NonNull
public static Document parse(@NonNull
                                      Reader stream)
                               throws SAXException,
                                      IOException

Parse the supplied XML stream data to a Document.

This function does not close the stream.

In most cases you should prefer parse(InputStream).

Parameters:

stream - The XML stream.

Returns:

The XML Document.

Throws:

SAXException - Error parsing the XML stream data e.g. badly formed XML.

IOException - Error reading from the steam.

Since:

2.0

parse

@NonNull
public static Document parse(@NonNull
                                      File file)
                               throws SAXException,
                                      IOException

Parse the supplied XML file data to a Document.

Parameters:

file - The file to parse.

Returns:

The parsed document.

Throws:

SAXException - Error parsing the XML file data e.g. badly formed XML.

IOException - Error reading from the file.

Since:

TODO

parse

@Deprecated
 @NonNull
public static Document parse(@NonNull
                                                   File file,
                                                   @NonNull
                                                   String encoding)
                                            throws SAXException,
                                                   IOException

Deprecated. use parse(File)

Throws:

SAXException

IOException

Since:

2.0

getValue

@NonNull
public static String getValue(@NonNull
                                       String xpath,
                                       @NonNull
                                       File file)
                                throws IOException,
                                       SAXException,
                                       XPathExpressionException

The a "value" from an XML file using XPath.

Uses the system encoding for reading the file.

Parameters:

xpath - The XPath expression to select the value.

file - The file to read.

Returns:

The data value. An empty String is returned when the expression does not evaluate to anything in the document.

Throws:

IOException - Error reading from the file.

SAXException - Error parsing the XML file data e.g. badly formed XML.

XPathExpressionException - Invalid XPath expression.

Since:

2.0

getValue

@NonNull
public static String getValue(@NonNull
                                       String xpath,
                                       @NonNull
                                       File file,
                                       @NonNull
                                       String fileDataEncoding)
                                throws IOException,
                                       SAXException,
                                       XPathExpressionException

The a "value" from an XML file using XPath.

Parameters:

xpath - The XPath expression to select the value.

file - The file to read.

fileDataEncoding - The file data format.

Returns:

The data value. An empty String is returned when the expression does not evaluate to anything in the document.

Throws:

IOException - Error reading from the file.

SAXException - Error parsing the XML file data e.g. badly formed XML.

XPathExpressionException - Invalid XPath expression.

Since:

2.0

getValue

public static String getValue(String xpath,
                              Document document)
                       throws XPathExpressionException

The a "value" from an XML file using XPath.

Parameters:

xpath - The XPath expression to select the value.

document - The document from which the value is to be extracted.

Returns:

The data value. An empty String is returned when the expression does not evaluate to anything in the document.

Throws:

XPathExpressionException - Invalid XPath expression.

Since:

2.0