com.android.tools.lint.client.api
Class LintClient

java.lang.Object
  com.android.tools.lint.client.api.LintClient

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

Information about the tool embedding the lint analyzer. IDEs and other tools implementing lint support will extend this to integrate logging, displaying errors, etc.

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.

Nested Class Summary

protected static class

LintClient.ClassPathInfo Information about class paths (sources, class files and libraries) usually associated with a project.

Field Summary

static java.lang.String	CLIENT_CLI The client name returned by getClientName() when running in the CLI (command line interface) version of lint, lint
static java.lang.String	CLIENT_GRADLE The client name returned by getClientName() when running in Gradle
static java.lang.String	CLIENT_STUDIO The client name returned by getClientName() when running in Android Studio/IntelliJ IDEA
static java.lang.String	CLIENT_UNKNOWN The client name returned by getClientName() when running in some unknown client
protected com.android.sdklib.repositoryv2.AndroidSdkHandler	mSdk
protected com.android.sdklib.IAndroidTarget[]	mTargets

Constructor Summary

protected	LintClient()
protected	LintClient(java.lang.String clientName)

Method Summary

IssueRegistry	addCustomLintRules(IssueRegistry registry) Adds in any custom lint rules and returns the result as a new issue registry, or the same one if no custom rules were found
boolean	checkForSuppressComments() Returns whether lint should look for suppress comments.
void	closeConnection(java.net.URLConnection connection) Closes a connection previously returned by openConnection(java.net.URL)
protected Project	createProject(java.io.File dir, java.io.File referenceDir) Create a project for the given directory
Location.Handle	createResourceItemHandle(com.android.ide.common.res2.ResourceItem item) For a lint client which supports resource items (via supportsProjectResources()) return a handle for a resource item
java.util.Map<java.lang.String,java.lang.String>	createSuperClassMap(Project project) Creates a super class map for the given project.
java.lang.ClassLoader	createUrlClassLoader(java.net.URL[] urls, java.lang.ClassLoader parent) Creates a ClassLoader which can load in a set of Jar files.
java.util.List<java.io.File>	findGlobalRuleJars() Finds any custom lint rule jars that should be included for analysis, regardless of project.
java.io.File	findResource(java.lang.String relativePath) Locates an SDK resource (relative to the SDK root directory).
java.util.List<java.io.File>	findRuleJars(Project project) Finds any custom lint rule jars that should be included for analysis in the given project
java.util.List<java.io.File>	getAssetFolders(Project project) Returns the asset folders.
com.android.sdklib.BuildToolInfo	getBuildTools(Project project) Returns the specific version of the build tools being used for the given project, if known
java.io.File	getCacheDir(boolean create) Returns a suitable location for storing cache files.
protected LintClient.ClassPathInfo	getClassPath(Project project) Considers the given project as an Eclipse project and returns class path information for the project - the source folder(s), the output folder and any libraries.
static java.lang.String	getClientName() Returns the name of the embedding client.
com.android.sdklib.IAndroidTarget	getCompileTarget(Project project) Returns the compile target to use for the given project
Configuration	getConfiguration(Project project, LintDriver driver) Returns a configuration for use by the given project.
int	getHighestKnownApiLevel() Returns the highest known API level.
java.util.List<java.io.File>	getJavaClassFolders(Project project) Returns the list of output folders for class files
java.util.List<java.io.File>	getJavaLibraries(Project project, boolean includeProvided) Returns the list of Java libraries
abstract JavaParser	getJavaParser(Project project) Returns a JavaParser to use to parse Java
java.util.List<java.io.File>	getJavaSourceFolders(Project project) Returns the list of source folders for Java source files
java.util.Collection<Project>	getKnownProjects() Returns the list of known projects (projects registered via getProject(File, File)
Project	getProject(java.io.File dir, java.io.File referenceDir) Returns a project for the given directory.
java.lang.String	getProjectName(Project project) Returns the name of the given project
com.android.ide.common.res2.AbstractResourceRepository	getProjectResources(Project project, boolean includeDependencies) Returns the project resources, if available
com.android.repository.api.ProgressIndicator	getRepositoryLogger() Returns a repository logger used by this client.
java.util.List<java.io.File>	getResourceFolders(Project project) Returns the resource folders.
com.android.ide.common.repository.ResourceVisibilityLookup.Provider	getResourceVisibilityProvider() Returns a shared ResourceVisibilityLookup.Provider
com.android.sdklib.repositoryv2.AndroidSdkHandler	getSdk() Returns the SDK installation (used to look up platforms etc)
java.io.File	getSdkHome() Returns the File pointing to the user's SDK install area.
SdkInfo	getSdkInfo(Project project) Returns the SdkInfo to use for the given project.
java.lang.String	getSuperClass(Project project, java.lang.String name) Returns the super class for the given class name, which should be in VM format (e.g.
com.android.sdklib.IAndroidTarget[]	getTargets() Returns all the IAndroidTarget versions installed in the user's SDK install area.
java.util.List<java.io.File>	getTestSourceFolders(Project project) Returns the list of source folders for test source files
abstract XmlParser	getXmlParser() Returns a XmlParser to use to parse XML
static boolean	isGradle() Returns true if the embedding client currently running lint is Gradle
boolean	isGradleProject(Project project) Returns true if this project is a Gradle-based Android project
boolean	isProjectDirectory(java.io.File dir) Returns true if the given directory is a lint project directory.
static boolean	isStudio() Returns true if the embedding client currently running lint is Android Studio (or IntelliJ IDEA)
java.lang.Boolean	isSubclassOf(Project project, java.lang.String name, java.lang.String superClassName) Checks whether the given name is a subclass of the given super class.
abstract void	log(Severity severity, java.lang.Throwable exception, java.lang.String format, java.lang.Object... args) Send an exception or error message to the log
void	log(java.lang.Throwable exception, java.lang.String format, java.lang.Object... args) Send an exception or error message (with warning severity) to the log
java.net.URLConnection	openConnection(java.net.URL url) Opens a URL connection.
byte[]	readBytes(java.io.File file) Reads the given binary file and returns the content as a byte array.
abstract java.lang.String	readFile(java.io.File file) Reads the given text file and returns the content as a string
void	registerProject(java.io.File dir, Project project) Registers the given project for the given directory.
java.lang.Class<? extends Detector>	replaceDetector(java.lang.Class<? extends Detector> detectorClass) Returns an optimal detector, if applicable.
abstract void	report(Context context, Issue issue, Severity severity, Location location, java.lang.String message, TextFormat format) Report the given issue.
boolean	supportsProjectResources() Returns true if this client supports project resource repository lookup via getProjectResources(Project,boolean)

Methods inherited from class java.lang.Object

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

Field Detail

mTargets

protected com.android.sdklib.IAndroidTarget[] mTargets

mSdk

protected com.android.sdklib.repositoryv2.AndroidSdkHandler mSdk

CLIENT_STUDIO

public static final java.lang.String CLIENT_STUDIO

The client name returned by getClientName() when running in Android Studio/IntelliJ IDEA

See Also:

Constant Field Values

CLIENT_GRADLE

public static final java.lang.String CLIENT_GRADLE

The client name returned by getClientName() when running in Gradle

See Also:

Constant Field Values

CLIENT_CLI

public static final java.lang.String CLIENT_CLI

The client name returned by getClientName() when running in the CLI (command line interface) version of lint, lint

See Also:

Constant Field Values

CLIENT_UNKNOWN

public static final java.lang.String CLIENT_UNKNOWN

The client name returned by getClientName() when running in some unknown client

See Also:

Constant Field Values

Constructor Detail

LintClient

protected LintClient(@NonNull
                     java.lang.String clientName)

LintClient

protected LintClient()

Method Detail

getConfiguration

@NonNull
public Configuration getConfiguration(@NonNull
                                              Project project,
                                              @Nullable
                                              LintDriver driver)

Returns a configuration for use by the given project. The configuration provides information about which issues are enabled, any customizations to the severity of an issue, etc.

By default this method returns a DefaultConfiguration.

Parameters:

project - the project to obtain a configuration for

driver - the current driver, if any

Returns:

a configuration, never null.

report

public abstract void report(@NonNull
                            Context context,
                            @NonNull
                            Issue issue,
                            @NonNull
                            Severity severity,
                            @Nullable
                            Location location,
                            @NonNull
                            java.lang.String message,
                            @NonNull
                            TextFormat format)

Report the given issue. This method will only be called if the configuration provided by getConfiguration(Project,LintDriver) has reported the corresponding issue as enabled and has not filtered out the issue with its Configuration.ignore(Context,Issue,Location,String) method.

Parameters:

context - the context used by the detector when the issue was found

issue - the issue that was found

severity - the severity of the issue

location - the location of the issue

message - the associated user message

format - the format of the description and location descriptions

log

public void log(@Nullable
                java.lang.Throwable exception,
                @Nullable
                java.lang.String format,
                @Nullable
                java.lang.Object... args)

Send an exception or error message (with warning severity) to the log

Parameters:

exception - the exception, possibly null

format - the error message using String.format(java.lang.String, java.lang.Object...) syntax, possibly null (though in that case the exception should not be null)

args - any arguments for the format string

log

public abstract void log(@NonNull
                         Severity severity,
                         @Nullable
                         java.lang.Throwable exception,
                         @Nullable
                         java.lang.String format,
                         @Nullable
                         java.lang.Object... args)

Send an exception or error message to the log

Parameters:

severity - the severity of the warning

exception - the exception, possibly null

format - the error message using String.format(java.lang.String, java.lang.Object...) syntax, possibly null (though in that case the exception should not be null)

args - any arguments for the format string

getXmlParser

@Nullable
public abstract XmlParser getXmlParser()

Returns a XmlParser to use to parse XML

Returns:

a new XmlParser, or null if this client does not support XML analysis

getJavaParser

@Nullable
public abstract JavaParser getJavaParser(@Nullable
                                                  Project project)

Returns a JavaParser to use to parse Java

Parameters:

project - the project to parse, if known (this can be used to look up the class path for type attribution etc, and it can also be used to more efficiently process a set of files, for example to perform type attribution for multiple units in a single pass)

Returns:

a new JavaParser, or null if this client does not support Java analysis

replaceDetector

@NonNull
public java.lang.Class<? extends Detector> replaceDetector(@NonNull
                                                                   java.lang.Class<? extends Detector> detectorClass)

Returns an optimal detector, if applicable. By default, just returns the original detector, but tools can replace detectors using this hook with a version that takes advantage of native capabilities of the tool.

Parameters:

detectorClass - the class of the detector to be replaced

Returns:

the new detector class, or just the original detector (not null)

readFile

@NonNull
public abstract java.lang.String readFile(@NonNull
                                                  java.io.File file)

Reads the given text file and returns the content as a string

Parameters:

file - the file to read

Returns:

the string to return, never null (will be empty if there is an I/O error)

readBytes

@NonNull
public byte[] readBytes(@NonNull
                                java.io.File file)
                 throws java.io.IOException

Reads the given binary file and returns the content as a byte array. By default this method will read the bytes from the file directly, but this can be customized by a client if for example I/O could be held in memory and not flushed to disk yet.

Parameters:

file - the file to read

Returns:

the bytes in the file, never null

Throws:

java.io.IOException - if the file does not exist, or if the file cannot be read for some reason

getJavaSourceFolders

@NonNull
public java.util.List<java.io.File> getJavaSourceFolders(@NonNull
                                                                 Project project)

Returns the list of source folders for Java source files

Parameters:

project - the project to look up Java source file locations for

Returns:

a list of source folders to search for .java files

getJavaClassFolders

@NonNull
public java.util.List<java.io.File> getJavaClassFolders(@NonNull
                                                                Project project)

Returns the list of output folders for class files

Parameters:

project - the project to look up class file locations for

Returns:

a list of output folders to search for .class files

getJavaLibraries

@NonNull
public java.util.List<java.io.File> getJavaLibraries(@NonNull
                                                             Project project,
                                                             boolean includeProvided)

Returns the list of Java libraries

Parameters:

project - the project to look up jar dependencies for

includeProvided - If true, included provided libraries too (libraries that are not packaged with the app, but are provided for compilation purposes and are assumed to be present in the running environment)

Returns:

a list of jar dependencies containing .class files

getTestSourceFolders

@NonNull
public java.util.List<java.io.File> getTestSourceFolders(@NonNull
                                                                 Project project)

Returns the list of source folders for test source files

Parameters:

project - the project to look up test source file locations for

Returns:

a list of source folders to search for .java files

getResourceFolders

@NonNull
public java.util.List<java.io.File> getResourceFolders(@NonNull
                                                               Project project)

Returns the resource folders.

Parameters:

project - the project to look up the resource folder for

Returns:

a list of files pointing to the resource folders, possibly empty

getAssetFolders

@NonNull
public java.util.List<java.io.File> getAssetFolders(@NonNull
                                                            Project project)

Returns the asset folders.

Parameters:

project - the project to look up the asset folder for

Returns:

a list of files pointing to the asset folders, possibly empty

getSdkInfo

@NonNull
public SdkInfo getSdkInfo(@NonNull
                                  Project project)

Returns the SdkInfo to use for the given project.

Parameters:

project - the project to look up an SdkInfo for

Returns:

an SdkInfo for the project

getCacheDir

@Nullable
public java.io.File getCacheDir(boolean create)

Returns a suitable location for storing cache files. Note that the directory may not exist.

Parameters:

create - if true, attempt to create the cache dir if it does not exist

Returns:

a suitable location for storing cache files, which may be null if the create flag was false, or if for some reason the directory could not be created

getSdkHome

@Nullable
public java.io.File getSdkHome()

Returns the File pointing to the user's SDK install area. This is generally the root directory containing the lint tool (but also platforms/ etc).

Returns:

a file pointing to the user's install area

findResource

@Nullable
public java.io.File findResource(@NonNull
                                          java.lang.String relativePath)

Locates an SDK resource (relative to the SDK root directory).

TODO: Consider switching to a URL return type instead.

Parameters:

relativePath - A relative path (using File.separator to separate path components) to the given resource

Returns:

a File pointing to the resource, or null if it does not exist

isGradleProject

public boolean isGradleProject(Project project)

Returns true if this project is a Gradle-based Android project

Parameters:

project - the project to check

Returns:

true if this is a Gradle-based project

getClassPath

@NonNull
protected LintClient.ClassPathInfo getClassPath(@NonNull
                                                        Project project)

Considers the given project as an Eclipse project and returns class path information for the project - the source folder(s), the output folder and any libraries.

Callers will not cache calls to this method, so if it's expensive to compute the classpath info, this method should perform its own caching.

Parameters:

project - the project to look up class path info for

Returns:

a class path info object, never null

getProject

@NonNull
public Project getProject(@NonNull
                                  java.io.File dir,
                                  @NonNull
                                  java.io.File referenceDir)

Returns a project for the given directory. This should return the same project for the same directory if called repeatedly.

Parameters:

dir - the directory containing the project

referenceDir - See Project.getReferenceDir().

Returns:

a project, never null

getKnownProjects

public java.util.Collection<Project> getKnownProjects()

Returns the list of known projects (projects registered via getProject(File, File)

Returns:

a collection of projects in any order

registerProject

public void registerProject(@NonNull
                            java.io.File dir,
                            @NonNull
                            Project project)

Registers the given project for the given directory. This can be used when projects are initialized outside of the client itself.

Parameters:

dir - the directory of the project, which must be unique

project - the project

createProject

@NonNull
protected Project createProject(@NonNull
                                        java.io.File dir,
                                        @NonNull
                                        java.io.File referenceDir)

Create a project for the given directory

Parameters:

dir - the root directory of the project

referenceDir - See Project.getReferenceDir().

Returns:

a new project

getProjectName

@NonNull
public java.lang.String getProjectName(@NonNull
                                               Project project)

Returns the name of the given project

Parameters:

project - the project to look up

Returns:

the name of the project

getTargets

@NonNull
public com.android.sdklib.IAndroidTarget[] getTargets()

Returns all the IAndroidTarget versions installed in the user's SDK install area.

Returns:

all the installed targets

getSdk

@Nullable
public com.android.sdklib.repositoryv2.AndroidSdkHandler getSdk()

Returns the SDK installation (used to look up platforms etc)

Returns:

the SDK if known

getCompileTarget

@Nullable
public com.android.sdklib.IAndroidTarget getCompileTarget(@NonNull
                                                                   Project project)

Returns the compile target to use for the given project

Parameters:

project - the project in question

Returns:

the compile target to use to build the given project

getHighestKnownApiLevel

public int getHighestKnownApiLevel()

Returns the highest known API level.

Returns:

the highest known API level

getBuildTools

@Nullable
public com.android.sdklib.BuildToolInfo getBuildTools(@NonNull
                                                               Project project)

Returns the specific version of the build tools being used for the given project, if known

Parameters:

project - the project in question

Returns:

the build tools version in use by the project, or null if not known

getSuperClass

@Nullable
public java.lang.String getSuperClass(@NonNull
                                               Project project,
                                               @NonNull
                                               java.lang.String name)

Returns the super class for the given class name, which should be in VM format (e.g. java/lang/Integer, not java.lang.Integer, and using $ rather than . for inner classes). If the super class is not known, returns null.

This is typically not necessary, since lint analyzes all the available classes. However, if this lint client is invoking lint in an incremental context (for example, an IDE offering incremental analysis of a single source file), then lint may not see all the classes, and the client can provide its own super class lookup.

Parameters:

project - the project containing the class

name - the fully qualified class name

Returns:

the corresponding super class name (in VM format), or null if not known

createSuperClassMap

@NonNull
public java.util.Map<java.lang.String,java.lang.String> createSuperClassMap(@NonNull
                                                                                    Project project)

Creates a super class map for the given project. The map maps from internal class name (e.g. java/lang/Integer, not java.lang.Integer) to its corresponding super class name. The root class, java/lang/Object, is not in the map.

Parameters:

project - the project to initialize the super class with; this will include local classes as well as any local .jar libraries; not transitive dependencies

Returns:

a map from class to its corresponding super class; never null

isSubclassOf

@Nullable
public java.lang.Boolean isSubclassOf(@NonNull
                                               Project project,
                                               @NonNull
                                               java.lang.String name,
                                               @NonNull
                                               java.lang.String superClassName)

Checks whether the given name is a subclass of the given super class. If the method does not know, it should return null, and otherwise return Boolean.TRUE or Boolean.FALSE.

Note that the class names are in internal VM format (java/lang/Integer, not java.lang.Integer, and using $ rather than . for inner classes).

Parameters:

project - the project context to look up the class in

name - the name of the class to be checked

superClassName - the name of the super class to compare to

Returns:

true if the class of the given name extends the given super class

findGlobalRuleJars

@NonNull
public java.util.List<java.io.File> findGlobalRuleJars()

Finds any custom lint rule jars that should be included for analysis, regardless of project.

The default implementation locates custom lint jars in ~/.android/lint/ and in $ANDROID_LINT_JARS

Returns:

a list of rule jars (possibly empty).

findRuleJars

@NonNull
public java.util.List<java.io.File> findRuleJars(@NonNull
                                                         Project project)

Finds any custom lint rule jars that should be included for analysis in the given project

Parameters:

project - the project to look up rule jars from

Returns:

a list of rule jars (possibly empty).

openConnection

@Nullable
public java.net.URLConnection openConnection(@NonNull
                                                      java.net.URL url)
                                      throws java.io.IOException

Opens a URL connection. Clients such as IDEs can override this to for example consider the user's IDE proxy settings.

Parameters:

url - the URL to read

Returns:

a URLConnection or null

Throws:

java.io.IOException - if any kind of IO exception occurs

closeConnection

public void closeConnection(@NonNull
                            java.net.URLConnection connection)
                     throws java.io.IOException

Closes a connection previously returned by openConnection(java.net.URL)

Throws:

java.io.IOException

isProjectDirectory

public boolean isProjectDirectory(@NonNull
                                  java.io.File dir)

Returns true if the given directory is a lint project directory. By default, a project directory is the directory containing a manifest file, but in Gradle projects for example it's the root gradle directory.

Parameters:

dir - the directory to check

Returns:

true if the directory represents a lint project

checkForSuppressComments

public boolean checkForSuppressComments()

Returns whether lint should look for suppress comments. Tools that already do this on their own can return false here to avoid doing unnecessary work.

addCustomLintRules

public IssueRegistry addCustomLintRules(@NonNull
                                        IssueRegistry registry)

Adds in any custom lint rules and returns the result as a new issue registry, or the same one if no custom rules were found

Parameters:

registry - the main registry to add rules to

Returns:

a new registry containing the passed in rules plus any custom rules, or the original registry if no custom rules were found

createUrlClassLoader

public java.lang.ClassLoader createUrlClassLoader(@NonNull
                                                  java.net.URL[] urls,
                                                  @NonNull
                                                  java.lang.ClassLoader parent)

Creates a ClassLoader which can load in a set of Jar files.

Parameters:

urls - the URLs

parent - the parent class loader

Returns:

a new class loader

supportsProjectResources

public boolean supportsProjectResources()

Returns true if this client supports project resource repository lookup via getProjectResources(Project,boolean)

Returns:

true if the client can provide project resources

getProjectResources

@Nullable
public com.android.ide.common.res2.AbstractResourceRepository getProjectResources(Project project,
                                                                                           boolean includeDependencies)

Returns the project resources, if available

Parameters:

includeDependencies - if true, include merged view of all dependencies

Returns:

the project resources, or null if not available

createResourceItemHandle

@NonNull
public Location.Handle createResourceItemHandle(@NonNull
                                                        com.android.ide.common.res2.ResourceItem item)

For a lint client which supports resource items (via supportsProjectResources()) return a handle for a resource item

Parameters:

item - the resource item to look up a location handle for

Returns:

a corresponding handle

getResourceVisibilityProvider

@NonNull
public com.android.ide.common.repository.ResourceVisibilityLookup.Provider getResourceVisibilityProvider()

Returns a shared ResourceVisibilityLookup.Provider

Returns:

a shared provider for looking up resource visibility

getClientName

@NonNull
public static java.lang.String getClientName()

Returns the name of the embedding client. It could be not just CLIENT_STUDIO, CLIENT_GRADLE, CLIENT_CLI etc but other values too as lint is integrated in other embedding contexts.

Returns:

the name of the embedding client

isStudio

public static boolean isStudio()

Returns true if the embedding client currently running lint is Android Studio (or IntelliJ IDEA)

Returns:

true if running in Android Studio / IntelliJ IDEA

isGradle

public static boolean isGradle()

Returns true if the embedding client currently running lint is Gradle

Returns:

true if running in Gradle

getRepositoryLogger

@NonNull
public com.android.repository.api.ProgressIndicator getRepositoryLogger()

Returns a repository logger used by this client.