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

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

All Implemented Interfaces:

IDescription, IAndroidVersionProvider, java.lang.Comparable<Package>

public class DocPackage
extends MajorRevisionPackage
implements IAndroidVersionProvider

Represents a doc XML node in an SDK repository.

Note that a doc package has a version and thus implements IAndroidVersionProvider. However there is no mandatory dependency that limits installation so this does not implement IPlatformDependency.

Nested Class Summary

Nested classes/interfaces inherited from class com.android.sdklib.internal.repository.packages.Package

Package.License, Package.UpdateInfo

Constructor Summary

DocPackage(SdkSource source, org.w3c.dom.Node packageNode, java.lang.String nsUri, java.util.Map<java.lang.String,java.lang.String> licenses)
Creates a new doc package from the attributes and elements of the given XML node.

Method Summary

Package.UpdateInfo	canBeUpdatedBy(Package replacementPackage) Computes whether the given package is a suitable update for the current package.
static Package	create(SdkSource source, java.util.Properties props, int apiLevel, java.lang.String codename, 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.
boolean	equals(java.lang.Object obj)
AndroidVersion	getAndroidVersion() Returns the version, for platform, add-on and doc packages.
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.
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.
java.lang.String	getShortDescription() Returns a short description for an IDescription.
int	hashCode()
java.lang.String	installId() Returns a string identifier to install this package from the command line.
boolean	sameItemAs(Package pkg) Consider doc packages to be the same if they cover the same API level, regardless of their revision number.
void	saveProperties(java.util.Properties props) Save the properties of the current packages in the given Properties object.

Methods inherited from class com.android.sdklib.internal.repository.packages.MajorRevisionPackage

getRevision

Methods inherited from class com.android.sdklib.internal.repository.packages.Package

compareTo, comparisonKey, getArchives, getDescription, getDescUrl, getLicense, getParentSource, getReleaseNote, getReleaseNoteUrl, hasArchive, hasCompatibleArchive, initializeArchives, isLocal, isObsolete, postInstallHook, postUnzipFileHook, preInstallHook, toString

Methods inherited from class java.lang.Object

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

Constructor Detail

DocPackage

public DocPackage(SdkSource source,
                  org.w3c.dom.Node packageNode,
                  java.lang.String nsUri,
                  java.util.Map<java.lang.String,java.lang.String> licenses)

Creates a new doc package from the attributes and elements of the given XML node. This constructor should throw an exception if the package cannot be created.

Parameters:

source - The SdkSource where this is loaded from.

packageNode - The XML element being parsed.

nsUri - The namespace URI of the originating XML document, to be able to deal with parameters that vary according to the originating XML schema.

licenses - The licenses loaded from the XML originating document.

Method Detail

create

public static Package create(SdkSource source,
                             java.util.Properties props,
                             int apiLevel,
                             java.lang.String codename,
                             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.

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

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.

Overrides:

saveProperties in class MajorRevisionPackage

getAndroidVersion

@NonNull
public AndroidVersion getAndroidVersion()

Returns the version, for platform, add-on and doc packages. Can be 0 if this is a local package of unknown api-level.

Specified by:

getAndroidVersion in interface IAndroidVersionProvider

installId

public java.lang.String installId()

Returns a string identifier to install this package from the command line. For docs, we use "doc-N" where N is the API or the preview codename.

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 Package.comparisonKey() and the Comparable interface.

Specified by:

installId in class Package

getListDescription

public java.lang.String getListDescription()

Returns a description of this package that is suitable for a list display.

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, Package.getShortDescription() should be used if you want more details such as the package revision number or the API, if applicable.

Specified by:

getListDescription in class Package

getShortDescription

public java.lang.String getShortDescription()

Returns a short description for an IDescription.

Specified by:

getShortDescription in interface IDescription

Specified by:

getShortDescription in class Package

getLongDescription

public java.lang.String getLongDescription()

Returns a long description for an IDescription. The long description is whatever the XML contains for the <description> field, or the short description if the former is empty.

Specified by:

getLongDescription in interface IDescription

Overrides:

getLongDescription in class Package

getInstallFolder

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

A "doc" package should always be located in SDK/docs.

Specified by:

getInstallFolder in class Package

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.

sameItemAs

public boolean sameItemAs(Package pkg)

Consider doc packages to be the same if they cover the same API level, regardless of their revision number.

Specified by:

sameItemAs in class Package

Parameters:

pkg - the package to compare.

Returns:

true if the item as equivalent.

canBeUpdatedBy

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

Doc packages are a bit different since there can only be one doc installed at the same time.

We now consider that docs for different APIs are NOT updates, e.g. doc for API N+1 is no longer considered an update for doc API N. However docs that have the same API version (API level + codename) are considered updates if they have a higher revision number (so 15 rev 2 is an update for 15 rev 1, but is not an update for 14 rev 1.)

Overrides:

canBeUpdatedBy in class MajorRevisionPackage

Parameters:

replacementPackage - The potential replacement package.

Returns:

One of the Package.UpdateInfo values.

See Also:

Package.sameItemAs(Package)

hashCode

public int hashCode()

Overrides:

hashCode in class Package

equals

public boolean equals(java.lang.Object obj)

Overrides:

equals in class Package