| |
||||
|
|
| Consortium Solutions Middleware Forge MyObjectWeb | ||||||||
|
|
| ASM
|
Frequently Asked QuestionsHere are some frequently asked questions about ASM, gathered by Mark Proctor.
0. How do I start using ASM?If you want to use ASM to generate classes from scratch, write a Java source file that is representative of the classes you want to generate, compile it(*), and then run the ASMifier on the compiled class to see the Java source code that generates this class with ASM. If you are using Eclipse it is even easier, thanks to the Bytecode Outline plugin. If you want to use ASM to transform classes, write two Java source files - first with and second without features that has to be added or removed and try to keep other differences as minimal as you can, compile them(*), and then run the ASMifier on both of them. Then compare the results with some visual diff tool. If you are using Eclipse it is even easier, thanks to the compare tool of the Bytecode Outline plugin. (*) Note that javac may produce different code for different -target, so you'll have to compile for your target environment, repeat that excercise for all required target's or use the earliest bytecode version if possible. 1. How do I remove a method/field?Use the ClassAdapter and return nothing: public FieldVisitor visitField (String name, ...) {
if (removeField(name)) {
// do nothing, in order to remove this field
return null;
} else {
// make the next visitor visit this field, in order to keep it
return super.visitField(name, ...);
}
}
2. How do I replace a method/field? I end up with duplicated members!You must either return the replacement method/field when you visit the original one using the ClassAdapter, or you must first remove the original method/field in the ClassAdapter (see "1. How do I remove a method/field?"), and then add the new method/field by calling a visit method on the ClassWriter. 3. How do I make ASM calculate visitMaxs for me?When calling the constructor for ClassWriter pass true. You must also still include the visitMaxs instruction, but the values you give are ignored, so visitMaxs(0,0) is fine. 4. Why do I get the [xxx] verifier error?If the message given by the JVM class verifier does not help you, you can use the verifier provided by ASM. For example, if you use a wrong constant when making "return" on a method, or if you do not use the appropriate LOAD or STORE instruction, depending on the local variable type, the JVM class verifier gives a "Register x contains wrong type" or "Expecting to find x on stack" error which does not say anything about the instruction that caused the error. In this case you can use the class verifier provided by ASM (asm-attrs.jar is needed with ASM 2.x only):
For example, in the helloworld example in the ASM distribution, if you replace visitLdc("Hello world!") with visitLdc(new Integer(1234)) you get the following error message when the generated class is verified as above: org.objectweb.asm.tree.analysis.AnalyzerException: Error at instruction 2: Argument 1: expected Ljava/lang/String;, but found I
at org.objectweb.asm.tree.analysis.Analyzer.analyze(Unknown Source)
at org.objectweb.asm.util.CheckClassAdapter.main(Unknown Source)
main([Ljava/lang/String;)V
00000 [Ljava/lang/String;. : GETSTATIC java/lang/System out Ljava/io/PrintStream;
00001 [Ljava/lang/String;. Ljava/io/PrintStream; : LDC 1234
00002 [Ljava/lang/String;. Ljava/io/PrintStream;I : INVOKEVIRTUAL java/io/PrintStream println (Ljava/lang/String;)V
00003 null : RETURN
This shows that the error comes from instruction 2 in method main. The instruction list shows that this instruction is INVOKEVIRTUAL. It also shows the types of the local variables and of the operand stack values just before this instruction will be executed (here local variable 0 contains a String, local variable 1 is not initialized, and the stack contains a PrintStream and an int). As explained in the error message, the println method called by INVOKEVIRTUAL expects a String as first argument, but the stack value corresponding to this argument is an int. Then either the INVOKEVIRTUAL instruction is wrong, or the instruction that pushed the integer is wrong. If your class is so "corrupted" that you cannot read it with a ClassReader, try to generate it by using a CheckClassAdapter in front of a ClassWriter: ClassWriter cw = new ClassWriter(true); ClassVisitor cv = new CheckClassAdapter(cw); // generate your class here: cv.visit(...); ... You will probably get an exception which will indicate why your generated class is incorrect. For example, if you forget to call visit(...) (which can happen if you forget to call super.visit(...) in a class adapter), the generated class contains an invalid constant pool index, and ClassReader is unable to read it. If you generate your class by using a CheckClassAdapter, as above, you get an exception "Cannot visit member before visit has been called.", which shows that you forgot to call the visit method. 5. How do I add my bytecode class to the system class loader?You must first have the security to do this, as defined in the policy file - there are no security restrictions as default for a standard java install. Use ClassLoader.defineClass, this however is a "protected" method, so you must use reflection to gain access to it: private Class loadClass (byte[] b) {
//override classDefine (as it is protected) and define the class.
Class clazz = null;
try {
ClassLoader loader = ClassLoader.getSystemClassLoader();
Class cls = Class.forName("java.lang.ClassLoader");
java.lang.reflect.Method method =
cls.getDeclaredMethod("defineClass", new Class[] { String.class, byte[].class, int.class, int.class });
// protected method invocaton
method.setAccessible(true);
try {
Object[] args = new Object[] { className, b, new Integer(0), new Integer(b.length)};
clazz = (Class) method.invoke(loader, args);
} finally {
method.setAccessible(false);
}
} catch (Exception e) {
e.printStackTrace();
System.exit(1);
}
return clazz;
}
Alternatively you can create your own ClassLoader by extending the existing class loader (example needed here). 6. How do I rename my class?It is not enough to rename just the class, you must also rename all the references to class members using the MethodAdapter. class ClassRenamer extends ClassAdapter implements Opcodes {
private Set oldNames;
private final String newName;
public ClassRenamer(ClassVisitor cv, Set oldNames, String newName) {
super(cv);
this.oldNames = oldNames;
this.newName = newName;
}
public void visit (int version, int access, String name, String signature, String superName, String[] interfaces) {
oldNames.add(name);
cv.visit(version, ACC_PUBLIC, newName, signature, superName, interfaces);
}
public MethodVisitor visitMethod (int access, String name, String desc, String signature, String[] exceptions) {
MethodVisitor mv = cv.visitMethod(access, name, fixDesc(desc), fix(signature), exceptions);
if (mv != null && (access & ACC_ABSTRACT) == 0) {
mv = new MethodRenamer(mv);
}
return mv;
}
class MethodRenamer extends MethodAdapter {
public MethodRenamer (final MethodVisitor mv) {
super(mv);
}
public void visitTypeInsn (int i, String s) {
if (oldNames.contains(s)) {
s = newName;
}
mv.visitTypeInsn(i, s);
}
public void visitFieldInsn (int opcode, String owner, String name, String desc) {
if (oldNames.contains(owner)) {
mv.visitFieldInsn(opcode, newName, name, fix(desc));
} else {
mv.visitFieldInsn(opcode, owner, name, fix(desc));
}
}
public void visitMethodInsn (int opcode, String owner, String name, String desc) {
if (oldNames.contains(owner)) {
mv.visitMethodInsn(opcode, newName, name, fix(desc));
} else {
mv.visitMethodInsn(opcode, owner, name, fix(desc));
}
}
}
private String fix (String s) {
if (s != null) {
Iterator it = oldNames.iterator();
String name;
while (it.hasNext()) {
name = (String) it.next();
if (s.indexOf(name) != -1) {
s = desc.replaceAll(name, newName);
}
}
}
return s;
}
}
7. How do method descriptors work?To understand this best it's good to read the source code of Type.java. Here is a quick overview:
Examples:
8. How can ASM help me create my descriptor types?Types.java provides the static method Type.getDescriptor, which takes a Class as a parameter. Examples:
9. How do I generate Setters and Getters for my class?Use the following code (this assumes that visitMaxs are computed by ASM - see "3. How do I make ASM calculate visitMaxs for me?"): void createSetter (String propertyName, String type, Class c) {
String methodName = "set" + propertyName.substring(0, 1).toUpperCase() + propertyName.substring(1);
MethodVisitor mv = cw.visitMethod(ACC_PUBLIC, methodName, "(" + type + ")V", null, null);
mv.visitVarInsn(ALOAD, 0);
mv.visitVarInsn(Type.getType(c).getOpcode(ILOAD), 1);
mv.visitFieldInsn(PUTFIELD, className, propertyName, type);
mv.visitInsn(RETURN);
mv.visitMaxs(0, 0);
}
void createGetter (String propertyName, String returnType, Class c) {
String methodName = "get" + propertyName.substring(0, 1).toUpperCase() + propertyName.substring(1);
MethodVisitor mv = cw.visitMethod(ACC_PUBLIC, methodName, "()" + returnType, null, null);
mv.visitVarInsn(ALOAD, 0);
mv.visitFieldInsn(GETFIELD, internalClassName, propertyName, returnType);
mv.visitInsn(Type.getType(c).getOpcode(IRETURN));
mv.visitMaxs(0, 0);
}
10. How do I get the bytecode of an existing class?If you want the bytecode instructions themselves, use TraceClassVisitor. If you want the ASM code to generate these bytecode instructions, use ASMifierClassVisitor. Both classes provide a "main" method to allow them to be called from the command line, passing your fully qualified class name as a parameter. Example:
or
Another, much easier method, if you are using Eclipse, is to use the Bytecode Outline plugin. 11. How do I generate [some Java code] with ASM?If you want to know how to generate a synchronized block, a try catch block, a finally statement, or any other Java construct, write the Java code you want to generate in a temporary class, compile it with javac, and then use the ASMifierClassVisitor to get the ASM code that will generate this class (see "10. How do I get the bytecode of an existing class?"). 12. How does the [xxx] bytecode instruction work?See chapter 6 of the Java Virtual Machine Specification. 13. Is ASM thread safe?The Type and ClassReader classes are thread safe, i.e. several threads can use a single Type object or a single ClassReader object concurrently without problems. The ClassWriter and MethodWriter classes are not thread safe, i.e. a single class cannot be generated by several concurrent threads (but, of course, several threads can generate distinct classes concurrently, if each thread uses its own ClassWriter instance). In order to generate a single class by using several concurrent threads, one should use ClassAdapter and MethodAdapter instances that delegate to normal ClassWriter and MethodWriter instances, and whose methods are all synchronized. More generally, ClassVisitor and MethodVisitor implementations, such as ClassWriter and ClassAdapter, do not have to be thread safe. However, non thread safe visitors can be made thread safe just by using a synchronizing class adapter in front of them. 14. What is the earliest JDK required to use ASM?The org.objectweb.asm package should work with JDK 1.1, or even with JDK 1.0 if Type is not used. Indeed, this package only requires the following JDK classes and methods:
The asm.util and asm.tree packages require JDK 1.2, since they use the List interface and the ArrayList class. 15. How to resolve conflicts between different ASM API versions available in a global classpath or within the same ClassLoader?Tools and frameworks that are using ASM for bytecode processing (e.g. Hibernate, CGLIB, AspectWerkz) should repackage ASM code within their own name space. This can be automated with Jar Jar Links tool. | |
| | Copyright © 1999-2005, ObjectWeb Consortium | contact | webmaster | Last modified at 2006-05-04 12:08 PM | |