-<html>\r
-<head>\r
- <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">\r
- <title>Javassist Tutorial</title>\r
- <link rel="stylesheet" type="text/css" href="brown.css">\r
-</head>\r
-\r
-<body>\r
-\r
-<div align="right">Getting Started with Javassist</div>\r
-\r
-<div align="left"><a href="tutorial.html">Previous page</a></div>\r
-<div align="right"><a href="tutorial3.html">Next page</a></div>\r
-\r
-<p>\r
-<a href="#intro">4. Introspection and customization</a>\r
-<ul>\r
-<li><a href="#before">Inserting source text at the beginning/end of a method body</a>\r
-<br><li><a href="#alter">Altering a method body</a>\r
-<br><li><a href="#add">Adding a new method or field</a>\r
-<br><li><a href="#runtime">Runtime support classes</a>\r
-<br><li><a href="#limit">Limitations</a>\r
-</ul>\r
-\r
-<p><br>\r
-\r
-<a name="intro">\r
-<h2>4. Introspection and customization</h2>\r
-\r
-<p><code>CtClass</code> provides methods for introspection. The\r
-introspective ability of Javassist is compatible with that of\r
-the Java reflection API. <code>CtClass</code> provides\r
-<code>getName()</code>, <code>getSuperclass()</code>,\r
-<code>getMethods()</code>, and so on.\r
-<code>CtClass</code> also provides methods for modifying a class\r
-definition. It allows to add a new field, constructor, and method.\r
-Instrumenting a method body is also possible.\r
-\r
-<p>\r
-Methods are represented by <code>CtMethod</code> objects. \r
-<code>CtMethod</code> provides several methods for modifying\r
-the definition of the method. Note that if a method is inherited\r
-from a super class, then \r
-the same <code>CtMethod</code> object\r
-that represents the inherited method represents the method declared\r
-in that super class.\r
-A <code>CtMethod</code> object corresponds to every method declaration.\r
-\r
-<p>\r
-For example, if class <code>Point</code> declares method <code>move()</code>\r
-and a subclass <code>ColorPoint</code> of <code>Point</code> does\r
-not override <code>move()</code>, the two <code>move()</code> methods\r
-declared in <code>Point</code> and inherited in <code>ColorPoint</code>\r
-are represented by the identical <code>CtMethod</code> object.\r
-If the method definition represented by this \r
-<code>CtMethod</code> object is modified, the modification is\r
-reflected on both the methods.\r
-If you want to modify only the <code>move()</code> method in\r
-<code>ColorPoint</code>, you first have to add to <code>ColorPoint</code>\r
-a copy of the <code>CtMethod</code> object representing <code>move()</code>\r
-in <code>Point</code>. A copy of the the <code>CtMethod</code> object\r
-can be obtained by <code>CtNewMethod.copy()</code>.\r
-\r
-\r
-<p><hr width="40%">\r
-\r
-<ul>\r
-Javassist does not allow to remove a method or field, but it allows\r
-to change the name. So if a method is not necessary any more, it should be\r
-renamed and changed to be a private method by calling\r
-<code>setName()</code>\r
-and <code>setModifiers()</code> declared in <code>CtMethod</code>.\r
-\r
-<p>Javassist does not allow to add an extra parameter to an existing\r
-method, either. Instead of doing that, a new method receiving the\r
-extra parameter as well as the other parameters should be added to the\r
-same class. For example, if you want to add an extra <code>int</code>\r
-parameter <code>newZ</code> to a method:\r
-\r
-<ul><pre>void move(int newX, int newY) { x = newX; y = newY; }</pre></ul>\r
-\r
-<p>in a <code>Point</code> class, then you should add the following\r
-method to the <code>Point</code> class:\r
-\r
-<ul><pre>void move(int newX, int newY, int newZ) {\r
- // do what you want with newZ.\r
- move(newX, newY);\r
-}</pre></ul>\r
-\r
-</ul>\r
-\r
-<p><hr width="40%">\r
-\r
-<p>Javassist also provides low-level API for directly editing a raw\r
-class file. For example, <code>getClassFile()</code> in\r
-<code>CtClass</code> returns a <code>ClassFile</code> object\r
-representing a raw class file. <code>getMethodInfo()</code> in\r
-<code>CtMethod</code> returns a <code>MethodInfo</code> object\r
-representing a <code>method_info</code> structure included in a class\r
-file. The low-level API uses the vocabulary from the Java Virtual\r
-machine specification. The users must have the knowledge about class\r
-files and bytecode. For more details, the users should see the\r
-<code>javassist.bytecode</code> package.\r
-\r
-<p>The class files modified by Javassist requires the\r
-<code>javassist.runtime</code> package for runtime support\r
-only if some special identifiers starting with <code>$</code>\r
-are used. Those special identifiers are described below.\r
-The class files modified without those special identifiers\r
-do not need the <code>javassist.runtime</code> package or any\r
-other Javassist packages at runtime.\r
-For more details, see the API documentation\r
-of the <code>javassist.runtime</code> package.\r
-\r
-<p><br>\r
-\r
-<a name="before">\r
-<h3>4.1 Inserting source text at the beginning/end of a method body</h3>\r
-\r
-<p><code>CtMethod</code> and <code>CtConstructor</code> provide\r
-methods <code>insertBefore()</code>, <code>insertAfter()</code>, and\r
-<code>addCatch()</code>. They are used for inserting a code fragment\r
-into the body of an existing method. The users can specify those code\r
-fragments with <em>source text</em> written in Java.\r
-Javassist includes a simple Java compiler for processing source\r
-text. It receives source text\r
-written in Java and compiles it into Java bytecode, which will be\r
-<em>inlined</em> into a method body.\r
-\r
-<p>\r
-Inserting a code fragment at the position specified by a line number\r
-is also possible\r
-(if the line number table is contained in the class file).\r
-<code>insertAt()</code> in <code>CtMethod</code> and\r
-<code>CtConstructor</code> takes source text and a line number in the source\r
-file of the original class definition.\r
-It compiles the source text and inserts the compiled code at the line number.\r
-\r
-<p>The methods <code>insertBefore()</code>, <code>insertAfter()</code>,\r
-<code>addCatch()</code>, and <code>insertAt()</code>\r
-receive a <code>String</code> object representing\r
-a statement or a block. A statement is a single control structure like\r
-<code>if</code> and <code>while</code> or an expression ending with\r
-a semi colon (<code>;</code>). A block is a set of\r
-statements surrounded with braces <code>{}</code>.\r
-Hence each of the following lines is an example of valid statement or block:\r
-\r
-<ul><pre>System.out.println("Hello");\r
-{ System.out.println("Hello"); }\r
-if (i < 0) { i = -i; }\r
-</pre></ul>\r
-\r
-<p>The statement and the block can refer to fields and methods.\r
-They can also refer to the parameters\r
-to the method that they are inserted into\r
-if that method was compiled with the -g option\r
-(to include a local variable attribute in the class file).\r
-Otherwise, they must access the method parameters through the special\r
-variables <code>$0</code>, <code>$1</code>, <code>$2</code>, ... described\r
-below. \r
-<em>Accessing local variables declared in the method is not allowed</em>\r
-although declaring a new local variable in the block is allowed.\r
-However, <code>insertAt()</code> allows the statement and the block\r
-to access local variables\r
-if these variables are available at the specified line number\r
-and the target method was compiled with the -g option.\r
-\r
-\r
-<!--\r
-<p><center><table border=8 cellspacing=0 bordercolor="#cfcfcf">\r
-<tr><td bgcolor="#cfcfcf">\r
-<b>Tip:</b>\r
-<br>    Local variables are not accessible.  \r
-</td></tr>\r
-</table></center>\r
--->\r
-\r
-<p>The <code>String</code> object passed to the methods\r
-<code>insertBefore()</code>, <code>insertAfter()</code>,\r
-<code>addCatch()</code>, and <code>insertAt()</code> are compiled by\r
-the compiler included in Javassist.\r
-Since the compiler supports language extensions,\r
-several identifiers starting with <code>$</code>\r
-have special meaning:\r
-\r
-<ul><table border=0>\r
-<tr>\r
-<td><code>$0</code>, <code>$1</code>, <code>$2</code>, ...    </td>\r
-<td>Actual parameters</td>\r
-</tr>\r
-\r
-<tr>\r
-<td><code>$args</code></td>\r
-<td>An array of parameters.\r
-The type of <code>$args</code> is <code>Object[]</code>.\r
-</td>\r
-</tr>\r
-\r
-<tr>\r
-<td><code>$$</code></td>\r
-<td rowspan=2>All actual parameters.<br>\r
-For example, <code>m($$)</code> is equivalent to\r
-<code>m($1,$2,</code>...<code>)</code></td>\r
-</tr>\r
-\r
-<tr><td> </td></tr>\r
-\r
-<tr>\r
-<td><code>$cflow(</code>...<code>)</code></td>\r
-<td><code>cflow</code> variable</td>\r
-</tr>\r
-\r
-<tr>\r
-<td><code>$r</code></td>\r
-<td>The result type. It is used in a cast expression.</td>\r
-</tr>\r
-\r
-<tr>\r
-<td><code>$w</code></td>\r
-<td>The wrapper type. It is used in a cast expression.</td>\r
-</tr>\r
-\r
-<tr>\r
-<td><code>$_</code></td>\r
-<td>The resulting value</td>\r
-</tr>\r
-\r
-<tr>\r
-<td><code>$sig</code></td>\r
-<td>An array of <code>java.lang.Class</code> objects representing\r
-the formal parameter types.\r
-</td>\r
-</tr>\r
-\r
-<tr>\r
-<td><code>$type</code></td>\r
-<td>A <code>java.lang.Class</code> object representing\r
-the formal result type.</td>\r
-</tr>\r
-\r
-<tr>\r
-<td><code>$class</code></td>\r
-<td>A <code>java.lang.Class</code> object representing\r
-the class currently edited.</td>\r
-</tr>\r
-\r
-</table>\r
-</ul>\r
-\r
-<h4>$0, $1, $2, ...</h4>\r
-\r
-<p>The parameters passed to the target method\r
-are accessible with\r
-<code>$0</code>, <code>$1</code>, <code>$2</code>, ... instead of\r
-the original parameter names.\r
-<code>$1</code> represents the\r
-first parameter, <code>$2</code> represents the second parameter, and\r
-so on. The types of those variables are identical to the parameter\r
-types.\r
-<code>$0</code> is\r
-equivalent to <code>this</code>. If the method is static,\r
-<code>$0</code> is not available.\r
-\r
-<p>These variables are used as following. Suppose that a class\r
-<code>Point</code>:\r
-\r
-<pre><ul>class Point {\r
- int x, y;\r
- void move(int dx, int dy) { x += dx; y += dy; }\r
-}\r
-</ul></pre>\r
-\r
-<p>To print the values of <code>dx</code> and <code>dy</code>\r
-whenever the method <code>move()</code> is called, execute this\r
-program:\r
-\r
-<ul><pre>ClassPool pool = ClassPool.getDefault();\r
-CtClass cc = pool.get("Point");\r
-CtMethod m = cc.getDeclaredMethod("move");\r
-m.insertBefore("{ System.out.println($1); System.out.println($2); }");\r
-cc.writeFile();\r
-</pre></ul>\r
-\r
-<p>Note that the source text passed to <code>insertBefore()</code> is\r
-surrounded with braces <code>{}</code>.\r
-<code>insertBefore()</code> accepts only a single statement or a block\r
-surrounded with braces.\r
-\r
-<p>The definition of the class <code>Point</code> after the\r
-modification is like this:\r
-\r
-<pre><ul>class Point {\r
- int x, y;\r
- void move(int dx, int dy) {\r
- { System.out.println(dx); System.out.println(dy); }\r
- x += dx; y += dy;\r
- }\r
-}\r
-</ul></pre>\r
-\r
-<p><code>$1</code> and <code>$2</code> are replaced with\r
-<code>dx</code> and <code>dy</code>, respectively.\r
-\r
-<p><code>$1</code>, <code>$2</code>, <code>$3</code> ... are\r
-updatable. If a new value is assigend to one of those variables,\r
-then the value of the parameter represented by that variable is\r
-also updated.\r
-\r
-\r
-<h4>$args</h4>\r
-\r
-<p>The variable <code>$args</code> represents an array of all the\r
-parameters. The type of that variable is an array of class\r
-<code>Object</code>. If a parameter type is a primitive type such as\r
-<code>int</code>, then the parameter value is converted into a wrapper\r
-object such as <code>java.lang.Integer</code> to store in\r
-<code>$args</code>. Thus, <code>$args[0]</code> is equivalent to\r
-<code>$1</code> unless the type of the first parameter is a primitive\r
-type. Note that <code>$args[0]</code> is not equivalent to\r
-<code>$0</code>; <code>$0</code> represents <code>this</code>.\r
-\r
-<p>If an array of <code>Object</code> is assigned to\r
-<code>$args</code>, then each element of that array is\r
-assigned to each parameter. If a parameter type is a primitive\r
-type, the type of the corresponding element must be a wrapper type.\r
-The value is converted from the wrapper type to the primitive type\r
-before it is assigned to the parameter.\r
-\r
-<h4>$$</h4>\r
-\r
-<p>The variable <code>$$</code> is abbreviation of a list of\r
-all the parameters separated by commas.\r
-For example, if the number of the parameters\r
-to method <code>move()</code> is three, then\r
-\r
-<ul><pre>move($$)</pre></ul>\r
-\r
-<p>is equivalent to this:\r
-\r
-<ul><pre>move($1, $2, $3)</pre></ul>\r
-\r
-<p>If <code>move()</code> does not take any parameters,\r
-then <code>move($$)</code> is\r
-equivalent to <code>move()</code>.\r
-\r
-<p><code>$$</code> can be used with another method.\r
-If you write an expression:\r
-\r
-<ul><pre>exMove($$, context)</pre></ul>\r
-\r
-<p>then this expression is equivalent to:\r
-\r
-<ul><pre>exMove($1, $2, $3, context)</pre></ul>\r
-\r
-<p>Note that <code>$$</code> enables generic notation of method call\r
-with respect to the number of parameters.\r
-It is typically used with <code>$proceed</code> shown later.\r
-\r
-<h4>$cflow</h4>\r
-\r
-<p><code>$cflow</code> means "control flow".\r
-This read-only variable returns the depth of the recursive calls\r
-to a specific method.\r
-\r
-<p>Suppose that the method shown below is represented by a\r
-<code>CtMethod</code> object <code>cm</code>:\r
-\r
-<ul><pre>int fact(int n) {\r
- if (n <= 1)\r
- return n;\r
- else\r
- return n * fact(n - 1);\r
-}</pre></ul>\r
-\r
-<p>To use <code>$cflow</code>, first declare that <code>$cflow</code>\r
-is used for monitoring calls to the method <code>fact()</code>:\r
-\r
-<ul><pre>CtMethod cm = ...;\r
-cm.useCflow("fact");</pre></ul>\r
-\r
-<p>The parameter to <code>useCflow()</code> is the identifier of the\r
-declared <code>$cflow</code> variable. Any valid Java name can be\r
-used as the identifier. Since the identifier can also include\r
-<code>.</code> (dot), for example, <code>"my.Test.fact"</code>\r
-is a valid identifier.\r
-\r
-<p>Then, <code>$cflow(fact)</code> represents the depth of the\r
-recursive calls to the method specified by <code>cm</code>. The value\r
-of <code>$cflow(fact)</code> is 0 (zero) when the method is\r
-first called whereas it is 1 when the method is recursively called\r
-within the method. For example,\r
-\r
-<ul><pre>\r
-cm.insertBefore("if ($cflow(fact) == 0)"\r
- + " System.out.println(\"fact \" + $1);");\r
-</pre></ul>\r
-\r
-<p>translates the method <code>fact()</code> so that it shows the\r
-parameter. Since the value of <code>$cflow(fact)</code> is checked,\r
-the method <code>fact()</code> does not show the parameter if it is\r
-recursively called within <code>fact()</code>.\r
-\r
-<p>The value of <code>$cflow</code> is the number of stack frames\r
-associated with the specified method <code>cm</code>\r
-under the current topmost\r
-stack frame for the current thread. <code>$cflow</code> is also\r
-accessible within a method different from the specified method\r
-<code>cm</code>.\r
-\r
-<h4>$r</h4>\r
-\r
-<p><code>$r</code> represents the result type (return type) of the method.\r
-It must be used as the cast type in a cast expression.\r
-For example, this is a typical use:\r
-\r
-<ul><pre>Object result = ... ;\r
-$_ = ($r)result;</pre></ul>\r
-\r
-<p>If the result type is a primitive type, then <code>($r)</code>\r
-follows special semantics. First, if the operand type of the cast\r
-expression is a primitive type, <code>($r)</code> works as a normal\r
-cast operator to the result type.\r
-On the other hand, if the operand type is a wrapper type,\r
-<code>($r)</code> converts from the wrapper type to the result type.\r
-For example, if the result type is <code>int</code>, then\r
-<code>($r)</code> converts from <code>java.lang.Integer</code> to\r
-<code>int</code>.\r
-\r
-<p>If the result type is <code>void</code>, then\r
-<code>($r)</code> does not convert a type; it does nothing.\r
-However, if the operand is a call to a <code>void</code> method,\r
-then <code>($r)</code> results in <code>null</code>. For example,\r
-if the result type is <code>void</code> and\r
-<code>foo()</code> is a <code>void</code> method, then\r
-\r
-<ul><pre>$_ = ($r)foo();</pre></ul>\r
-\r
-<p>is a valid statement.\r
-\r
-<p>The cast operator <code>($r)</code> is also useful in a\r
-<code>return</code> statement. Even if the result type is\r
-<code>void</code>, the following <code>return</code> statement is valid:\r
-\r
-<ul><pre>return ($r)result;</pre></ul>\r
-\r
-<p>Here, <code>result</code> is some local variable.\r
-Since <code>($r)</code> is specified, the resulting value is\r
-discarded.\r
-This <code>return</code> statement is regarded as the equivalent\r
-of the <code>return</code> statement without a resulting value:\r
-\r
-<ul><pre>return;</pre></ul>\r
-\r
-<h4>$w</h4>\r
-\r
-<p><code>$w</code> represents a wrapper type.\r
-It must be used as the cast type in a cast expression.\r
-<code>($w)</code> converts from a primitive type to the corresponding\r
-wrapper type.\r
-\r
-The following code is an example:\r
-\r
-<ul><pre>Integer i = ($w)5;</pre></ul>\r
-\r
-<p>The selected wrapper type depends on the type of the expression\r
-following <code>($w)</code>. If the type of the expression is\r
-<code>double</code>, then the wrapper type is <code>java.lang.Double</code>.\r
-\r
-<p>If the type of the expression following <code>($w)</code> is not\r
-a primitive type, then <code>($w)</code> does nothing.\r
-\r
-<h4>$_</h4>\r
-\r
-<p><code>insertAfter()</code> in <code>CtMethod</code> and\r
-<code>CtConstructor</code> inserts the\r
-compiled code at the end of the method. In the statement given to\r
-<code>insertAfter()</code>, not only the variables shown above such as\r
-<code>$0</code>, <code>$1</code>, ... but also <code>$_</code> is\r
-available.\r
-\r
-<p>The variable <code>$_</code> represents the resulting value of the\r
-method. The type of that variable is the type of the result type (the\r
-return type) of the method. If the result type is <code>void</code>,\r
-then the type of <code>$_</code> is <code>Object</code> and the value\r
-of <code>$_</code> is <code>null</code>.\r
-\r
-<p>Although the compiled code inserted by <code>insertAfter()</code>\r
-is executed just before the control normally returns from the method,\r
-it can be also executed when an exception is thrown from the method.\r
-To execute it when an exception is thrown, the second parameter\r
-<code>asFinally</code> to <code>insertAfter()</code> must be\r
-<code>true</code>.\r
-\r
-<p>If an exception is thrown, the compiled code inserted by\r
-<code>insertAfter()</code> is executed as a <code>finally</code>\r
-clause. The value of <code>$_</code> is <code>0</code> or\r
-<code>null</code> in the compiled code. After the execution of the\r
-compiled code terminates, the exception originally thrown is re-thrown\r
-to the caller. Note that the value of <code>$_</code> is never thrown\r
-to the caller; it is rather discarded.\r
-\r
-<h4>$sig</h4>\r
-\r
-<p>The value of <code>$sig</code> is an array of\r
-<code>java.lang.Class</code> objects that represent the formal\r
-parameter types in declaration order.\r
-\r
-<h4>$type</h4>\r
-\r
-<p>The value of <code>$type</code> is an <code>java.lang.Class</code>\r
-object representing the formal type of the result value. This\r
-variable is available only in <code>insertAfter()</code> in\r
-<code>CtMethod</code> and <code>CtConstructor</code>.\r
-\r
-<h4>$class</h4>\r
-\r
-<p>The value of <code>$class</code> is an <code>java.lang.Class</code>\r
-object representing the class in which the edited method is declared.\r
-This represents the type of <code>$0</code>.\r
-\r
-<h4>addCatch()</h4>\r
-\r
-<p><code>addCatch()</code> inserts a code fragment into a method body\r
-so that the code fragment is executed when the method body throws\r
-an exception and the control returns to the caller. In the source\r
-text representing the inserted code fragment, the exception value\r
-is referred to with the special variable <code>$e</code>.\r
-\r
-<p>For example, this program:\r
-\r
-<ul><pre>\r
-CtMethod m = ...;\r
-CtClass etype = ClassPool.getDefault().get("java.io.IOException");\r
-m.addCatch("{ System.out.println($e); throw $e; }", etype);\r
-</pre></ul>\r
-\r
-<p>translates the method body represented by <code>m</code> into\r
-something like this:\r
-\r
-<ul><pre>\r
-try {\r
- <font face="serif"><em>the original method body</em></font>\r
-}\r
-catch (java.io.IOException e) {\r
- System.out.println(e);\r
- throw e;\r
-}\r
-</pre></ul>\r
-\r
-<p>Note that the inserted code fragment must end with a\r
-<code>throw</code> or <code>return</code> statement.\r
-\r
-<p><br>\r
-\r
-<a name="alter">\r
-<h3>4.2 Altering a method body</h3>\r
-\r
-<p><code>CtMethod</code> and <code>CtConstructor</code> provide\r
-<code>setBody()</code> for substituting a whole\r
-method body. They compile the given source text into Java bytecode\r
-and substitutes it for the original method body. If the given source\r
-text is <code>null</code>, the substituted body includes only a\r
-<code>return</code> statement, which returns zero or null unless the\r
-result type is <code>void</code>.\r
-\r
-<p>In the source text given to <code>setBody()</code>, the identifiers\r
-starting with <code>$</code> have special meaning\r
-\r
-<ul><table border=0>\r
-<tr>\r
-<td><code>$0</code>, <code>$1</code>, <code>$2</code>, ...    </td>\r
-<td>Actual parameters</td>\r
-</tr>\r
-\r
-<tr>\r
-<td><code>$args</code></td>\r
-<td>An array of parameters.\r
-The type of <code>$args</code> is <code>Object[]</code>.\r
-</td>\r
-</tr>\r
-\r
-<tr>\r
-<td><code>$$</code></td>\r
-<td>All actual parameters.<br>\r
-</tr>\r
-\r
-<tr>\r
-<td><code>$cflow(</code>...<code>)</code></td>\r
-<td><code>cflow</code> variable</td>\r
-</tr>\r
-\r
-<tr>\r
-<td><code>$r</code></td>\r
-<td>The result type. It is used in a cast expression.</td>\r
-</tr>\r
-\r
-<tr>\r
-<td><code>$w</code></td>\r
-<td>The wrapper type. It is used in a cast expression.</td>\r
-</tr>\r
-\r
-<tr>\r
-<td><code>$sig</code></td>\r
-<td>An array of <code>java.lang.Class</code> objects representing\r
-the formal parameter types.\r
-</td>\r
-</tr>\r
-\r
-<tr>\r
-<td><code>$type</code></td>\r
-<td>A <code>java.lang.Class</code> object representing\r
-the formal result type.</td>\r
-</tr>\r
-\r
-<tr>\r
-<td><code>$class</code></td>\r
-<td rowspan=2>A <code>java.lang.Class</code> object representing\r
-the class that declares the method<br>\r
-currently edited (the type of $0).</td>\r
-</tr>\r
-\r
-<tr><td> </td></tr>\r
-\r
-</table>\r
-</ul>\r
-\r
-Note that <code>$_</code> is not available.\r
-\r
-<h4>Substituting source text for an existing expression</h4>\r
-\r
-<p>Javassist allows modifying only an expression included in a method body.\r
-<code>javassist.expr.ExprEditor</code> is a class\r
-for replacing an expression in a method body.\r
-The users can define a subclass of <code>ExprEditor</code>\r
-to specify how an expression is modified.\r
-\r
-<p>To run an <code>ExprEditor</code> object, the users must\r
-call <code>instrument()</code> in <code>CtMethod</code> or\r
-<code>CtClass</code>.\r
-\r
-For example,\r
-\r
-<ul><pre>\r
-CtMethod cm = ... ;\r
-cm.instrument(\r
- new ExprEditor() {\r
- public void edit(MethodCall m)\r
- throws CannotCompileException\r
- {\r
- if (m.getClassName().equals("Point")\r
- && m.getMethodName().equals("move"))\r
- m.replace("{ $1 = 0; $_ = $proceed($$); }");\r
- }\r
- });\r
-</pre></ul>\r
-\r
-<p>searches the method body represented by <code>cm</code> and\r
-replaces all calls to <code>move()</code> in class <code>Point</code>\r
-with a block:\r
-\r
-<ul><pre>{ $1 = 0; $_ = $proceed($$); }\r
-</pre></ul>\r
-\r
-<p>so that the first parameter to <code>move()</code> is always 0.\r
-Note that the substituted code is not an expression but\r
-a statement or a block.\r
-\r
-<p>The method <code>instrument()</code> searches a method body.\r
-If it finds an expression such as a method call, field access, and object\r
-creation, then it calls <code>edit()</code> on the given\r
-<code>ExprEditor</code> object. The parameter to <code>edit()</code>\r
-is an object representing the found expression. The <code>edit()</code>\r
-method can inspect and replace the expression through that object.\r
-\r
-<p>Calling <code>replace()</code> on the parameter to <code>edit()</code>\r
-substitutes the given statement or block for the expression. If the given\r
-block is an empty block, that is, if <code>replace("{}")</code>\r
-is executed, then the expression is removed from the method body.\r
-\r
-If you want to insert a statement (or a block) before/after the\r
-expression, a block like the following should be passed to\r
-<code>replace()</code>:\r
-\r
-<ul><pre>\r
-{ <em>before-statements;</em>\r
- $_ = $proceed($$);\r
- <em>after-statements;</em> }\r
-</pre></ul>\r
-\r
-<p>whichever the expression is either a method call, field access,\r
-object creation, or others. The second statement could be:\r
-\r
-<ul><pre>$_ = $proceed();</pre></ul>\r
-\r
-<p>if the expression is read access, or\r
-\r
-<ul><pre>$proceed($$);</pre></ul>\r
-\r
-<p>if the expression is write access.\r
-\r
-<p>Local variables available in the target expression is\r
-also available in the source text passed to <code>replace()</code>\r
-if the method searched by <code>instrument()</code> was compiled\r
-with the -g option (the class file includes a local variable\r
-attribute).\r
-\r
-<h4>javassist.expr.MethodCall</h4>\r
-\r
-<p>A <code>MethodCall</code> object represents a method call.\r
-The method <code>replace()</code> in\r
-<code>MethodCall</code> substitutes a statement or\r
-a block for the method call.\r
-It receives source text representing the substitued statement or\r
-block, in which the identifiers starting with <code>$</code>\r
-have special meaning as in the source text passed to\r
-<code>insertBefore()</code>.\r
-\r
-<ul><table border=0>\r
-<tr>\r
-<td><code>$0</code></td>\r
-<td rowspan=3>\r
-The target object of the method call.<br>\r
-This is not equivalent to <code>this</code>, which represents\r
-the caller-side <code>this</code> object.<br>\r
-<code>$0</code> is <code>null</code> if the method is static.\r
-</td>\r
-</tr>\r
-\r
-<tr><td> </td></tr>\r
-\r
-<tr><td> </td></tr>\r
-\r
-<tr>\r
-<td><code>$1</code>, <code>$2</code>, ...    </td>\r
-<td>\r
-The parameters of the method call.\r
-</td>\r
-</tr>\r
-\r
-<tr><td>\r
-<code>$_</code></td>\r
-<td>The resulting value of the method call.</td>\r
-</tr>\r
-\r
-<tr><td><code>$r</code></td>\r
-<td>The result type of the method call.</td>\r
-</tr>\r
-\r
-<tr><td><code>$class</code>    </td>\r
-<td>A <code>java.lang.Class</code> object representing\r
-the class declaring the method.\r
-</td>\r
-</tr>\r
-\r
-<tr><td><code>$sig</code>    </td>\r
-<td>An array of <code>java.lang.Class</code> objects representing\r
-the formal parameter types.</td>\r
-</tr>\r
-\r
-<tr><td><code>$type</code>    </td>\r
-<td>A <code>java.lang.Class</code> object representing\r
-the formal result type.</td>\r
-</tr>\r
-\r
-<tr><td><code>$proceed</code>    </td>\r
-<td>The name of the method originally called\r
-in the expression.</td>\r
-</tr>\r
-\r
-</table>\r
-</ul>\r
-\r
-<p>Here the method call means the one represented by the\r
-<code>MethodCall</code> object.\r
-\r
-<p>The other identifiers such as <code>$w</code>,\r
-<code>$args</code> and <code>$$</code>\r
-are also available.\r
-\r
-<p>Unless the result type of the method call is <code>void</code>,\r
-a value must be assigned to\r
-<code>$_</code> in the source text and the type of <code>$_</code>\r
-is the result type.\r
-If the result type is <code>void</code>, the type of <code>$_</code>\r
-is <code>Object</code> and the value assigned to <code>$_</code>\r
-is ignored.\r
-\r
-<p><code>$proceed</code> is not a <code>String</code> value but special\r
-syntax. It must be followed by an argument list surrounded by parentheses\r
-<code>( )</code>.\r
-\r
-<h4>javassist.expr.FieldAccess</h4>\r
-\r
-<p>A <code>FieldAccess</code> object represents field access.\r
-The method <code>edit()</code> in <code>ExprEditor</code>\r
-receives this object if field access is found.\r
-The method <code>replace()</code> in\r
-<code>FieldAccess</code> receives\r
-source text representing the substitued statement or\r
-block for the field access.\r
-\r
-<p>\r
-In the source text, the identifiers starting with <code>$</code>\r
-have special meaning:\r
-\r
-<ul><table border=0>\r
-<tr>\r
-<td><code>$0</code></td>\r
-<td rowspan=3>\r
-The object containing the field accessed by the expression.\r
-This is not equivalent to <code>this</code>.<br>\r
-<code>this</code> represents the object that the method including the\r
-expression is invoked on.<br>\r
-<code>$0</code> is <code>null</code> if the field is static.\r
-</td>\r
-</tr>\r
-\r
-<tr><td> </td></tr>\r
-\r
-<tr><td> </td></tr>\r
-\r
-<tr>\r
-<td><code>$1</code></td>\r
-<td rowspan=2>\r
-The value that would be stored in the field\r
-if the expression is write access.\r
-<br>Otherwise, <code>$1</code> is not available.\r
-</td>\r
-</tr>\r
-\r
-<tr><td> </td></tr>\r
-\r
-<tr>\r
-<td><code>$_</code></td>\r
-<td rowspan=2>\r
-The resulting value of the field access\r
-if the expression is read access.\r
-<br>Otherwise, the value stored in <code>$_</code> is discarded.\r
-</td>\r
-</tr>\r
-\r
-<tr><td> </td></tr>\r
-<tr>\r
-<td><code>$r</code></td>\r
-<td rowspan=2>\r
-The type of the field if the expression is read access.\r
-<br>Otherwise, <code>$r</code> is <code>void</code>.\r
-</td>\r
-</tr>\r
-\r
-<tr><td> </td></tr>\r
-\r
-<tr><td><code>$class</code>    </td>\r
-<td>A <code>java.lang.Class</code> object representing\r
-the class declaring the field.\r
-</td></tr>\r
-\r
-<tr><td><code>$type</code></td>\r
-<td>A <code>java.lang.Class</code> object representing\r
-the field type.</td>\r
-</tr>\r
-\r
-<tr><td><code>$proceed</code>    </td>\r
-<td>The name of a virtual method executing the original\r
-field access.\r
-.</td>\r
-</tr>\r
-\r
-</table>\r
-</ul>\r
-\r
-<p>The other identifiers such as <code>$w</code>,\r
-<code>$args</code> and <code>$$</code>\r
-are also available.\r
-\r
-<p>If the expression is read access, a value must be assigned to\r
-<code>$_</code> in the source text. The type of <code>$_</code>\r
-is the type of the field.\r
-\r
-<h4>javassist.expr.NewExpr</h4>\r
-\r
-<p>A <code>NewExpr</code> object represents object creation\r
-with the <code>new</code> operator (not including array creation).\r
-The method <code>edit()</code> in <code>ExprEditor</code>\r
-receives this object if object creation is found.\r
-The method <code>replace()</code> in\r
-<code>NewExpr</code> receives\r
-source text representing the substitued statement or\r
-block for the object creation.\r
-\r
-<p>\r
-In the source text, the identifiers starting with <code>$</code>\r
-have special meaning:\r
-\r
-<ul><table border=0>\r
-\r
-<tr>\r
-<td><code>$0</code></td>\r
-<td>\r
-<code>null</code>.\r
-</td>\r
-</tr>\r
-\r
-<tr>\r
-<td><code>$1</code>, <code>$2</code>, ...    </td>\r
-<td>\r
-The parameters to the constructor.\r
-</td>\r
-</tr>\r
-\r
-<tr>\r
-<td><code>$_</code></td>\r
-<td rowspan=2>\r
-The resulting value of the object creation.\r
-<br>A newly created object must be stored in this variable.\r
-</td>\r
-</tr>\r
-\r
-<tr><td> </td></tr>\r
-\r
-<tr>\r
-<td><code>$r</code></td>\r
-<td>\r
-The type of the created object.\r
-</td>\r
-</tr>\r
-\r
-<tr><td><code>$sig</code>    </td>\r
-<td>An array of <code>java.lang.Class</code> objects representing\r
-the formal parameter types.</td>\r
-</tr>\r
-\r
-<tr><td><code>$type</code>    </td>\r
-<td>A <code>java.lang.Class</code> object representing\r
-the class of the created object.\r
-</td></tr>\r
-\r
-<tr><td><code>$proceed</code>    </td>\r
-<td>The name of a virtual method executing the original\r
-object creation.\r
-.</td>\r
-</tr>\r
-\r
-</table>\r
-</ul>\r
-\r
-<p>The other identifiers such as <code>$w</code>,\r
-<code>$args</code> and <code>$$</code>\r
-are also available.\r
-\r
-<h4>javassist.expr.NewArray</h4>\r
-\r
-<p>A <code>NewArray</code> object represents array creation\r
-with the <code>new</code> operator.\r
-The method <code>edit()</code> in <code>ExprEditor</code>\r
-receives this object if array creation is found.\r
-The method <code>replace()</code> in\r
-<code>NewArray</code> receives\r
-source text representing the substitued statement or\r
-block for the array creation.\r
-\r
-<p>\r
-In the source text, the identifiers starting with <code>$</code>\r
-have special meaning:\r
-\r
-<ul><table border=0>\r
-\r
-<tr>\r
-<td><code>$0</code></td>\r
-<td>\r
-<code>null</code>.\r
-</td>\r
-</tr>\r
-\r
-<tr>\r
-<td><code>$1</code>, <code>$2</code>, ...    </td>\r
-<td>\r
-The size of each dimension.\r
-</td>\r
-</tr>\r
-\r
-<tr>\r
-<td><code>$_</code></td>\r
-<td rowspan=2>\r
-The resulting value of the array creation.\r
-<br>A newly created array must be stored in this variable.\r
-</td>\r
-</tr>\r
-\r
-<tr><td> </td></tr>\r
-\r
-<tr>\r
-<td><code>$r</code></td>\r
-<td>\r
-The type of the created array.\r
-</td>\r
-</tr>\r
-\r
-<tr><td><code>$type</code>    </td>\r
-<td>A <code>java.lang.Class</code> object representing\r
-the class of the created array.\r
-</td></tr>\r
-\r
-<tr><td><code>$proceed</code>    </td>\r
-<td>The name of a virtual method executing the original\r
-array creation.\r
-.</td>\r
-</tr>\r
-\r
-</table>\r
-</ul>\r
-\r
-<p>The other identifiers such as <code>$w</code>,\r
-<code>$args</code> and <code>$$</code>\r
-are also available.\r
-\r
-<p>For example, if the array creation is the following expression,\r
-\r
-<ul><pre>\r
-String[][] s = new String[3][4];\r
-</pre></ul>\r
-\r
-then the value of $1 and $2 are 3 and 4, respectively. $3 is not available.\r
-\r
-<p>If the array creation is the following expression,\r
-\r
-<ul><pre>\r
-String[][] s = new String[3][];\r
-</pre></ul>\r
-\r
-then the value of $1 is 3 but $2 is not available.\r
-\r
-<h4>javassist.expr.Instanceof</h4>\r
-\r
-<p>A <code>Instanceof</code> object represents an <code>instanceof</code>\r
-expression.\r
-The method <code>edit()</code> in <code>ExprEditor</code>\r
-receives this object if an instanceof expression is found.\r
-The method <code>replace()</code> in\r
-<code>Instanceof</code> receives\r
-source text representing the substitued statement or\r
-block for the expression.\r
-\r
-<p>\r
-In the source text, the identifiers starting with <code>$</code>\r
-have special meaning:\r
-\r
-<ul><table border=0>\r
-\r
-<tr>\r
-<td><code>$0</code></td>\r
-<td>\r
-<code>null</code>.\r
-</td>\r
-</tr>\r
-\r
-<tr>\r
-<td><code>$1</code></td>\r
-<td>\r
-The value on the left hand side of the original\r
-<code>instanceof</code> operator.\r
-</td>\r
-</tr>\r
-\r
-<tr>\r
-<td><code>$_</code></td>\r
-<td>\r
-The resulting value of the expression.\r
-The type of <code>$_</code> is <code>boolean</code>.\r
-</td>\r
-</tr>\r
-\r
-<tr>\r
-<td><code>$r</code></td>\r
-<td>\r
-The type on the right hand side of the <code>instanceof</code> operator.\r
-</td>\r
-</tr>\r
-\r
-<tr><td><code>$type</code></td>\r
-<td>A <code>java.lang.Class</code> object representing\r
-the type on the right hand side of the <code>instanceof</code> operator.\r
-</td>\r
-</tr>\r
-\r
-<tr><td><code>$proceed</code>    </td>\r
-<td rowspan=4>The name of a virtual method executing the original\r
-<code>instanceof</code> expression.\r
-<br>It takes one parameter (the type is <code>java.lang.Object</code>)\r
-and returns true\r
-<br>if the parameter value is an instance of the type on the right\r
-hand side of\r
-<br>the original <code>instanceof</code> operator.\r
-Otherwise, it returns false.\r
-</td>\r
-</tr>\r
-\r
-<tr><td> </td></tr>\r
-<tr><td> </td></tr>\r
-<tr><td> </td></tr>\r
-\r
-</table>\r
-</ul>\r
-\r
-<p>The other identifiers such as <code>$w</code>,\r
-<code>$args</code> and <code>$$</code>\r
-are also available.\r
-\r
-<h4>javassist.expr.Cast</h4>\r
-\r
-<p>A <code>Cast</code> object represents an expression for\r
-explicit type casting.\r
-The method <code>edit()</code> in <code>ExprEditor</code>\r
-receives this object if explicit type casting is found.\r
-The method <code>replace()</code> in\r
-<code>Cast</code> receives\r
-source text representing the substitued statement or\r
-block for the expression.\r
-\r
-<p>\r
-In the source text, the identifiers starting with <code>$</code>\r
-have special meaning:\r
-\r
-<ul><table border=0>\r
-\r
-<tr>\r
-<td><code>$0</code></td>\r
-<td>\r
-<code>null</code>.\r
-</td>\r
-</tr>\r
-\r
-<tr>\r
-<td><code>$1</code></td>\r
-<td>\r
-The value the type of which is explicitly cast.\r
-</td>\r
-</tr>\r
-\r
-<tr>\r
-<td><code>$_</code></td>\r
-<td rowspan=2>\r
-The resulting value of the expression.\r
-The type of <code>$_</code> is the same as the type\r
-<br>after the explicit casting, that is, the type surrounded\r
-by <code>( )</code>.\r
-</td>\r
-</tr>\r
-\r
-<tr><td> </td></tr>\r
-\r
-<tr>\r
-<td><code>$r</code></td>\r
-<td>the type after the explicit casting, or the type surrounded\r
-by <code>( )</code>.\r
-</td>\r
-</tr>\r
-\r
-<tr><td><code>$type</code></td>\r
-<td>A <code>java.lang.Class</code> object representing\r
-the same type as <code>$r</code>.\r
-</td>\r
-</tr>\r
-\r
-<tr><td><code>$proceed</code>    </td>\r
-<td rowspan=3>The name of a virtual method executing the original\r
-type casting.\r
-<br>It takes one parameter of the type <code>java.lang.Object</code>\r
-and returns it after\r
-<br>the explicit type casting specified by the original expression.\r
-\r
-</td>\r
-</tr>\r
-\r
-<tr><td> </td></tr>\r
-\r
-<tr><td> </td></tr>\r
-\r
-</table>\r
-</ul>\r
-\r
-<p>The other identifiers such as <code>$w</code>,\r
-<code>$args</code> and <code>$$</code>\r
-are also available.\r
-\r
-<h4>javassist.expr.Handler</h4>\r
-\r
-<p>A <code>Handler</code> object represents a <code>catch</code>\r
-clause of <code>try-catch</code> statement.\r
-The method <code>edit()</code> in <code>ExprEditor</code>\r
-receives this object if a <code>catch</code> is found.\r
-The method <code>insertBefore()</code> in\r
-<code>Handler</code> compiles the received\r
-source text and inserts it at the beginning of the <code>catch</code> clause.\r
-\r
-<p>\r
-In the source text, the identifiers starting with <code>$</code>\r
-have meaning:\r
-\r
-<ul><table border=0>\r
-\r
-<tr>\r
-<td><code>$1</code></td>\r
-<td>\r
-The exception object caught by the <code>catch</code> clause.\r
-</td>\r
-</tr>\r
-\r
-<tr>\r
-<td><code>$r</code></td>\r
-<td>the type of the exception caught by the <code>catch</code> clause.\r
-It is used in a cast expression.\r
-</td>\r
-</tr>\r
-\r
-<tr>\r
-<td><code>$w</code></td>\r
-<td>The wrapper type. It is used in a cast expression.\r
-</td>\r
-</tr>\r
-\r
-<tr><td><code>$type</code>    </td>\r
-<td rowspan=2>\r
-A <code>java.lang.Class</code> object representing\r
-<br>the type of the exception caught by the <code>catch</code> clause.\r
-</td>\r
-</tr>\r
-\r
-<tr><td> </td></tr>\r
-\r
-</table>\r
-</ul>\r
-\r
-<p>If a new exception object is assigned to <code>$1</code>,\r
-it is passed to the original <code>catch</code> clause as the caught\r
-exception.\r
-\r
-<p><br>\r
-\r
-<a name="add">\r
-<h3>4.3 Adding a new method or field</h3>\r
-\r
-<h4>Adding a method</h4>\r
-\r
-<p>Javassist allows the users to create a new method and constructor\r
-from scratch. <code>CtNewMethod</code>\r
-and <code>CtNewConstructor</code> provide several factory methods,\r
-which are static methods for creating <code>CtMethod</code> or\r
-<code>CtConstructor</code> objects.\r
-Especially, <code>make()</code> creates \r
-a <code>CtMethod</code> or <code>CtConstructor</code> object\r
-from the given source text.\r
-\r
-<p>For example, this program:\r
-\r
-<ul><pre>\r
-CtClass point = ClassPool.getDefault().get("Point");\r
-CtMethod m = CtNewMethod.make(\r
- "public int xmove(int dx) { x += dx; }",\r
- point);\r
-point.addMethod(m);\r
-</pre></ul>\r
-\r
-<p>adds a public method <code>xmove()</code> to class <code>Point</code>.\r
-In this example, <code>x</code> is a <code>int</code> field in\r
-the class <code>Point</code>.\r
-\r
-<p>The source text passed to <code>make()</code> can include the\r
-identifiers starting with <code>$</code> except <code>$_</code>\r
-as in <code>setBody()</code>.\r
-It can also include\r
-<code>$proceed</code> if the target object and the target method name\r
-are also given to <code>make()</code>. For example,\r
-\r
-<ul><pre>\r
-CtClass point = ClassPool.getDefault().get("Point");\r
-CtMethod m = CtNewMethod.make(\r
- "public int ymove(int dy) { $proceed(0, dy); }",\r
- point, "this", "move");\r
-</pre></ul>\r
-\r
-<p>this program creates a method <code>ymove()</code> defined below:\r
-\r
-<ul><pre>\r
-public int ymove(int dy) { this.move(0, dy); }\r
-</pre></ul>\r
-\r
-<p>Note that <code>$proceed</code> has been replaced with\r
-<code>this.move</code>.\r
-\r
-<p>Javassist provides another way to add a new method.\r
-You can first create an abstract method and later give it a method body:\r
-\r
-<ul><pre>\r
-CtClass cc = ... ;\r
-CtMethod m = new CtMethod(CtClass.intType, "move",\r
- new CtClass[] { CtClass.intType }, cc);\r
-cc.addMethod(m);\r
-m.setBody("{ x += $1; }");\r
-cc.setModifiers(cc.getModifiers() & ~Modifier.ABSTRACT);\r
-</pre></ul>\r
-\r
-<p>Since Javassist makes a class abstract if an abstract method is\r
-added to the class, you have to explicitly change the class back to a\r
-non-abstract one after calling <code>setBody()</code>.\r
-\r
-\r
-<h4>Mutual recursive methods</h4>\r
-\r
-<p>Javassist cannot compile a method if it calls another method that\r
-has not been added to a class. (Javassist can compile a method that\r
-calls itself recursively.) To add mutual recursive methods to a class,\r
-you need a trick shown below. Suppose that you want to add methods\r
-<code>m()</code> and <code>n()</code> to a class represented\r
-by <code>cc</code>:\r
-\r
-<ul><pre>\r
-CtClass cc = ... ;\r
-CtMethod m = CtNewMethod.make("public abstract int m(int i);", cc);\r
-CtMethod n = CtNewMethod.make("public abstract int n(int i);", cc);\r
-cc.addMethod(m);\r
-cc.addMethod(n);\r
-m.setBody("{ return ($1 <= 0) ? 1 : (n($1 - 1) * $1); }");\r
-n.setBody("{ return m($1); }");\r
-cc.setModifiers(cc.getModifiers() & ~Modifier.ABSTRACT);\r
-</pre></ul>\r
-\r
-<p>You must first make two abstract methods and add them to the class.\r
-Then you can give the method bodies to these methods even if the method\r
-bodies include method calls to each other. Finally you must change the\r
-class to a not-abstract class since <code>addMethod()</code> automatically\r
-changes a class into an abstract one if an abstract method is added.\r
-\r
-<h4>Adding a field</h4>\r
-\r
-<p>Javassist also allows the users to create a new field.\r
-\r
-<ul><pre>\r
-CtClass point = ClassPool.getDefault().get("Point");\r
-CtField f = new CtField(CtClass.intType, "z", point);\r
-point.addField(f);\r
-</pre></ul>\r
-\r
-<p>This program adds a field named <code>z</code> to class\r
-<code>Point</code>.\r
-\r
-<p>If the initial value of the added field must be specified,\r
-the program shown above must be modified into:\r
-\r
-<ul><pre>\r
-CtClass point = ClassPool.getDefault().get("Point");\r
-CtField f = new CtField(CtClass.intType, "z", point);\r
-point.addField(f, "0"); <em>// initial value is 0.</em>\r
-</pre></ul>\r
-\r
-<p>Now, the method <code>addField()</code> receives the second parameter,\r
-which is the source text representing an expression computing the initial\r
-value. This source text can be any Java expression if the result type\r
-of the expression matches the type of the field. Note that an expression\r
-does not end with a semi colon (<code>;</code>).\r
-\r
-<p>Furthermore, the above code can be rewritten into the following\r
-simple code:\r
-\r
-<ul><pre>\r
-CtClass point = ClassPool.getDefault().get("Point");\r
-CtField f = CtField.make("public int z = 0;", point);\r
-point.addField(f);\r
-</pre></ul>\r
-\r
-\r
-<p><br>\r
-\r
-<a name="runtime">\r
-<h3>4.4 Runtime support classes</h3>\r
-\r
-<p>In most cases, a class modified by Javassist does not require\r
-Javassist to run. However, some kinds of bytecode generated by the\r
-Javassist compiler need runtime support classes, which are in the\r
-<code>javassist.runtime</code> package (for details, please read\r
-the API reference of that package). Note that the\r
-<code>javassist.runtime</code> package is the only package that\r
-classes modified by Javassist may need for running. The other\r
-Javassist classes are never used at runtime of the modified classes.\r
-\r
-<p><br>\r
-\r
-<a name="limit">\r
-<h3>4.5 Limitations</h3>\r
-\r
-<p>In the current implementation, the Java compiler included in Javassist\r
-has several limitations with respect to the language that the compiler can\r
-accept. Those limitations are:\r
-\r
-<p><li>The new syntax introduced by J2SE 5.0 (including enums and generics)\r
-has not been supported. Annotations are supported only by the low level\r
-API of Javassist.\r
-See the <code>javassist.bytecode.annotation</code> package.\r
-\r
-<p><li>All the class names must be fully qualified (they must include\r
-package names). This is because the compiler does not support\r
-<code>import</code>\r
-declarations. However, the <code>java.lang</code> package is an\r
-exception; for example, the compiler accepts <code>Object</code> as\r
-well as <code>java.lang.Object</code>.\r
-\r
-<p><li>Array initializers, a comma-separated list of expressions\r
-enclosed by braces <code>{</code> and <code>}</code>, are not\r
-supported.\r
-\r
-<p><li>Inner classes or anonymous classes are not supported.\r
-\r
-<p><li>Labeled <code>continue</code> and <code>break</code> statements\r
-are not supported.\r
-\r
-<p><li>The compiler does not correctly implement the Java method dispatch\r
-algorithm. The compiler may confuse if methods defined in a class\r
-have the same name but take different parameter lists.\r
-\r
-<p>For example,\r
-\r
-<ul><pre>\r
-class A {} \r
-class B extends A {} \r
-class C extends C {} \r
-\r
-class X { \r
- void foo(A a) { .. } \r
- void foo(B b) { .. } \r
-}\r
-</pre></ul>\r
-\r
-<p>If the compiled expression is <code>x.foo(new C())</code>, where\r
-<code>x</code> is an instance of X, the compiler may produce a call\r
-to <code>foo(A)</code> although the compiler can correctly compile\r
-<code>foo((B)new C())</code>.\r
-\r
-<p><li>The users are recommended to use <code>#</code> as the separator\r
-between a class name and a static method or field name.\r
-For example, in regular Java,\r
-\r
-<ul><pre>javassist.CtClass.intType.getName()</pre></ul>\r
-\r
-<p>calls a method <code>getName()</code> on\r
-the object indicated by the static field <code>intType</code>\r
-in <code>javassist.CtClass</code>. In Javassist, the users can\r
-write the expression shown above but they are recommended to\r
-write:\r
-\r
-<ul><pre>javassist.CtClass#intType.getName()</pre></ul>\r
-\r
-<p>so that the compiler can quickly parse the expression.\r
-</ul>\r
-\r
-<p><br>\r
-\r
-<a href="tutorial.html">Previous page</a>\r
- <a href="tutorial3.html">Next page</a>\r
-\r
-<hr>\r
-Java(TM) is a trademark of Sun Microsystems, Inc.<br>\r
-Copyright (C) 2000-2004 by Shigeru Chiba, All rights reserved.\r
-</body>\r
-</html>\r
+<html>
+<head>
+ <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
+ <title>Javassist Tutorial</title>
+ <link rel="stylesheet" type="text/css" href="brown.css">
+</head>
+
+<body>
+
+<div align="right">Getting Started with Javassist</div>
+
+<div align="left"><a href="tutorial.html">Previous page</a></div>
+<div align="right"><a href="tutorial3.html">Next page</a></div>
+
+<p>
+<a href="#intro">4. Introspection and customization</a>
+<ul>
+<li><a href="#before">Inserting source text at the beginning/end of a method body</a>
+<br><li><a href="#alter">Altering a method body</a>
+<br><li><a href="#add">Adding a new method or field</a>
+<br><li><a href="#runtime">Runtime support classes</a>
+<br><li><a href="#limit">Limitations</a>
+</ul>
+
+<p><br>
+
+<a name="intro">
+<h2>4. Introspection and customization</h2>
+
+<p><code>CtClass</code> provides methods for introspection. The
+introspective ability of Javassist is compatible with that of
+the Java reflection API. <code>CtClass</code> provides
+<code>getName()</code>, <code>getSuperclass()</code>,
+<code>getMethods()</code>, and so on.
+<code>CtClass</code> also provides methods for modifying a class
+definition. It allows to add a new field, constructor, and method.
+Instrumenting a method body is also possible.
+
+<p>
+Methods are represented by <code>CtMethod</code> objects.
+<code>CtMethod</code> provides several methods for modifying
+the definition of the method. Note that if a method is inherited
+from a super class, then
+the same <code>CtMethod</code> object
+that represents the inherited method represents the method declared
+in that super class.
+A <code>CtMethod</code> object corresponds to every method declaration.
+
+<p>
+For example, if class <code>Point</code> declares method <code>move()</code>
+and a subclass <code>ColorPoint</code> of <code>Point</code> does
+not override <code>move()</code>, the two <code>move()</code> methods
+declared in <code>Point</code> and inherited in <code>ColorPoint</code>
+are represented by the identical <code>CtMethod</code> object.
+If the method definition represented by this
+<code>CtMethod</code> object is modified, the modification is
+reflected on both the methods.
+If you want to modify only the <code>move()</code> method in
+<code>ColorPoint</code>, you first have to add to <code>ColorPoint</code>
+a copy of the <code>CtMethod</code> object representing <code>move()</code>
+in <code>Point</code>. A copy of the the <code>CtMethod</code> object
+can be obtained by <code>CtNewMethod.copy()</code>.
+
+
+<p><hr width="40%">
+
+<ul>
+Javassist does not allow to remove a method or field, but it allows
+to change the name. So if a method is not necessary any more, it should be
+renamed and changed to be a private method by calling
+<code>setName()</code>
+and <code>setModifiers()</code> declared in <code>CtMethod</code>.
+
+<p>Javassist does not allow to add an extra parameter to an existing
+method, either. Instead of doing that, a new method receiving the
+extra parameter as well as the other parameters should be added to the
+same class. For example, if you want to add an extra <code>int</code>
+parameter <code>newZ</code> to a method:
+
+<ul><pre>void move(int newX, int newY) { x = newX; y = newY; }</pre></ul>
+
+<p>in a <code>Point</code> class, then you should add the following
+method to the <code>Point</code> class:
+
+<ul><pre>void move(int newX, int newY, int newZ) {
+ // do what you want with newZ.
+ move(newX, newY);
+}</pre></ul>
+
+</ul>
+
+<p><hr width="40%">
+
+<p>Javassist also provides low-level API for directly editing a raw
+class file. For example, <code>getClassFile()</code> in
+<code>CtClass</code> returns a <code>ClassFile</code> object
+representing a raw class file. <code>getMethodInfo()</code> in
+<code>CtMethod</code> returns a <code>MethodInfo</code> object
+representing a <code>method_info</code> structure included in a class
+file. The low-level API uses the vocabulary from the Java Virtual
+machine specification. The users must have the knowledge about class
+files and bytecode. For more details, the users should see the
+<code>javassist.bytecode</code> package.
+
+<p>The class files modified by Javassist requires the
+<code>javassist.runtime</code> package for runtime support
+only if some special identifiers starting with <code>$</code>
+are used. Those special identifiers are described below.
+The class files modified without those special identifiers
+do not need the <code>javassist.runtime</code> package or any
+other Javassist packages at runtime.
+For more details, see the API documentation
+of the <code>javassist.runtime</code> package.
+
+<p><br>
+
+<a name="before">
+<h3>4.1 Inserting source text at the beginning/end of a method body</h3>
+
+<p><code>CtMethod</code> and <code>CtConstructor</code> provide
+methods <code>insertBefore()</code>, <code>insertAfter()</code>, and
+<code>addCatch()</code>. They are used for inserting a code fragment
+into the body of an existing method. The users can specify those code
+fragments with <em>source text</em> written in Java.
+Javassist includes a simple Java compiler for processing source
+text. It receives source text
+written in Java and compiles it into Java bytecode, which will be
+<em>inlined</em> into a method body.
+
+<p>
+Inserting a code fragment at the position specified by a line number
+is also possible
+(if the line number table is contained in the class file).
+<code>insertAt()</code> in <code>CtMethod</code> and
+<code>CtConstructor</code> takes source text and a line number in the source
+file of the original class definition.
+It compiles the source text and inserts the compiled code at the line number.
+
+<p>The methods <code>insertBefore()</code>, <code>insertAfter()</code>,
+<code>addCatch()</code>, and <code>insertAt()</code>
+receive a <code>String</code> object representing
+a statement or a block. A statement is a single control structure like
+<code>if</code> and <code>while</code> or an expression ending with
+a semi colon (<code>;</code>). A block is a set of
+statements surrounded with braces <code>{}</code>.
+Hence each of the following lines is an example of valid statement or block:
+
+<ul><pre>System.out.println("Hello");
+{ System.out.println("Hello"); }
+if (i < 0) { i = -i; }
+</pre></ul>
+
+<p>The statement and the block can refer to fields and methods.
+They can also refer to the parameters
+to the method that they are inserted into
+if that method was compiled with the -g option
+(to include a local variable attribute in the class file).
+Otherwise, they must access the method parameters through the special
+variables <code>$0</code>, <code>$1</code>, <code>$2</code>, ... described
+below.
+<em>Accessing local variables declared in the method is not allowed</em>
+although declaring a new local variable in the block is allowed.
+However, <code>insertAt()</code> allows the statement and the block
+to access local variables
+if these variables are available at the specified line number
+and the target method was compiled with the -g option.
+
+
+<!--
+<p><center><table border=8 cellspacing=0 bordercolor="#cfcfcf">
+<tr><td bgcolor="#cfcfcf">
+<b>Tip:</b>
+<br>    Local variables are not accessible.  
+</td></tr>
+</table></center>
+-->
+
+<p>The <code>String</code> object passed to the methods
+<code>insertBefore()</code>, <code>insertAfter()</code>,
+<code>addCatch()</code>, and <code>insertAt()</code> are compiled by
+the compiler included in Javassist.
+Since the compiler supports language extensions,
+several identifiers starting with <code>$</code>
+have special meaning:
+
+<ul><table border=0>
+<tr>
+<td><code>$0</code>, <code>$1</code>, <code>$2</code>, ...    </td>
+<td>Actual parameters</td>
+</tr>
+
+<tr>
+<td><code>$args</code></td>
+<td>An array of parameters.
+The type of <code>$args</code> is <code>Object[]</code>.
+</td>
+</tr>
+
+<tr>
+<td><code>$$</code></td>
+<td rowspan=2>All actual parameters.<br>
+For example, <code>m($$)</code> is equivalent to
+<code>m($1,$2,</code>...<code>)</code></td>
+</tr>
+
+<tr><td> </td></tr>
+
+<tr>
+<td><code>$cflow(</code>...<code>)</code></td>
+<td><code>cflow</code> variable</td>
+</tr>
+
+<tr>
+<td><code>$r</code></td>
+<td>The result type. It is used in a cast expression.</td>
+</tr>
+
+<tr>
+<td><code>$w</code></td>
+<td>The wrapper type. It is used in a cast expression.</td>
+</tr>
+
+<tr>
+<td><code>$_</code></td>
+<td>The resulting value</td>
+</tr>
+
+<tr>
+<td><code>$sig</code></td>
+<td>An array of <code>java.lang.Class</code> objects representing
+the formal parameter types.
+</td>
+</tr>
+
+<tr>
+<td><code>$type</code></td>
+<td>A <code>java.lang.Class</code> object representing
+the formal result type.</td>
+</tr>
+
+<tr>
+<td><code>$class</code></td>
+<td>A <code>java.lang.Class</code> object representing
+the class currently edited.</td>
+</tr>
+
+</table>
+</ul>
+
+<h4>$0, $1, $2, ...</h4>
+
+<p>The parameters passed to the target method
+are accessible with
+<code>$0</code>, <code>$1</code>, <code>$2</code>, ... instead of
+the original parameter names.
+<code>$1</code> represents the
+first parameter, <code>$2</code> represents the second parameter, and
+so on. The types of those variables are identical to the parameter
+types.
+<code>$0</code> is
+equivalent to <code>this</code>. If the method is static,
+<code>$0</code> is not available.
+
+<p>These variables are used as following. Suppose that a class
+<code>Point</code>:
+
+<pre><ul>class Point {
+ int x, y;
+ void move(int dx, int dy) { x += dx; y += dy; }
+}
+</ul></pre>
+
+<p>To print the values of <code>dx</code> and <code>dy</code>
+whenever the method <code>move()</code> is called, execute this
+program:
+
+<ul><pre>ClassPool pool = ClassPool.getDefault();
+CtClass cc = pool.get("Point");
+CtMethod m = cc.getDeclaredMethod("move");
+m.insertBefore("{ System.out.println($1); System.out.println($2); }");
+cc.writeFile();
+</pre></ul>
+
+<p>Note that the source text passed to <code>insertBefore()</code> is
+surrounded with braces <code>{}</code>.
+<code>insertBefore()</code> accepts only a single statement or a block
+surrounded with braces.
+
+<p>The definition of the class <code>Point</code> after the
+modification is like this:
+
+<pre><ul>class Point {
+ int x, y;
+ void move(int dx, int dy) {
+ { System.out.println(dx); System.out.println(dy); }
+ x += dx; y += dy;
+ }
+}
+</ul></pre>
+
+<p><code>$1</code> and <code>$2</code> are replaced with
+<code>dx</code> and <code>dy</code>, respectively.
+
+<p><code>$1</code>, <code>$2</code>, <code>$3</code> ... are
+updatable. If a new value is assigend to one of those variables,
+then the value of the parameter represented by that variable is
+also updated.
+
+
+<h4>$args</h4>
+
+<p>The variable <code>$args</code> represents an array of all the
+parameters. The type of that variable is an array of class
+<code>Object</code>. If a parameter type is a primitive type such as
+<code>int</code>, then the parameter value is converted into a wrapper
+object such as <code>java.lang.Integer</code> to store in
+<code>$args</code>. Thus, <code>$args[0]</code> is equivalent to
+<code>$1</code> unless the type of the first parameter is a primitive
+type. Note that <code>$args[0]</code> is not equivalent to
+<code>$0</code>; <code>$0</code> represents <code>this</code>.
+
+<p>If an array of <code>Object</code> is assigned to
+<code>$args</code>, then each element of that array is
+assigned to each parameter. If a parameter type is a primitive
+type, the type of the corresponding element must be a wrapper type.
+The value is converted from the wrapper type to the primitive type
+before it is assigned to the parameter.
+
+<h4>$$</h4>
+
+<p>The variable <code>$$</code> is abbreviation of a list of
+all the parameters separated by commas.
+For example, if the number of the parameters
+to method <code>move()</code> is three, then
+
+<ul><pre>move($$)</pre></ul>
+
+<p>is equivalent to this:
+
+<ul><pre>move($1, $2, $3)</pre></ul>
+
+<p>If <code>move()</code> does not take any parameters,
+then <code>move($$)</code> is
+equivalent to <code>move()</code>.
+
+<p><code>$$</code> can be used with another method.
+If you write an expression:
+
+<ul><pre>exMove($$, context)</pre></ul>
+
+<p>then this expression is equivalent to:
+
+<ul><pre>exMove($1, $2, $3, context)</pre></ul>
+
+<p>Note that <code>$$</code> enables generic notation of method call
+with respect to the number of parameters.
+It is typically used with <code>$proceed</code> shown later.
+
+<h4>$cflow</h4>
+
+<p><code>$cflow</code> means "control flow".
+This read-only variable returns the depth of the recursive calls
+to a specific method.
+
+<p>Suppose that the method shown below is represented by a
+<code>CtMethod</code> object <code>cm</code>:
+
+<ul><pre>int fact(int n) {
+ if (n <= 1)
+ return n;
+ else
+ return n * fact(n - 1);
+}</pre></ul>
+
+<p>To use <code>$cflow</code>, first declare that <code>$cflow</code>
+is used for monitoring calls to the method <code>fact()</code>:
+
+<ul><pre>CtMethod cm = ...;
+cm.useCflow("fact");</pre></ul>
+
+<p>The parameter to <code>useCflow()</code> is the identifier of the
+declared <code>$cflow</code> variable. Any valid Java name can be
+used as the identifier. Since the identifier can also include
+<code>.</code> (dot), for example, <code>"my.Test.fact"</code>
+is a valid identifier.
+
+<p>Then, <code>$cflow(fact)</code> represents the depth of the
+recursive calls to the method specified by <code>cm</code>. The value
+of <code>$cflow(fact)</code> is 0 (zero) when the method is
+first called whereas it is 1 when the method is recursively called
+within the method. For example,
+
+<ul><pre>
+cm.insertBefore("if ($cflow(fact) == 0)"
+ + " System.out.println(\"fact \" + $1);");
+</pre></ul>
+
+<p>translates the method <code>fact()</code> so that it shows the
+parameter. Since the value of <code>$cflow(fact)</code> is checked,
+the method <code>fact()</code> does not show the parameter if it is
+recursively called within <code>fact()</code>.
+
+<p>The value of <code>$cflow</code> is the number of stack frames
+associated with the specified method <code>cm</code>
+under the current topmost
+stack frame for the current thread. <code>$cflow</code> is also
+accessible within a method different from the specified method
+<code>cm</code>.
+
+<h4>$r</h4>
+
+<p><code>$r</code> represents the result type (return type) of the method.
+It must be used as the cast type in a cast expression.
+For example, this is a typical use:
+
+<ul><pre>Object result = ... ;
+$_ = ($r)result;</pre></ul>
+
+<p>If the result type is a primitive type, then <code>($r)</code>
+follows special semantics. First, if the operand type of the cast
+expression is a primitive type, <code>($r)</code> works as a normal
+cast operator to the result type.
+On the other hand, if the operand type is a wrapper type,
+<code>($r)</code> converts from the wrapper type to the result type.
+For example, if the result type is <code>int</code>, then
+<code>($r)</code> converts from <code>java.lang.Integer</code> to
+<code>int</code>.
+
+<p>If the result type is <code>void</code>, then
+<code>($r)</code> does not convert a type; it does nothing.
+However, if the operand is a call to a <code>void</code> method,
+then <code>($r)</code> results in <code>null</code>. For example,
+if the result type is <code>void</code> and
+<code>foo()</code> is a <code>void</code> method, then
+
+<ul><pre>$_ = ($r)foo();</pre></ul>
+
+<p>is a valid statement.
+
+<p>The cast operator <code>($r)</code> is also useful in a
+<code>return</code> statement. Even if the result type is
+<code>void</code>, the following <code>return</code> statement is valid:
+
+<ul><pre>return ($r)result;</pre></ul>
+
+<p>Here, <code>result</code> is some local variable.
+Since <code>($r)</code> is specified, the resulting value is
+discarded.
+This <code>return</code> statement is regarded as the equivalent
+of the <code>return</code> statement without a resulting value:
+
+<ul><pre>return;</pre></ul>
+
+<h4>$w</h4>
+
+<p><code>$w</code> represents a wrapper type.
+It must be used as the cast type in a cast expression.
+<code>($w)</code> converts from a primitive type to the corresponding
+wrapper type.
+
+The following code is an example:
+
+<ul><pre>Integer i = ($w)5;</pre></ul>
+
+<p>The selected wrapper type depends on the type of the expression
+following <code>($w)</code>. If the type of the expression is
+<code>double</code>, then the wrapper type is <code>java.lang.Double</code>.
+
+<p>If the type of the expression following <code>($w)</code> is not
+a primitive type, then <code>($w)</code> does nothing.
+
+<h4>$_</h4>
+
+<p><code>insertAfter()</code> in <code>CtMethod</code> and
+<code>CtConstructor</code> inserts the
+compiled code at the end of the method. In the statement given to
+<code>insertAfter()</code>, not only the variables shown above such as
+<code>$0</code>, <code>$1</code>, ... but also <code>$_</code> is
+available.
+
+<p>The variable <code>$_</code> represents the resulting value of the
+method. The type of that variable is the type of the result type (the
+return type) of the method. If the result type is <code>void</code>,
+then the type of <code>$_</code> is <code>Object</code> and the value
+of <code>$_</code> is <code>null</code>.
+
+<p>Although the compiled code inserted by <code>insertAfter()</code>
+is executed just before the control normally returns from the method,
+it can be also executed when an exception is thrown from the method.
+To execute it when an exception is thrown, the second parameter
+<code>asFinally</code> to <code>insertAfter()</code> must be
+<code>true</code>.
+
+<p>If an exception is thrown, the compiled code inserted by
+<code>insertAfter()</code> is executed as a <code>finally</code>
+clause. The value of <code>$_</code> is <code>0</code> or
+<code>null</code> in the compiled code. After the execution of the
+compiled code terminates, the exception originally thrown is re-thrown
+to the caller. Note that the value of <code>$_</code> is never thrown
+to the caller; it is rather discarded.
+
+<h4>$sig</h4>
+
+<p>The value of <code>$sig</code> is an array of
+<code>java.lang.Class</code> objects that represent the formal
+parameter types in declaration order.
+
+<h4>$type</h4>
+
+<p>The value of <code>$type</code> is an <code>java.lang.Class</code>
+object representing the formal type of the result value. This
+variable is available only in <code>insertAfter()</code> in
+<code>CtMethod</code> and <code>CtConstructor</code>.
+
+<h4>$class</h4>
+
+<p>The value of <code>$class</code> is an <code>java.lang.Class</code>
+object representing the class in which the edited method is declared.
+This represents the type of <code>$0</code>.
+
+<h4>addCatch()</h4>
+
+<p><code>addCatch()</code> inserts a code fragment into a method body
+so that the code fragment is executed when the method body throws
+an exception and the control returns to the caller. In the source
+text representing the inserted code fragment, the exception value
+is referred to with the special variable <code>$e</code>.
+
+<p>For example, this program:
+
+<ul><pre>
+CtMethod m = ...;
+CtClass etype = ClassPool.getDefault().get("java.io.IOException");
+m.addCatch("{ System.out.println($e); throw $e; }", etype);
+</pre></ul>
+
+<p>translates the method body represented by <code>m</code> into
+something like this:
+
+<ul><pre>
+try {
+ <font face="serif"><em>the original method body</em></font>
+}
+catch (java.io.IOException e) {
+ System.out.println(e);
+ throw e;
+}
+</pre></ul>
+
+<p>Note that the inserted code fragment must end with a
+<code>throw</code> or <code>return</code> statement.
+
+<p><br>
+
+<a name="alter">
+<h3>4.2 Altering a method body</h3>
+
+<p><code>CtMethod</code> and <code>CtConstructor</code> provide
+<code>setBody()</code> for substituting a whole
+method body. They compile the given source text into Java bytecode
+and substitutes it for the original method body. If the given source
+text is <code>null</code>, the substituted body includes only a
+<code>return</code> statement, which returns zero or null unless the
+result type is <code>void</code>.
+
+<p>In the source text given to <code>setBody()</code>, the identifiers
+starting with <code>$</code> have special meaning
+
+<ul><table border=0>
+<tr>
+<td><code>$0</code>, <code>$1</code>, <code>$2</code>, ...    </td>
+<td>Actual parameters</td>
+</tr>
+
+<tr>
+<td><code>$args</code></td>
+<td>An array of parameters.
+The type of <code>$args</code> is <code>Object[]</code>.
+</td>
+</tr>
+
+<tr>
+<td><code>$$</code></td>
+<td>All actual parameters.<br>
+</tr>
+
+<tr>
+<td><code>$cflow(</code>...<code>)</code></td>
+<td><code>cflow</code> variable</td>
+</tr>
+
+<tr>
+<td><code>$r</code></td>
+<td>The result type. It is used in a cast expression.</td>
+</tr>
+
+<tr>
+<td><code>$w</code></td>
+<td>The wrapper type. It is used in a cast expression.</td>
+</tr>
+
+<tr>
+<td><code>$sig</code></td>
+<td>An array of <code>java.lang.Class</code> objects representing
+the formal parameter types.
+</td>
+</tr>
+
+<tr>
+<td><code>$type</code></td>
+<td>A <code>java.lang.Class</code> object representing
+the formal result type.</td>
+</tr>
+
+<tr>
+<td><code>$class</code></td>
+<td rowspan=2>A <code>java.lang.Class</code> object representing
+the class that declares the method<br>
+currently edited (the type of $0).</td>
+</tr>
+
+<tr><td> </td></tr>
+
+</table>
+</ul>
+
+Note that <code>$_</code> is not available.
+
+<h4>Substituting source text for an existing expression</h4>
+
+<p>Javassist allows modifying only an expression included in a method body.
+<code>javassist.expr.ExprEditor</code> is a class
+for replacing an expression in a method body.
+The users can define a subclass of <code>ExprEditor</code>
+to specify how an expression is modified.
+
+<p>To run an <code>ExprEditor</code> object, the users must
+call <code>instrument()</code> in <code>CtMethod</code> or
+<code>CtClass</code>.
+
+For example,
+
+<ul><pre>
+CtMethod cm = ... ;
+cm.instrument(
+ new ExprEditor() {
+ public void edit(MethodCall m)
+ throws CannotCompileException
+ {
+ if (m.getClassName().equals("Point")
+ && m.getMethodName().equals("move"))
+ m.replace("{ $1 = 0; $_ = $proceed($$); }");
+ }
+ });
+</pre></ul>
+
+<p>searches the method body represented by <code>cm</code> and
+replaces all calls to <code>move()</code> in class <code>Point</code>
+with a block:
+
+<ul><pre>{ $1 = 0; $_ = $proceed($$); }
+</pre></ul>
+
+<p>so that the first parameter to <code>move()</code> is always 0.
+Note that the substituted code is not an expression but
+a statement or a block.
+
+<p>The method <code>instrument()</code> searches a method body.
+If it finds an expression such as a method call, field access, and object
+creation, then it calls <code>edit()</code> on the given
+<code>ExprEditor</code> object. The parameter to <code>edit()</code>
+is an object representing the found expression. The <code>edit()</code>
+method can inspect and replace the expression through that object.
+
+<p>Calling <code>replace()</code> on the parameter to <code>edit()</code>
+substitutes the given statement or block for the expression. If the given
+block is an empty block, that is, if <code>replace("{}")</code>
+is executed, then the expression is removed from the method body.
+
+If you want to insert a statement (or a block) before/after the
+expression, a block like the following should be passed to
+<code>replace()</code>:
+
+<ul><pre>
+{ <em>before-statements;</em>
+ $_ = $proceed($$);
+ <em>after-statements;</em> }
+</pre></ul>
+
+<p>whichever the expression is either a method call, field access,
+object creation, or others. The second statement could be:
+
+<ul><pre>$_ = $proceed();</pre></ul>
+
+<p>if the expression is read access, or
+
+<ul><pre>$proceed($$);</pre></ul>
+
+<p>if the expression is write access.
+
+<p>Local variables available in the target expression is
+also available in the source text passed to <code>replace()</code>
+if the method searched by <code>instrument()</code> was compiled
+with the -g option (the class file includes a local variable
+attribute).
+
+<h4>javassist.expr.MethodCall</h4>
+
+<p>A <code>MethodCall</code> object represents a method call.
+The method <code>replace()</code> in
+<code>MethodCall</code> substitutes a statement or
+a block for the method call.
+It receives source text representing the substitued statement or
+block, in which the identifiers starting with <code>$</code>
+have special meaning as in the source text passed to
+<code>insertBefore()</code>.
+
+<ul><table border=0>
+<tr>
+<td><code>$0</code></td>
+<td rowspan=3>
+The target object of the method call.<br>
+This is not equivalent to <code>this</code>, which represents
+the caller-side <code>this</code> object.<br>
+<code>$0</code> is <code>null</code> if the method is static.
+</td>
+</tr>
+
+<tr><td> </td></tr>
+
+<tr><td> </td></tr>
+
+<tr>
+<td><code>$1</code>, <code>$2</code>, ...    </td>
+<td>
+The parameters of the method call.
+</td>
+</tr>
+
+<tr><td>
+<code>$_</code></td>
+<td>The resulting value of the method call.</td>
+</tr>
+
+<tr><td><code>$r</code></td>
+<td>The result type of the method call.</td>
+</tr>
+
+<tr><td><code>$class</code>    </td>
+<td>A <code>java.lang.Class</code> object representing
+the class declaring the method.
+</td>
+</tr>
+
+<tr><td><code>$sig</code>    </td>
+<td>An array of <code>java.lang.Class</code> objects representing
+the formal parameter types.</td>
+</tr>
+
+<tr><td><code>$type</code>    </td>
+<td>A <code>java.lang.Class</code> object representing
+the formal result type.</td>
+</tr>
+
+<tr><td><code>$proceed</code>    </td>
+<td>The name of the method originally called
+in the expression.</td>
+</tr>
+
+</table>
+</ul>
+
+<p>Here the method call means the one represented by the
+<code>MethodCall</code> object.
+
+<p>The other identifiers such as <code>$w</code>,
+<code>$args</code> and <code>$$</code>
+are also available.
+
+<p>Unless the result type of the method call is <code>void</code>,
+a value must be assigned to
+<code>$_</code> in the source text and the type of <code>$_</code>
+is the result type.
+If the result type is <code>void</code>, the type of <code>$_</code>
+is <code>Object</code> and the value assigned to <code>$_</code>
+is ignored.
+
+<p><code>$proceed</code> is not a <code>String</code> value but special
+syntax. It must be followed by an argument list surrounded by parentheses
+<code>( )</code>.
+
+<h4>javassist.expr.FieldAccess</h4>
+
+<p>A <code>FieldAccess</code> object represents field access.
+The method <code>edit()</code> in <code>ExprEditor</code>
+receives this object if field access is found.
+The method <code>replace()</code> in
+<code>FieldAccess</code> receives
+source text representing the substitued statement or
+block for the field access.
+
+<p>
+In the source text, the identifiers starting with <code>$</code>
+have special meaning:
+
+<ul><table border=0>
+<tr>
+<td><code>$0</code></td>
+<td rowspan=3>
+The object containing the field accessed by the expression.
+This is not equivalent to <code>this</code>.<br>
+<code>this</code> represents the object that the method including the
+expression is invoked on.<br>
+<code>$0</code> is <code>null</code> if the field is static.
+</td>
+</tr>
+
+<tr><td> </td></tr>
+
+<tr><td> </td></tr>
+
+<tr>
+<td><code>$1</code></td>
+<td rowspan=2>
+The value that would be stored in the field
+if the expression is write access.
+<br>Otherwise, <code>$1</code> is not available.
+</td>
+</tr>
+
+<tr><td> </td></tr>
+
+<tr>
+<td><code>$_</code></td>
+<td rowspan=2>
+The resulting value of the field access
+if the expression is read access.
+<br>Otherwise, the value stored in <code>$_</code> is discarded.
+</td>
+</tr>
+
+<tr><td> </td></tr>
+<tr>
+<td><code>$r</code></td>
+<td rowspan=2>
+The type of the field if the expression is read access.
+<br>Otherwise, <code>$r</code> is <code>void</code>.
+</td>
+</tr>
+
+<tr><td> </td></tr>
+
+<tr><td><code>$class</code>    </td>
+<td>A <code>java.lang.Class</code> object representing
+the class declaring the field.
+</td></tr>
+
+<tr><td><code>$type</code></td>
+<td>A <code>java.lang.Class</code> object representing
+the field type.</td>
+</tr>
+
+<tr><td><code>$proceed</code>    </td>
+<td>The name of a virtual method executing the original
+field access.
+.</td>
+</tr>
+
+</table>
+</ul>
+
+<p>The other identifiers such as <code>$w</code>,
+<code>$args</code> and <code>$$</code>
+are also available.
+
+<p>If the expression is read access, a value must be assigned to
+<code>$_</code> in the source text. The type of <code>$_</code>
+is the type of the field.
+
+<h4>javassist.expr.NewExpr</h4>
+
+<p>A <code>NewExpr</code> object represents object creation
+with the <code>new</code> operator (not including array creation).
+The method <code>edit()</code> in <code>ExprEditor</code>
+receives this object if object creation is found.
+The method <code>replace()</code> in
+<code>NewExpr</code> receives
+source text representing the substitued statement or
+block for the object creation.
+
+<p>
+In the source text, the identifiers starting with <code>$</code>
+have special meaning:
+
+<ul><table border=0>
+
+<tr>
+<td><code>$0</code></td>
+<td>
+<code>null</code>.
+</td>
+</tr>
+
+<tr>
+<td><code>$1</code>, <code>$2</code>, ...    </td>
+<td>
+The parameters to the constructor.
+</td>
+</tr>
+
+<tr>
+<td><code>$_</code></td>
+<td rowspan=2>
+The resulting value of the object creation.
+<br>A newly created object must be stored in this variable.
+</td>
+</tr>
+
+<tr><td> </td></tr>
+
+<tr>
+<td><code>$r</code></td>
+<td>
+The type of the created object.
+</td>
+</tr>
+
+<tr><td><code>$sig</code>    </td>
+<td>An array of <code>java.lang.Class</code> objects representing
+the formal parameter types.</td>
+</tr>
+
+<tr><td><code>$type</code>    </td>
+<td>A <code>java.lang.Class</code> object representing
+the class of the created object.
+</td></tr>
+
+<tr><td><code>$proceed</code>    </td>
+<td>The name of a virtual method executing the original
+object creation.
+.</td>
+</tr>
+
+</table>
+</ul>
+
+<p>The other identifiers such as <code>$w</code>,
+<code>$args</code> and <code>$$</code>
+are also available.
+
+<h4>javassist.expr.NewArray</h4>
+
+<p>A <code>NewArray</code> object represents array creation
+with the <code>new</code> operator.
+The method <code>edit()</code> in <code>ExprEditor</code>
+receives this object if array creation is found.
+The method <code>replace()</code> in
+<code>NewArray</code> receives
+source text representing the substitued statement or
+block for the array creation.
+
+<p>
+In the source text, the identifiers starting with <code>$</code>
+have special meaning:
+
+<ul><table border=0>
+
+<tr>
+<td><code>$0</code></td>
+<td>
+<code>null</code>.
+</td>
+</tr>
+
+<tr>
+<td><code>$1</code>, <code>$2</code>, ...    </td>
+<td>
+The size of each dimension.
+</td>
+</tr>
+
+<tr>
+<td><code>$_</code></td>
+<td rowspan=2>
+The resulting value of the array creation.
+<br>A newly created array must be stored in this variable.
+</td>
+</tr>
+
+<tr><td> </td></tr>
+
+<tr>
+<td><code>$r</code></td>
+<td>
+The type of the created array.
+</td>
+</tr>
+
+<tr><td><code>$type</code>    </td>
+<td>A <code>java.lang.Class</code> object representing
+the class of the created array.
+</td></tr>
+
+<tr><td><code>$proceed</code>    </td>
+<td>The name of a virtual method executing the original
+array creation.
+.</td>
+</tr>
+
+</table>
+</ul>
+
+<p>The other identifiers such as <code>$w</code>,
+<code>$args</code> and <code>$$</code>
+are also available.
+
+<p>For example, if the array creation is the following expression,
+
+<ul><pre>
+String[][] s = new String[3][4];
+</pre></ul>
+
+then the value of $1 and $2 are 3 and 4, respectively. $3 is not available.
+
+<p>If the array creation is the following expression,
+
+<ul><pre>
+String[][] s = new String[3][];
+</pre></ul>
+
+then the value of $1 is 3 but $2 is not available.
+
+<h4>javassist.expr.Instanceof</h4>
+
+<p>A <code>Instanceof</code> object represents an <code>instanceof</code>
+expression.
+The method <code>edit()</code> in <code>ExprEditor</code>
+receives this object if an instanceof expression is found.
+The method <code>replace()</code> in
+<code>Instanceof</code> receives
+source text representing the substitued statement or
+block for the expression.
+
+<p>
+In the source text, the identifiers starting with <code>$</code>
+have special meaning:
+
+<ul><table border=0>
+
+<tr>
+<td><code>$0</code></td>
+<td>
+<code>null</code>.
+</td>
+</tr>
+
+<tr>
+<td><code>$1</code></td>
+<td>
+The value on the left hand side of the original
+<code>instanceof</code> operator.
+</td>
+</tr>
+
+<tr>
+<td><code>$_</code></td>
+<td>
+The resulting value of the expression.
+The type of <code>$_</code> is <code>boolean</code>.
+</td>
+</tr>
+
+<tr>
+<td><code>$r</code></td>
+<td>
+The type on the right hand side of the <code>instanceof</code> operator.
+</td>
+</tr>
+
+<tr><td><code>$type</code></td>
+<td>A <code>java.lang.Class</code> object representing
+the type on the right hand side of the <code>instanceof</code> operator.
+</td>
+</tr>
+
+<tr><td><code>$proceed</code>    </td>
+<td rowspan=4>The name of a virtual method executing the original
+<code>instanceof</code> expression.
+<br>It takes one parameter (the type is <code>java.lang.Object</code>)
+and returns true
+<br>if the parameter value is an instance of the type on the right
+hand side of
+<br>the original <code>instanceof</code> operator.
+Otherwise, it returns false.
+</td>
+</tr>
+
+<tr><td> </td></tr>
+<tr><td> </td></tr>
+<tr><td> </td></tr>
+
+</table>
+</ul>
+
+<p>The other identifiers such as <code>$w</code>,
+<code>$args</code> and <code>$$</code>
+are also available.
+
+<h4>javassist.expr.Cast</h4>
+
+<p>A <code>Cast</code> object represents an expression for
+explicit type casting.
+The method <code>edit()</code> in <code>ExprEditor</code>
+receives this object if explicit type casting is found.
+The method <code>replace()</code> in
+<code>Cast</code> receives
+source text representing the substitued statement or
+block for the expression.
+
+<p>
+In the source text, the identifiers starting with <code>$</code>
+have special meaning:
+
+<ul><table border=0>
+
+<tr>
+<td><code>$0</code></td>
+<td>
+<code>null</code>.
+</td>
+</tr>
+
+<tr>
+<td><code>$1</code></td>
+<td>
+The value the type of which is explicitly cast.
+</td>
+</tr>
+
+<tr>
+<td><code>$_</code></td>
+<td rowspan=2>
+The resulting value of the expression.
+The type of <code>$_</code> is the same as the type
+<br>after the explicit casting, that is, the type surrounded
+by <code>( )</code>.
+</td>
+</tr>
+
+<tr><td> </td></tr>
+
+<tr>
+<td><code>$r</code></td>
+<td>the type after the explicit casting, or the type surrounded
+by <code>( )</code>.
+</td>
+</tr>
+
+<tr><td><code>$type</code></td>
+<td>A <code>java.lang.Class</code> object representing
+the same type as <code>$r</code>.
+</td>
+</tr>
+
+<tr><td><code>$proceed</code>    </td>
+<td rowspan=3>The name of a virtual method executing the original
+type casting.
+<br>It takes one parameter of the type <code>java.lang.Object</code>
+and returns it after
+<br>the explicit type casting specified by the original expression.
+
+</td>
+</tr>
+
+<tr><td> </td></tr>
+
+<tr><td> </td></tr>
+
+</table>
+</ul>
+
+<p>The other identifiers such as <code>$w</code>,
+<code>$args</code> and <code>$$</code>
+are also available.
+
+<h4>javassist.expr.Handler</h4>
+
+<p>A <code>Handler</code> object represents a <code>catch</code>
+clause of <code>try-catch</code> statement.
+The method <code>edit()</code> in <code>ExprEditor</code>
+receives this object if a <code>catch</code> is found.
+The method <code>insertBefore()</code> in
+<code>Handler</code> compiles the received
+source text and inserts it at the beginning of the <code>catch</code> clause.
+
+<p>
+In the source text, the identifiers starting with <code>$</code>
+have meaning:
+
+<ul><table border=0>
+
+<tr>
+<td><code>$1</code></td>
+<td>
+The exception object caught by the <code>catch</code> clause.
+</td>
+</tr>
+
+<tr>
+<td><code>$r</code></td>
+<td>the type of the exception caught by the <code>catch</code> clause.
+It is used in a cast expression.
+</td>
+</tr>
+
+<tr>
+<td><code>$w</code></td>
+<td>The wrapper type. It is used in a cast expression.
+</td>
+</tr>
+
+<tr><td><code>$type</code>    </td>
+<td rowspan=2>
+A <code>java.lang.Class</code> object representing
+<br>the type of the exception caught by the <code>catch</code> clause.
+</td>
+</tr>
+
+<tr><td> </td></tr>
+
+</table>
+</ul>
+
+<p>If a new exception object is assigned to <code>$1</code>,
+it is passed to the original <code>catch</code> clause as the caught
+exception.
+
+<p><br>
+
+<a name="add">
+<h3>4.3 Adding a new method or field</h3>
+
+<h4>Adding a method</h4>
+
+<p>Javassist allows the users to create a new method and constructor
+from scratch. <code>CtNewMethod</code>
+and <code>CtNewConstructor</code> provide several factory methods,
+which are static methods for creating <code>CtMethod</code> or
+<code>CtConstructor</code> objects.
+Especially, <code>make()</code> creates
+a <code>CtMethod</code> or <code>CtConstructor</code> object
+from the given source text.
+
+<p>For example, this program:
+
+<ul><pre>
+CtClass point = ClassPool.getDefault().get("Point");
+CtMethod m = CtNewMethod.make(
+ "public int xmove(int dx) { x += dx; }",
+ point);
+point.addMethod(m);
+</pre></ul>
+
+<p>adds a public method <code>xmove()</code> to class <code>Point</code>.
+In this example, <code>x</code> is a <code>int</code> field in
+the class <code>Point</code>.
+
+<p>The source text passed to <code>make()</code> can include the
+identifiers starting with <code>$</code> except <code>$_</code>
+as in <code>setBody()</code>.
+It can also include
+<code>$proceed</code> if the target object and the target method name
+are also given to <code>make()</code>. For example,
+
+<ul><pre>
+CtClass point = ClassPool.getDefault().get("Point");
+CtMethod m = CtNewMethod.make(
+ "public int ymove(int dy) { $proceed(0, dy); }",
+ point, "this", "move");
+</pre></ul>
+
+<p>this program creates a method <code>ymove()</code> defined below:
+
+<ul><pre>
+public int ymove(int dy) { this.move(0, dy); }
+</pre></ul>
+
+<p>Note that <code>$proceed</code> has been replaced with
+<code>this.move</code>.
+
+<p>Javassist provides another way to add a new method.
+You can first create an abstract method and later give it a method body:
+
+<ul><pre>
+CtClass cc = ... ;
+CtMethod m = new CtMethod(CtClass.intType, "move",
+ new CtClass[] { CtClass.intType }, cc);
+cc.addMethod(m);
+m.setBody("{ x += $1; }");
+cc.setModifiers(cc.getModifiers() & ~Modifier.ABSTRACT);
+</pre></ul>
+
+<p>Since Javassist makes a class abstract if an abstract method is
+added to the class, you have to explicitly change the class back to a
+non-abstract one after calling <code>setBody()</code>.
+
+
+<h4>Mutual recursive methods</h4>
+
+<p>Javassist cannot compile a method if it calls another method that
+has not been added to a class. (Javassist can compile a method that
+calls itself recursively.) To add mutual recursive methods to a class,
+you need a trick shown below. Suppose that you want to add methods
+<code>m()</code> and <code>n()</code> to a class represented
+by <code>cc</code>:
+
+<ul><pre>
+CtClass cc = ... ;
+CtMethod m = CtNewMethod.make("public abstract int m(int i);", cc);
+CtMethod n = CtNewMethod.make("public abstract int n(int i);", cc);
+cc.addMethod(m);
+cc.addMethod(n);
+m.setBody("{ return ($1 <= 0) ? 1 : (n($1 - 1) * $1); }");
+n.setBody("{ return m($1); }");
+cc.setModifiers(cc.getModifiers() & ~Modifier.ABSTRACT);
+</pre></ul>
+
+<p>You must first make two abstract methods and add them to the class.
+Then you can give the method bodies to these methods even if the method
+bodies include method calls to each other. Finally you must change the
+class to a not-abstract class since <code>addMethod()</code> automatically
+changes a class into an abstract one if an abstract method is added.
+
+<h4>Adding a field</h4>
+
+<p>Javassist also allows the users to create a new field.
+
+<ul><pre>
+CtClass point = ClassPool.getDefault().get("Point");
+CtField f = new CtField(CtClass.intType, "z", point);
+point.addField(f);
+</pre></ul>
+
+<p>This program adds a field named <code>z</code> to class
+<code>Point</code>.
+
+<p>If the initial value of the added field must be specified,
+the program shown above must be modified into:
+
+<ul><pre>
+CtClass point = ClassPool.getDefault().get("Point");
+CtField f = new CtField(CtClass.intType, "z", point);
+point.addField(f, "0"); <em>// initial value is 0.</em>
+</pre></ul>
+
+<p>Now, the method <code>addField()</code> receives the second parameter,
+which is the source text representing an expression computing the initial
+value. This source text can be any Java expression if the result type
+of the expression matches the type of the field. Note that an expression
+does not end with a semi colon (<code>;</code>).
+
+<p>Furthermore, the above code can be rewritten into the following
+simple code:
+
+<ul><pre>
+CtClass point = ClassPool.getDefault().get("Point");
+CtField f = CtField.make("public int z = 0;", point);
+point.addField(f);
+</pre></ul>
+
+
+<p><br>
+
+<a name="runtime">
+<h3>4.4 Runtime support classes</h3>
+
+<p>In most cases, a class modified by Javassist does not require
+Javassist to run. However, some kinds of bytecode generated by the
+Javassist compiler need runtime support classes, which are in the
+<code>javassist.runtime</code> package (for details, please read
+the API reference of that package). Note that the
+<code>javassist.runtime</code> package is the only package that
+classes modified by Javassist may need for running. The other
+Javassist classes are never used at runtime of the modified classes.
+
+<p><br>
+
+<a name="limit">
+<h3>4.5 Limitations</h3>
+
+<p>In the current implementation, the Java compiler included in Javassist
+has several limitations with respect to the language that the compiler can
+accept. Those limitations are:
+
+<p><li>The new syntax introduced by J2SE 5.0 (including enums and generics)
+has not been supported. Annotations are supported only by the low level
+API of Javassist.
+See the <code>javassist.bytecode.annotation</code> package.
+
+<p><li>All the class names must be fully qualified (they must include
+package names). This is because the compiler does not support
+<code>import</code>
+declarations. However, the <code>java.lang</code> package is an
+exception; for example, the compiler accepts <code>Object</code> as
+well as <code>java.lang.Object</code>.
+
+<p><li>Array initializers, a comma-separated list of expressions
+enclosed by braces <code>{</code> and <code>}</code>, are not
+supported.
+
+<p><li>Inner classes or anonymous classes are not supported.
+
+<p><li>Labeled <code>continue</code> and <code>break</code> statements
+are not supported.
+
+<p><li>The compiler does not correctly implement the Java method dispatch
+algorithm. The compiler may confuse if methods defined in a class
+have the same name but take different parameter lists.
+
+<p>For example,
+
+<ul><pre>
+class A {}
+class B extends A {}
+class C extends C {}
+
+class X {
+ void foo(A a) { .. }
+ void foo(B b) { .. }
+}
+</pre></ul>
+
+<p>If the compiled expression is <code>x.foo(new C())</code>, where
+<code>x</code> is an instance of X, the compiler may produce a call
+to <code>foo(A)</code> although the compiler can correctly compile
+<code>foo((B)new C())</code>.
+
+<p><li>The users are recommended to use <code>#</code> as the separator
+between a class name and a static method or field name.
+For example, in regular Java,
+
+<ul><pre>javassist.CtClass.intType.getName()</pre></ul>
+
+<p>calls a method <code>getName()</code> on
+the object indicated by the static field <code>intType</code>
+in <code>javassist.CtClass</code>. In Javassist, the users can
+write the expression shown above but they are recommended to
+write:
+
+<ul><pre>javassist.CtClass#intType.getName()</pre></ul>
+
+<p>so that the compiler can quickly parse the expression.
+</ul>
+
+<p><br>
+
+<a href="tutorial.html">Previous page</a>
+ <a href="tutorial3.html">Next page</a>
+
+<hr>
+Java(TM) is a trademark of Sun Microsystems, Inc.<br>
+Copyright (C) 2000-2004 by Shigeru Chiba, All rights reserved.
+</body>
+</html>
projects / javassist.git / commitdiff