com.android.utils

Class XmlUtils

java.lang.Object

com.android.utils.XmlUtils

public class XmlUtils
extends java.lang.Object

XML Utilities.

For Kotlin usage, many of these are exposed as more convenient extension methods in DomExtensions

Field Summary

Fields

Modifier and Type	Field and Description
static char	NS_SEPARATOR Separator for xml namespace and localname
static java.lang.String	XML_COMMENT_BEGIN
static java.lang.String	XML_COMMENT_END
static java.lang.String	XML_PROLOG

Constructor Summary

Constructors

Constructor and Description
XmlUtils()

Method Summary

Modifier and Type	Method and Description
static void	appendXmlAttributeValue(java.lang.StringBuilder sb, java.lang.String attrValue) Appends text to the given StringBuilder and escapes it as required for a DOM attribute node.
static void	appendXmlAttributeValue(java.lang.StringBuilder sb, java.lang.String attrValue, int start, int end) Appends text to the given StringBuilder and escapes it as required for a DOM attribute node.
static void	appendXmlTextValue(java.lang.StringBuilder sb, java.lang.String textValue) Appends text to the given StringBuilder and escapes it as required for a DOM text node.
static void	appendXmlTextValue(java.lang.StringBuilder sb, java.lang.String textValue, int start, int end) Appends text to the given StringBuilder and escapes it as required for a DOM text node.
static void	attachSourceFile(org.w3c.dom.Node node, SourceFile sourceFile)
static javax.xml.parsers.SAXParserFactory	configureSaxFactory(javax.xml.parsers.SAXParserFactory factory, boolean namespaceAware, boolean checkDtd)
static org.w3c.dom.Document	createDocument(boolean namespaceAware) Creates and returns a new empty document.
static javax.xml.parsers.SAXParser	createSaxParser(javax.xml.parsers.SAXParserFactory factory)
static javax.xml.parsers.SAXParser	createSaxParser(javax.xml.parsers.SAXParserFactory factory, boolean allowDocTypeDeclarations)
static java.lang.String	formatFloatAttribute(double value) Formats the number and removes trailing zeros after the decimal dot and also the dot itself if there were non-zero digits after it.
static java.lang.String	fromXmlAttributeValue(java.lang.String escapedAttrValue) Converts the given XML-attribute-safe value to a java string
static org.w3c.dom.Element	getFirstSubTag(org.w3c.dom.Node parent) Returns the first child element of the given node
static org.w3c.dom.Element	getFirstSubTagByName(org.w3c.dom.Node parent, java.lang.String name) Returns the next sibling element from the given node that matches the given name
static org.w3c.dom.Element	getNextTag(org.w3c.dom.Node node) Returns the next sibling element from the given node
static org.w3c.dom.Element	getNextTagByName(org.w3c.dom.Node node, java.lang.String name) Returns the next sibling element from the given node
static org.w3c.dom.Comment	getPreviousComment(org.w3c.dom.Node element) Returns the comment preceding the given element with no other elements in between, or null if the element is not preceded by a comment.
static java.lang.String	getPreviousCommentText(org.w3c.dom.Node element) Returns the text of the comment preceding the given element with no other elements in between, or null if the element is not preceded by a comment or if the comment is empty or consists of only whitespace characters.
static org.w3c.dom.Element	getPreviousTag(org.w3c.dom.Node node) Returns the previous sibling element from the given node
static org.w3c.dom.Element	getPreviousTagByName(org.w3c.dom.Node node, java.lang.String name)
static java.lang.String	getRootTagName(java.io.File xmlFile) Returns the name of the root element tag stored in the given file, or null if it can't be determined.
static java.lang.String	getRootTagName(java.lang.String xmlText) Returns the name of the root element tag stored in the given file, or null if it can't be determined.
static SourceFilePosition	getSourceFilePosition(org.w3c.dom.Node node)
static int	getSubTagCount(org.w3c.dom.Node parent) Returns the number of children sub tags of the given node.
static java.lang.Iterable<org.w3c.dom.Element>	getSubTags(org.w3c.dom.Node parent) Returns an iterator for the children elements of the given node.
static java.util.List<org.w3c.dom.Element>	getSubTagsAsList(org.w3c.dom.Node parent) Returns the children elements of the given node
static java.lang.Iterable<org.w3c.dom.Element>	getSubTagsByName(org.w3c.dom.Node parent, java.lang.String tagName) Returns an iterator for the children elements of the given node matching the given tag name.
static java.io.Reader	getUtfReader(java.io.File file) Returns a character reader for the given file, which must be a UTF encoded file.
static boolean	hasElementChildren(org.w3c.dom.Node node) Returns true if the given node has one or more element children
static boolean	isProtoXml(byte[] bytes) Checks if the given array of bytes is likely to represent XML in a proto format.
static boolean	isProtoXml(java.io.InputStream stream) Checks if the given input stream is likely to represent XML in a proto format.
static java.lang.String	lookupNamespacePrefix(org.w3c.dom.Node node, java.lang.String nsUri) Returns the namespace prefix matching the requested namespace URI.
static java.lang.String	lookupNamespacePrefix(org.w3c.dom.Node node, java.lang.String nsUri, boolean create) Returns the namespace prefix matching the requested namespace URI.
static java.lang.String	lookupNamespacePrefix(org.w3c.dom.Node node, java.lang.String nsUri, java.lang.String defaultPrefix, boolean create) Returns the namespace prefix matching the requested namespace URI.
static org.w3c.dom.Document	parseDocument(java.io.Reader xml, boolean namespaceAware) Parses the given Reader as a DOM document, using the JDK parser.
static org.w3c.dom.Document	parseDocument(java.lang.String xml, boolean namespaceAware) Parses the given XML string as a DOM document, using the JDK parser.
static org.w3c.dom.Document	parseDocumentSilently(java.lang.String xml, boolean namespaceAware) Parses the given XML string as a DOM document, using the JDK parser.
static org.w3c.dom.Document	parseUtfXmlFile(java.io.File file, boolean namespaceAware) Parses the given UTF file as a DOM document, using the JDK parser.
static java.lang.String	stripBom(java.lang.String xml) Strips out a leading UTF byte order mark, if present
static java.lang.String	toXml(org.w3c.dom.Node node) Dump an XML tree to string.
static java.lang.String	toXml(org.w3c.dom.Node node, java.util.Map<SourcePosition,SourceFilePosition> blame)
static java.lang.String	toXmlAttributeValue(java.lang.String attrValue) Converts the given attribute value to an XML-attribute-safe value, meaning that single and double quotes are replaced with their corresponding XML entities.
static java.lang.String	toXmlTextValue(java.lang.String textValue) Converts the given attribute value to an XML-text-safe value, meaning that less than and ampersand characters are escaped.

Methods inherited from class java.lang.Object

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

Field Detail

XML_COMMENT_BEGIN

public static final java.lang.String XML_COMMENT_BEGIN

See Also:

Constant Field Values

XML_COMMENT_END

public static final java.lang.String XML_COMMENT_END

See Also:

Constant Field Values

XML_PROLOG

public static final java.lang.String XML_PROLOG

See Also:

Constant Field Values

NS_SEPARATOR

public static final char NS_SEPARATOR

Separator for xml namespace and localname

See Also:

Constant Field Values

Constructor Detail

XmlUtils

public XmlUtils()

Method Detail

lookupNamespacePrefix

@NonNull
public static java.lang.String lookupNamespacePrefix(@NonNull
                                                              org.w3c.dom.Node node,
                                                              @NonNull
                                                              java.lang.String nsUri)

Returns the namespace prefix matching the requested namespace URI. If no such declaration is found, returns the default "android" prefix for the Android URI, and "app" for other URI's. By default the app namespace will be created. If this is not desirable, call lookupNamespacePrefix(Node, String, boolean) instead.

Parameters:

node - The current node. Must not be null.

nsUri - The namespace URI of which the prefix is to be found, e.g. SdkConstants.ANDROID_URI

Returns:

The first prefix declared or the default "android" prefix (or "app" for non-Android URIs)

lookupNamespacePrefix

@NonNull
public static java.lang.String lookupNamespacePrefix(@NonNull
                                                              org.w3c.dom.Node node,
                                                              @NonNull
                                                              java.lang.String nsUri,
                                                              boolean create)

Returns the namespace prefix matching the requested namespace URI. If no such declaration is found, returns the default "android" prefix for the Android URI, and "app" for other URI's.

Parameters:

node - The current node. Must not be null.

nsUri - The namespace URI of which the prefix is to be found, e.g. SdkConstants.ANDROID_URI

create - whether the namespace declaration should be created, if necessary

Returns:

The first prefix declared or the default "android" prefix (or "app" for non-Android URIs)

lookupNamespacePrefix

public static java.lang.String lookupNamespacePrefix(@Nullable
                                                     org.w3c.dom.Node node,
                                                     @Nullable
                                                     java.lang.String nsUri,
                                                     @Nullable
                                                     java.lang.String defaultPrefix,
                                                     boolean create)

Returns the namespace prefix matching the requested namespace URI. If no such declaration is found, returns the default "android" prefix.

Parameters:

node - The current node. Must not be null.

nsUri - The namespace URI of which the prefix is to be found, e.g. SdkConstants.ANDROID_URI

defaultPrefix - The default prefix (root) to use if the namespace is not found. If null, do not create a new namespace if this URI is not defined for the document.

create - whether the namespace declaration should be created, if necessary

Returns:

The first prefix declared or the provided prefix (possibly with a number appended to avoid conflicts with existing prefixes.

toXmlAttributeValue

@NonNull
public static java.lang.String toXmlAttributeValue(@NonNull
                                                            java.lang.String attrValue)

Converts the given attribute value to an XML-attribute-safe value, meaning that single and double quotes are replaced with their corresponding XML entities.

Parameters:

attrValue - the value to be escaped

Returns:

the escaped value

fromXmlAttributeValue

@NonNull
public static java.lang.String fromXmlAttributeValue(@NonNull
                                                              java.lang.String escapedAttrValue)

Converts the given XML-attribute-safe value to a java string

Parameters:

escapedAttrValue - the escaped value

Returns:

the unescaped value

toXmlTextValue

@NonNull
public static java.lang.String toXmlTextValue(@NonNull
                                                       java.lang.String textValue)

Converts the given attribute value to an XML-text-safe value, meaning that less than and ampersand characters are escaped.

Parameters:

textValue - the text value to be escaped

Returns:

the escaped value

appendXmlAttributeValue

public static void appendXmlAttributeValue(@NonNull
                                           java.lang.StringBuilder sb,
                                           @NonNull
                                           java.lang.String attrValue)

Appends text to the given StringBuilder and escapes it as required for a DOM attribute node.

Parameters:

sb - the string builder

attrValue - the attribute value to be appended and escaped

appendXmlAttributeValue

public static void appendXmlAttributeValue(@NonNull
                                           java.lang.StringBuilder sb,
                                           @NonNull
                                           java.lang.String attrValue,
                                           int start,
                                           int end)

Appends text to the given StringBuilder and escapes it as required for a DOM attribute node.

Parameters:

sb - the string builder

attrValue - the attribute value to be appended and escaped

start - the starting offset in the text string

end - the ending offset in the text string

appendXmlTextValue

public static void appendXmlTextValue(@NonNull
                                      java.lang.StringBuilder sb,
                                      @NonNull
                                      java.lang.String textValue)

Appends text to the given StringBuilder and escapes it as required for a DOM text node.

Parameters:

sb - the string builder

textValue - the text value to be appended and escaped

appendXmlTextValue

public static void appendXmlTextValue(@NonNull
                                      java.lang.StringBuilder sb,
                                      @NonNull
                                      java.lang.String textValue,
                                      int start,
                                      int end)

Appends text to the given StringBuilder and escapes it as required for a DOM text node.

Parameters:

sb - the string builder

textValue - the text value to be appended and escaped

start - the starting offset in the text string

end - the ending offset in the text string

hasElementChildren

public static boolean hasElementChildren(@NonNull
                                         org.w3c.dom.Node node)

Returns true if the given node has one or more element children

Parameters:

node - the node to test for element children

Returns:

true if the node has one or more element children

getUtfReader

@NonNull
public static java.io.Reader getUtfReader(@NonNull
                                                   java.io.File file)
                                            throws java.io.IOException

Returns a character reader for the given file, which must be a UTF encoded file.

The reader does not need to be closed by the caller (because the file is read in full in one shot and the resulting array is then wrapped in a byte array input stream, which does not need to be closed.)

Throws:

java.io.IOException

parseDocument

@NonNull
public static org.w3c.dom.Document parseDocument(@NonNull
                                                          java.lang.String xml,
                                                          boolean namespaceAware)
                                                   throws java.io.IOException,
                                                          org.xml.sax.SAXException

Parses the given XML string as a DOM document, using the JDK parser. The parser does not validate, and is optionally namespace aware.

Parameters:

xml - the XML content to be parsed (must be well formed)

namespaceAware - whether the parser is namespace aware

Returns:

the DOM document

Throws:

java.io.IOException

org.xml.sax.SAXException

parseDocument

@NonNull
public static org.w3c.dom.Document parseDocument(@NonNull
                                                          java.io.Reader xml,
                                                          boolean namespaceAware)
                                                   throws java.io.IOException,
                                                          org.xml.sax.SAXException

Parses the given Reader as a DOM document, using the JDK parser. The parser does not validate, and is optionally namespace aware.

Parameters:

xml - a reader for the XML content to be parsed (must be well formed)

namespaceAware - whether the parser is namespace aware

Returns:

the DOM document

Throws:

java.io.IOException

org.xml.sax.SAXException

parseUtfXmlFile

@NonNull
public static org.w3c.dom.Document parseUtfXmlFile(@NonNull
                                                            java.io.File file,
                                                            boolean namespaceAware)
                                                     throws java.io.IOException,
                                                            org.xml.sax.SAXException

Parses the given UTF file as a DOM document, using the JDK parser. The parser does not validate, and is optionally namespace aware.

Parameters:

file - the UTF encoded file to parse

namespaceAware - whether the parser is namespace aware

Returns:

the DOM document

Throws:

java.io.IOException

org.xml.sax.SAXException

createDocument

@NonNull
public static org.w3c.dom.Document createDocument(boolean namespaceAware)

Creates and returns a new empty document.

stripBom

@NonNull
public static java.lang.String stripBom(@NonNull
                                                 java.lang.String xml)

Strips out a leading UTF byte order mark, if present

parseDocumentSilently

@Nullable
public static org.w3c.dom.Document parseDocumentSilently(@NonNull
                                                                   java.lang.String xml,
                                                                   boolean namespaceAware)

Parses the given XML string as a DOM document, using the JDK parser. The parser does not validate, and is optionally namespace aware. Any parsing errors are silently ignored.

Parameters:

xml - the XML content to be parsed (must be well formed)

namespaceAware - whether the parser is namespace aware

Returns:

the DOM document, or null

configureSaxFactory

public static javax.xml.parsers.SAXParserFactory configureSaxFactory(@NonNull
                                                                     javax.xml.parsers.SAXParserFactory factory,
                                                                     boolean namespaceAware,
                                                                     boolean checkDtd)

createSaxParser

@NonNull
public static javax.xml.parsers.SAXParser createSaxParser(@NonNull
                                                                   javax.xml.parsers.SAXParserFactory factory)
                                                            throws javax.xml.parsers.ParserConfigurationException,
                                                                   org.xml.sax.SAXException

Throws:

javax.xml.parsers.ParserConfigurationException

org.xml.sax.SAXException

createSaxParser

@NonNull
public static javax.xml.parsers.SAXParser createSaxParser(@NonNull
                                                                   javax.xml.parsers.SAXParserFactory factory,
                                                                   boolean allowDocTypeDeclarations)
                                                            throws javax.xml.parsers.ParserConfigurationException,
                                                                   org.xml.sax.SAXException

Throws:

javax.xml.parsers.ParserConfigurationException

org.xml.sax.SAXException

toXml

public static java.lang.String toXml(@NonNull
                                     org.w3c.dom.Node node)

Dump an XML tree to string. This does not perform any pretty printing. To perform pretty printing, use XmlPrettyPrinter.prettyPrint(node) in sdk-common.

toXml

public static java.lang.String toXml(@NonNull
                                     org.w3c.dom.Node node,
                                     @Nullable
                                     java.util.Map<SourcePosition,SourceFilePosition> blame)

attachSourceFile

public static void attachSourceFile(@NonNull
                                    org.w3c.dom.Node node,
                                    @NonNull
                                    SourceFile sourceFile)

getSourceFilePosition

@NonNull
public static SourceFilePosition getSourceFilePosition(@NonNull
                                                                org.w3c.dom.Node node)

formatFloatAttribute

@NonNull
public static java.lang.String formatFloatAttribute(double value)

Formats the number and removes trailing zeros after the decimal dot and also the dot itself if there were non-zero digits after it.

Parameters:

value - the value to be formatted

Returns:

the corresponding XML string for the value

getRootTagName

@Nullable
public static java.lang.String getRootTagName(@NonNull
                                                        java.io.File xmlFile)

Returns the name of the root element tag stored in the given file, or null if it can't be determined.

getRootTagName

@Nullable
public static java.lang.String getRootTagName(@NonNull
                                                        java.lang.String xmlText)

Returns the name of the root element tag stored in the given file, or null if it can't be determined.

getSubTagsAsList

@NonNull
public static java.util.List<org.w3c.dom.Element> getSubTagsAsList(@NonNull
                                                                            org.w3c.dom.Node parent)

Returns the children elements of the given node

Parameters:

parent - the parent node

Returns:

a list of element children, never null

getSubTags

@NonNull
public static java.lang.Iterable<org.w3c.dom.Element> getSubTags(@Nullable
                                                                          org.w3c.dom.Node parent)

Returns an iterator for the children elements of the given node. If you want to access the children as a list, use getSubTagsAsList(Node) instead.

NOTE: The iterator() call can only be called once!

getSubTagsByName

@NonNull
public static java.lang.Iterable<org.w3c.dom.Element> getSubTagsByName(@Nullable
                                                                                org.w3c.dom.Node parent,
                                                                                @NonNull
                                                                                java.lang.String tagName)

Returns an iterator for the children elements of the given node matching the given tag name.

If you want to access the children as a list, use getSubTagsAsList(Node) instead.

NOTE: The iterator() call can only be called once!

getFirstSubTag

@Nullable
public static org.w3c.dom.Element getFirstSubTag(@Nullable
                                                           org.w3c.dom.Node parent)

Returns the first child element of the given node

getNextTag

@Nullable
public static org.w3c.dom.Element getNextTag(@Nullable
                                                       org.w3c.dom.Node node)

Returns the next sibling element from the given node

getPreviousTag

@Nullable
public static org.w3c.dom.Element getPreviousTag(@Nullable
                                                           org.w3c.dom.Node node)

Returns the previous sibling element from the given node

getFirstSubTagByName

@Nullable
public static org.w3c.dom.Element getFirstSubTagByName(@Nullable
                                                                 org.w3c.dom.Node parent,
                                                                 @NonNull
                                                                 java.lang.String name)

Returns the next sibling element from the given node that matches the given name

getNextTagByName

@Nullable
public static org.w3c.dom.Element getNextTagByName(@Nullable
                                                             org.w3c.dom.Node node,
                                                             @NonNull
                                                             java.lang.String name)

Returns the next sibling element from the given node

getPreviousTagByName

@Nullable
public static org.w3c.dom.Element getPreviousTagByName(@Nullable
                                                                 org.w3c.dom.Node node,
                                                                 @NonNull
                                                                 java.lang.String name)

getPreviousComment

@Nullable
public static org.w3c.dom.Comment getPreviousComment(@NonNull
                                                               org.w3c.dom.Node element)

Returns the comment preceding the given element with no other elements in between, or null if the element is not preceded by a comment.

getPreviousCommentText

@Nullable
public static java.lang.String getPreviousCommentText(@NonNull
                                                                org.w3c.dom.Node element)

Returns the text of the comment preceding the given element with no other elements in between, or null if the element is not preceded by a comment or if the comment is empty or consists of only whitespace characters.

getSubTagCount

public static int getSubTagCount(@Nullable
                                 org.w3c.dom.Node parent)

Returns the number of children sub tags of the given node.

Parameters:

parent - the parent node

Returns:

the count of element children

isProtoXml

public static boolean isProtoXml(@NonNull
                                 byte[] bytes)

Checks if the given array of bytes is likely to represent XML in a proto format.

Parameters:

bytes - the candidate XML contents to check

Returns:

true if the bytes are likely to represent proto XML

isProtoXml

public static boolean isProtoXml(@NonNull
                                 java.io.InputStream stream)

Checks if the given input stream is likely to represent XML in a proto format.

Parameters:

stream - the candidate XML stream to check

Returns:

true if the stream is likely to represent proto XML