1 files changed, 149 insertions, 0 deletions
diff --git a/tools/external/asm/org/objectweb/asm/tree/package.html b/tools/external/asm/org/objectweb/asm/tree/package.html
new file mode 100644
index 000000000..d45521151
--- /dev/null
+++ b/tools/external/asm/org/objectweb/asm/tree/package.html
@@ -0,0 +1,149 @@
+<html>
+<!--
+ * ASM: a very small and fast Java bytecode manipulation framework
+ * Copyright (c) 2000-2005 INRIA, France Telecom
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ * 1. Redistributions of source code must retain the above copyright
+ *    notice, this list of conditions and the following disclaimer.
+ * 2. Redistributions in binary form must reproduce the above copyright
+ *    notice, this list of conditions and the following disclaimer in the
+ *    documentation and/or other materials provided with the distribution.
+ * 3. Neither the name of the copyright holders nor the names of its
+ *    contributors may be used to endorse or promote products derived from
+ *    this software without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
+ * THE POSSIBILITY OF SUCH DAMAGE.
+-->
+<body>
+  
+<p>  
+Provides an ASM visitor that constructs a tree representation of the
+classes it visits. This class adapter can be useful to implement "complex"
+class manipulation operations, i.e., operations that would be very hard to
+implement without using a tree representation (such as optimizing the number
+of local variables used by a method).
+</p>
+  
+<p>
+However, this class adapter has a cost: it makes ASM bigger and slower. Indeed
+it requires more than twenty new classes, and multiplies the time needed to
+transform a class by almost two (it is almost two times faster to read, "modify"
+and write a class with a ClassAdapter than with a ClassNode). This is why
+this package is bundled in an optional <tt>asm-tree.jar</tt> library that
+is separated from (but requires) the <tt>asm.jar</tt> library, which contains
+the core ASM framework. This is also why <i><font color="red">it is recommanded
+not to use this class adapter when it is possible</font></i>.
+</p>
+
+<p>
+The root class is the ClassNode, that can be created from scratch or
+from existing bytecode. For example:
+</p>
+  
+<pre>
+  ClassReader cr = new ClassReader(source);
+  ClassNode cn = new ClassNode();
+  cr.accept(cn, true);
+</pre>
+
+<p>  
+Now content of ClassNode can be modified and then
+serialized back into bytecode:
+</p>
+
+<pre>
+  ClassWriter cw = new ClassWriter(true);
+  cn.accept(cw);
+</pre>  
+
+<p>
+Several strategies can be used to construct method code from scratch. The first
+possibility is to create a MethodNode, and then create and add XXXInsnNode to 
+the instructions list:
+</p>
+
+<pre>
+MethodNode m = new MethodNode(...);
+m.instructions.add(new VarInsnNode(ALOAD, 0));
+...
+</pre>
+
+<p>
+Alternatively, you can use the fact that MethodNode is a MethodVisitor, and use
+that to create the XXXInsnNode and add them to the instructions list through
+the standard MethodVisitor interface:
+</p>
+
+<pre>
+MethodNode m = new MethodNode(...);
+m.visitVarInsn(ALOAD, 0);
+...
+</pre>
+
+<p>
+If you cannot generate all the instructions in sequential order, i.e. if you 
+need to keep some pointers in the instruction list to insert some instructions
+at these places after other instructions have been generated, you can define
+an InsnListInsnNode pseudo instruction class that will in fact contain an 
+instruction list, will possibly implement the MethodVisitor interface, and whose
+accept method will call the accept method of all the instructions of its list.
+</p>
+
+<pre>
+MethodNode m = new MethodNode(...);
+m.visitVarInsn(ALOAD, 0);
+InsnListInsnNode ptr = new InsnListInsnNode();
+m.instructions.add(ptr);
+m.visitVarInsn(ALOAD, 1);
+ptr.visitXXXInsn(...); // inserts an instruction between ALOAD 0 and ALOAD 1
+</pre>
+
+<p>
+If you need to insert instructions while iterating over an existing instruction 
+list, you can also use several strategies. The first one is to use a 
+ListIterator over the instruction list, and use its add method to insert
+instructions:
+</p>
+
+<pre>
+ListIterator i = m.instructions.listIterator();
+while (i.hasNext()) {
+    AbstractInsnNode n = (AbstractInsnNode) i.next();
+    if (...) {
+        i.add(new VarInsnNode(ALOAD, 0));
+    }
+}
+</pre>
+
+<p>
+If you want to insert these instructions through the MethodVisitor interface,
+you can define your own InsnListIterator class, that will implement both the 
+ListIterator and MethodVisitor interface.
+</p>
+
+<p>
+Another strategy is to use ListIterator.add to insert InsnListInsnNode pseudo
+instructions, and then use these inserted pseudo instructions to insert an 
+arbitrary number of instructions at these places.
+</p>
+
+<p>  
+@since ASM 1.3.3
+</p>
+    
+</body>
+</html>