com.android.sdklib.repository.local
Class LocalSdk

java.lang.Object
  extended by 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:


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.