dalvik.system

Class DexFile

java.lang.Object

dalvik.system.DexFile

public final class DexFile
extends Object

Manipulates DEX files. The class is similar in principle to ZipFile. It is used primarily by class loaders.

Note we don't directly open and read the DEX file here. They're memory-mapped read-only by the VM.

Field Summary

Fields

Modifier and Type	Field and Description
static int	DEX2OAT_NEEDED See getDexOptNeeded(String, String, String, boolean).
static int	NO_DEXOPT_NEEDED See getDexOptNeeded(String, String, String, boolean).
static int	PATCHOAT_NEEDED See getDexOptNeeded(String, String, String, boolean).
static int	SELF_PATCHOAT_NEEDED See getDexOptNeeded(String, String, String, boolean).

Constructor Summary

Constructors

Constructor and Description
DexFile(File file) Opens a DEX file from a given File object.
DexFile(String fileName) Opens a DEX file from a given filename.

Method Summary

Modifier and Type	Method and Description
void	close() Closes the DEX file.
Enumeration<String>	entries() Enumerate the names of the classes in this DEX file.
protected void	finalize() Called when the class is finalized.
static int	getDexOptNeeded(String fileName, String pkgname, String instructionSet, boolean defer) Returns the VM's opinion of what kind of dexopt is needed to make the apk/jar file up to date.
String	getName() Gets the name of the (already opened) DEX file.
static boolean	isDexOptNeeded(String fileName) Returns true if the VM believes that the apk/jar file is out of date and should be passed through "dexopt" again.
Class	loadClass(String name, ClassLoader loader) Loads a class.
Class	loadClassBinaryName(String name, ClassLoader loader, List<Throwable> suppressed) See loadClass(String, ClassLoader).
static DexFile	loadDex(String sourcePathName, String outputPathName, int flags) Open a DEX file, specifying the file in which the optimized DEX data should be written.
String	toString() Returns a string containing a concise, human-readable description of this object.

Methods inherited from class java.lang.Object

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

Field Detail

NO_DEXOPT_NEEDED

public static final int NO_DEXOPT_NEEDED

See getDexOptNeeded(String, String, String, boolean).

See Also:

Constant Field Values

DEX2OAT_NEEDED

public static final int DEX2OAT_NEEDED

See getDexOptNeeded(String, String, String, boolean).

See Also:

Constant Field Values

PATCHOAT_NEEDED

public static final int PATCHOAT_NEEDED

See getDexOptNeeded(String, String, String, boolean).

See Also:

Constant Field Values

SELF_PATCHOAT_NEEDED

public static final int SELF_PATCHOAT_NEEDED

See getDexOptNeeded(String, String, String, boolean).

See Also:

Constant Field Values

Constructor Detail

DexFile

public DexFile(File file)
        throws IOException

Opens a DEX file from a given File object. This will usually be a ZIP/JAR file with a "classes.dex" inside. The VM will generate the name of the corresponding file in /data/dalvik-cache and open it, possibly creating or updating it first if system permissions allow. Don't pass in the name of a file in /data/dalvik-cache, as the named file is expected to be in its original (pre-dexopt) state.

Parameters:

file - the File object referencing the actual DEX file

Throws:

IOException - if an I/O error occurs, such as the file not being found or access rights missing for opening it

DexFile

public DexFile(String fileName)
        throws IOException

Opens a DEX file from a given filename. This will usually be a ZIP/JAR file with a "classes.dex" inside. The VM will generate the name of the corresponding file in /data/dalvik-cache and open it, possibly creating or updating it first if system permissions allow. Don't pass in the name of a file in /data/dalvik-cache, as the named file is expected to be in its original (pre-dexopt) state.

Parameters:

fileName - the filename of the DEX file

Throws:

IOException - if an I/O error occurs, such as the file not being found or access rights missing for opening it

Method Detail

loadDex

public static DexFile loadDex(String sourcePathName,
                              String outputPathName,
                              int flags)
                       throws IOException

Open a DEX file, specifying the file in which the optimized DEX data should be written. If the optimized form exists and appears to be current, it will be used; if not, the VM will attempt to regenerate it. This is intended for use by applications that wish to download and execute DEX files outside the usual application installation mechanism. This function should not be called directly by an application; instead, use a class loader such as dalvik.system.DexClassLoader.

Parameters:

sourcePathName - Jar or APK file with "classes.dex". (May expand this to include "raw DEX" in the future.)

outputPathName - File that will hold the optimized form of the DEX data.

flags - Enable optional features. (Currently none defined.)

Returns:

A new or previously-opened DexFile.

Throws:

IOException - If unable to open the source or output file.

getName

public String getName()

Gets the name of the (already opened) DEX file.

Returns:

the file name

toString

public String toString()

Description copied from class: Object

Returns a string containing a concise, human-readable description of this object. Subclasses are encouraged to override this method and provide an implementation that takes into account the object's type and data. The default implementation is equivalent to the following expression:

   getClass().getName() + '@' + Integer.toHexString(hashCode())

See Writing a useful toString method if you intend implementing your own toString method.

Overrides:

toString in class Object

Returns:

a printable representation of this object.

close

public void close()
           throws IOException

Closes the DEX file.

This may not be able to release all of the resources. If classes from this DEX file are still resident, the DEX file can't be unmapped. In the case where we do not release all the resources, close is called again in the finalizer.

Throws:

IOException - if an I/O error occurs during closing the file, which normally should not happen

loadClass

public Class loadClass(String name,
                       ClassLoader loader)

Loads a class. Returns the class on success, or a null reference on failure.

If you are not calling this from a class loader, this is most likely not going to do what you want. Use Class.forName(String) instead.

The method does not throw ClassNotFoundException if the class isn't found because it isn't reasonable to throw exceptions wildly every time a class is not found in the first DEX file we look at.

Parameters:

name - the class name, which should look like "java/lang/String"

loader - the class loader that tries to load the class (in most cases the caller of the method

Returns:

the Class object representing the class, or null if the class cannot be loaded

loadClassBinaryName

public Class loadClassBinaryName(String name,
                                 ClassLoader loader,
                                 List<Throwable> suppressed)

See loadClass(String, ClassLoader). This takes a "binary" class name to better match ClassLoader semantics.

entries

public Enumeration<String> entries()

Enumerate the names of the classes in this DEX file.

Returns:

an enumeration of names of classes contained in the DEX file, in the usual internal form (like "java/lang/String").

finalize

protected void finalize()
                 throws Throwable

Called when the class is finalized. Makes sure the DEX file is closed.

Overrides:

finalize in class Object

Throws:

IOException - if an I/O error occurs during closing the file, which normally should not happen

Throwable

isDexOptNeeded

public static boolean isDexOptNeeded(String fileName)
                              throws FileNotFoundException,
                                     IOException

Returns true if the VM believes that the apk/jar file is out of date and should be passed through "dexopt" again.

Parameters:

fileName - the absolute path to the apk/jar file to examine.

Returns:

true if dexopt should be called on the file, false otherwise.

Throws:

FileNotFoundException - if fileName is not readable, not a file, or not present.

IOException - if fileName is not a valid apk/jar file or if problems occur while parsing it.

NullPointerException - if fileName is null.

getDexOptNeeded

public static int getDexOptNeeded(String fileName,
                                  String pkgname,
                                  String instructionSet,
                                  boolean defer)
                           throws FileNotFoundException,
                                  IOException

Returns the VM's opinion of what kind of dexopt is needed to make the apk/jar file up to date.

Parameters:

fileName - the absolute path to the apk/jar file to examine.

Returns:

NO_DEXOPT_NEEDED if the apk/jar is already up to date. DEX2OAT_NEEDED if dex2oat should be called on the apk/jar file. PATCHOAT_NEEDED if patchoat should be called on the apk/jar file to patch the odex file along side the apk/jar. SELF_PATCHOAT_NEEDED if selfpatchoat should be called on the apk/jar file to patch the oat file in the dalvik cache.

Throws:

FileNotFoundException - if fileName is not readable, not a file, or not present.

IOException - if fileName is not a valid apk/jar file or if problems occur while parsing it.

NullPointerException - if fileName is null.