com.android.tools.lint.checks

Class ApiLookup

java.lang.Object

com.android.tools.lint.checks.ApiDatabase

com.android.tools.lint.checks.ApiLookup

public class ApiLookup
extends ApiDatabase

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

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.

When creating the memory data structure it performs a few other steps to help memory:

• 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.

Field Summary

Fields

Modifier and Type	Field and Description
static int	SDK_DATABASE_MIN_VERSION Database moved from platform-tools to SDK in API level 26
static java.lang.String	XML_FILE_PATH

Fields inherited from class com.android.tools.lint.checks.ApiDatabase

API_MASK, containerCount, DEBUG_SEARCH, FILE_HEADER, HAS_EXTRA_BYTE_FLAG, mData, mIndices, WRITE_STATS

Method Summary

Modifier and Type	Method and Description
boolean	containsClass(java.lang.String className) Returns true if the given owner class is known in the API database.
static boolean	equivalentFragmentAtOffset(java.lang.String classOrPackageName, int offset, java.lang.String fragment) Checks if the substring of the given class or package name at the given offset is equal to the given fragment or differs only by separators.
static boolean	equivalentName(java.lang.String name1, java.lang.String name2) Checks if the two given class or package names are equal or differ only by separators.
static ApiLookup	get(com.android.tools.lint.client.api.LintClient client) Returns an instance of the API database
static ApiLookup	get(com.android.tools.lint.client.api.LintClient client, com.android.sdklib.IAndroidTarget target) Returns an instance of the API database
int	getClassDeprecatedIn(java.lang.String className) Returns the API version the given class was deprecated in, or -1 if the class is not deprecated.
int	getClassRemovedIn(java.lang.String className) Returns the API version the given class was removed in, or -1 if the class was not removed.
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	getFieldDeprecatedIn(java.lang.String owner, java.lang.String name) Returns the API version the given field was deprecated in, or -1 if the field is not deprecated.
int	getFieldRemovedIn(java.lang.String owner, java.lang.String name) Returns the API version the given field was removed in, or -1 if the field was not removed.
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.
int	getMethodDeprecatedIn(java.lang.String owner, java.lang.String name, java.lang.String desc) Returns the API version the given call was deprecated in, or -1 if the method is not deprecated.
int	getMethodRemovedIn(java.lang.String owner, java.lang.String name, java.lang.String desc) Returns the API version the given call was removed in, or -1 if the method was not removed.
int	getMethodVersion(java.lang.String owner, java.lang.String name, java.lang.String desc) Returns the API version required by the given method call.
java.util.Collection<ApiMember>	getRemovedFields(java.lang.String owner) Returns all removed fields of the given class and all its super classes and interfaces.
java.util.Collection<ApiMember>	getRemovedMethods(java.lang.String owner) Returns all removed methods of the given class and all its super classes and interfaces.
com.android.sdklib.IAndroidTarget	getTarget() Returns the associated Android target, if known
int	getValidCastVersion(java.lang.String sourceClass, java.lang.String destinationClass) Returns the API version required to perform the given cast, or -1 if this is valid for all versions of the class (or, if these are not known classes or if the cast is not valid at all.)
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 classOrPackageName, int packageNameLength) Returns true if the given package is a valid Java package supported in any version of Android.
static boolean	startsWithEquivalentPrefix(java.lang.String classOrPackageName, java.lang.String prefix) Checks if the beginning part of the given class or package name is equal to the given prefix, or differs only by separators.

Methods inherited from class com.android.tools.lint.checks.ApiDatabase

compare, dumpEntry, findClass, findContainer, get2ByteInt, get3ByteInt, get4ByteInt, getBinaryFormatVersion, put2ByteInt, put3ByteInt, readData, writeDatabase

Methods inherited from class java.lang.Object

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

Field Detail

XML_FILE_PATH

public static final java.lang.String XML_FILE_PATH

See Also:

Constant Field Values

SDK_DATABASE_MIN_VERSION

public static final int SDK_DATABASE_MIN_VERSION

Database moved from platform-tools to SDK in API level 26

See Also:

Constant Field Values

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

get

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

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.

target - the corresponding Android target, if known

Returns:

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

getTarget

@Nullable
public com.android.sdklib.IAndroidTarget getTarget()

Returns the associated Android target, if known

Returns:

the target, if known

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())

Returns:

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

getValidCastVersion

public int getValidCastVersion(@NonNull
                               java.lang.String sourceClass,
                               @NonNull
                               java.lang.String destinationClass)

Returns the API version required to perform the given cast, or -1 if this is valid for all versions of the class (or, if these are not known classes or if the cast is not valid at all.)

Note also that this method should only be called for interfaces that are actually implemented by this class or extending the given super class (check elsewhere); it doesn't distinguish between interfaces implemented in the initial version of the class and interfaces not implemented at all.

Parameters:

sourceClass - the internal name of the class, e.g. its fully qualified name (as returned by Class.getName())

destinationClass - the class to cast the sourceClass to

Returns:

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

getClassDeprecatedIn

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

Returns the API version the given class was deprecated in, or -1 if the class is not deprecated.

Parameters:

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

Returns:

the API version the API was deprecated in, or -1 if it's unknown or version 0

getClassRemovedIn

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

Returns the API version the given class was removed in, or -1 if the class was not removed.

Parameters:

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

Returns:

the API version the API was removed in, or -1 if it's unknown or version 0

containsClass

public boolean containsClass(@NonNull
                             java.lang.String className)

Returns true if the given owner class is known in the API database.

Parameters:

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

Returns:

true if this is a class found in the API database

getMethodVersion

public int getMethodVersion(@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 field's owner class, e.g. its fully qualified name (as returned by Class.getName())

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

getMethodDeprecatedIn

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

Returns the API version the given call was deprecated in, or -1 if the method is not deprecated.

Parameters:

owner - the internal name of the field's owner class, e.g. its fully qualified name (as returned by Class.getName())

name - the method's name

desc - the method's descriptor - see Type

Returns:

the API version the API was deprecated in, or -1 if the method is not deprecated

getMethodRemovedIn

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

Returns the API version the given call was removed in, or -1 if the method was not removed.

Parameters:

owner - the internal name of the field's owner class, e.g. its fully qualified name (as returned by Class.getName())

name - the method's name

desc - the method's descriptor - see Type

Returns:

the API version the API was removed in, or -1 if the method was not removed

getRemovedFields

@Nullable
public java.util.Collection<ApiMember> getRemovedFields(@NonNull
                                                                  java.lang.String owner)

Returns all removed fields of the given class and all its super classes and interfaces.

Parameters:

owner - the internal name of the field's owner class, e.g. its fully qualified name (as returned by Class.getName())

Returns:

the removed fields, or null if the owner class was not found

getRemovedMethods

@Nullable
public java.util.Collection<ApiMember> getRemovedMethods(@NonNull
                                                                   java.lang.String owner)

Returns all removed methods of the given class and all its super classes and interfaces.

Parameters:

owner - the internal name of the field's owner class, e.g. its fully qualified name (as returned by Class.getName())

Returns:

the removed methods, or null if the owner class was not found

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 field's owner class, e.g. its fully qualified name (as returned by Class.getName())

name - the method's name

Returns:

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

getFieldDeprecatedIn

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

Returns the API version the given field was deprecated in, or -1 if the field is not deprecated.

Parameters:

owner - the internal name of the field's owner class, e.g. its fully qualified name (as returned by Class.getName())

name - the method's name

Returns:

the API version the API was deprecated in, or -1 if the field is not deprecated

getFieldRemovedIn

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

Returns the API version the given field was removed in, or -1 if the field was not removed.

Parameters:

owner - the internal name of the field's owner class, e.g. its fully qualified name (as returned by Class.getName())

name - the method's name

Returns:

the API version the API was removed in, or -1 if the field was not removed

isRelevantOwner

public 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 classOrPackageName,
                                  int packageNameLength)

Returns true if the given package is a valid Java package supported in any version of Android.

Parameters:

classOrPackageName - the name of a package or a class

packageNameLength - the length of the package part of the name

Returns:

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

equivalentName

public static boolean equivalentName(@NonNull
                                     java.lang.String name1,
                                     @NonNull
                                     java.lang.String name2)

Checks if the two given class or package names are equal or differ only by separators. Separators '.', '/', and '$' are considered equivalent.

startsWithEquivalentPrefix

public static boolean startsWithEquivalentPrefix(@NonNull
                                                 java.lang.String classOrPackageName,
                                                 @NonNull
                                                 java.lang.String prefix)

Checks if the beginning part of the given class or package name is equal to the given prefix, or differs only by separators. Separators '.', '/', and '$' are considered equivalent.

equivalentFragmentAtOffset

public static boolean equivalentFragmentAtOffset(@NonNull
                                                 java.lang.String classOrPackageName,
                                                 int offset,
                                                 @NonNull
                                                 java.lang.String fragment)

Checks if the substring of the given class or package name at the given offset is equal to the given fragment or differs only by separators. Separators '.', '/', and '$' are considered equivalent.