Package dalvik.system

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

    • 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

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