1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096109710981099110011011102110311041105110611071108110911101111111211131114111511161117111811191120112111221123112411251126112711281129113011311132113311341135113611371138113911401141114211431144114511461147114811491150115111521153115411551156115711581159116011611162116311641165116611671168116911701171117211731174117511761177117811791180118111821183118411851186118711881189119011911192119311941195119611971198119912001201120212031204120512061207120812091210121112121213121412151216121712181219122012211222122312241225122612271228122912301231123212331234123512361237123812391240124112421243124412451246124712481249125012511252125312541255125612571258125912601261126212631264126512661267126812691270127112721273127412751276127712781279128012811282128312841285128612871288128912901291129212931294129512961297129812991300130113021303130413051306130713081309131013111312131313141315131613171318131913201321132213231324132513261327132813291330133113321333133413351336133713381339134013411342134313441345134613471348134913501351135213531354135513561357135813591360136113621363136413651366136713681369137013711372137313741375137613771378137913801381138213831384138513861387138813891390139113921393139413951396139713981399140014011402140314041405140614071408140914101411141214131414141514161417141814191420142114221423142414251426142714281429143014311432143314341435143614371438143914401441144214431444144514461447144814491450145114521453145414551456145714581459146014611462146314641465146614671468146914701471147214731474147514761477147814791480148114821483148414851486148714881489149014911492149314941495149614971498149915001501150215031504150515061507150815091510151115121513151415151516151715181519152015211522152315241525152615271528152915301531153215331534153515361537153815391540154115421543154415451546154715481549155015511552155315541555155615571558155915601561156215631564156515661567156815691570157115721573157415751576157715781579158015811582158315841585158615871588158915901591159215931594159515961597159815991600160116021603160416051606160716081609161016111612161316141615161616171618161916201621162216231624162516261627 |
- <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="#annotation">Annotations</a>
- <br><li><a href="#import">Import</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
- <a href="tutorial3.html#intro"><code>javassist.bytecode</code> package</a>.
-
- <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><code>this</code> and 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>$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 refers to <code>Void.class</code> if this is a constructor.
-
- <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><code>this</code> and 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. It cannot be or contain a try-catch statement.
-
- <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.ConstructorCall</h4>
-
- <p>A <code>ConstructorCall</code> object represents a constructor call
- such as <code>this()</code> and <code>super</code> included in a constructor
- body.
- The method <code>replace()</code> in
- <code>ConstructorCall</code> substitutes a statement or
- a block for the constructor call.
- It receives source text representing the substituted 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>
- The target object of the constructor call.
- This is equivalent to <code>this</code>.
- </td>
- </tr>
-
- <tr>
- <td><code>$1</code>, <code>$2</code>, ...    </td>
- <td>
- The parameters of the constructor call.
- </td>
- </tr>
-
- <tr><td><code>$class</code>    </td>
- <td>A <code>java.lang.Class</code> object representing
- the class declaring the constructor.
- </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>$proceed</code>    </td>
- <td>The name of the constructor originally called
- in the expression.</td>
- </tr>
-
- </table>
- </ul>
-
- <p>Here the constructor call means the one represented by the
- <code>ConstructorCall</code> object.
-
- <p>The other identifiers such as <code>$w</code>,
- <code>$args</code> and <code>$$</code>
- are also available.
-
- <p>Since any constructor must call either a constructor of the super
- class or another constructor of the same class,
- the substituted statement must include a constructor call,
- normally a call to <code>$proceed()</code>.
-
- <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>
-
- <h4>Removing a member</h4>
-
- <p>To remove a field or a method, call <code>removeField()</code>
- or <code>removeMethod()</code> in <code>CtClass</code>. A
- <code>CtConstructor</code> can be removed by <code>removeConstructor()</code>
- in <code>CtClass</code>.
-
- <p><br>
-
- <a name="annotation">
- <h3>4.4 Annotations</h3>
-
- <p><code>CtClass</code>, <code>CtMethod</code>, <code>CtField</code>
- and <code>CtConstructor</code> provides a convenient method
- <code>getAnnotations()</code> for reading annotations.
- It returns an annotation-type object.
-
- <p>For example, suppose the following annotation:
-
- <ul><pre>
- public @interface Author {
- String name();
- int year();
- }
- </pre></ul>
-
- <p>This annotation is used as the following:
-
- <ul><pre>
- @Author(name="Chiba", year=2005)
- public class Point {
- int x, y;
- }
- </pre></ul>
-
- <p>Then, the value of the annotation can be obtained by
- <code>getAnnotations()</code>.
- It returns an array containing
- annotation-type objects.
-
- <ul><pre>
- CtClass cc = ClassPool.getDefault().get("Point");
- Object[] all = cc.getAnnotations();
- Author a = (Author)all[0];
- String name = a.name();
- int year = a.year();
- System.out.println("name: " + name + ", year: " + year);
- </pre></ul>
-
- <p>This code snippet should print:
-
- <ul><pre>
- name: Chiba, year: 2005
- </pre></ul>
-
- <p>
- Since the annoation of <code>Point</code> is only <code>@Author</code>,
- the length of the array <code>all</code> is one
- and <code>all[0]</code> is an <code>Author</code> object.
- The member values of the annotation can be obtained
- by calling <code>name()</code> and <code>year()</code>
- on the <code>Author</code> object.
-
- <p>To use <code>getAnnotations()</code>, annotation types
- such as <code>Author</code> must be included in the current
- class path. <em>They must be also accessible from a
- <code>ClassPool</code> object.</em> If the class file of an annotation
- type is not found, Javassist cannot obtain the default values
- of the members of that annotation type.
-
- <p><br>
-
- <a name="runtime">
- <h3>4.5 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="import">
- <h3>4.6 Import</h3>
-
- <p>All the class names in source code must be fully qualified
- (they must include package names).
- However, the <code>java.lang</code> package is an
- exception; for example, the Javassist compiler can
- resolve <code>Object</code> as
- well as <code>java.lang.Object</code>.
-
- <p>To tell the compiler to search other packages when resolving a
- class name, call <code>importPackage()</code> in <code>ClassPool</code>.
- For example,
-
- <ul><pre>
- ClassPool pool = ClassPool.getDefault();
- pool.importPackage("java.awt");
- CtClass cc = pool.makeClass("Test");
- CtField f = CtField.make("public Point p;", cc);
- cc.addField(f);
- </pre></ul>
-
- <p>The seconde line instructs the compiler
- to import the <code>java.awt</code> package.
- Thus, the third line will not throw an exception.
- The compiler can recognize <code>Point</code>
- as <code>java.awt.Point</code>.
-
- <p>Note that <code>importPackage()</code> <em>does not</em> affect
- the <code>get()</code> method in <code>ClassPool</code>.
- Only the compiler considers the imported packages.
- The parameter to <code>get()</code>
- must be always a fully qualified name.
-
- <p><br>
-
- <a name="limit">
- <h3>4.7 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>Array initializers, a comma-separated list of expressions
- enclosed by braces <code>{</code> and <code>}</code>, are not
- available unless the array dimension is one.
-
- <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 B {}
-
- 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-2010 by Shigeru Chiba, All rights reserved.
- </body>
- </html>
|