com.android.tools.lint.checks
Class ApiLookup

java.lang.Object
  com.android.tools.lint.checks.ApiLookup

public class ApiLookup
extends java.lang.Object

Database for API checking: Allows quick lookup of a given class, method or field to see which API level it was introduced in.

This class is optimized for quick bytecode lookup used in conjunction with the ASM library: It has lookup methods that take internal JVM signatures, and for a method call for example it processes the owner, name and description parameters separately the way they are provided from ASM.

The Api class provides access to the full Android API along with version information, initialized from an XML file. This lookup class adds a binary cache around the API to make initialization faster and to require fewer objects. It creates a binary cache data structure, which fits in a single byte array, which means that to open the database you can just read in the byte array and go. On one particular machine, this takes about 30-50 ms versus 600-800ms for the full parse. It also helps memory by placing everything in a compact byte array instead of needing separate strings (2 bytes per character in a char[] for the 25k method entries, 11k field entries and 6k class entries) - and it also avoids the same number of Map.Entry objects. When creating the memory data structure it performs a few other steps to help memory:

• It stores the strings as single bytes, since all the JVM signatures are in ASCII
• It strips out the method return types (which takes the binary size down from about 4.7M to 4.0M)
• It strips out all APIs that have since=1, since the lookup only needs to find classes, methods and fields that have an API level *higher* than 1. This drops the memory use down from 4.0M to 1.7M.

Method Summary

static ApiLookup	get(com.android.tools.lint.client.api.LintClient client) Returns an instance of the API database
int	getCallVersion(java.lang.String owner, java.lang.String name, java.lang.String desc) Returns the API version required by the given method call.
int	getClassVersion(java.lang.String className) Returns the API version required by the given class reference, or -1 if this is not a known API class.
int	getFieldVersion(java.lang.String owner, java.lang.String name) Returns the API version required to access the given field, or -1 if this is not a known API method.
static boolean	isRelevantClass(java.lang.String name) Quick determination whether a given class name is possibly interesting; this is a quick package prefix check to determine whether we need to consider the class at all.
static boolean	isRelevantOwner(java.lang.String owner) Returns true if the given owner (in VM format) is relevant to the database.
boolean	isValidJavaPackage(java.lang.String owner) Returns true if the given owner (in VM format) is a valid Java package supported in any version of Android.

Methods inherited from class java.lang.Object

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

Method Detail

get

@Nullable
public static ApiLookup get(@NonNull
                                     com.android.tools.lint.client.api.LintClient client)

Returns an instance of the API database

Parameters:

client - the client to associate with this database - used only for logging. The database object may be shared among repeated invocations, and in that case client used will be the one originally passed in. In other words, this parameter may be ignored if the client created is not new.

Returns:

a (possibly shared) instance of the API database, or null if its data can't be found

isRelevantClass

public static boolean isRelevantClass(java.lang.String name)

Quick determination whether a given class name is possibly interesting; this is a quick package prefix check to determine whether we need to consider the class at all. This let's us do less actual searching for the vast majority of APIs (in libraries, application code etc) that have nothing to do with the APIs in our packages.

Parameters:

name - the class name in VM format (e.g. using / instead of .)

Returns:

true if the owner is possibly relevant

getClassVersion

public int getClassVersion(@NonNull
                           java.lang.String className)

Returns the API version required by the given class reference, or -1 if this is not a known API class. Note that it may return -1 for classes introduced in version 1; internally the database only stores version data for version 2 and up.

Parameters:

className - the internal name of the class, e.g. its fully qualified name (as returned by Class.getName(), but with '.' replaced by '/'.

Returns:

the minimum API version the method is supported for, or -1 if it's unknown or version 1.

getCallVersion

public int getCallVersion(@NonNull
                          java.lang.String owner,
                          @NonNull
                          java.lang.String name,
                          @NonNull
                          java.lang.String desc)

Returns the API version required by the given method call. The method is referred to by its owner, name and desc fields. If the method is unknown it returns -1. Note that it may return -1 for classes introduced in version 1; internally the database only stores version data for version 2 and up.

Parameters:

owner - the internal name of the method's owner class, e.g. its fully qualified name (as returned by Class.getName(), but with '.' replaced by '/'.

name - the method's name

desc - the method's descriptor - see Type

Returns:

the minimum API version the method is supported for, or -1 if it's unknown or version 1.

getFieldVersion

public int getFieldVersion(@NonNull
                           java.lang.String owner,
                           @NonNull
                           java.lang.String name)

Returns the API version required to access the given field, or -1 if this is not a known API method. Note that it may return -1 for classes introduced in version 1; internally the database only stores version data for version 2 and up.

Parameters:

owner - the internal name of the method's owner class, e.g. its fully qualified name (as returned by Class.getName(), but with '.' replaced by '/'.

name - the method's name

Returns:

the minimum API version the method is supported for, or -1 if it's unknown or version 1

isRelevantOwner

public static boolean isRelevantOwner(@NonNull
                                      java.lang.String owner)

Returns true if the given owner (in VM format) is relevant to the database. This allows quick filtering out of owners that won't return any data for the various #getFieldVersion etc methods.

Parameters:

owner - the owner to look up

Returns:

true if the owner might be relevant to the API database

isValidJavaPackage

public boolean isValidJavaPackage(@NonNull
                                  java.lang.String owner)

Returns true if the given owner (in VM format) is a valid Java package supported in any version of Android.

Parameters:

owner - the package, in VM format

Returns:

true if the package is included in one or more versions of Android