com.android.tools.lint.client.api

Class XmlParser

java.lang.Object

com.android.tools.lint.client.api.XmlParser

@Beta
public abstract class XmlParser
extends java.lang.Object

A wrapper for an XML parser. This allows tools integrating lint to map directly to builtin services, such as already-parsed data structures in XML editors.

NOTE: This is not a public or final API; if you rely on this be prepared to adjust your code for the next tools release.

Constructor Summary

Constructors

Constructor and Description
XmlParser()

Method Summary

Modifier and Type	Method and Description
abstract Location.Handle	createLocationHandle(XmlContext context, org.w3c.dom.Node node) Creates a light-weight handle to a location for the given node.
void	dispose(XmlContext context, org.w3c.dom.Document document) Dispose any data structures held for the given context.
abstract org.w3c.dom.Node	findNodeAt(XmlContext context, int offset) Returns the leaf node at the given offset (biased towards the right), or null if not found
abstract Location	getLocation(java.io.File file, org.w3c.dom.Node node) Attempt to create a location for a given XML node.
abstract Location	getLocation(XmlContext context, org.w3c.dom.Node node) Returns a Location for the given DOM node
abstract Location	getLocation(XmlContext context, org.w3c.dom.Node node, int start, int end) Returns a Location for the given DOM node.
abstract Location	getNameLocation(XmlContext context, org.w3c.dom.Node node) Returns a Location for the given DOM node
abstract int	getNodeEndOffset(XmlContext context, org.w3c.dom.Node node) Returns the end offset of the given node, or -1 if not known
abstract int	getNodeStartOffset(XmlContext context, org.w3c.dom.Node node) Returns the start offset of the given node, or -1 if not known
abstract Location	getValueLocation(XmlContext context, org.w3c.dom.Attr node) Returns a Location for the given DOM node
abstract org.w3c.dom.Document	parseXml(java.io.File file) Parse the given XML content and returns as a Document
abstract org.w3c.dom.Document	parseXml(XmlContext context) Parse the file pointed to by the given context and return as a Document

Methods inherited from class java.lang.Object

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

Constructor Detail

XmlParser

public XmlParser()

Method Detail

parseXml

@Nullable
public abstract org.w3c.dom.Document parseXml(@NonNull
                                                        java.io.File file)
                                                 throws java.io.IOException,
                                                        org.xml.sax.SAXException,
                                                        javax.xml.parsers.ParserConfigurationException

Parse the given XML content and returns as a Document

Parameters:

file - the file to be parsed

Returns:

the parsed DOM document

Throws:

java.io.IOException

org.xml.sax.SAXException

javax.xml.parsers.ParserConfigurationException

parseXml

@Nullable
public abstract org.w3c.dom.Document parseXml(@NonNull
                                                        XmlContext context)

Parse the file pointed to by the given context and return as a Document

Parameters:

context - the context pointing to the file to be parsed, typically via Context.getContents() but the file handle ( Context.file can also be used to map to an existing editor buffer in the surrounding tool, etc)

Returns:

the parsed DOM document, or null if parsing fails

getLocation

@NonNull
public abstract Location getLocation(@NonNull
                                              XmlContext context,
                                              @NonNull
                                              org.w3c.dom.Node node)

Returns a Location for the given DOM node

Parameters:

context - information about the file being parsed

node - the node to create a location for

Returns:

a location for the given node

getLocation

@NonNull
public abstract Location getLocation(@NonNull
                                              java.io.File file,
                                              @NonNull
                                              org.w3c.dom.Node node)

Attempt to create a location for a given XML node. Note that since DOM does not normally provide offset information for nodes, this doesn't work if you pass in a random DOM node from your own parsing operations; you should only call this method with nodes provided by lint in the first place (internally it uses a special parser which tracks offset information.)

Parameters:

file - the file that contains the node that was parsed

node - the node itself

Returns:

a location for the node, if possible

getLocation

@NonNull
public abstract Location getLocation(@NonNull
                                              XmlContext context,
                                              @NonNull
                                              org.w3c.dom.Node node,
                                              int start,
                                              int end)

Returns a Location for the given DOM node. Like getLocation(XmlContext, Node), but allows a position range that is a subset of the node range.

Parameters:

context - information about the file being parsed

node - the node to create a location for

start - the starting position within the node, inclusive

end - the ending position within the node, exclusive

Returns:

a location for the given node

getNameLocation

@NonNull
public abstract Location getNameLocation(@NonNull
                                                  XmlContext context,
                                                  @NonNull
                                                  org.w3c.dom.Node node)

Returns a Location for the given DOM node

Parameters:

context - information about the file being parsed

node - the node to create a location for

Returns:

a location for the given node

getValueLocation

@NonNull
public abstract Location getValueLocation(@NonNull
                                                   XmlContext context,
                                                   @NonNull
                                                   org.w3c.dom.Attr node)

Returns a Location for the given DOM node

Parameters:

context - information about the file being parsed

node - the node to create a location for

Returns:

a location for the given node

createLocationHandle

@NonNull
public abstract Location.Handle createLocationHandle(@NonNull
                                                              XmlContext context,
                                                              @NonNull
                                                              org.w3c.dom.Node node)

Creates a light-weight handle to a location for the given node. It can be turned into a full fledged location by Location.Handle.resolve().

Parameters:

context - the context providing the node

node - the node (element or attribute) to create a location handle for

Returns:

a location handle

dispose

public void dispose(@NonNull
                    XmlContext context,
                    @NonNull
                    org.w3c.dom.Document document)

Dispose any data structures held for the given context.

Parameters:

context - information about the file previously parsed

document - the document that was parsed and is now being disposed

getNodeStartOffset

public abstract int getNodeStartOffset(@NonNull
                                       XmlContext context,
                                       @NonNull
                                       org.w3c.dom.Node node)

Returns the start offset of the given node, or -1 if not known

Parameters:

context - the context providing the node

node - the node (element or attribute) to create a location handle for

Returns:

the start offset, or -1 if not known

getNodeEndOffset

public abstract int getNodeEndOffset(@NonNull
                                     XmlContext context,
                                     @NonNull
                                     org.w3c.dom.Node node)

Returns the end offset of the given node, or -1 if not known

Parameters:

context - the context providing the node

node - the node (element or attribute) to create a location handle for

Returns:

the end offset, or -1 if not known

findNodeAt

@Nullable
public abstract org.w3c.dom.Node findNodeAt(@NonNull
                                                      XmlContext context,
                                                      int offset)

Returns the leaf node at the given offset (biased towards the right), or null if not found

Parameters:

offset - the offset to search at

Returns:

the leaf node, if any