org.ow2.asmdex
Class ApplicationWriter

java.lang.Object
  org.ow2.asmdex.ApplicationVisitor
      org.ow2.asmdex.ApplicationWriter

public class ApplicationWriter
extends ApplicationVisitor

A ApplicationVisitor that generates an Android dex file in bytecode form. More precisely this visitor generates a byte array conforming to the dex file format. It can be used alone, to generate Android classes "from scratch", or with one or more ApplicationReader and adapter Application visitor to generate a modified class from one or more existing Java applications.

KNOWN ISSUES

• The line number management from the beginning to the "data" for parse/sparse switch/ fillArray till the end is wrong. It can't be fixed properly. It shouldn't matter much, as it only happen if two or more switches/fillArray are encoded, and if there are line number for each. Only the last one will be encoded, at the beginning of the first structure.

DIFFERENCES WITH THE DX BYTECODE :

• TypeList are correctly sorted, but dx put the Annotations TypeList before the others.
• AnnotationItems are correctly sorted, but dx seems to put the Throws exception before the others. I don't do that, as my collected is ordered naturally.
• Annotation_directory_item are not sorted by increasing offset.
• First line number isn't perfectly accurate, because we don't have it through the ASM interface. So the first one found becomes the first one in the debug_info_item header. It is not perfectly accurate, because it doesn't represent the first actual line number of the method. However, it works fine and allows to get the same file size.

NOTES:

• The management of several Local Variable that uses the SAME register number isn't accurate, but won't be improved (is it useful ?). Each End/Restart is linked to the last Local Variable found (with the right register number), till a new one is added. Works fine for all the cases found.
• The "type_id" doesn't exist as a Class, because it only contains a string_id. Structures referring to "type_id" directly refers to a String (added to the Constant Pool as both String and Type). So there is a Type structure, but only present in the Constant Pool.
• The Debug Info.
  • We only know the instruction addresses when actually writing the Dex file (except for the Jump Instruction, but they might change if an Instruction must be resized). So we can't write the DBG_ADVANCE_PC/Special Opcodes as we gather the Instructions. It is simpler to write the Debug Instructions along with writing effectively the Code Item.
  • The Line Number are added to the Instructions directly.
  • We can get the Line_start if the first instruction has a line number. Else, we consider it is 1.

Author:

Julien Névo, based on the ASM Framework.

Field Summary

static boolean	DISPLAY_WRITER_INFORMATION Indicates if the writer information must be displayed.
static boolean	SKIP_DEBUG_INFO_ITEMS Indicates if the writer must encode the Debug information that it is given.

Fields inherited from class org.ow2.asmdex.ApplicationVisitor

api, av

Constructor Summary

ApplicationWriter()
Constructs an new ClassWriter.

ApplicationWriter(ApplicationReader applicationReader)
Constructs a new ClassWriter object and enables optimizations for "mostly add" bytecode transformations.

Method Summary

void	addFieldFromApplicationReader(java.lang.String className, java.lang.String type, java.lang.String fieldName) When the optimization about the ApplicationReader/ApplicationWriter is enabled, the ApplicationReader will want to register Fields into the Constant Pool of the Writer.
void	addMethodFromApplicationReader(java.lang.String className, java.lang.String prototype, java.lang.String methodName) When the optimization about the ApplicationReader/ApplicationWriter is enabled, the ApplicationReader will want to register Methods into the Constant Pool of the Writer.
void	addStringFromApplicationReader(java.lang.String string) When the optimization about the ApplicationReader/ApplicationWriter is enabled, the ApplicationReader will want to register Strings into the Constant Pool of the Writer.
void	addTypeNameFromApplicationReader(java.lang.String type) When the optimization about the ApplicationReader/ApplicationWriter is enabled, the ApplicationReader will want to register Types into the Constant Pool of the Writer.
ApplicationReader	getApplicationReader() Returns the ApplicationReader that may be linked to this ApplicationWriter.
ConstantPool	getConstantPool() Gets the Constant Pool.
byte[]	toByteArray() Returns the bytecode of the class that was built with this application writer.
void	visit() Visits the header of the application.
ClassVisitor	visitClass(int access, java.lang.String name, java.lang.String[] signature, java.lang.String superName, java.lang.String[] interfaces) Visits a class of the application.
void	visitEnd() Visits the end of the application.

Methods inherited from class java.lang.Object

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

Field Detail

DISPLAY_WRITER_INFORMATION

public static final boolean DISPLAY_WRITER_INFORMATION

Indicates if the writer information must be displayed.

See Also:

Constant Field Values

SKIP_DEBUG_INFO_ITEMS

public static final boolean SKIP_DEBUG_INFO_ITEMS

Indicates if the writer must encode the Debug information that it is given. If the flag is true, the debug_info_items are not encoded at all, which is different from the SKIP_DEBUG from ApplicationReader that just doesn't emit visitLocalVariable and visitLineNumber, but has no power over the creation of the debug_info_items.

See Also:

Constant Field Values

Constructor Detail

ApplicationWriter

public ApplicationWriter()

Constructs an new ClassWriter.

ApplicationWriter

public ApplicationWriter(ApplicationReader applicationReader)

Constructs a new ClassWriter object and enables optimizations for "mostly add" bytecode transformations. These optimizations are the following:

• The constant pool from the original application is copied as is in the new application, which saves time. New constant pool entries will be added if necessary, but unused constant pool entries won't be removed.
• Methods that are not transformed are copied as is in the new application, directly from the original application bytecode (i.e. without emiting visit events for all the method instructions), which saves a lot of time. Untransformed methods are detected by the fact that the ApplicationReader receives MethodVisitor objects that come from a ApplicationWriter (and not from any other ApplicationVisitor instance).

Parameters:

applicationReader - the ApplicationReader used to read the original application. It will be used to copy the entire constant pool from the original application and also to copy other fragments of original bytecode where applicable.

Method Detail

visit

public void visit()

Description copied from class: ApplicationVisitor

Visits the header of the application.

Overrides:

visit in class ApplicationVisitor

visitClass

public ClassVisitor visitClass(int access,
                               java.lang.String name,
                               java.lang.String[] signature,
                               java.lang.String superName,
                               java.lang.String[] interfaces)

Description copied from class: ApplicationVisitor

Visits a class of the application. This method must return a new ClassVisitor instance (or null) each time it is called, i.e., it should not return a previously returned visitor.

Overrides:

visitClass in class ApplicationVisitor

Parameters:

access - the access flags of the class (see Opcodes).

name - the internal name of the class.

signature - the signature of this class. May be null if the class is not a generic one, and does not extend or implement generic classes or interfaces.

superName - the internal of name of the super class. For interfaces, the super class is Object. May be null, but only for the Object class.

interfaces - the internal names of the class's interfaces. May be null.

Returns:

an object to visit the byte code of the application, or null if this application visitor is not interested in visiting the code of this class.

visitEnd

public void visitEnd()

Description copied from class: ApplicationVisitor

Visits the end of the application. This method, which is the last one to be called, is used to inform the visitor that the whole Application has been visited.

Overrides:

visitEnd in class ApplicationVisitor

toByteArray

public byte[] toByteArray()

Returns the bytecode of the class that was built with this application writer. The application Dex file must have been parsed before.

Returns:

the bytecode of the class that was build with this application writer, or Null if the application has not been parsed yet.

getConstantPool

public ConstantPool getConstantPool()

Gets the Constant Pool.

Returns:

the Constant Pool.

getApplicationReader

public ApplicationReader getApplicationReader()

Returns the ApplicationReader that may be linked to this ApplicationWriter. May be null.

addStringFromApplicationReader

public void addStringFromApplicationReader(java.lang.String string)

When the optimization about the ApplicationReader/ApplicationWriter is enabled, the ApplicationReader will want to register Strings into the Constant Pool of the Writer. This method is used for that. Note that the String added should be considered by the Writer as symbolic, as more of them can be added later.

Parameters:

string - the String to add to the Constant Pool.

addTypeNameFromApplicationReader

public void addTypeNameFromApplicationReader(java.lang.String type)

When the optimization about the ApplicationReader/ApplicationWriter is enabled, the ApplicationReader will want to register Types into the Constant Pool of the Writer. This method is used for that. Note that the Type added should be considered by the Writer as symbolic, as more of them can be added later.

Parameters:

type - the Type to add to the Constant Pool.

addFieldFromApplicationReader

public void addFieldFromApplicationReader(java.lang.String className,
                                          java.lang.String type,
                                          java.lang.String fieldName)

When the optimization about the ApplicationReader/ApplicationWriter is enabled, the ApplicationReader will want to register Fields into the Constant Pool of the Writer. This method is used for that. Note that the Field added should be considered by the Writer as symbolic, as more of them can be added later.

Parameters:

className - the Class owner name.

type - the type of the Field.

fieldName - the name of the Field.

addMethodFromApplicationReader

public void addMethodFromApplicationReader(java.lang.String className,
                                           java.lang.String prototype,
                                           java.lang.String methodName)

When the optimization about the ApplicationReader/ApplicationWriter is enabled, the ApplicationReader will want to register Methods into the Constant Pool of the Writer. This method is used for that. Note that the Method added should be considered by the Writer as symbolic, as more of them can be added later.

Parameters:

className - the Class owner name.

prototype - the prototype of the method, in TypeDescriptor format.

methodName - the name of the Method.