com.android.sdklib
Class AndroidVersion

java.lang.Object
  com.android.sdklib.AndroidVersion

All Implemented Interfaces:

java.lang.Comparable<AndroidVersion>

public final class AndroidVersion
extends java.lang.Object
implements java.lang.Comparable<AndroidVersion>

Represents the version of a target or device.

A version is defined by an API level and an optional code name.

• Release versions of the Android platform are identified by their API level (integer), (technically the code name for release version is "REL" but this class will return null instead.)
• Preview versions of the platform are identified by a code name. Their API level is usually set to the value of the previous platform.

While this class contains both values, its goal is to abstract them, so that code comparing 2+ versions doesn't have to deal with the logic of handle both values.

There are some cases where ones may want to access the values directly. This can be done with getApiLevel() and getCodename().

For generic UI display of the API version, getApiString() is to be used.

Nested Class Summary

static class

AndroidVersion.AndroidVersionException Thrown when an AndroidVersion object could not be created.

Field Summary

static AndroidVersion

DEFAULT The default AndroidVersion for minSdkVersion and targetSdkVersion if not specified

Constructor Summary

AndroidVersion(int apiLevel, java.lang.String codename)
Creates an AndroidVersion with the given api level and codename.

AndroidVersion(java.util.Properties properties)
Creates an AndroidVersion from Properties.

AndroidVersion(java.util.Properties properties, int defaultApiLevel, java.lang.String defaultCodeName)
Creates an AndroidVersion from Properties, with default values if the Properties object doesn't contain the expected values.

AndroidVersion(java.lang.String apiOrCodename)
Creates an AndroidVersion from a string that may be an integer API level or a string codename.

Method Summary

boolean	canRun(AndroidVersion appVersion) Checks whether a device running a version similar to the receiver can run a project compiled for the given version.
int	compareTo(AndroidVersion o) Compares this object with the specified object for order.
int	compareTo(int apiLevel, java.lang.String codename)
boolean	equals(int apiLevel) Returns true if the AndroidVersion is an API level equals to apiLevel.
boolean	equals(java.lang.Object obj) Compares the receiver with either an AndroidVersion object or a String object.
int	getApiLevel() Returns the api level as an integer.
java.lang.String	getApiString() Returns a string representing the API level and/or the code name.
java.lang.String	getCodename() Returns the version code name if applicable, null otherwise.
int	getFeatureLevel() Returns the API level as an integer.
int	hashCode()
boolean	isGreaterOrEqualThan(int api) Compares this version with the specified API and returns true if this version is greater or equal than the requested API -- that is the current version is a suitable min-api-level for the argument API.
boolean	isPreview() Returns whether or not the version is a preview version.
void	saveProperties(java.util.Properties props)
java.lang.String	toString() Returns a string with the API Level and optional codename.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

DEFAULT

public static final AndroidVersion DEFAULT

The default AndroidVersion for minSdkVersion and targetSdkVersion if not specified

Constructor Detail

AndroidVersion

public AndroidVersion(int apiLevel,
                      @Nullable
                      java.lang.String codename)

Creates an AndroidVersion with the given api level and codename. Codename should be null for a release version, otherwise it's a preview codename.

AndroidVersion

public AndroidVersion(@Nullable
                      java.util.Properties properties,
                      int defaultApiLevel,
                      @Nullable
                      java.lang.String defaultCodeName)

Creates an AndroidVersion from Properties, with default values if the Properties object doesn't contain the expected values.

The Properties is expected to have been filled with saveProperties(Properties).

AndroidVersion

public AndroidVersion(@NonNull
                      java.util.Properties properties)
               throws AndroidVersion.AndroidVersionException

Creates an AndroidVersion from Properties. The properties must contain android version information, or an exception will be thrown.

Throws:

AndroidVersion.AndroidVersionException - if no Android version information have been found

See Also:

saveProperties(Properties)

AndroidVersion

public AndroidVersion(@NonNull
                      java.lang.String apiOrCodename)
               throws AndroidVersion.AndroidVersionException

Creates an AndroidVersion from a string that may be an integer API level or a string codename.

Important: An important limitation of this method is that cannot possible recreate the API level integer from a pure string codename. This is only OK to use if the caller can guarantee that only getApiString() will be used later. Wrong things will happen if the caller then tries to resolve the numeric getApiLevel().

Parameters:

apiOrCodename - A non-null API integer or a codename in its "ALL_CAPS" format. "REL" is notable not a valid codename.

Throws:

AndroidVersion.AndroidVersionException - if the input isn't a pure integer or doesn't look like a valid string codename.

Method Detail

saveProperties

public void saveProperties(@NonNull
                           java.util.Properties props)

getApiLevel

public int getApiLevel()

Returns the api level as an integer.

For target that are in preview mode, this can be superseded by getCodename().

To display the API level in the UI, use getApiString(), which will use the codename if applicable.

See Also:

getCodename(), getApiString()

getFeatureLevel

public int getFeatureLevel()

Returns the API level as an integer. If this is a preview platform, it will return the expected final version of the API rather than the current API level. This is the "feature level" as opposed to the "release level" returned by getApiLevel() in the sense that it is useful when you want to check the presence of a given feature from an API, and we consider the feature present in preview platforms as well.

Returns:

the API level of this version, +1 for preview platforms

getCodename

@Nullable
public java.lang.String getCodename()

Returns the version code name if applicable, null otherwise.

If the codename is non null, then the API level should be ignored, and this should be used as a unique identifier of the target instead.

getApiString

@NonNull
public java.lang.String getApiString()

Returns a string representing the API level and/or the code name.

isPreview

public boolean isPreview()

Returns whether or not the version is a preview version.

canRun

public boolean canRun(@NonNull
                      AndroidVersion appVersion)

Checks whether a device running a version similar to the receiver can run a project compiled for the given version.

Be aware that this is not a perfect test, as other properties could break compatibility despite this method returning true. For a more comprehensive test, see IAndroidTarget.canRunOn(IAndroidTarget).

Nevertheless, when testing if an application can run on a device (where there is no access to the list of optional libraries), this method can give a good indication of whether there is a chance the application could run, or if there's a direct incompatibility.

equals

public boolean equals(int apiLevel)

Returns true if the AndroidVersion is an API level equals to apiLevel.

equals

public boolean equals(java.lang.Object obj)

Compares the receiver with either an AndroidVersion object or a String object.

If obj is a String, then the method will first check if it's a string representation of a number, in which case it'll compare it to the api level. Otherwise, it'll compare it against the code name.

For all other type of object give as parameter, this method will return false.

Overrides:

equals in class java.lang.Object

hashCode

public int hashCode()

Overrides:

hashCode in class java.lang.Object

toString

public java.lang.String toString()

Returns a string with the API Level and optional codename. Useful for debugging. For display purpose, please use getApiString() instead.

Overrides:

toString in class java.lang.Object

compareTo

public int compareTo(@NonNull
                     AndroidVersion o)

Compares this object with the specified object for order. Returns a negative integer, zero, or a positive integer as this object is less than, equal to, or greater than the specified object.

Specified by:

compareTo in interface java.lang.Comparable<AndroidVersion>

Parameters:

o - the Object to be compared.

Returns:

a negative integer, zero, or a positive integer as this object is less than, equal to, or greater than the specified object.

compareTo

public int compareTo(int apiLevel,
                     @Nullable
                     java.lang.String codename)

isGreaterOrEqualThan

public boolean isGreaterOrEqualThan(int api)

Compares this version with the specified API and returns true if this version is greater or equal than the requested API -- that is the current version is a suitable min-api-level for the argument API.