1 <html> 2 <head> 3 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> 4 <title>Javassist Tutorial</title> 5 <link rel="stylesheet" type="text/css" href="brown.css"> 6 </head> 7 8 <body> 9 10 <div align="right">Getting Started with Javassist</div> 11 12 <div align="left"><a href="tutorial.html">Previous page</a></div> 13 <div align="right"><a href="tutorial3.html">Next page</a></div> 14 15 <p> 16 <a href="#intro">4. Introspection and customization</a> 17 <ul> 18 <li><a href="#before">Inserting source text at the beginning/end of a method body</a> 19 <br><li><a href="#alter">Altering a method body</a> 20 <br><li><a href="#add">Adding a new method or field</a> 21 <br><li><a href="#runtime">Runtime support classes</a> 22 <br><li><a href="#annotation">Annotations</a> 23 <br><li><a href="#import">Import</a> 24 <br><li><a href="#limit">Limitations</a> 25 </ul> 26 27 <p><br> 28 29 <a name="intro"> 30 <h2>4. Introspection and customization</h2> 31 32 <p><code>CtClass</code> provides methods for introspection. The 33 introspective ability of Javassist is compatible with that of 34 the Java reflection API. <code>CtClass</code> provides 35 <code>getName()</code>, <code>getSuperclass()</code>, 36 <code>getMethods()</code>, and so on. 37 <code>CtClass</code> also provides methods for modifying a class 38 definition. It allows to add a new field, constructor, and method. 39 Instrumenting a method body is also possible. 40 41 <p> 42 Methods are represented by <code>CtMethod</code> objects. 43 <code>CtMethod</code> provides several methods for modifying 44 the definition of the method. Note that if a method is inherited 45 from a super class, then 46 the same <code>CtMethod</code> object 47 that represents the inherited method represents the method declared 48 in that super class. 49 A <code>CtMethod</code> object corresponds to every method declaration. 50 51 <p> 52 For example, if class <code>Point</code> declares method <code>move()</code> 53 and a subclass <code>ColorPoint</code> of <code>Point</code> does 54 not override <code>move()</code>, the two <code>move()</code> methods 55 declared in <code>Point</code> and inherited in <code>ColorPoint</code> 56 are represented by the identical <code>CtMethod</code> object. 57 If the method definition represented by this 58 <code>CtMethod</code> object is modified, the modification is 59 reflected on both the methods. 60 If you want to modify only the <code>move()</code> method in 61 <code>ColorPoint</code>, you first have to add to <code>ColorPoint</code> 62 a copy of the <code>CtMethod</code> object representing <code>move()</code> 63 in <code>Point</code>. A copy of the the <code>CtMethod</code> object 64 can be obtained by <code>CtNewMethod.copy()</code>. 65 66 67 <p><hr width="40%"> 68 69 <ul> 70 Javassist does not allow to remove a method or field, but it allows 71 to change the name. So if a method is not necessary any more, it should be 72 renamed and changed to be a private method by calling 73 <code>setName()</code> 74 and <code>setModifiers()</code> declared in <code>CtMethod</code>. 75 76 <p>Javassist does not allow to add an extra parameter to an existing 77 method, either. Instead of doing that, a new method receiving the 78 extra parameter as well as the other parameters should be added to the 79 same class. For example, if you want to add an extra <code>int</code> 80 parameter <code>newZ</code> to a method: 81 82 <ul><pre>void move(int newX, int newY) { x = newX; y = newY; }</pre></ul> 83 84 <p>in a <code>Point</code> class, then you should add the following 85 method to the <code>Point</code> class: 86 87 <ul><pre>void move(int newX, int newY, int newZ) { 88 // do what you want with newZ. 89 move(newX, newY); 90 }</pre></ul> 91 92 </ul> 93 94 <p><hr width="40%"> 95 96 <p>Javassist also provides low-level API for directly editing a raw 97 class file. For example, <code>getClassFile()</code> in 98 <code>CtClass</code> returns a <code>ClassFile</code> object 99 representing a raw class file. <code>getMethodInfo()</code> in 100 <code>CtMethod</code> returns a <code>MethodInfo</code> object 101 representing a <code>method_info</code> structure included in a class 102 file. The low-level API uses the vocabulary from the Java Virtual 103 machine specification. The users must have the knowledge about class 104 files and bytecode. For more details, the users should see the 105 <a href="tutorial3.html#intro"><code>javassist.bytecode</code> package</a>. 106 107 <p>The class files modified by Javassist requires the 108 <code>javassist.runtime</code> package for runtime support 109 only if some special identifiers starting with <code>$</code> 110 are used. Those special identifiers are described below. 111 The class files modified without those special identifiers 112 do not need the <code>javassist.runtime</code> package or any 113 other Javassist packages at runtime. 114 For more details, see the API documentation 115 of the <code>javassist.runtime</code> package. 116 117 <p><br> 118 119 <a name="before"> 120 <h3>4.1 Inserting source text at the beginning/end of a method body</h3> 121 122 <p><code>CtMethod</code> and <code>CtConstructor</code> provide 123 methods <code>insertBefore()</code>, <code>insertAfter()</code>, and 124 <code>addCatch()</code>. They are used for inserting a code fragment 125 into the body of an existing method. The users can specify those code 126 fragments with <em>source text</em> written in Java. 127 Javassist includes a simple Java compiler for processing source 128 text. It receives source text 129 written in Java and compiles it into Java bytecode, which will be 130 <em>inlined</em> into a method body. 131 132 <p> 133 Inserting a code fragment at the position specified by a line number 134 is also possible 135 (if the line number table is contained in the class file). 136 <code>insertAt()</code> in <code>CtMethod</code> and 137 <code>CtConstructor</code> takes source text and a line number in the source 138 file of the original class definition. 139 It compiles the source text and inserts the compiled code at the line number. 140 141 <p>The methods <code>insertBefore()</code>, <code>insertAfter()</code>, 142 <code>addCatch()</code>, and <code>insertAt()</code> 143 receive a <code>String</code> object representing 144 a statement or a block. A statement is a single control structure like 145 <code>if</code> and <code>while</code> or an expression ending with 146 a semi colon (<code>;</code>). A block is a set of 147 statements surrounded with braces <code>{}</code>. 148 Hence each of the following lines is an example of valid statement or block: 149 150 <ul><pre>System.out.println("Hello"); 151 { System.out.println("Hello"); } 152 if (i < 0) { i = -i; } 153 </pre></ul> 154 155 <p>The statement and the block can refer to fields and methods. 156 They can also refer to the parameters 157 to the method that they are inserted into 158 if that method was compiled with the -g option 159 (to include a local variable attribute in the class file). 160 Otherwise, they must access the method parameters through the special 161 variables <code>$0</code>, <code>$1</code>, <code>$2</code>, ... described 162 below. 163 <em>Accessing local variables declared in the method is not allowed</em> 164 although declaring a new local variable in the block is allowed. 165 However, <code>insertAt()</code> allows the statement and the block 166 to access local variables 167 if these variables are available at the specified line number 168 and the target method was compiled with the -g option. 169 170 171 <!-- 172 <p><center><table border=8 cellspacing=0 bordercolor="#cfcfcf"> 173 <tr><td bgcolor="#cfcfcf"> 174 <b>Tip:</b> 175 <br>    Local variables are not accessible.   176 </td></tr> 177 </table></center> 178 --> 179 180 <p>The <code>String</code> object passed to the methods 181 <code>insertBefore()</code>, <code>insertAfter()</code>, 182 <code>addCatch()</code>, and <code>insertAt()</code> are compiled by 183 the compiler included in Javassist. 184 Since the compiler supports language extensions, 185 several identifiers starting with <code>$</code> 186 have special meaning: 187 188 <ul><table border=0> 189 <tr> 190 <td><code>$0</code>, <code>$1</code>, <code>$2</code>, ...    </td> 191 <td><code>this</code> and actual parameters</td> 192 </tr> 193 194 <tr> 195 <td><code>$args</code></td> 196 <td>An array of parameters. 197 The type of <code>$args</code> is <code>Object[]</code>. 198 </td> 199 </tr> 200 201 <tr> 202 <td><code>$$</code></td> 203 <td rowspan=2>All actual parameters.<br> 204 For example, <code>m($$)</code> is equivalent to 205 <code>m($1,$2,</code>...<code>)</code></td> 206 </tr> 207 208 <tr><td> </td></tr> 209 210 <tr> 211 <td><code>$cflow(</code>...<code>)</code></td> 212 <td><code>cflow</code> variable</td> 213 </tr> 214 215 <tr> 216 <td><code>$r</code></td> 217 <td>The result type. It is used in a cast expression.</td> 218 </tr> 219 220 <tr> 221 <td><code>$w</code></td> 222 <td>The wrapper type. It is used in a cast expression.</td> 223 </tr> 224 225 <tr> 226 <td><code>$_</code></td> 227 <td>The resulting value</td> 228 </tr> 229 230 <tr> 231 <td><code>$sig</code></td> 232 <td>An array of <code>java.lang.Class</code> objects representing 233 the formal parameter types. 234 </td> 235 </tr> 236 237 <tr> 238 <td><code>$type</code></td> 239 <td>A <code>java.lang.Class</code> object representing 240 the formal result type.</td> 241 </tr> 242 243 <tr> 244 <td><code>$class</code></td> 245 <td>A <code>java.lang.Class</code> object representing 246 the class currently edited.</td> 247 </tr> 248 249 </table> 250 </ul> 251 252 <h4>$0, $1, $2, ...</h4> 253 254 <p>The parameters passed to the target method 255 are accessible with 256 <code>$1</code>, <code>$2</code>, ... instead of 257 the original parameter names. 258 <code>$1</code> represents the 259 first parameter, <code>$2</code> represents the second parameter, and 260 so on. The types of those variables are identical to the parameter 261 types. 262 <code>$0</code> is 263 equivalent to <code>this</code>. If the method is static, 264 <code>$0</code> is not available. 265 266 <p>These variables are used as following. Suppose that a class 267 <code>Point</code>: 268 269 <pre><ul>class Point { 270 int x, y; 271 void move(int dx, int dy) { x += dx; y += dy; } 272 } 273 </ul></pre> 274 275 <p>To print the values of <code>dx</code> and <code>dy</code> 276 whenever the method <code>move()</code> is called, execute this 277 program: 278 279 <ul><pre>ClassPool pool = ClassPool.getDefault(); 280 CtClass cc = pool.get("Point"); 281 CtMethod m = cc.getDeclaredMethod("move"); 282 m.insertBefore("{ System.out.println($1); System.out.println($2); }"); 283 cc.writeFile(); 284 </pre></ul> 285 286 <p>Note that the source text passed to <code>insertBefore()</code> is 287 surrounded with braces <code>{}</code>. 288 <code>insertBefore()</code> accepts only a single statement or a block 289 surrounded with braces. 290 291 <p>The definition of the class <code>Point</code> after the 292 modification is like this: 293 294 <pre><ul>class Point { 295 int x, y; 296 void move(int dx, int dy) { 297 { System.out.println(dx); System.out.println(dy); } 298 x += dx; y += dy; 299 } 300 } 301 </ul></pre> 302 303 <p><code>$1</code> and <code>$2</code> are replaced with 304 <code>dx</code> and <code>dy</code>, respectively. 305 306 <p><code>$1</code>, <code>$2</code>, <code>$3</code> ... are 307 updatable. If a new value is assigend to one of those variables, 308 then the value of the parameter represented by that variable is 309 also updated. 310 311 312 <h4>$args</h4> 313 314 <p>The variable <code>$args</code> represents an array of all the 315 parameters. The type of that variable is an array of class 316 <code>Object</code>. If a parameter type is a primitive type such as 317 <code>int</code>, then the parameter value is converted into a wrapper 318 object such as <code>java.lang.Integer</code> to store in 319 <code>$args</code>. Thus, <code>$args[0]</code> is equivalent to 320 <code>$1</code> unless the type of the first parameter is a primitive 321 type. Note that <code>$args[0]</code> is not equivalent to 322 <code>$0</code>; <code>$0</code> represents <code>this</code>. 323 324 <p>If an array of <code>Object</code> is assigned to 325 <code>$args</code>, then each element of that array is 326 assigned to each parameter. If a parameter type is a primitive 327 type, the type of the corresponding element must be a wrapper type. 328 The value is converted from the wrapper type to the primitive type 329 before it is assigned to the parameter. 330 331 <h4>$$</h4> 332 333 <p>The variable <code>$$</code> is abbreviation of a list of 334 all the parameters separated by commas. 335 For example, if the number of the parameters 336 to method <code>move()</code> is three, then 337 338 <ul><pre>move($$)</pre></ul> 339 340 <p>is equivalent to this: 341 342 <ul><pre>move($1, $2, $3)</pre></ul> 343 344 <p>If <code>move()</code> does not take any parameters, 345 then <code>move($$)</code> is 346 equivalent to <code>move()</code>. 347 348 <p><code>$$</code> can be used with another method. 349 If you write an expression: 350 351 <ul><pre>exMove($$, context)</pre></ul> 352 353 <p>then this expression is equivalent to: 354 355 <ul><pre>exMove($1, $2, $3, context)</pre></ul> 356 357 <p>Note that <code>$$</code> enables generic notation of method call 358 with respect to the number of parameters. 359 It is typically used with <code>$proceed</code> shown later. 360 361 <h4>$cflow</h4> 362 363 <p><code>$cflow</code> means "control flow". 364 This read-only variable returns the depth of the recursive calls 365 to a specific method. 366 367 <p>Suppose that the method shown below is represented by a 368 <code>CtMethod</code> object <code>cm</code>: 369 370 <ul><pre>int fact(int n) { 371 if (n <= 1) 372 return n; 373 else 374 return n * fact(n - 1); 375 }</pre></ul> 376 377 <p>To use <code>$cflow</code>, first declare that <code>$cflow</code> 378 is used for monitoring calls to the method <code>fact()</code>: 379 380 <ul><pre>CtMethod cm = ...; 381 cm.useCflow("fact");</pre></ul> 382 383 <p>The parameter to <code>useCflow()</code> is the identifier of the 384 declared <code>$cflow</code> variable. Any valid Java name can be 385 used as the identifier. Since the identifier can also include 386 <code>.</code> (dot), for example, <code>"my.Test.fact"</code> 387 is a valid identifier. 388 389 <p>Then, <code>$cflow(fact)</code> represents the depth of the 390 recursive calls to the method specified by <code>cm</code>. The value 391 of <code>$cflow(fact)</code> is 0 (zero) when the method is 392 first called whereas it is 1 when the method is recursively called 393 within the method. For example, 394 395 <ul><pre> 396 cm.insertBefore("if ($cflow(fact) == 0)" 397 + " System.out.println(\"fact \" + $1);"); 398 </pre></ul> 399 400 <p>translates the method <code>fact()</code> so that it shows the 401 parameter. Since the value of <code>$cflow(fact)</code> is checked, 402 the method <code>fact()</code> does not show the parameter if it is 403 recursively called within <code>fact()</code>. 404 405 <p>The value of <code>$cflow</code> is the number of stack frames 406 associated with the specified method <code>cm</code> 407 under the current topmost 408 stack frame for the current thread. <code>$cflow</code> is also 409 accessible within a method different from the specified method 410 <code>cm</code>. 411 412 <h4>$r</h4> 413 414 <p><code>$r</code> represents the result type (return type) of the method. 415 It must be used as the cast type in a cast expression. 416 For example, this is a typical use: 417 418 <ul><pre>Object result = ... ; 419 $_ = ($r)result;</pre></ul> 420 421 <p>If the result type is a primitive type, then <code>($r)</code> 422 follows special semantics. First, if the operand type of the cast 423 expression is a primitive type, <code>($r)</code> works as a normal 424 cast operator to the result type. 425 On the other hand, if the operand type is a wrapper type, 426 <code>($r)</code> converts from the wrapper type to the result type. 427 For example, if the result type is <code>int</code>, then 428 <code>($r)</code> converts from <code>java.lang.Integer</code> to 429 <code>int</code>. 430 431 <p>If the result type is <code>void</code>, then 432 <code>($r)</code> does not convert a type; it does nothing. 433 However, if the operand is a call to a <code>void</code> method, 434 then <code>($r)</code> results in <code>null</code>. For example, 435 if the result type is <code>void</code> and 436 <code>foo()</code> is a <code>void</code> method, then 437 438 <ul><pre>$_ = ($r)foo();</pre></ul> 439 440 <p>is a valid statement. 441 442 <p>The cast operator <code>($r)</code> is also useful in a 443 <code>return</code> statement. Even if the result type is 444 <code>void</code>, the following <code>return</code> statement is valid: 445 446 <ul><pre>return ($r)result;</pre></ul> 447 448 <p>Here, <code>result</code> is some local variable. 449 Since <code>($r)</code> is specified, the resulting value is 450 discarded. 451 This <code>return</code> statement is regarded as the equivalent 452 of the <code>return</code> statement without a resulting value: 453 454 <ul><pre>return;</pre></ul> 455 456 <h4>$w</h4> 457 458 <p><code>$w</code> represents a wrapper type. 459 It must be used as the cast type in a cast expression. 460 <code>($w)</code> converts from a primitive type to the corresponding 461 wrapper type. 462 463 The following code is an example: 464 465 <ul><pre>Integer i = ($w)5;</pre></ul> 466 467 <p>The selected wrapper type depends on the type of the expression 468 following <code>($w)</code>. If the type of the expression is 469 <code>double</code>, then the wrapper type is <code>java.lang.Double</code>. 470 471 <p>If the type of the expression following <code>($w)</code> is not 472 a primitive type, then <code>($w)</code> does nothing. 473 474 <h4>$_</h4> 475 476 <p><code>insertAfter()</code> in <code>CtMethod</code> and 477 <code>CtConstructor</code> inserts the 478 compiled code at the end of the method. In the statement given to 479 <code>insertAfter()</code>, not only the variables shown above such as 480 <code>$0</code>, <code>$1</code>, ... but also <code>$_</code> is 481 available. 482 483 <p>The variable <code>$_</code> represents the resulting value of the 484 method. The type of that variable is the type of the result type (the 485 return type) of the method. If the result type is <code>void</code>, 486 then the type of <code>$_</code> is <code>Object</code> and the value 487 of <code>$_</code> is <code>null</code>. 488 489 <p>Although the compiled code inserted by <code>insertAfter()</code> 490 is executed just before the control normally returns from the method, 491 it can be also executed when an exception is thrown from the method. 492 To execute it when an exception is thrown, the second parameter 493 <code>asFinally</code> to <code>insertAfter()</code> must be 494 <code>true</code>. 495 496 <p>If an exception is thrown, the compiled code inserted by 497 <code>insertAfter()</code> is executed as a <code>finally</code> 498 clause. The value of <code>$_</code> is <code>0</code> or 499 <code>null</code> in the compiled code. After the execution of the 500 compiled code terminates, the exception originally thrown is re-thrown 501 to the caller. Note that the value of <code>$_</code> is never thrown 502 to the caller; it is rather discarded. 503 504 <h4>$sig</h4> 505 506 <p>The value of <code>$sig</code> is an array of 507 <code>java.lang.Class</code> objects that represent the formal 508 parameter types in declaration order. 509 510 <h4>$type</h4> 511 512 <p>The value of <code>$type</code> is an <code>java.lang.Class</code> 513 object representing the formal type of the result value. This 514 variable refers to <code>Void.class</code> if this is a constructor. 515 516 <h4>$class</h4> 517 518 <p>The value of <code>$class</code> is an <code>java.lang.Class</code> 519 object representing the class in which the edited method is declared. 520 This represents the type of <code>$0</code>. 521 522 <h4>addCatch()</h4> 523 524 <p><code>addCatch()</code> inserts a code fragment into a method body 525 so that the code fragment is executed when the method body throws 526 an exception and the control returns to the caller. In the source 527 text representing the inserted code fragment, the exception value 528 is referred to with the special variable <code>$e</code>. 529 530 <p>For example, this program: 531 532 <ul><pre> 533 CtMethod m = ...; 534 CtClass etype = ClassPool.getDefault().get("java.io.IOException"); 535 m.addCatch("{ System.out.println($e); throw $e; }", etype); 536 </pre></ul> 537 538 <p>translates the method body represented by <code>m</code> into 539 something like this: 540 541 <ul><pre> 542 try { 543 <font face="serif"><em>the original method body</em></font> 544 } 545 catch (java.io.IOException e) { 546 System.out.println(e); 547 throw e; 548 } 549 </pre></ul> 550 551 <p>Note that the inserted code fragment must end with a 552 <code>throw</code> or <code>return</code> statement. 553 554 <p><br> 555 556 <a name="alter"> 557 <h3>4.2 Altering a method body</h3> 558 559 <p><code>CtMethod</code> and <code>CtConstructor</code> provide 560 <code>setBody()</code> for substituting a whole 561 method body. They compile the given source text into Java bytecode 562 and substitutes it for the original method body. If the given source 563 text is <code>null</code>, the substituted body includes only a 564 <code>return</code> statement, which returns zero or null unless the 565 result type is <code>void</code>. 566 567 <p>In the source text given to <code>setBody()</code>, the identifiers 568 starting with <code>$</code> have special meaning 569 570 <ul><table border=0> 571 <tr> 572 <td><code>$0</code>, <code>$1</code>, <code>$2</code>, ...    </td> 573 <td><code>this</code> and actual parameters</td> 574 </tr> 575 576 <tr> 577 <td><code>$args</code></td> 578 <td>An array of parameters. 579 The type of <code>$args</code> is <code>Object[]</code>. 580 </td> 581 </tr> 582 583 <tr> 584 <td><code>$$</code></td> 585 <td>All actual parameters.<br> 586 </tr> 587 588 <tr> 589 <td><code>$cflow(</code>...<code>)</code></td> 590 <td><code>cflow</code> variable</td> 591 </tr> 592 593 <tr> 594 <td><code>$r</code></td> 595 <td>The result type. It is used in a cast expression.</td> 596 </tr> 597 598 <tr> 599 <td><code>$w</code></td> 600 <td>The wrapper type. It is used in a cast expression.</td> 601 </tr> 602 603 <tr> 604 <td><code>$sig</code></td> 605 <td>An array of <code>java.lang.Class</code> objects representing 606 the formal parameter types. 607 </td> 608 </tr> 609 610 <tr> 611 <td><code>$type</code></td> 612 <td>A <code>java.lang.Class</code> object representing 613 the formal result type.</td> 614 </tr> 615 616 <tr> 617 <td><code>$class</code></td> 618 <td rowspan=2>A <code>java.lang.Class</code> object representing 619 the class that declares the method<br> 620 currently edited (the type of $0).</td> 621 </tr> 622 623 <tr><td> </td></tr> 624 625 </table> 626 </ul> 627 628 Note that <code>$_</code> is not available. 629 630 <h4>Substituting source text for an existing expression</h4> 631 632 <p>Javassist allows modifying only an expression included in a method body. 633 <code>javassist.expr.ExprEditor</code> is a class 634 for replacing an expression in a method body. 635 The users can define a subclass of <code>ExprEditor</code> 636 to specify how an expression is modified. 637 638 <p>To run an <code>ExprEditor</code> object, the users must 639 call <code>instrument()</code> in <code>CtMethod</code> or 640 <code>CtClass</code>. 641 642 For example, 643 644 <ul><pre> 645 CtMethod cm = ... ; 646 cm.instrument( 647 new ExprEditor() { 648 public void edit(MethodCall m) 649 throws CannotCompileException 650 { 651 if (m.getClassName().equals("Point") 652 && m.getMethodName().equals("move")) 653 m.replace("{ $1 = 0; $_ = $proceed($$); }"); 654 } 655 }); 656 </pre></ul> 657 658 <p>searches the method body represented by <code>cm</code> and 659 replaces all calls to <code>move()</code> in class <code>Point</code> 660 with a block: 661 662 <ul><pre>{ $1 = 0; $_ = $proceed($$); } 663 </pre></ul> 664 665 <p>so that the first parameter to <code>move()</code> is always 0. 666 Note that the substituted code is not an expression but 667 a statement or a block. It cannot be or contain a try-catch statement. 668 669 <p>The method <code>instrument()</code> searches a method body. 670 If it finds an expression such as a method call, field access, and object 671 creation, then it calls <code>edit()</code> on the given 672 <code>ExprEditor</code> object. The parameter to <code>edit()</code> 673 is an object representing the found expression. The <code>edit()</code> 674 method can inspect and replace the expression through that object. 675 676 <p>Calling <code>replace()</code> on the parameter to <code>edit()</code> 677 substitutes the given statement or block for the expression. If the given 678 block is an empty block, that is, if <code>replace("{}")</code> 679 is executed, then the expression is removed from the method body. 680 681 If you want to insert a statement (or a block) before/after the 682 expression, a block like the following should be passed to 683 <code>replace()</code>: 684 685 <ul><pre> 686 { <em>before-statements;</em> 687 $_ = $proceed($$); 688 <em>after-statements;</em> } 689 </pre></ul> 690 691 <p>whichever the expression is either a method call, field access, 692 object creation, or others. The second statement could be: 693 694 <ul><pre>$_ = $proceed();</pre></ul> 695 696 <p>if the expression is read access, or 697 698 <ul><pre>$proceed($$);</pre></ul> 699 700 <p>if the expression is write access. 701 702 <p>Local variables available in the target expression is 703 also available in the source text passed to <code>replace()</code> 704 if the method searched by <code>instrument()</code> was compiled 705 with the -g option (the class file includes a local variable 706 attribute). 707 708 <h4>javassist.expr.MethodCall</h4> 709 710 <p>A <code>MethodCall</code> object represents a method call. 711 The method <code>replace()</code> in 712 <code>MethodCall</code> substitutes a statement or 713 a block for the method call. 714 It receives source text representing the substitued statement or 715 block, in which the identifiers starting with <code>$</code> 716 have special meaning as in the source text passed to 717 <code>insertBefore()</code>. 718 719 <ul><table border=0> 720 <tr> 721 <td><code>$0</code></td> 722 <td rowspan=3> 723 The target object of the method call.<br> 724 This is not equivalent to <code>this</code>, which represents 725 the caller-side <code>this</code> object.<br> 726 <code>$0</code> is <code>null</code> if the method is static. 727 </td> 728 </tr> 729 730 <tr><td> </td></tr> 731 732 <tr><td> </td></tr> 733 734 <tr> 735 <td><code>$1</code>, <code>$2</code>, ...    </td> 736 <td> 737 The parameters of the method call. 738 </td> 739 </tr> 740 741 <tr><td> 742 <code>$_</code></td> 743 <td>The resulting value of the method call.</td> 744 </tr> 745 746 <tr><td><code>$r</code></td> 747 <td>The result type of the method call.</td> 748 </tr> 749 750 <tr><td><code>$class</code>    </td> 751 <td>A <code>java.lang.Class</code> object representing 752 the class declaring the method. 753 </td> 754 </tr> 755 756 <tr><td><code>$sig</code>    </td> 757 <td>An array of <code>java.lang.Class</code> objects representing 758 the formal parameter types.</td> 759 </tr> 760 761 <tr><td><code>$type</code>    </td> 762 <td>A <code>java.lang.Class</code> object representing 763 the formal result type.</td> 764 </tr> 765 766 <tr><td><code>$proceed</code>    </td> 767 <td>The name of the method originally called 768 in the expression.</td> 769 </tr> 770 771 </table> 772 </ul> 773 774 <p>Here the method call means the one represented by the 775 <code>MethodCall</code> object. 776 777 <p>The other identifiers such as <code>$w</code>, 778 <code>$args</code> and <code>$$</code> 779 are also available. 780 781 <p>Unless the result type of the method call is <code>void</code>, 782 a value must be assigned to 783 <code>$_</code> in the source text and the type of <code>$_</code> 784 is the result type. 785 If the result type is <code>void</code>, the type of <code>$_</code> 786 is <code>Object</code> and the value assigned to <code>$_</code> 787 is ignored. 788 789 <p><code>$proceed</code> is not a <code>String</code> value but special 790 syntax. It must be followed by an argument list surrounded by parentheses 791 <code>( )</code>. 792 793 <h4>javassist.expr.ConstructorCall</h4> 794 795 <p>A <code>ConstructorCall</code> object represents a constructor call 796 such as <code>this()</code> and <code>super</code> included in a constructor 797 body. 798 The method <code>replace()</code> in 799 <code>ConstructorCall</code> substitutes a statement or 800 a block for the constructor call. 801 It receives source text representing the substituted statement or 802 block, in which the identifiers starting with <code>$</code> 803 have special meaning as in the source text passed to 804 <code>insertBefore()</code>. 805 806 <ul><table border=0> 807 <tr> 808 <td><code>$0</code></td> 809 <td> 810 The target object of the constructor call. 811 This is equivalent to <code>this</code>. 812 </td> 813 </tr> 814 815 <tr> 816 <td><code>$1</code>, <code>$2</code>, ...    </td> 817 <td> 818 The parameters of the constructor call. 819 </td> 820 </tr> 821 822 <tr><td><code>$class</code>    </td> 823 <td>A <code>java.lang.Class</code> object representing 824 the class declaring the constructor. 825 </td> 826 </tr> 827 828 <tr><td><code>$sig</code>    </td> 829 <td>An array of <code>java.lang.Class</code> objects representing 830 the formal parameter types.</td> 831 </tr> 832 833 <tr><td><code>$proceed</code>    </td> 834 <td>The name of the constructor originally called 835 in the expression.</td> 836 </tr> 837 838 </table> 839 </ul> 840 841 <p>Here the constructor call means the one represented by the 842 <code>ConstructorCall</code> object. 843 844 <p>The other identifiers such as <code>$w</code>, 845 <code>$args</code> and <code>$$</code> 846 are also available. 847 848 <p>Since any constructor must call either a constructor of the super 849 class or another constructor of the same class, 850 the substituted statement must include a constructor call, 851 normally a call to <code>$proceed()</code>. 852 853 <p><code>$proceed</code> is not a <code>String</code> value but special 854 syntax. It must be followed by an argument list surrounded by parentheses 855 <code>( )</code>. 856 857 <h4>javassist.expr.FieldAccess</h4> 858 859 <p>A <code>FieldAccess</code> object represents field access. 860 The method <code>edit()</code> in <code>ExprEditor</code> 861 receives this object if field access is found. 862 The method <code>replace()</code> in 863 <code>FieldAccess</code> receives 864 source text representing the substitued statement or 865 block for the field access. 866 867 <p> 868 In the source text, the identifiers starting with <code>$</code> 869 have special meaning: 870 871 <ul><table border=0> 872 <tr> 873 <td><code>$0</code></td> 874 <td rowspan=3> 875 The object containing the field accessed by the expression. 876 This is not equivalent to <code>this</code>.<br> 877 <code>this</code> represents the object that the method including the 878 expression is invoked on.<br> 879 <code>$0</code> is <code>null</code> if the field is static. 880 </td> 881 </tr> 882 883 <tr><td> </td></tr> 884 885 <tr><td> </td></tr> 886 887 <tr> 888 <td><code>$1</code></td> 889 <td rowspan=2> 890 The value that would be stored in the field 891 if the expression is write access. 892 <br>Otherwise, <code>$1</code> is not available. 893 </td> 894 </tr> 895 896 <tr><td> </td></tr> 897 898 <tr> 899 <td><code>$_</code></td> 900 <td rowspan=2> 901 The resulting value of the field access 902 if the expression is read access. 903 <br>Otherwise, the value stored in <code>$_</code> is discarded. 904 </td> 905 </tr> 906 907 <tr><td> </td></tr> 908 <tr> 909 <td><code>$r</code></td> 910 <td rowspan=2> 911 The type of the field if the expression is read access. 912 <br>Otherwise, <code>$r</code> is <code>void</code>. 913 </td> 914 </tr> 915 916 <tr><td> </td></tr> 917 918 <tr><td><code>$class</code>    </td> 919 <td>A <code>java.lang.Class</code> object representing 920 the class declaring the field. 921 </td></tr> 922 923 <tr><td><code>$type</code></td> 924 <td>A <code>java.lang.Class</code> object representing 925 the field type.</td> 926 </tr> 927 928 <tr><td><code>$proceed</code>    </td> 929 <td>The name of a virtual method executing the original 930 field access. 931 .</td> 932 </tr> 933 934 </table> 935 </ul> 936 937 <p>The other identifiers such as <code>$w</code>, 938 <code>$args</code> and <code>$$</code> 939 are also available. 940 941 <p>If the expression is read access, a value must be assigned to 942 <code>$_</code> in the source text. The type of <code>$_</code> 943 is the type of the field. 944 945 <h4>javassist.expr.NewExpr</h4> 946 947 <p>A <code>NewExpr</code> object represents object creation 948 with the <code>new</code> operator (not including array creation). 949 The method <code>edit()</code> in <code>ExprEditor</code> 950 receives this object if object creation is found. 951 The method <code>replace()</code> in 952 <code>NewExpr</code> receives 953 source text representing the substitued statement or 954 block for the object creation. 955 956 <p> 957 In the source text, the identifiers starting with <code>$</code> 958 have special meaning: 959 960 <ul><table border=0> 961 962 <tr> 963 <td><code>$0</code></td> 964 <td> 965 <code>null</code>. 966 </td> 967 </tr> 968 969 <tr> 970 <td><code>$1</code>, <code>$2</code>, ...    </td> 971 <td> 972 The parameters to the constructor. 973 </td> 974 </tr> 975 976 <tr> 977 <td><code>$_</code></td> 978 <td rowspan=2> 979 The resulting value of the object creation. 980 <br>A newly created object must be stored in this variable. 981 </td> 982 </tr> 983 984 <tr><td> </td></tr> 985 986 <tr> 987 <td><code>$r</code></td> 988 <td> 989 The type of the created object. 990 </td> 991 </tr> 992 993 <tr><td><code>$sig</code>    </td> 994 <td>An array of <code>java.lang.Class</code> objects representing 995 the formal parameter types.</td> 996 </tr> 997 998 <tr><td><code>$type</code>    </td> 999 <td>A <code>java.lang.Class</code> object representing 1000 the class of the created object. 1001 </td></tr> 1002 1003 <tr><td><code>$proceed</code>    </td> 1004 <td>The name of a virtual method executing the original 1005 object creation. 1006 .</td> 1007 </tr> 1008 1009 </table> 1010 </ul> 1011 1012 <p>The other identifiers such as <code>$w</code>, 1013 <code>$args</code> and <code>$$</code> 1014 are also available. 1015 1016 <h4>javassist.expr.NewArray</h4> 1017 1018 <p>A <code>NewArray</code> object represents array creation 1019 with the <code>new</code> operator. 1020 The method <code>edit()</code> in <code>ExprEditor</code> 1021 receives this object if array creation is found. 1022 The method <code>replace()</code> in 1023 <code>NewArray</code> receives 1024 source text representing the substitued statement or 1025 block for the array creation. 1026 1027 <p> 1028 In the source text, the identifiers starting with <code>$</code> 1029 have special meaning: 1030 1031 <ul><table border=0> 1032 1033 <tr> 1034 <td><code>$0</code></td> 1035 <td> 1036 <code>null</code>. 1037 </td> 1038 </tr> 1039 1040 <tr> 1041 <td><code>$1</code>, <code>$2</code>, ...    </td> 1042 <td> 1043 The size of each dimension. 1044 </td> 1045 </tr> 1046 1047 <tr> 1048 <td><code>$_</code></td> 1049 <td rowspan=2> 1050 The resulting value of the array creation. 1051 <br>A newly created array must be stored in this variable. 1052 </td> 1053 </tr> 1054 1055 <tr><td> </td></tr> 1056 1057 <tr> 1058 <td><code>$r</code></td> 1059 <td> 1060 The type of the created array. 1061 </td> 1062 </tr> 1063 1064 <tr><td><code>$type</code>    </td> 1065 <td>A <code>java.lang.Class</code> object representing 1066 the class of the created array. 1067 </td></tr> 1068 1069 <tr><td><code>$proceed</code>    </td> 1070 <td>The name of a virtual method executing the original 1071 array creation. 1072 .</td> 1073 </tr> 1074 1075 </table> 1076 </ul> 1077 1078 <p>The other identifiers such as <code>$w</code>, 1079 <code>$args</code> and <code>$$</code> 1080 are also available. 1081 1082 <p>For example, if the array creation is the following expression, 1083 1084 <ul><pre> 1085 String[][] s = new String[3][4]; 1086 </pre></ul> 1087 1088 then the value of $1 and $2 are 3 and 4, respectively. $3 is not available. 1089 1090 <p>If the array creation is the following expression, 1091 1092 <ul><pre> 1093 String[][] s = new String[3][]; 1094 </pre></ul> 1095 1096 then the value of $1 is 3 but $2 is not available. 1097 1098 <h4>javassist.expr.Instanceof</h4> 1099 1100 <p>A <code>Instanceof</code> object represents an <code>instanceof</code> 1101 expression. 1102 The method <code>edit()</code> in <code>ExprEditor</code> 1103 receives this object if an instanceof expression is found. 1104 The method <code>replace()</code> in 1105 <code>Instanceof</code> receives 1106 source text representing the substitued statement or 1107 block for the expression. 1108 1109 <p> 1110 In the source text, the identifiers starting with <code>$</code> 1111 have special meaning: 1112 1113 <ul><table border=0> 1114 1115 <tr> 1116 <td><code>$0</code></td> 1117 <td> 1118 <code>null</code>. 1119 </td> 1120 </tr> 1121 1122 <tr> 1123 <td><code>$1</code></td> 1124 <td> 1125 The value on the left hand side of the original 1126 <code>instanceof</code> operator. 1127 </td> 1128 </tr> 1129 1130 <tr> 1131 <td><code>$_</code></td> 1132 <td> 1133 The resulting value of the expression. 1134 The type of <code>$_</code> is <code>boolean</code>. 1135 </td> 1136 </tr> 1137 1138 <tr> 1139 <td><code>$r</code></td> 1140 <td> 1141 The type on the right hand side of the <code>instanceof</code> operator. 1142 </td> 1143 </tr> 1144 1145 <tr><td><code>$type</code></td> 1146 <td>A <code>java.lang.Class</code> object representing 1147 the type on the right hand side of the <code>instanceof</code> operator. 1148 </td> 1149 </tr> 1150 1151 <tr><td><code>$proceed</code>    </td> 1152 <td rowspan=4>The name of a virtual method executing the original 1153 <code>instanceof</code> expression. 1154 <br>It takes one parameter (the type is <code>java.lang.Object</code>) 1155 and returns true 1156 <br>if the parameter value is an instance of the type on the right 1157 hand side of 1158 <br>the original <code>instanceof</code> operator. 1159 Otherwise, it returns false. 1160 </td> 1161 </tr> 1162 1163 <tr><td> </td></tr> 1164 <tr><td> </td></tr> 1165 <tr><td> </td></tr> 1166 1167 </table> 1168 </ul> 1169 1170 <p>The other identifiers such as <code>$w</code>, 1171 <code>$args</code> and <code>$$</code> 1172 are also available. 1173 1174 <h4>javassist.expr.Cast</h4> 1175 1176 <p>A <code>Cast</code> object represents an expression for 1177 explicit type casting. 1178 The method <code>edit()</code> in <code>ExprEditor</code> 1179 receives this object if explicit type casting is found. 1180 The method <code>replace()</code> in 1181 <code>Cast</code> receives 1182 source text representing the substitued statement or 1183 block for the expression. 1184 1185 <p> 1186 In the source text, the identifiers starting with <code>$</code> 1187 have special meaning: 1188 1189 <ul><table border=0> 1190 1191 <tr> 1192 <td><code>$0</code></td> 1193 <td> 1194 <code>null</code>. 1195 </td> 1196 </tr> 1197 1198 <tr> 1199 <td><code>$1</code></td> 1200 <td> 1201 The value the type of which is explicitly cast. 1202 </td> 1203 </tr> 1204 1205 <tr> 1206 <td><code>$_</code></td> 1207 <td rowspan=2> 1208 The resulting value of the expression. 1209 The type of <code>$_</code> is the same as the type 1210 <br>after the explicit casting, that is, the type surrounded 1211 by <code>( )</code>. 1212 </td> 1213 </tr> 1214 1215 <tr><td> </td></tr> 1216 1217 <tr> 1218 <td><code>$r</code></td> 1219 <td>the type after the explicit casting, or the type surrounded 1220 by <code>( )</code>. 1221 </td> 1222 </tr> 1223 1224 <tr><td><code>$type</code></td> 1225 <td>A <code>java.lang.Class</code> object representing 1226 the same type as <code>$r</code>. 1227 </td> 1228 </tr> 1229 1230 <tr><td><code>$proceed</code>    </td> 1231 <td rowspan=3>The name of a virtual method executing the original 1232 type casting. 1233 <br>It takes one parameter of the type <code>java.lang.Object</code> 1234 and returns it after 1235 <br>the explicit type casting specified by the original expression. 1236 1237 </td> 1238 </tr> 1239 1240 <tr><td> </td></tr> 1241 1242 <tr><td> </td></tr> 1243 1244 </table> 1245 </ul> 1246 1247 <p>The other identifiers such as <code>$w</code>, 1248 <code>$args</code> and <code>$$</code> 1249 are also available. 1250 1251 <h4>javassist.expr.Handler</h4> 1252 1253 <p>A <code>Handler</code> object represents a <code>catch</code> 1254 clause of <code>try-catch</code> statement. 1255 The method <code>edit()</code> in <code>ExprEditor</code> 1256 receives this object if a <code>catch</code> is found. 1257 The method <code>insertBefore()</code> in 1258 <code>Handler</code> compiles the received 1259 source text and inserts it at the beginning of the <code>catch</code> clause. 1260 1261 <p> 1262 In the source text, the identifiers starting with <code>$</code> 1263 have meaning: 1264 1265 <ul><table border=0> 1266 1267 <tr> 1268 <td><code>$1</code></td> 1269 <td> 1270 The exception object caught by the <code>catch</code> clause. 1271 </td> 1272 </tr> 1273 1274 <tr> 1275 <td><code>$r</code></td> 1276 <td>the type of the exception caught by the <code>catch</code> clause. 1277 It is used in a cast expression. 1278 </td> 1279 </tr> 1280 1281 <tr> 1282 <td><code>$w</code></td> 1283 <td>The wrapper type. It is used in a cast expression. 1284 </td> 1285 </tr> 1286 1287 <tr><td><code>$type</code>    </td> 1288 <td rowspan=2> 1289 A <code>java.lang.Class</code> object representing 1290 <br>the type of the exception caught by the <code>catch</code> clause. 1291 </td> 1292 </tr> 1293 1294 <tr><td> </td></tr> 1295 1296 </table> 1297 </ul> 1298 1299 <p>If a new exception object is assigned to <code>$1</code>, 1300 it is passed to the original <code>catch</code> clause as the caught 1301 exception. 1302 1303 <p><br> 1304 1305 <a name="add"> 1306 <h3>4.3 Adding a new method or field</h3> 1307 1308 <h4>Adding a method</h4> 1309 1310 <p>Javassist allows the users to create a new method and constructor 1311 from scratch. <code>CtNewMethod</code> 1312 and <code>CtNewConstructor</code> provide several factory methods, 1313 which are static methods for creating <code>CtMethod</code> or 1314 <code>CtConstructor</code> objects. 1315 Especially, <code>make()</code> creates 1316 a <code>CtMethod</code> or <code>CtConstructor</code> object 1317 from the given source text. 1318 1319 <p>For example, this program: 1320 1321 <ul><pre> 1322 CtClass point = ClassPool.getDefault().get("Point"); 1323 CtMethod m = CtNewMethod.make( 1324 "public int xmove(int dx) { x += dx; }", 1325 point); 1326 point.addMethod(m); 1327 </pre></ul> 1328 1329 <p>adds a public method <code>xmove()</code> to class <code>Point</code>. 1330 In this example, <code>x</code> is a <code>int</code> field in 1331 the class <code>Point</code>. 1332 1333 <p>The source text passed to <code>make()</code> can include the 1334 identifiers starting with <code>$</code> except <code>$_</code> 1335 as in <code>setBody()</code>. 1336 It can also include 1337 <code>$proceed</code> if the target object and the target method name 1338 are also given to <code>make()</code>. For example, 1339 1340 <ul><pre> 1341 CtClass point = ClassPool.getDefault().get("Point"); 1342 CtMethod m = CtNewMethod.make( 1343 "public int ymove(int dy) { $proceed(0, dy); }", 1344 point, "this", "move"); 1345 </pre></ul> 1346 1347 <p>this program creates a method <code>ymove()</code> defined below: 1348 1349 <ul><pre> 1350 public int ymove(int dy) { this.move(0, dy); } 1351 </pre></ul> 1352 1353 <p>Note that <code>$proceed</code> has been replaced with 1354 <code>this.move</code>. 1355 1356 <p>Javassist provides another way to add a new method. 1357 You can first create an abstract method and later give it a method body: 1358 1359 <ul><pre> 1360 CtClass cc = ... ; 1361 CtMethod m = new CtMethod(CtClass.intType, "move", 1362 new CtClass[] { CtClass.intType }, cc); 1363 cc.addMethod(m); 1364 m.setBody("{ x += $1; }"); 1365 cc.setModifiers(cc.getModifiers() & ~Modifier.ABSTRACT); 1366 </pre></ul> 1367 1368 <p>Since Javassist makes a class abstract if an abstract method is 1369 added to the class, you have to explicitly change the class back to a 1370 non-abstract one after calling <code>setBody()</code>. 1371 1372 1373 <h4>Mutual recursive methods</h4> 1374 1375 <p>Javassist cannot compile a method if it calls another method that 1376 has not been added to a class. (Javassist can compile a method that 1377 calls itself recursively.) To add mutual recursive methods to a class, 1378 you need a trick shown below. Suppose that you want to add methods 1379 <code>m()</code> and <code>n()</code> to a class represented 1380 by <code>cc</code>: 1381 1382 <ul><pre> 1383 CtClass cc = ... ; 1384 CtMethod m = CtNewMethod.make("public abstract int m(int i);", cc); 1385 CtMethod n = CtNewMethod.make("public abstract int n(int i);", cc); 1386 cc.addMethod(m); 1387 cc.addMethod(n); 1388 m.setBody("{ return ($1 <= 0) ? 1 : (n($1 - 1) * $1); }"); 1389 n.setBody("{ return m($1); }"); 1390 cc.setModifiers(cc.getModifiers() & ~Modifier.ABSTRACT); 1391 </pre></ul> 1392 1393 <p>You must first make two abstract methods and add them to the class. 1394 Then you can give the method bodies to these methods even if the method 1395 bodies include method calls to each other. Finally you must change the 1396 class to a not-abstract class since <code>addMethod()</code> automatically 1397 changes a class into an abstract one if an abstract method is added. 1398 1399 <h4>Adding a field</h4> 1400 1401 <p>Javassist also allows the users to create a new field. 1402 1403 <ul><pre> 1404 CtClass point = ClassPool.getDefault().get("Point"); 1405 CtField f = new CtField(CtClass.intType, "z", point); 1406 point.addField(f); 1407 </pre></ul> 1408 1409 <p>This program adds a field named <code>z</code> to class 1410 <code>Point</code>. 1411 1412 <p>If the initial value of the added field must be specified, 1413 the program shown above must be modified into: 1414 1415 <ul><pre> 1416 CtClass point = ClassPool.getDefault().get("Point"); 1417 CtField f = new CtField(CtClass.intType, "z", point); 1418 point.addField(f, "0"); <em>// initial value is 0.</em> 1419 </pre></ul> 1420 1421 <p>Now, the method <code>addField()</code> receives the second parameter, 1422 which is the source text representing an expression computing the initial 1423 value. This source text can be any Java expression if the result type 1424 of the expression matches the type of the field. Note that an expression 1425 does not end with a semi colon (<code>;</code>). 1426 1427 <p>Furthermore, the above code can be rewritten into the following 1428 simple code: 1429 1430 <ul><pre> 1431 CtClass point = ClassPool.getDefault().get("Point"); 1432 CtField f = CtField.make("public int z = 0;", point); 1433 point.addField(f); 1434 </pre></ul> 1435 1436 <h4>Removing a member</h4> 1437 1438 <p>To remove a field or a method, call <code>removeField()</code> 1439 or <code>removeMethod()</code> in <code>CtClass</code>. A 1440 <code>CtConstructor</code> can be removed by <code>removeConstructor()</code> 1441 in <code>CtClass</code>. 1442 1443 <p><br> 1444 1445 <a name="annotation"> 1446 <h3>4.4 Annotations</h3> 1447 1448 <p><code>CtClass</code>, <code>CtMethod</code>, <code>CtField</code> 1449 and <code>CtConstructor</code> provides a convenient method 1450 <code>getAnnotations()</code> for reading annotations. 1451 It returns an annotation-type object. 1452 1453 <p>For example, suppose the following annotation: 1454 1455 <ul><pre> 1456 public @interface Author { 1457 String name(); 1458 int year(); 1459 } 1460 </pre></ul> 1461 1462 <p>This annotation is used as the following: 1463 1464 <ul><pre> 1465 @Author(name="Chiba", year=2005) 1466 public class Point { 1467 int x, y; 1468 } 1469 </pre></ul> 1470 1471 <p>Then, the value of the annotation can be obtained by 1472 <code>getAnnotations()</code>. 1473 It returns an array containing 1474 annotation-type objects. 1475 1476 <ul><pre> 1477 CtClass cc = ClassPool.getDefault().get("Point"); 1478 Object[] all = cc.getAnnotations(); 1479 Author a = (Author)all[0]; 1480 String name = a.name(); 1481 int year = a.year(); 1482 System.out.println("name: " + name + ", year: " + year); 1483 </pre></ul> 1484 1485 <p>This code snippet should print: 1486 1487 <ul><pre> 1488 name: Chiba, year: 2005 1489 </pre></ul> 1490 1491 <p> 1492 Since the annoation of <code>Point</code> is only <code>@Author</code>, 1493 the length of the array <code>all</code> is one 1494 and <code>all[0]</code> is an <code>Author</code> object. 1495 The member values of the annotation can be obtained 1496 by calling <code>name()</code> and <code>year()</code> 1497 on the <code>Author</code> object. 1498 1499 <p>To use <code>getAnnotations()</code>, annotation types 1500 such as <code>Author</code> must be included in the current 1501 class path. <em>They must be also accessible from a 1502 <code>ClassPool</code> object.</em> If the class file of an annotation 1503 type is not found, Javassist cannot obtain the default values 1504 of the members of that annotation type. 1505 1506 <p><br> 1507 1508 <a name="runtime"> 1509 <h3>4.5 Runtime support classes</h3> 1510 1511 <p>In most cases, a class modified by Javassist does not require 1512 Javassist to run. However, some kinds of bytecode generated by the 1513 Javassist compiler need runtime support classes, which are in the 1514 <code>javassist.runtime</code> package (for details, please read 1515 the API reference of that package). Note that the 1516 <code>javassist.runtime</code> package is the only package that 1517 classes modified by Javassist may need for running. The other 1518 Javassist classes are never used at runtime of the modified classes. 1519 1520 <p><br> 1521 1522 <a name="import"> 1523 <h3>4.6 Import</h3> 1524 1525 <p>All the class names in source code must be fully qualified 1526 (they must include package names). 1527 However, the <code>java.lang</code> package is an 1528 exception; for example, the Javassist compiler can 1529 resolve <code>Object</code> as 1530 well as <code>java.lang.Object</code>. 1531 1532 <p>To tell the compiler to search other packages when resolving a 1533 class name, call <code>importPackage()</code> in <code>ClassPool</code>. 1534 For example, 1535 1536 <ul><pre> 1537 ClassPool pool = ClassPool.getDefault(); 1538 pool.importPackage("java.awt"); 1539 CtClass cc = pool.makeClass("Test"); 1540 CtField f = CtField.make("public Point p;", cc); 1541 cc.addField(f); 1542 </pre></ul> 1543 1544 <p>The seconde line instructs the compiler 1545 to import the <code>java.awt</code> package. 1546 Thus, the third line will not throw an exception. 1547 The compiler can recognize <code>Point</code> 1548 as <code>java.awt.Point</code>. 1549 1550 <p>Note that <code>importPackage()</code> <em>does not</em> affect 1551 the <code>get()</code> method in <code>ClassPool</code>. 1552 Only the compiler considers the imported packages. 1553 The parameter to <code>get()</code> 1554 must be always a fully qualified name. 1555 1556 <p><br> 1557 1558 <a name="limit"> 1559 <h3>4.7 Limitations</h3> 1560 1561 <p>In the current implementation, the Java compiler included in Javassist 1562 has several limitations with respect to the language that the compiler can 1563 accept. Those limitations are: 1564 1565 <p><li>The new syntax introduced by J2SE 5.0 (including enums and generics) 1566 has not been supported. Annotations are supported only by the low level 1567 API of Javassist. 1568 See the <code>javassist.bytecode.annotation</code> package. 1569 1570 <p><li>Array initializers, a comma-separated list of expressions 1571 enclosed by braces <code>{</code> and <code>}</code>, are not 1572 available unless the array dimension is one. 1573 1574 <p><li>Inner classes or anonymous classes are not supported. 1575 1576 <p><li>Labeled <code>continue</code> and <code>break</code> statements 1577 are not supported. 1578 1579 <p><li>The compiler does not correctly implement the Java method dispatch 1580 algorithm. The compiler may confuse if methods defined in a class 1581 have the same name but take different parameter lists. 1582 1583 <p>For example, 1584 1585 <ul><pre> 1586 class A {} 1587 class B extends A {} 1588 class C extends B {} 1589 1590 class X { 1591 void foo(A a) { .. } 1592 void foo(B b) { .. } 1593 } 1594 </pre></ul> 1595 1596 <p>If the compiled expression is <code>x.foo(new C())</code>, where 1597 <code>x</code> is an instance of X, the compiler may produce a call 1598 to <code>foo(A)</code> although the compiler can correctly compile 1599 <code>foo((B)new C())</code>. 1600 1601 <p><li>The users are recommended to use <code>#</code> as the separator 1602 between a class name and a static method or field name. 1603 For example, in regular Java, 1604 1605 <ul><pre>javassist.CtClass.intType.getName()</pre></ul> 1606 1607 <p>calls a method <code>getName()</code> on 1608 the object indicated by the static field <code>intType</code> 1609 in <code>javassist.CtClass</code>. In Javassist, the users can 1610 write the expression shown above but they are recommended to 1611 write: 1612 1613 <ul><pre>javassist.CtClass#intType.getName()</pre></ul> 1614 1615 <p>so that the compiler can quickly parse the expression. 1616 </ul> 1617 1618 <p><br> 1619 1620 <a href="tutorial.html">Previous page</a> 1621 <a href="tutorial3.html">Next page</a> 1622 1623 <hr> 1624 Java(TM) is a trademark of Sun Microsystems, Inc.<br> 1625 Copyright (C) 2000-2010 by Shigeru Chiba, All rights reserved. 1626 </body> 1627 </html> 1628