com.android.sdklib.internal.repository.packages
Class Package

java.lang.Object
  com.android.sdklib.internal.repository.packages.Package

All Implemented Interfaces:

IDescription, java.lang.Comparable<Package>

Direct Known Subclasses:

FullRevisionPackage, MajorRevisionPackage

public abstract class Package
extends java.lang.Object
implements IDescription, java.lang.Comparable<Package>

A Package is the base class for "something" that can be downloaded from the SDK repository.

A package has some attributes (revision, description) and a list of archives which represent the downloadable bits.

Packages are contained by a SdkSource (a download site).

Derived classes must implement the IDescription methods.

Nested Class Summary

static class	Package.License License text, with an optional license XML reference.
static class	Package.UpdateInfo Enum for the result of canBeUpdatedBy(Package).

Constructor Summary

Package(SdkSource source, java.util.Properties props, int revision, java.lang.String license, java.lang.String description, java.lang.String descUrl, Archive.Os archiveOs, Archive.Arch archiveArch, java.lang.String archiveOsPath)
Manually create a new package with one archive and the given attributes.

Method Summary

abstract Package.UpdateInfo	canBeUpdatedBy(Package replacementPackage) Computes whether the given package is a suitable update for the current package.
int	compareTo(Package other) Returns an ordering suitable for display like this: - Tools - Platform-Tools - Built-Tools - Docs.
protected java.lang.String	comparisonKey() Computes a comparison key for each package used by compareTo(Package).
boolean	equals(java.lang.Object obj)
Archive[]	getArchives() Returns the archives defined in this package.
java.lang.String	getDescription() Returns the optional description for all packages (platform, add-on, tool, doc) or for a lib.
java.lang.String	getDescUrl() Returns the optional description URL for all packages (platform, add-on, tool, doc).
abstract java.io.File	getInstallFolder(java.lang.String osSdkRoot, SdkManager sdkManager) Computes a potential installation folder if an archive of this package were to be installed right away in the given SDK root.
Package.License	getLicense() Returns the optional description for all packages (platform, add-on, tool, doc) or for a lib.
abstract java.lang.String	getListDescription() Returns a description of this package that is suitable for a list display.
java.lang.String	getLongDescription() Returns a long description for an IDescription.
SdkSource	getParentSource() Returns the source that created (and owns) this package.
java.lang.String	getReleaseNote() Returns the optional release note for all packages (platform, add-on, tool, doc) or for a lib.
java.lang.String	getReleaseNoteUrl() Returns the optional release note URL for all packages (platform, add-on, tool, doc).
abstract FullRevision	getRevision() Returns the revision, an int > 0, for all packages (platform, add-on, tool, doc).
abstract java.lang.String	getShortDescription() Returns a short description for an IDescription.
boolean	hasArchive(Archive archive) Returns true if this package contains the exact given archive.
boolean	hasCompatibleArchive() Returns whether the Package has at least one Archive compatible with the host platform.
int	hashCode()
protected Archive[]	initializeArchives(java.util.Properties props, Archive.Os archiveOs, Archive.Arch archiveArch, java.lang.String archiveOsPath) Called by the constructor to get the initial mArchives array.
abstract java.lang.String	installId() Returns a short, reasonably unique string identifier that can be used to identify this package when installing from the command-line interface.
boolean	isLocal() A package is local (that is 'installed locally') if it contains a single archive that is local.
boolean	isObsolete() Returns true if the package is deemed obsolete, that is it contains an actual <obsolete> element.
void	postInstallHook(Archive archive, ITaskMonitor monitor, java.io.File installFolder) Hook called right after an archive has been installed.
void	postUnzipFileHook(Archive archive, ITaskMonitor monitor, IFileOp fileOp, java.io.File unzippedFile, org.apache.commons.compress.archivers.zip.ZipArchiveEntry zipEntry) Hook called right after a file has been unzipped (during an install).
boolean	preInstallHook(Archive archive, ITaskMonitor monitor, java.lang.String osSdkRoot, java.io.File installFolder) Hook called right before an archive is installed.
abstract boolean	sameItemAs(Package pkg) Returns whether the give package represents the same item as the current package.
void	saveProperties(java.util.Properties props) Save the properties of the current packages in the given Properties object.
java.lang.String	toString() Returns the short description of the source, if not null.

Methods inherited from class java.lang.Object

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

Constructor Detail

Package

public Package(SdkSource source,
               java.util.Properties props,
               int revision,
               java.lang.String license,
               java.lang.String description,
               java.lang.String descUrl,
               Archive.Os archiveOs,
               Archive.Arch archiveArch,
               java.lang.String archiveOsPath)

Manually create a new package with one archive and the given attributes. This is used to create packages from local directories in which case there must be one archive which URL is the actual target location.

Properties from props are used first when possible, e.g. if props is non null.

By design, this creates a package with one and only one archive.

Method Detail

initializeArchives

protected Archive[] initializeArchives(java.util.Properties props,
                                       Archive.Os archiveOs,
                                       Archive.Arch archiveArch,
                                       java.lang.String archiveOsPath)

Called by the constructor to get the initial mArchives array.

This is invoked by the local-package constructor and allows mock testing classes to override the archives created. This is an implementation details and clients must not rely on this.

Returns:

Always return a non-null array. The array may be empty.

saveProperties

public void saveProperties(java.util.Properties props)

Save the properties of the current packages in the given Properties object. These properties will later be give the constructor that takes a Properties object.

getParentSource

public SdkSource getParentSource()

Returns the source that created (and owns) this package. Can be null.

isObsolete

public boolean isObsolete()

Returns true if the package is deemed obsolete, that is it contains an actual <obsolete> element.

getRevision

public abstract FullRevision getRevision()

Returns the revision, an int > 0, for all packages (platform, add-on, tool, doc). Can be 0 if this is a local package of unknown revision.

getLicense

public Package.License getLicense()

Returns the optional description for all packages (platform, add-on, tool, doc) or for a lib. It is null if the element has not been specified in the repository XML.

getDescription

public java.lang.String getDescription()

Returns the optional description for all packages (platform, add-on, tool, doc) or for a lib. Can be empty but not null.

getDescUrl

public java.lang.String getDescUrl()

Returns the optional description URL for all packages (platform, add-on, tool, doc). Can be empty but not null.

getReleaseNote

public java.lang.String getReleaseNote()

Returns the optional release note for all packages (platform, add-on, tool, doc) or for a lib. Can be empty but not null.

getReleaseNoteUrl

public java.lang.String getReleaseNoteUrl()

Returns the optional release note URL for all packages (platform, add-on, tool, doc). Can be empty but not null.

getArchives

public Archive[] getArchives()

Returns the archives defined in this package. Can be an empty array but not null.

hasArchive

public boolean hasArchive(Archive archive)

Returns true if this package contains the exact given archive. Important: This compares object references, not object equality.

hasCompatibleArchive

public boolean hasCompatibleArchive()

Returns whether the Package has at least one Archive compatible with the host platform.

installId

public abstract java.lang.String installId()

Returns a short, reasonably unique string identifier that can be used to identify this package when installing from the command-line interface. 'android list sdk' will show these IDs and then in turn they can be provided to 'android update sdk --no-ui --filter' to select some specific packages.

The identifiers must have the following properties:
- They must contain only simple alphanumeric characters.
- Commas, whitespace and any special character that could be obviously problematic to a shell interface should be avoided (so dash/underscore are OK, but things like colon, pipe or dollar should be avoided.)
- The name must be consistent across calls and reasonably unique for the package type. Collisions can occur but should be rare.
- Different package types should have a clearly different name pattern.
- The revision number should not be included, as this would prevent updates from being automated (which is the whole point.)
- It must remain reasonably human readable.
- If no such id can exist (for example for a local package that cannot be installed) then an empty string should be returned. Don't return null.

Important: This is not a strong unique identifier for the package. If you need a strong unique identifier, you should use comparisonKey() and the Comparable interface.

toString

public java.lang.String toString()

Returns the short description of the source, if not null. Otherwise returns the default Object toString result.

This is mostly helpful for debugging. For UI display, use the IDescription interface.

Overrides:

toString in class java.lang.Object

getListDescription

public abstract java.lang.String getListDescription()

Returns a description of this package that is suitable for a list display. Should not be empty. Must never be null.

Note that this is the "base" name for the package with no specific revision nor API mentioned. In contrast, getShortDescription() should be used if you want more details such as the package revision number or the API, if applicable.

getShortDescription

public abstract java.lang.String getShortDescription()

Returns a short description for an IDescription. Can be empty but not null.

Specified by:

getShortDescription in interface IDescription

getLongDescription

public java.lang.String getLongDescription()

Returns a long description for an IDescription. Can be empty but not null.

Specified by:

getLongDescription in interface IDescription

isLocal

public boolean isLocal()

A package is local (that is 'installed locally') if it contains a single archive that is local. If not local, it's a remote package, only available on a remote source for download and installation.

getInstallFolder

public abstract java.io.File getInstallFolder(java.lang.String osSdkRoot,
                                              SdkManager sdkManager)

Computes a potential installation folder if an archive of this package were to be installed right away in the given SDK root.

Some types of packages install in a fix location, for example docs and tools. In this case the returned folder may already exist with a different archive installed at the desired location.
For other packages types, such as add-on or platform, the folder name is only partially relevant to determine the content and thus a real check will be done to provide an existing or new folder depending on the current content of the SDK.

Note that the installer *will* create all directories returned here just before installation so this method must not attempt to create them.

Parameters:

osSdkRoot - The OS path of the SDK root folder.

sdkManager - An existing SDK manager to list current platforms and addons.

Returns:

A new File corresponding to the directory to use to install this package.

preInstallHook

public boolean preInstallHook(Archive archive,
                              ITaskMonitor monitor,
                              java.lang.String osSdkRoot,
                              java.io.File installFolder)

Hook called right before an archive is installed. The archive has already been downloaded successfully and will be installed in the directory specified by installFolder when this call returns.

The hook lets the package decide if installation of this specific archive should be continue. The installer will still install the remaining packages if possible.

The base implementation always return true.

Note that the installer *will* create all directories specified by getInstallFolder(java.lang.String, com.android.sdklib.SdkManager) just before installation, so they must not be created here. This is also called before the previous install dir is removed so the previous content is still there during upgrade.

Parameters:

archive - The archive that will be installed

monitor - The ITaskMonitor to display errors.

osSdkRoot - The OS path of the SDK root folder.

installFolder - The folder where the archive will be installed. Note that this is not the folder where the archive was temporary unzipped. The installFolder, if it exists, contains the old archive that will soon be replaced by the new one.

Returns:

True if installing this archive shall continue, false if it should be skipped.

postUnzipFileHook

public void postUnzipFileHook(Archive archive,
                              ITaskMonitor monitor,
                              IFileOp fileOp,
                              java.io.File unzippedFile,
                              org.apache.commons.compress.archivers.zip.ZipArchiveEntry zipEntry)

Hook called right after a file has been unzipped (during an install).

The base class implementation makes sure to properly adjust set executable permission on Linux and MacOS system if the zip entry was marked as +x.

Parameters:

archive - The archive that is being installed.

monitor - The ITaskMonitor to display errors.

fileOp - The IFileOp used by the archive installer.

unzippedFile - The file that has just been unzipped in the install temp directory.

zipEntry - The ZipArchiveEntry that has just been unzipped.

postInstallHook

public void postInstallHook(Archive archive,
                            ITaskMonitor monitor,
                            java.io.File installFolder)

Hook called right after an archive has been installed.

Parameters:

archive - The archive that has been installed.

monitor - The ITaskMonitor to display errors.

installFolder - The folder where the archive was successfully installed. Null if the installation failed, in case the archive needs to do some cleanup after preInstallHook.

sameItemAs

public abstract boolean sameItemAs(Package pkg)

Returns whether the give package represents the same item as the current package.

Two packages are considered the same if they represent the same thing, except for the revision number.

Parameters:

pkg - the package to compare.

Returns:

true if the item as equivalent.

canBeUpdatedBy

public abstract Package.UpdateInfo canBeUpdatedBy(Package replacementPackage)

Computes whether the given package is a suitable update for the current package.

An update is just that: a new package that supersedes the current one. If the new package does not represent the same item or if it has the same or lower revision as the current one, it's not an update.

Parameters:

replacementPackage - The potential replacement package.

Returns:

One of the Package.UpdateInfo values.

See Also:

sameItemAs(Package)

compareTo

public int compareTo(Package other)

Returns an ordering suitable for display like this:
- Tools
- Platform-Tools
- Built-Tools
- Docs.
- Platform n preview
- Platform n
- Platform n-1
- Samples packages
- Add-on based on n preview
- Add-on based on n
- Add-on based on n-1
- Extra packages

Important: this must NOT be used to compare if two packages are the same thing. This is achieved by sameItemAs(Package) or canBeUpdatedBy(Package).

The order done here is suitable for display, and this may not be the appropriate order when comparing whether packages are equal or of greater revision -- if you need to compare revisions, then use getRevision().compareTo(rev) directly.

This compareTo(Package) method is purely an implementation detail to perform the right ordering of the packages in the list of available or installed packages.

Important: Derived classes should consider overriding comparisonKey() instead of this method.

Specified by:

compareTo in interface java.lang.Comparable<Package>

comparisonKey

protected java.lang.String comparisonKey()

Computes a comparison key for each package used by compareTo(Package). The key is a string. The base package class return a string that encodes the package type, the revision number and the platform version, if applicable, in the form:

      t:N|v:NNNN.P|r:NNNN|
 

All fields must start by a "letter colon" prefix and end with a vertical pipe (|, ASCII 124).

The string format may change between releases and clients should not store them outside of the session or expect them to be consistent between different releases. They are purely an internal implementation details of the compareTo(Package) method.

Derived classes should get the string from the super class and then append or insert their own |-separated content. For example an extra vendor name & path can be inserted before the revision number, since it has more sorting weight.

hashCode

public int hashCode()

Overrides:

hashCode in class java.lang.Object

equals

public boolean equals(java.lang.Object obj)

Overrides:

equals in class java.lang.Object