com.android.sdklib.repository.local
Class LocalSdk

java.lang.Object
  com.android.sdklib.repository.local.LocalSdk

public class LocalSdk
extends java.lang.Object

This class keeps information on the current locally installed SDK. It tries to lazily load information as much as possible.

Packages are accessed by their type and a main query attribute, depending on the package type. There are different versions of getPkgInfo(com.android.sdklib.repository.descriptors.IPkgDesc) which depend on the query attribute.

Type	Query parameter	Getter
Tools	Unique instance	getPkgInfo(PkgType.PKG_TOOLS) => LocalPkgInfo
Platform-Tools	Unique instance	getPkgInfo(PkgType.PKG_PLATFORM_TOOLS) => LocalPkgInfo
Docs	Unique instance	getPkgInfo(PkgType.PKG_DOCS) => LocalPkgInfo
Build-Tools	FullRevision	getLatestBuildTool() => BuildToolInfo, or getBuildTool(FullRevision) => BuildToolInfo, or getPkgInfo(PkgType.PKG_BUILD_TOOLS, FullRevision) => LocalPkgInfo, or getPkgsInfos(PkgType.PKG_BUILD_TOOLS) => LocalPkgInfo[]
Extras	String vendor/path	getExtra(String) => LocalExtraPkgInfo, or getPkgInfo(PkgType.PKG_EXTRAS, String) => LocalPkgInfo, or getPkgsInfos(PkgType.PKG_EXTRAS) => LocalPkgInfo[]
Sources	AndroidVersion	getPkgInfo(PkgType.PKG_SOURCES, AndroidVersion) => LocalPkgInfo, or getPkgsInfos(PkgType.PKG_SOURCES) => LocalPkgInfo[]
Samples	AndroidVersion	getPkgInfo(PkgType.PKG_SAMPLES, AndroidVersion) => LocalPkgInfo, or getPkgsInfos(PkgType.PKG_SAMPLES) => LocalPkgInfo[]
Platforms	AndroidVersion	getPkgInfo(PkgType.PKG_PLATFORMS, AndroidVersion) => LocalPkgInfo, or getPkgInfo(PkgType.PKG_ADDONS, String) => LocalPkgInfo, or getPkgsInfos(PkgType.PKG_PLATFORMS) => LocalPkgInfo[], or getTargetFromHashString(String) => IAndroidTarget
Add-ons	AndroidVersion x String vendor/path	getPkgInfo(PkgType.PKG_ADDONS, String) => LocalPkgInfo, or getPkgsInfos(PkgType.PKG_ADDONS) => LocalPkgInfo[], or getTargetFromHashString(String) => IAndroidTarget
System images	AndroidVersion x String ABI	getPkgsInfos(PkgType.PKG_SYS_IMAGES) => LocalPkgInfo[]

Apps/libraries that use it are encouraged to keep an existing instance around (using a singleton or similar mechanism).

Threading: All accessor methods are synchronized on the same internal lock so it's safe to call them from any thread, even concurrently.
A method like getPkgsInfos returns a copy of its data array, which objects are not altered after creation, so its value is not influenced by the internal state after it returns.

Implementation Background:

• The sdk manager has a set of "Package" classes that cover both local and remote SDK operations.
• Goal was to split it in 2 cleanly separated parts: LocalSdk parses sdk on disk, and RemoteSdk wraps the downloaded manifest.
• The local SDK should be a singleton accessible somewhere, so there will be one in ADT (via the Sdk instance), one in Studio, and one in the command line tool.
  Right now there's a bit of mess with some classes creating a temp LocalSdkParser, some others using an SdkManager instance, and that needs to be sorted out.
• As a transition, the SdkManager instance wraps a LocalSdk and uses this. Eventually the SdkManager.java class will go away (its name is totally misleading, for starters.)
• The current LocalSdkParser stays as-is for compatibility purposes and the goal is also to totally remove it when the SdkManager class goes away.

Constructor Summary

	LocalSdk() Creates an initial LocalSdk instance with an unknown location.
	LocalSdk(java.io.File sdkRoot) Creates an initial LocalSdk instance for a known SDK location.
protected	LocalSdk(IFileOp fileOp) Creates an initial LocalSdk instance with an unknown location.

Method Summary

void	clearLocalPkg(java.util.EnumSet<PkgType> filters) Clear the tracked visited folders & the cached LocalPkgInfo for the given filter types.
BuildToolInfo	getBuildTool(FullRevision revision) Returns the BuildToolInfo for the given revision.
LocalExtraPkgInfo	getExtra(java.lang.String vendor, java.lang.String path) Retrieves information on an extra package identified by its String vendor/path.
IFileOp	getFileOp()
BuildToolInfo	getLatestBuildTool() Returns the highest build-tool revision known, or null if there are are no build-tools.
java.io.File	getLocation() Location of the SDK.
java.lang.String	getPath() Deprecated.
LocalPkgInfo	getPkgInfo(IPkgDesc descriptor) Retrieves information on a package identified by an IPkgDesc.
LocalPkgInfo	getPkgInfo(PkgType filter) For unique local packages.
LocalPkgInfo	getPkgInfo(PkgType filter, AndroidVersion version) Retrieves information on a package identified by an AndroidVersion.
LocalPkgInfo	getPkgInfo(PkgType filter, FullRevision revision) Retrieves information on a package identified by its FullRevision.
LocalPkgInfo	getPkgInfo(PkgType filter, java.lang.String path) Retrieves information on a package identified by its String path.
LocalPkgInfo	getPkgInfo(PkgType filter, java.lang.String vendor, java.lang.String path) Retrieves information on a package identified by both vendor and path strings.
LocalPkgInfo[]	getPkgsInfos(java.util.EnumSet<PkgType> filters) Retrieve all the info about the requested package types.
LocalPkgInfo[]	getPkgsInfos(PkgType filter) Retrieve all the info about the requested package type.
IAndroidTarget	getTargetFromHashString(java.lang.String hash) Returns a target from a hash that was generated by IAndroidTarget.hashString().
IAndroidTarget[]	getTargets() Returns the targets (platforms & addons) that are available in the SDK.
boolean	hasChanged(java.util.EnumSet<PkgType> filters) Check the tracked visited folders to see if anything has changed for the requested filter types.
void	setLocation(java.io.File sdkRoot) Sets or changes the SDK root location.

Methods inherited from class java.lang.Object

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

Constructor Detail

LocalSdk

public LocalSdk()

Creates an initial LocalSdk instance with an unknown location.

LocalSdk

public LocalSdk(@NonNull
                java.io.File sdkRoot)

Creates an initial LocalSdk instance for a known SDK location.

Parameters:

sdkRoot - The location of the SDK root folder.

LocalSdk

protected LocalSdk(@NonNull
                   IFileOp fileOp)

Creates an initial LocalSdk instance with an unknown location. This is designed for unit tests to override the FileOp being used.

Parameters:

fileOp - The alternate FileOp to use for all file-based interactions.

Method Detail

getFileOp

@NonNull
public IFileOp getFileOp()

setLocation

public void setLocation(@NonNull
                        java.io.File sdkRoot)

Sets or changes the SDK root location. This also clears any cached information.

Parameters:

sdkRoot - The location of the SDK root folder.

getLocation

@Nullable
public java.io.File getLocation()

Location of the SDK. Maybe null. Can be changed.

Returns:

The location of the SDK. Null if not initialized yet.

getPath

@Deprecated
@Nullable
public java.lang.String getPath()

Deprecated.

Location of the SDK. Maybe null. Can be changed. The getLocation() API replaces this function.

Returns:

The location of the SDK. Null if not initialized yet.

clearLocalPkg

public void clearLocalPkg(@NonNull
                          java.util.EnumSet<PkgType> filters)

Clear the tracked visited folders & the cached LocalPkgInfo for the given filter types.

Parameters:

filters - A set of PkgType constants or PkgType.PKG_ALL to clear everything.

hasChanged

public boolean hasChanged(@NonNull
                          java.util.EnumSet<PkgType> filters)

Check the tracked visited folders to see if anything has changed for the requested filter types. This does not refresh or reload any package information.

Parameters:

filters - A set of PkgType constants or PkgType.PKG_ALL to clear everything.

getPkgInfo

@Nullable
public LocalPkgInfo getPkgInfo(@NonNull
                                        IPkgDesc descriptor)

Retrieves information on a package identified by an IPkgDesc.

Parameters:

descriptor - IPkgDesc describing a package.

Returns:

The first package found with the same descriptor or null.

getPkgInfo

@Nullable
public LocalPkgInfo getPkgInfo(@NonNull
                                        PkgType filter,
                                        @NonNull
                                        AndroidVersion version)

Retrieves information on a package identified by an AndroidVersion. Note: don't use this for PkgType.PKG_SYS_IMAGE since there can be more than one ABI and this method only returns a single package per filter type.

Parameters:

filter - PkgType.PKG_PLATFORM, PkgType.PKG_SAMPLE or PkgType.PKG_SOURCE.

version - The AndroidVersion specific for this package type.

Returns:

An existing package information or null if not found.

getPkgInfo

@Nullable
public LocalPkgInfo getPkgInfo(@NonNull
                                        PkgType filter,
                                        @NonNull
                                        FullRevision revision)

Retrieves information on a package identified by its FullRevision.

Note that PkgType.PKG_TOOLS and PkgType.PKG_PLATFORM_TOOLS are unique in a local SDK so you'll want to use getPkgInfo(PkgType) to retrieve them instead.

Parameters:

filter - PkgType.PKG_BUILD_TOOLS.

revision - The FullRevision uniquely identifying this package.

Returns:

An existing package information or null if not found.

getPkgInfo

@Nullable
public LocalPkgInfo getPkgInfo(@NonNull
                                        PkgType filter,
                                        @NonNull
                                        java.lang.String path)

Retrieves information on a package identified by its String path.

For add-ons and platforms, the path is the target hash string (see AndroidTargetHash for helpers methods to generate this string.)

Parameters:

filter - PkgType.PKG_ADDON, PkgType.PKG_PLATFORM.

path - The vendor/path uniquely identifying this package.

Returns:

An existing package information or null if not found.

getPkgInfo

@Nullable
public LocalPkgInfo getPkgInfo(@NonNull
                                        PkgType filter,
                                        @NonNull
                                        java.lang.String vendor,
                                        @NonNull
                                        java.lang.String path)

Retrieves information on a package identified by both vendor and path strings.

For add-ons the path is target hash string (see AndroidTargetHash for helpers methods to generate this string.)

Parameters:

filter - PkgType.PKG_EXTRA, PkgType.PKG_ADDON.

vendor - The vendor id of the extra package.

path - The path uniquely identifying this package for its vendor.

Returns:

An existing package information or null if not found.

getExtra

@Nullable
public LocalExtraPkgInfo getExtra(@NonNull
                                           java.lang.String vendor,
                                           @NonNull
                                           java.lang.String path)

Retrieves information on an extra package identified by its String vendor/path.

Parameters:

vendor - The vendor id of the extra package.

path - The path uniquely identifying this package for its vendor.

Returns:

An existing extra package information or null if not found.

getPkgInfo

@Nullable
public LocalPkgInfo getPkgInfo(@NonNull
                                        PkgType filter)

For unique local packages. Returns the cached LocalPkgInfo for the requested type. Loads it from disk if not cached.

Parameters:

filter - PkgType.PKG_TOOLS or PkgType.PKG_PLATFORM_TOOLS or PkgType.PKG_DOC.

Returns:

null if the package is not installed.

getPkgsInfos

@NonNull
public LocalPkgInfo[] getPkgsInfos(@NonNull
                                           PkgType filter)

Retrieve all the info about the requested package type. This is used for the package types that have one or more instances, each with different versions. The resulting array is sorted according to the PkgInfo's sort order.

Note: you can use this with PkgType.PKG_TOOLS, PkgType.PKG_PLATFORM_TOOLS and PkgType.PKG_DOC but since there can only be one package of these types, it is more efficient to use getPkgInfo(PkgType) to query them.

Parameters:

filter - One of PkgType constants.

Returns:

A list (possibly empty) of matching installed packages. Never returns null.

getPkgsInfos

@NonNull
public LocalPkgInfo[] getPkgsInfos(@NonNull
                                           java.util.EnumSet<PkgType> filters)

Retrieve all the info about the requested package types. This is used for the package types that have one or more instances, each with different versions. The resulting array is sorted according to the PkgInfo's sort order.

To force the LocalSdk parser to load everything, simply call this method with the PkgType.PKG_ALL argument to load all the known package types.

Note: you can use this with PkgType.PKG_TOOLS, PkgType.PKG_PLATFORM_TOOLS and PkgType.PKG_DOC but since there can only be one package of these types, it is more efficient to use getPkgInfo(PkgType) to query them.

Parameters:

filters - One or more of PkgType.PKG_ADDON, PkgType.PKG_PLATFORM, PkgType.PKG_BUILD_TOOLS, PkgType.PKG_EXTRA, PkgType.PKG_SOURCE, PkgType.PKG_SYS_IMAGE

Returns:

A list (possibly empty) of matching installed packages. Never returns null.

getBuildTool

@Nullable
public BuildToolInfo getBuildTool(@Nullable
                                           FullRevision revision)

Returns the BuildToolInfo for the given revision.

Parameters:

revision - The requested revision.

Returns:

A BuildToolInfo. Can be null if revision is null or is not part of the known set returned by getPkgsInfos(PkgType.PKG_BUILD_TOOLS).

getLatestBuildTool

@Nullable
public BuildToolInfo getLatestBuildTool()

Returns the highest build-tool revision known, or null if there are are no build-tools.

If no specific build-tool package is installed but the platform-tools is lower than 17, then this creates and returns a "legacy" built-tool package using platform-tools. (We only split build-tools out of platform-tools starting with revision 17, before they were both the same thing.)

Returns:

The highest build-tool revision known, or null.

getTargets

@NonNull
public IAndroidTarget[] getTargets()

Returns the targets (platforms & addons) that are available in the SDK. The target list is created on demand the first time then cached. It will not refreshed unless clearLocalPkg(java.util.EnumSet) is called to clear platforms and/or add-ons.

The array can be empty but not null.

getTargetFromHashString

@Nullable
public IAndroidTarget getTargetFromHashString(@Nullable
                                                       java.lang.String hash)

Returns a target from a hash that was generated by IAndroidTarget.hashString().

Parameters:

hash - the IAndroidTarget hash string.

Returns:

The matching IAndroidTarget or null.