to top
Android APIs
public final class

DexFile

extends Object
java.lang.Object
   ↳ dalvik.system.DexFile

Class Overview

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.

Summary

Public Constructors
DexFile(File file)
Opens a DEX file from a given File object.
DexFile(String fileName)
Opens a DEX file from a given filename.
Public Methods
void close()
Closes the DEX file.
Enumeration<String> entries()
Enumerate the names of the classes in this DEX file.
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.
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.
Protected Methods
void finalize()
Called when the class is finalized.
[Expand]
Inherited Methods
From class java.lang.Object

Public Constructors

public DexFile (File file)

Since: API Level 1

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

public DexFile (String fileName)

Since: API Level 1

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

Public Methods

public void close ()

Since: API Level 1

Closes the DEX file.

This may not be able to release any resources. If classes from this DEX file are still resident, the DEX file can't be unmapped.

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

public Enumeration<String> entries ()

Since: API Level 1

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").

public String getName ()

Since: API Level 1

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

Returns
  • the file name

public static boolean isDexOptNeeded (String fileName)

Since: API Level 1

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.
StaleDexCacheError if the optimized dex file is stale but exists on a read-only partition.

public Class loadClass (String name, ClassLoader loader)

Since: API Level 1

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

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

Since: API Level 3

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.

Protected Methods

protected void finalize ()

Since: API Level 1

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

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