com.android.sdklib.build
Class ApkBuilder

java.lang.Object
  extended by com.android.sdklib.build.ApkBuilder
All Implemented Interfaces:
IArchiveBuilder

public final class ApkBuilder
extends java.lang.Object
implements IArchiveBuilder

Class making the final apk packaging. The inputs are: - packaged resources (output of aapt) - code file (output of dx) - Java resources coming from the project, its libraries, and its jar files - Native libraries from the project or its library.


Nested Class Summary
static class ApkBuilder.FileEntry
           
static interface ApkBuilder.JarStatus
          Status for the addition of a jar file resources into the APK.
static class ApkBuilder.SigningInfo
          Signing information.
 
Constructor Summary
ApkBuilder(java.io.File apkFile, java.io.File resFile, java.io.File dexFile, java.security.PrivateKey key, java.security.cert.X509Certificate certificate, java.io.PrintStream verboseStream)
          Creates a new instance.
ApkBuilder(java.io.File apkFile, java.io.File resFile, java.io.File dexFile, java.lang.String debugStoreOsPath, java.io.PrintStream verboseStream)
          Creates a new instance.
ApkBuilder(java.lang.String apkOsPath, java.lang.String resOsPath, java.lang.String dexOsPath, java.security.PrivateKey key, java.security.cert.X509Certificate certificate, java.io.PrintStream verboseStream)
          Creates a new instance.
ApkBuilder(java.lang.String apkOsPath, java.lang.String resOsPath, java.lang.String dexOsPath, java.lang.String storeOsPath, java.io.PrintStream verboseStream)
          Creates a new instance.
 
Method Summary
 void addFile(java.io.File file, java.lang.String archivePath)
          Adds a file to the APK at a given path
 void addNativeLibraries(java.io.File nativeFolder)
          Adds the native libraries from the top native folder.
 void addNativeLibraries(java.util.List<ApkBuilder.FileEntry> entries)
           
 ApkBuilder.JarStatus addResourcesFromJar(java.io.File jarFile)
          Adds the resources from a jar file.
 void addSourceFolder(java.io.File sourceFolder)
          Adds the resources from a source folder.
static void addSourceFolder(IArchiveBuilder builder, java.io.File sourceFolder)
          Adds the resources from a source folder to a given IArchiveBuilder
 void addZipFile(java.io.File zipFile)
          Adds the content from a zip file.
static boolean checkFileForPackaging(java.lang.String fileName)
          Checks a file to make sure it should be packaged as standard resources.
static boolean checkFileForPackaging(java.lang.String fileName, java.lang.String extension)
          Checks a file to make sure it should be packaged as standard resources.
static boolean checkFolderForPackaging(java.lang.String folderName)
          Checks whether a folder and its content is valid for packaging into the .apk as standard Java resource.
static ApkBuilder.SigningInfo getDebugKey(java.lang.String storeOsPath, java.io.PrintStream verboseStream)
          Returns the key and certificate from a given debug store.
static java.lang.String getDebugKeystore()
           
static java.util.List<ApkBuilder.FileEntry> getNativeFiles(java.io.File nativeFolder, boolean debugMode)
           
 void sealApk()
          Seals the APK, and signs it if necessary.
 void setDebugMode(boolean debugMode)
          Sets the debug mode.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

ApkBuilder

public ApkBuilder(java.lang.String apkOsPath,
                  java.lang.String resOsPath,
                  java.lang.String dexOsPath,
                  java.lang.String storeOsPath,
                  java.io.PrintStream verboseStream)
           throws ApkCreationException
Creates a new instance. This creates a new builder that will create the specified output file, using the two mandatory given input files. An optional debug keystore can be provided. If set, it is expected that the store password is 'android' and the key alias and password are 'androiddebugkey' and 'android'. An optional PrintStream can also be provided for verbose output. If null, there will be no output.

Parameters:
apkOsPath - the OS path of the file to create.
resOsPath - the OS path of the packaged resource file.
dexOsPath - the OS path of the dex file. This can be null for apk with no code.
verboseStream - the stream to which verbose output should go. If null, verbose mode is not enabled.
Throws:
ApkCreationException

ApkBuilder

public ApkBuilder(java.lang.String apkOsPath,
                  java.lang.String resOsPath,
                  java.lang.String dexOsPath,
                  java.security.PrivateKey key,
                  java.security.cert.X509Certificate certificate,
                  java.io.PrintStream verboseStream)
           throws ApkCreationException
Creates a new instance. This creates a new builder that will create the specified output file, using the two mandatory given input files. Optional PrivateKey and X509Certificate can be provided to sign the APK. An optional PrintStream can also be provided for verbose output. If null, there will be no output.

Parameters:
apkOsPath - the OS path of the file to create.
resOsPath - the OS path of the packaged resource file.
dexOsPath - the OS path of the dex file. This can be null for apk with no code.
key - the private key used to sign the package. Can be null.
certificate - the certificate used to sign the package. Can be null.
verboseStream - the stream to which verbose output should go. If null, verbose mode is not enabled.
Throws:
ApkCreationException

ApkBuilder

public ApkBuilder(java.io.File apkFile,
                  java.io.File resFile,
                  java.io.File dexFile,
                  java.lang.String debugStoreOsPath,
                  java.io.PrintStream verboseStream)
           throws ApkCreationException
Creates a new instance. This creates a new builder that will create the specified output file, using the two mandatory given input files. An optional debug keystore can be provided. If set, it is expected that the store password is 'android' and the key alias and password are 'androiddebugkey' and 'android'. An optional PrintStream can also be provided for verbose output. If null, there will be no output.

Parameters:
apkFile - the file to create
resFile - the file representing the packaged resource file.
dexFile - the file representing the dex file. This can be null for apk with no code.
debugStoreOsPath - the OS path to the debug keystore, if needed or null.
verboseStream - the stream to which verbose output should go. If null, verbose mode is not enabled.
Throws:
ApkCreationException

ApkBuilder

public ApkBuilder(java.io.File apkFile,
                  java.io.File resFile,
                  java.io.File dexFile,
                  java.security.PrivateKey key,
                  java.security.cert.X509Certificate certificate,
                  java.io.PrintStream verboseStream)
           throws ApkCreationException
Creates a new instance. This creates a new builder that will create the specified output file, using the two mandatory given input files. Optional PrivateKey and X509Certificate can be provided to sign the APK. An optional PrintStream can also be provided for verbose output. If null, there will be no output.

Parameters:
apkFile - the file to create
resFile - the file representing the packaged resource file.
dexFile - the file representing the dex file. This can be null for apk with no code.
key - the private key used to sign the package. Can be null.
certificate - the certificate used to sign the package. Can be null.
verboseStream - the stream to which verbose output should go. If null, verbose mode is not enabled.
Throws:
ApkCreationException
Method Detail

getDebugKey

public static ApkBuilder.SigningInfo getDebugKey(java.lang.String storeOsPath,
                                                 java.io.PrintStream verboseStream)
                                          throws ApkCreationException
Returns the key and certificate from a given debug store. It is expected that the store password is 'android' and the key alias and password are 'androiddebugkey' and 'android' respectively.

Parameters:
storeOsPath - the OS path to the debug store.
verboseStream - an option PrintStream to display verbose information
Returns:
they key and certificate in a ApkBuilder.SigningInfo object or null.
Throws:
ApkCreationException

setDebugMode

public void setDebugMode(boolean debugMode)
Sets the debug mode. In debug mode, when native libraries are present, the packaging will also include one or more copies of gdbserver in the final APK file. These are used for debugging native code, to ensure that gdbserver is accessible to the application. There will be one version of gdbserver for each ABI supported by the application. the gbdserver files are placed in the libs/abi/ folders automatically by the NDK.

Parameters:
debugMode - the debug mode flag.

addFile

public void addFile(java.io.File file,
                    java.lang.String archivePath)
             throws ApkCreationException,
                    SealedApkException,
                    DuplicateFileException
Adds a file to the APK at a given path

Specified by:
addFile in interface IArchiveBuilder
Parameters:
file - the file to add
archivePath - the path of the file inside the APK archive.
Throws:
ApkCreationException - if an error occurred
SealedApkException - if the APK is already sealed.
DuplicateFileException - if a file conflicts with another already added to the APK at the same location inside the APK archive.

addZipFile

public void addZipFile(java.io.File zipFile)
                throws ApkCreationException,
                       SealedApkException,
                       DuplicateFileException
Adds the content from a zip file. All file keep the same path inside the archive.

Parameters:
zipFile - the zip File.
Throws:
ApkCreationException - if an error occurred
SealedApkException - if the APK is already sealed.
DuplicateFileException - if a file conflicts with another already added to the APK at the same location inside the APK archive.

addResourcesFromJar

public ApkBuilder.JarStatus addResourcesFromJar(java.io.File jarFile)
                                         throws ApkCreationException,
                                                SealedApkException,
                                                DuplicateFileException
Adds the resources from a jar file.

Parameters:
jarFile - the jar File.
Returns:
a ApkBuilder.JarStatus object indicating if native libraries where found in the jar file.
Throws:
ApkCreationException - if an error occurred
SealedApkException - if the APK is already sealed.
DuplicateFileException - if a file conflicts with another already added to the APK at the same location inside the APK archive.

addSourceFolder

public void addSourceFolder(java.io.File sourceFolder)
                     throws ApkCreationException,
                            SealedApkException,
                            DuplicateFileException
Adds the resources from a source folder.

Parameters:
sourceFolder - the source folder.
Throws:
ApkCreationException - if an error occurred
SealedApkException - if the APK is already sealed.
DuplicateFileException - if a file conflicts with another already added to the APK at the same location inside the APK archive.

addSourceFolder

public static void addSourceFolder(IArchiveBuilder builder,
                                   java.io.File sourceFolder)
                            throws ApkCreationException,
                                   DuplicateFileException
Adds the resources from a source folder to a given IArchiveBuilder

Parameters:
sourceFolder - the source folder.
Throws:
ApkCreationException - if an error occurred
DuplicateFileException - if a file conflicts with another already added to the APK at the same location inside the APK archive.

addNativeLibraries

public void addNativeLibraries(java.io.File nativeFolder)
                        throws ApkCreationException,
                               SealedApkException,
                               DuplicateFileException
Adds the native libraries from the top native folder. The content of this folder must be the various ABI folders. This may or may not copy gdbserver into the apk based on whether the debug mode is set.

Parameters:
nativeFolder - the native folder.
Throws:
ApkCreationException - if an error occurred
SealedApkException - if the APK is already sealed.
DuplicateFileException - if a file conflicts with another already added to the APK at the same location inside the APK archive.
See Also:
setDebugMode(boolean)

addNativeLibraries

public void addNativeLibraries(java.util.List<ApkBuilder.FileEntry> entries)
                        throws SealedApkException,
                               DuplicateFileException,
                               ApkCreationException
Throws:
SealedApkException
DuplicateFileException
ApkCreationException

getNativeFiles

public static java.util.List<ApkBuilder.FileEntry> getNativeFiles(java.io.File nativeFolder,
                                                                  boolean debugMode)
                                                           throws ApkCreationException
Throws:
ApkCreationException

sealApk

public void sealApk()
             throws ApkCreationException,
                    SealedApkException
Seals the APK, and signs it if necessary.

Throws:
ApkCreationException
ApkCreationException - if an error occurred
SealedApkException - if the APK is already sealed.

getDebugKeystore

public static java.lang.String getDebugKeystore()
                                         throws ApkCreationException
Throws:
ApkCreationException

checkFolderForPackaging

public static boolean checkFolderForPackaging(java.lang.String folderName)
Checks whether a folder and its content is valid for packaging into the .apk as standard Java resource.

Parameters:
folderName - the name of the folder.

checkFileForPackaging

public static boolean checkFileForPackaging(java.lang.String fileName)
Checks a file to make sure it should be packaged as standard resources.

Parameters:
fileName - the name of the file (including extension)
Returns:
true if the file should be packaged as standard java resources.

checkFileForPackaging

public static boolean checkFileForPackaging(java.lang.String fileName,
                                            java.lang.String extension)
Checks a file to make sure it should be packaged as standard resources.

Parameters:
fileName - the name of the file (including extension)
extension - the extension of the file (excluding '.')
Returns:
true if the file should be packaged as standard java resources.