|
12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485868788899091929394959697989910010110210310410510610710810911011111211311411511611711811912012112212312412512612712812913013113213313413513613713813914014114214314414514614714814915015115215315415515615715815916016116216316416516616716816917017117217317417517617717817918018118218318418518618718818919019119219319419519619719819920020120220320420520620720820921021121221321421521621721821922022122222322422522622722822923023123223323423523623723823924024124224324424524624724824925025125225325425525625725825926026126226326426526626726826927027127227327427527627727827928028128228328428528628728828929029129229329429529629729829930030130230330430530630730830931031131231331431531631731831932032132232332432532632732832933033133233333433533633733833934034134234334434534634734834935035135235335435535635735835936036136236336436536636736836937037137237337437537637737837938038138238338438538638738838939039139239339439539639739839940040140240340440540640740840941041141241341441541641741841942042142242342442542642742842943043143243343443543643743843944044144244344444544644744844945045145245345445545645745845946046146246346446546646746846947047147247347447547647747847948048148248348448548648748848949049149249349449549649749849950050150250350450550650750850951051151251351451551651751851952052152252352452552652752852953053153253353453553653753853954054154254354454554654754854955055155255355455555655755855956056156256356456556656756856957057157257357457557657757857958058158258358458558658758858959059159259359459559659759859960060160260360460560660760860961061161261361461561661761861962062162262362462562662762862963063163263363463563663763863964064164264364464564664764864965065165265365465565665765865966066166266366466566666766866967067167267367467567667767867968068168268368468568668768868969069169269369469569669769869970070170270370470570670770870971071171271371471571671771871972072172272372472572672772872973073173273373473573673773873974074174274374474574674774874975075175275375475575675775875976076176276376476576676776876977077177277377477577677777877978078178278378478578678778878979079179279379479579679779879980080180280380480580680780880981081181281381481581681781881982082182282382482582682782882983083183283383483583683783883984084184284384484584684784884985085185285385485585685785885986086186286386486586686786886987087187287387487587687787887988088188288388488588688788888989089189289389489589689789889990090190290390490590690790890991091191291391491591691791891992092192292392492592692792892993093193293393493593693793893994094194294394494594694794894995095195295395495595695795895996096196296396496596696796896997097197297397497597697797897998098198298398498598698798898999099199299399499599699799899910001001100210031004100510061007100810091010101110121013101410151016101710181019102010211022102310241025102610271028102910301031103210331034103510361037103810391040104110421043104410451046104710481049105010511052105310541055105610571058105910601061106210631064106510661067106810691070107110721073107410751076107710781079108010811082108310841085108610871088108910901091109210931094109510961097109810991100110111021103110411051106110711081109111011111112111311141115111611171118111911201121112211231124112511261127112811291130113111321133113411351136113711381139114011411142114311441145114611471148114911501151115211531154115511561157115811591160116111621163116411651166116711681169117011711172117311741175117611771178117911801181118211831184118511861187118811891190119111921193119411951196119711981199120012011202120312041205120612071208120912101211121212131214121512161217121812191220122112221223122412251226122712281229123012311232123312341235123612371238123912401241124212431244124512461247124812491250125112521253125412551256125712581259126012611262126312641265126612671268126912701271127212731274127512761277127812791280128112821283128412851286128712881289129012911292129312941295129612971298129913001301130213031304130513061307130813091310131113121313131413151316131713181319132013211322132313241325132613271328132913301331133213331334133513361337133813391340134113421343134413451346134713481349135013511352135313541355135613571358135913601361136213631364136513661367136813691370137113721373137413751376137713781379138013811382138313841385138613871388138913901391139213931394139513961397139813991400140114021403140414051406140714081409141014111412141314141415141614171418141914201421142214231424142514261427142814291430143114321433143414351436143714381439144014411442144314441445144614471448144914501451145214531454145514561457145814591460146114621463146414651466146714681469147014711472147314741475147614771478147914801481148214831484148514861487148814891490149114921493149414951496149714981499150015011502150315041505150615071508150915101511151215131514151515161517151815191520152115221523152415251526152715281529153015311532153315341535153615371538153915401541154215431544154515461547154815491550155115521553155415551556155715581559156015611562156315641565156615671568156915701571157215731574157515761577157815791580158115821583158415851586158715881589159015911592159315941595159615971598159916001601160216031604160516061607160816091610161116121613161416151616161716181619162016211622162316241625162616271628162916301631163216331634 |
- <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 by the low level
- API of Javassist.
- See the <code>javassist.bytecode.annotation</code> package
- (and also <code>getAnnotations()</code>
- in <code>CtClass</code> and <code>CtBehavior</code>).
- Generics are also only partly supported. See <a href="./tutorial3.html#generics">the latter section</a> for more details.
-
- <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.
- Note that this is a limitation of the compiler only.
- It cannot compile source code including an anonymous-class declaration.
- Javassist can read and modify a class file of inner/anonymous class.
-
- <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-2015 by Shigeru Chiba, All rights reserved.
- </body>
- </html>
|