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

java.lang.Object
  extended by 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
protected  com.android.sdklib.repository.local.LocalSdk mSdk
           
protected  com.android.sdklib.IAndroidTarget[] mTargets
           
 
Constructor Summary
LintClient()
           
 
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.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.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.
 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)
          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
 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.repository.local.LocalSdk 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
 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.
 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.repository.local.LocalSdk mSdk
Constructor Detail

LintClient

public 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)
Returns the list of Java libraries

Parameters:
project - the project to look up jar dependencies for
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

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.repository.local.LocalSdk 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

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

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