From cdeddfd6fc34a06734f9fa525cf5c7437a6c8fb6 Mon Sep 17 00:00:00 2001 From: chiba Date: Wed, 23 Apr 2003 17:08:37 +0000 Subject: Changed the copyright notices and removed tab characters. git-svn-id: http://anonsvn.jboss.org/repos/javassist/trunk@9 30ef5769-5b8d-40dd-aea6-55b5d6557bb3 --- tutorial/tutorial2.html | 2188 ++++++++++++++++++++++++----------------------- 1 file changed, 1119 insertions(+), 1069 deletions(-) (limited to 'tutorial/tutorial2.html') diff --git a/tutorial/tutorial2.html b/tutorial/tutorial2.html index b76996ce..6287f1ee 100644 --- a/tutorial/tutorial2.html +++ b/tutorial/tutorial2.html @@ -1,1069 +1,1119 @@ - - - - Javassist Tutorial - - - - - -
Getting Started with Javassist
- -
Previous page
- - -

5. Introspection and customization

- -

CtClass provides methods for introspection. The -introspective ability of Javassist is compatible with that of -the Java reflection API. CtClass provides -getName(), getSuperclass(), -getMethods(), and so on. -CtClass 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. - -

- - - -

- -

Javassist also provides low-level API for directly editing a raw -class file. For example, getClassFile() in -CtClass returns a ClassFile object -representing a raw class file. getMethodInfo() in -CtMethod returns a MethodInfo object -representing a method_info 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 -javassist.bytecode package. - -


- -

5.1 Inserting source text at the beginning/end of a method body

- -

CtMethod and CtConstructor provide -methods insertBefore(), insertAfter(), and -addCatch(). They are used for inserting a code fragment -into the body of an existing method. The users can specify those code -fragments with source text 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 inserted -into a method body. - -

The methods insertBefore(), insertAfter(), and -addCatch() receives a String object representing -a statement or a block. A statement is a single control structure like -if and while or an expression ending with -a semi colon (;). A block is a set of -statements surrounded with braces {}. -Hence each of the following lines is an example of valid statement or block: - -

- -

The statement and the block can refer to fields and methods. -However, they cannot refer to local variables declared in the -method that they are inserted into. -They can refer to the parameters -to the method although they must use different names -$0, $1, $2, ... described -below. Declaring a local variable in the block is allowed. - - - -

The String object passed to the methods -insertBefore(), insertAfter(), and -addCatch() are compiled by -the compiler included in Javassist. -Since the compiler supports language extensions, -several identifiers starting with $ -have special meaning: - -

- -

$0, $1, $2, ...

- -

The parameters passed to the methods insertBefore(), -insertAfter(), and addCatch() -are accessible with -$0, $1, $2, ... instead of -the original parameter names. -$1 represents the -first parameter, $2 represents the second parameter, and -so on. The types of those variables are identical to the parameter -types. -$0 is -equivalent to this. If the method is static, -$0 is not available. - -

These variables are used as following. Suppose that a class -Point: - -

    class Point {
-    int x, y;
-    void move(int dx, int dy) { x += dx; y += dy; }
-}
-
- -

To print the values of dx and dy -whenever the method move() is called, execute this -program: - -

- -

Note that the source text passed to insertBefore() is -surrounded with braces {}. -insertBefore() accepts only a single statement or a block -surrounded with braces. - -

The definition of the class Point after the -modification is like this: - -

    class Point {
-    int x, y;
-    void move(int dx, int dy) {
-        { System.out.println(dx); System.out.println(dy); }
-        x += dx; y += dy;
-    }
-}
-
- -

$1 and $2 are replaced with -dx and dy, respectively. - -

$1, $2, $3 ... 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. - - -

$args

- -

The variable $args represents an array of all the -parameters. The type of that variable is an array of class -Object. If a parameter type is a primitive type such as -int, then the parameter value is converted into a wrapper -object such as java.lang.Integer to store in -$args. Thus, $args[0] is equivalent to -$1 unless the type of the first parameter is a primitive -type. Note that $args[0] is not equivalent to -$0; $0 represents this. - -

If an array of Object is assigned to -$args, 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. - -

$$

- -

The variable $$ is abbreviation of a list of -all the parameters separated by commas. -For example, if the number of the parameters -to method move() is three, then - -

- -

is equivalent to this: - -

- -

If move() does not take any parameters, -then move($$) is -equivalent to move(). - -

$$ can be used with another method. -If you write an expression: - -

- -

then this expression is equivalent to: - -

- -

Note that $$ enables generic notation of method call -with respect to the number of parameters. -It is typically used with $proceed shown later. - -

$cflow

- -

$cflow means "control flow". -This read-only variable returns the depth of the recursive calls -to a specific method. - -

Suppose that the method shown below is represented by a -CtMethod object cm: - -

- -

To use $cflow, first declare that $cflow -is used for monitoring calls to the method fact(): - -

- -

The parameter to useCflow() is the identifier of the -declared $cflow variable. Any valid Java name can be -used as the identifier. Since the identifier can also include -. (dot), for example, "my.Test.fact" -is a valid identifier. - -

Then, $cflow(fact) represents the depth of the -recursive calls to the method specified by cm. The value -of $cflow(fact) is 0 (zero) when the method is -first called whereas it is 1 when the method is recursively called -within the method. For example, - -

- -

translates the method fact() so that it shows the -parameter. Since the value of $cflow(fact) is checked, -the method fact() does not show the parameter if it is -recursively called within fact(). - -

The value of $cflow is the number of stack frames -associated with the specified method cm -under the current topmost -stack frame for the current thread. $cflow is also -accessible within a method different from the specified method -cm. - -

$r

- -

$r 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: - -

- -

If the result type is a primitive type, then ($r) -converts from the wrapper type to the primitive type. -For example, if the result type is int, then -($r) converts from java.lang.Integer to -int. - -

If the result type is void, then -($r) does not convert a type; it does nothing. -Moreover, the soruce text can include a return -statement with a resulting value: - -

- -

Here, result is some local variable. -Since ($r) is specified, the resulting value is -discarded. -This return statement is regarded as the equivalent -of the return statement without a resulting value: - -

- -

$w

- -

$w represents a wrapper type. -It must be used as the cast type in a cast expression. -($w) converts from a primitive type to the corresponding -wrapper type. - -The following code is an example: - -

- -

The selected wrapper type depends on the type of the expression -following ($w). If the type of the expression is -double, then the wrapper type is java.lang.Double. - -

If the type of the expression following ($w) is not -a primitive type, then ($w) does nothing. - -

$_

- -

insertAfter() in CtMethod and -CtConstructor inserts the -compiled code at the end of the method. In the statement given to -insertAfter(), not only the variables shown above such as -$0, $1, ... but also $_ is -available. - -

The variable $_ 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 void, -then the type of $_ is Object and the value -of $_ is null. - -

Although the compiled code inserted by insertAfter() -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 -asFinally to insertAfter() must be -true. - -

If an exception is thrown, the compiled code inserted by -insertAfter() is executed as a finally -clause. The value of $_ is 0 or -null 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 $_ is never thrown -to the caller; it is rather discarded. - -

$sig

- -

The value of $sig is an array of -java.lang.Class objects that represent the formal -parameter types in declaration order. - -

$type

- -

The value of $type is an java.lang.Class -object representing the formal type of the result value. This -variable is available only in insertAfter() in -CtMethod and CtConstructor. - -

$class

- -

The value of $class is an java.lang.Class -object representing the class in which the edited method is declared. - -

addCatch()

- -

addCatch() 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 name specified by the third parameter to -addCatch(). - -

For example, this program: - -

- -

translates the method body represented by m into -something like this: - -

- -

Note that the inserted code fragment must end with a -throw or return statement. - -


- -

5.2 Modifying a method body

- -

javassist.expr.ExprEditor is a class -for replacing an expression in a method body. -The users can define a subclass of ExprEditor -to specify how an expression is modified. - -

To run an ExprEditor object, the users must -call instrument() in CtMethod or -CtClass. - -For example, - -

- -

searches the method body represented by cm and -replaces all calls to move() in class Point -with a block: - -

- -

so that the first parameter to move() is always 0. -Note that the substituted code is not an expression but -a statement or a block. - -

The method instrument() searches a method body. -If it finds an expression such as a method call, field access, and object -creation, then it calls edit() on the given -ExprEditor object. The parameter to edit() -is an object representing the found expression. The edit() -method can inspect and replace the expression through that object. - -

Calling replace() on the parameter to edit() -substitutes the given statement or block for the expression. If the given -block is an empty block, that is, if replace("{}") -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 -replace(): - -

- -

whichever the expression is either a method call, field access, -object creation, or others. The second statement could be: - -

- -

if the expression is read access, or - -

- -

if the expression is write access. - -

javassist.expr.MethodCall

- -

A MethodCall object represents a method call. -The method replace() in -MethodCall 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 $ -have special meaning as in the source text passed to -insertBefore(). - -

- -

Here the method call means the one represented by the -MethodCall object. - -

The other identifiers such as $w, -$args and $$ -are also available. - -

Unless the result type of the method call is void, -a value must be assigned to -$_ in the source text and the type of $_ -is the result type. -If the result type is void, the type of $_ -is Object and the value assigned to $_ -is ignored. - -

$proceed is not a String value but special -syntax. It must be followed by an argument list surrounded by parentheses -( ). - -

javassist.expr.FieldAccess

- -

A FieldAccess object represents field access. -The method edit() in ExprEditor -receive this object if field access is found. -The method replace() in -FieldAccess receives -source text representing the substitued statement or -block for the field access. - -In the source text, the identifiers starting with $ -have also special meaning: - -

- -

The other identifiers such as $w, -$args and $$ -are also available. - -

If the expression is read access, a value must be assigned to -$_ in the source text. The type of $_ -is the type of the field. - -

javassist.expr.NewExpr

- -

A NewExpr object represents object creation -with the new operator. -The method edit() in ExprEditor -receive this object if object creation is found. -The method replace() in -NewExpr receives -source text representing the substitued statement or -block for the object creation. - -In the source text, the identifiers starting with $ -have also special meaning: - -

- -

The other identifiers such as $w, -$args and $$ -are also available. - -

javassist.expr.Instanceof

- -

A Instanceof object represents an instanceof -expression. -The method edit() in ExprEditor -receive this object if an instanceof expression is found. -The method replace() in -Instanceof receives -source text representing the substitued statement or -block for the expression. - -In the source text, the identifiers starting with $ -have also special meaning: - -

- -

The other identifiers such as $w, -$args and $$ -are also available. - -

javassist.expr.Cast

- -

A Cast object represents an expression for -explicit type casting. -The method edit() in ExprEditor -receive this object if explicit type casting is found. -The method replace() in -Cast receives -source text representing the substitued statement or -block for the expression. - -In the source text, the identifiers starting with $ -have also special meaning: - -

- -

The other identifiers such as $w, -$args and $$ -are also available. - -


- -

5.3 Adding a new method or field

- -

Javassist allows the users to create a new method and constructor -from scratch. CtNewMethod -and CtNewConstructor provide several factory methods, -which are static methods for creating CtMethod or -CtConstructor objects. -Especially, make() creates -a CtMethod or CtConstructor object -from the given source text. - -

For example, this program: - -

- -

adds a public method xmove() to class Point. -In this example, x is a int field in -the class Point. - -

The source text passed to make() can refer to -$proceed if the target object and the target method name -are also given to make(). For example, - -

- -

this program creates a method ymove() defined below: - -

- -

Note that $proceed has been replaced with -this.move. - -

Javassist also allows the users to create a new field. - -

- -

This program adds a field named z to class -Point. - -

If the initial value of the added field must be specified, -the program shown above must be modified into: - -

- -

Now, the method addField() 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 (;). - -


- -

5.4 Limitations

- -

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: - -

  • The .class notation is not supported. Use the -method Class.forName(). -In regular -Java, an expression Point.class means a Class -object representing the Point class. This notation is -not available. - -

  • Array initializers, a comma-separated list of expressions -enclosed by braces { and }, are not -supported. - -

  • Inner classes or anonymous classes are not supported. - -

  • switch statements are not supported yet. - -

  • Labeled continue and break statements -are not supported. - -

  • The finally clause following -try and catch clauses is not supported. - -

  • 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. - -

  • The users are recommended to use # as the separator -between a class name and a static method or field name. -For example, in regular Java, - -
      javassist.CtClass.intType.getName()
    - -

    calls a method getName() on -the object indicated by the static field intType -in javassist.CtClass. In Javassist, the users can -write the expression shown above but they are recommended to -write: - -

      javassist.CtClass#intType.getName()
    - -

    so that the compiler can quickly parse the expression. - - -


    - -    Previous page - -

    -Java(TM) is a trademark of Sun Microsystems, Inc.
    -Copyright (C) 2000-2002 by Shigeru Chiba, All rights reserved. - - + + + + Javassist Tutorial + + + + + +
    Getting Started with Javassist
    + +
    Previous page
    + + +

    5. Introspection and customization

    + +

    CtClass provides methods for introspection. The +introspective ability of Javassist is compatible with that of +the Java reflection API. CtClass provides +getName(), getSuperclass(), +getMethods(), and so on. +CtClass 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. + +

    + +
      +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 +setName() +and setModifiers() declared in CtMethod. + +

      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 int +parameter newZ to a method: + +

        void move(int newX, int newY) { x = newX; y = newY; }
      + +

      in a Point class, then you should add the following +method to the Point class: + +

        void move(int newX, int newY, int newZ) {
+    // do what you want with newZ.
+    move(newX, newY);
+}
      + +
    + +

    + +

    Javassist also provides low-level API for directly editing a raw +class file. For example, getClassFile() in +CtClass returns a ClassFile object +representing a raw class file. getMethodInfo() in +CtMethod returns a MethodInfo object +representing a method_info 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 +javassist.bytecode package. + +


    + +

    5.1 Inserting source text at the beginning/end of a method body

    + +

    CtMethod and CtConstructor provide +methods insertBefore(), insertAfter(), and +addCatch(). They are used for inserting a code fragment +into the body of an existing method. The users can specify those code +fragments with source text 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 inserted +into a method body. + +

    The methods insertBefore(), insertAfter(), and +addCatch() receives a String object representing +a statement or a block. A statement is a single control structure like +if and while or an expression ending with +a semi colon (;). A block is a set of +statements surrounded with braces {}. +Hence each of the following lines is an example of valid statement or block: + +

      System.out.println("Hello");
+{ System.out.println("Hello"); }
+if (i < 0) { i = -i; }
+
    + +

    The statement and the block can refer to fields and methods. +However, they cannot refer to local variables declared in the +method that they are inserted into. +They can refer to the parameters +to the method although they must use different names +$0, $1, $2, ... described +below. Declaring a local variable in the block is allowed. + + + +

    The String object passed to the methods +insertBefore(), insertAfter(), and +addCatch() are compiled by +the compiler included in Javassist. +Since the compiler supports language extensions, +several identifiers starting with $ +have special meaning: + +

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      $0, $1, $2, ...    Actual parameters
      $argsAn array of parameters. +The type of $args is Object[]. +
      $$All actual parameters.
      +For example, m($$) is equivalent to +m($1,$2,...)
       
      $cflow(...)cflow variable
      $rThe result type. It is used in a cast expression.
      $wThe wrapper type. It is used in a cast expression.
      $_The resulting value
      $sigAn array of java.lang.Class objects representing +the formal parameter types. +
      $typeA java.lang.Class object representing +the formal result type.
      $classA java.lang.Class object representing +the class currently edited.
      +
    + +

    $0, $1, $2, ...

    + +

    The parameters passed to the methods insertBefore(), +insertAfter(), and addCatch() +are accessible with +$0, $1, $2, ... instead of +the original parameter names. +$1 represents the +first parameter, $2 represents the second parameter, and +so on. The types of those variables are identical to the parameter +types. +$0 is +equivalent to this. If the method is static, +$0 is not available. + +

    These variables are used as following. Suppose that a class +Point: + +

      class Point {
+    int x, y;
+    void move(int dx, int dy) { x += dx; y += dy; }
+}
+
    + +

    To print the values of dx and dy +whenever the method move() is called, execute this +program: + +

      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();
+
    + +

    Note that the source text passed to insertBefore() is +surrounded with braces {}. +insertBefore() accepts only a single statement or a block +surrounded with braces. + +

    The definition of the class Point after the +modification is like this: + +

      class Point {
+    int x, y;
+    void move(int dx, int dy) {
+        { System.out.println(dx); System.out.println(dy); }
+        x += dx; y += dy;
+    }
+}
+
    + +

    $1 and $2 are replaced with +dx and dy, respectively. + +

    $1, $2, $3 ... 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. + + +

    $args

    + +

    The variable $args represents an array of all the +parameters. The type of that variable is an array of class +Object. If a parameter type is a primitive type such as +int, then the parameter value is converted into a wrapper +object such as java.lang.Integer to store in +$args. Thus, $args[0] is equivalent to +$1 unless the type of the first parameter is a primitive +type. Note that $args[0] is not equivalent to +$0; $0 represents this. + +

    If an array of Object is assigned to +$args, 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. + +

    $$

    + +

    The variable $$ is abbreviation of a list of +all the parameters separated by commas. +For example, if the number of the parameters +to method move() is three, then + +

      move($$)
    + +

    is equivalent to this: + +

      move($1, $2, $3)
    + +

    If move() does not take any parameters, +then move($$) is +equivalent to move(). + +

    $$ can be used with another method. +If you write an expression: + +

      exMove($$, context)
    + +

    then this expression is equivalent to: + +

      exMove($1, $2, $3, context)
    + +

    Note that $$ enables generic notation of method call +with respect to the number of parameters. +It is typically used with $proceed shown later. + +

    $cflow

    + +

    $cflow means "control flow". +This read-only variable returns the depth of the recursive calls +to a specific method. + +

    Suppose that the method shown below is represented by a +CtMethod object cm: + +

      int fact(int n) {
+    if (n <= 1)
+        return n;
+    else
+        return n * fact(n - 1);
+}
    + +

    To use $cflow, first declare that $cflow +is used for monitoring calls to the method fact(): + +

      CtMethod cm = ...;
+cm.useCflow("fact");
    + +

    The parameter to useCflow() is the identifier of the +declared $cflow variable. Any valid Java name can be +used as the identifier. Since the identifier can also include +. (dot), for example, "my.Test.fact" +is a valid identifier. + +

    Then, $cflow(fact) represents the depth of the +recursive calls to the method specified by cm. The value +of $cflow(fact) is 0 (zero) when the method is +first called whereas it is 1 when the method is recursively called +within the method. For example, + +

      +cm.insertBefore("if ($cflow(fact) == 0)"
+              + "    System.out.println(\"fact \" + $1);");
+
    + +

    translates the method fact() so that it shows the +parameter. Since the value of $cflow(fact) is checked, +the method fact() does not show the parameter if it is +recursively called within fact(). + +

    The value of $cflow is the number of stack frames +associated with the specified method cm +under the current topmost +stack frame for the current thread. $cflow is also +accessible within a method different from the specified method +cm. + +

    $r

    + +

    $r 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: + +

      Object result = ... ;
+$_ = ($r)result;
    + +

    If the result type is a primitive type, then ($r) +converts from the wrapper type to the primitive type. +For example, if the result type is int, then +($r) converts from java.lang.Integer to +int. + +

    If the result type is void, then +($r) does not convert a type; it does nothing. +Moreover, the soruce text can include a return +statement with a resulting value: + +

      return ($r)result;
    + +

    Here, result is some local variable. +Since ($r) is specified, the resulting value is +discarded. +This return statement is regarded as the equivalent +of the return statement without a resulting value: + +

      return;
    + +

    $w

    + +

    $w represents a wrapper type. +It must be used as the cast type in a cast expression. +($w) converts from a primitive type to the corresponding +wrapper type. + +The following code is an example: + +

      Integer i = ($w)5;
    + +

    The selected wrapper type depends on the type of the expression +following ($w). If the type of the expression is +double, then the wrapper type is java.lang.Double. + +

    If the type of the expression following ($w) is not +a primitive type, then ($w) does nothing. + +

    $_

    + +

    insertAfter() in CtMethod and +CtConstructor inserts the +compiled code at the end of the method. In the statement given to +insertAfter(), not only the variables shown above such as +$0, $1, ... but also $_ is +available. + +

    The variable $_ 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 void, +then the type of $_ is Object and the value +of $_ is null. + +

    Although the compiled code inserted by insertAfter() +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 +asFinally to insertAfter() must be +true. + +

    If an exception is thrown, the compiled code inserted by +insertAfter() is executed as a finally +clause. The value of $_ is 0 or +null 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 $_ is never thrown +to the caller; it is rather discarded. + +

    $sig

    + +

    The value of $sig is an array of +java.lang.Class objects that represent the formal +parameter types in declaration order. + +

    $type

    + +

    The value of $type is an java.lang.Class +object representing the formal type of the result value. This +variable is available only in insertAfter() in +CtMethod and CtConstructor. + +

    $class

    + +

    The value of $class is an java.lang.Class +object representing the class in which the edited method is declared. + +

    addCatch()

    + +

    addCatch() 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 $e. + +

    For example, this program: + +

      +CtMethod m = ...;
+CtClass etype = ClassPool.getDefault().get("java.io.IOException");
+m.addCatch("{ System.out.println($e); throw $e; }", etype);
+
    + +

    translates the method body represented by m into +something like this: + +

      +try {
+    the original method body
+}
+catch (java.io.IOException e) {
+    System.out.println(e);
+    throw e;
+}
+
    + +

    Note that the inserted code fragment must end with a +throw or return statement. + +


    + +

    5.2 Modifying a method body

    + +

    javassist.expr.ExprEditor is a class +for replacing an expression in a method body. +The users can define a subclass of ExprEditor +to specify how an expression is modified. + +

    To run an ExprEditor object, the users must +call instrument() in CtMethod or +CtClass. + +For example, + +

      +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($$); }");
+        }
+    });
+
    + +

    searches the method body represented by cm and +replaces all calls to move() in class Point +with a block: + +

      { $1 = 0; $_ = $proceed($$); }
+
    + +

    so that the first parameter to move() is always 0. +Note that the substituted code is not an expression but +a statement or a block. + +

    The method instrument() searches a method body. +If it finds an expression such as a method call, field access, and object +creation, then it calls edit() on the given +ExprEditor object. The parameter to edit() +is an object representing the found expression. The edit() +method can inspect and replace the expression through that object. + +

    Calling replace() on the parameter to edit() +substitutes the given statement or block for the expression. If the given +block is an empty block, that is, if replace("{}") +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 +replace(): + +

      +{ before-statements;
+  $_ = $proceed($$);
+  after-statements; }
+
    + +

    whichever the expression is either a method call, field access, +object creation, or others. The second statement could be: + +

      $_ = $proceed();
    + +

    if the expression is read access, or + +

      $proceed($$);
    + +

    if the expression is write access. + +

    javassist.expr.MethodCall

    + +

    A MethodCall object represents a method call. +The method replace() in +MethodCall 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 $ +have special meaning as in the source text passed to +insertBefore(). + +

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      $0 +The target object of the method call.
      +This is not equivalent to this, which represents +the caller-side this object.
      +$0 is null if the method is static. +
       
       
      $1, $2, ...     +The parameters of the method call. +
      +$_The resulting value of the method call.
      $rThe result type of the method call.
      $class    A java.lang.Class object representing +the class declaring the method. +
      $sig    An array of java.lang.Class objects representing +the formal parameter types.
      $type    A java.lang.Class object representing +the formal result type.
      $proceed    The name of the method originally called +in the expression.
      +
    + +

    Here the method call means the one represented by the +MethodCall object. + +

    The other identifiers such as $w, +$args and $$ +are also available. + +

    Unless the result type of the method call is void, +a value must be assigned to +$_ in the source text and the type of $_ +is the result type. +If the result type is void, the type of $_ +is Object and the value assigned to $_ +is ignored. + +

    $proceed is not a String value but special +syntax. It must be followed by an argument list surrounded by parentheses +( ). + +

    javassist.expr.FieldAccess

    + +

    A FieldAccess object represents field access. +The method edit() in ExprEditor +receives this object if field access is found. +The method replace() in +FieldAccess receives +source text representing the substitued statement or +block for the field access. + +In the source text, the identifiers starting with $ +have also special meaning: + +

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      $0 +The object containing the field accessed by the expression. +This is not equivalent to this.
      +this represents the object that the method including the +expression is invoked on.
      +$0 is null if the field is static. +
       
       
      $1 +The value that would be stored in the field +if the expression is write access. +
      Otherwise, $1 is not available. +
       
      $_ +The resulting value of the field access +if the expression is read access. +
      Otherwise, the value stored in $_ is discarded. +
       
      $r +The type of the field if the expression is read access. +
      Otherwise, $r is void. +
       
      $class    A java.lang.Class object representing +the class declaring the field. +
      $typeA java.lang.Class object representing +the field type.
      $proceed    The name of a virtual method executing the original +field access. +.
      +
    + +

    The other identifiers such as $w, +$args and $$ +are also available. + +

    If the expression is read access, a value must be assigned to +$_ in the source text. The type of $_ +is the type of the field. + +

    javassist.expr.NewExpr

    + +

    A NewExpr object represents object creation +with the new operator. +The method edit() in ExprEditor +receives this object if object creation is found. +The method replace() in +NewExpr receives +source text representing the substitued statement or +block for the object creation. + +In the source text, the identifiers starting with $ +have also special meaning: + +

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      $0 +null. +
      $1, $2, ...     +The parameters to the constructor. +
      $_ +The resulting value of the object creation. +
      A newly created object must be stored in this variable. +
       
      $r +The type of the created object. +
      $class    A java.lang.Class object representing +the class of the created object. +
      $sig    An array of java.lang.Class objects representing +the formal parameter types.
      $proceed    The name of a virtual method executing the original +object creation. +.
      +
    + +

    The other identifiers such as $w, +$args and $$ +are also available. + +

    javassist.expr.Instanceof

    + +

    A Instanceof object represents an instanceof +expression. +The method edit() in ExprEditor +receives this object if an instanceof expression is found. +The method replace() in +Instanceof receives +source text representing the substitued statement or +block for the expression. + +In the source text, the identifiers starting with $ +have also special meaning: + +

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      $0 +null. +
      $1 +The value on the left hand side of the original +instanceof operator. +
      $_ +The resulting value of the expression. +The type of $_ is boolean. +
      $r +The type on the right hand side of the instanceof operator. +
      $typeA java.lang.Class object representing +the type on the right hand side of the instanceof operator. +
      $proceed    The name of a virtual method executing the original +instanceof expression. +
      It takes one parameter (the type is java.lang.Object) +and returns true +
      if the parameter value is an instance of the type on the right +hand side of +
      the original instanceof operator. +Otherwise, it returns false. +
       
       
       
      +
    + +

    The other identifiers such as $w, +$args and $$ +are also available. + +

    javassist.expr.Cast

    + +

    A Cast object represents an expression for +explicit type casting. +The method edit() in ExprEditor +receives this object if explicit type casting is found. +The method replace() in +Cast receives +source text representing the substitued statement or +block for the expression. + +In the source text, the identifiers starting with $ +have also special meaning: + +

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      $0 +null. +
      $1 +The value the type of which is explicitly cast. +
      $_ +The resulting value of the expression. +The type of $_ is the same as the type +
      after the explicit casting, that is, the type surrounded +by ( ). +
       
      $rthe type after the explicit casting, or the type surrounded +by ( ). +
      $typeA java.lang.Class object representing +the same type as $r. +
      $proceed    The name of a virtual method executing the original +type casting. +
      It takes one parameter of the type java.lang.Object +and returns it after +
      the explicit type casting specified by the original expression. + +
       
       
      +
    + +

    The other identifiers such as $w, +$args and $$ +are also available. + +

    javassist.expr.Handler

    + +

    A Handler object represents a catch +clause of try-catch statement. +The method edit() in ExprEditor +receives this object if a catch is found. +The method insertBefore() in +Handler compiles the received +source text and inserts it at the beginning of the catch clause. + +In the source text, the identifiers starting with $ +have special meaning: + +

      + + + + + + + + + + + + + + + + + + + + + + +
      $1 +The exception object caught by the catch clause. +
      $rthe type of the exception caught by the catch clause. +It is used in a cast expression. +
      $wThe wrapper type. It is used in a cast expression. +
      $type     +A java.lang.Class object representing +
      the type of the exception caught by the catch clause. +
       
      +
    + +

    If a new exception object is assigned to $1, +it is passed to the original catch clause as the caught +exception. + +


    + +

    5.3 Adding a new method or field

    + +

    Javassist allows the users to create a new method and constructor +from scratch. CtNewMethod +and CtNewConstructor provide several factory methods, +which are static methods for creating CtMethod or +CtConstructor objects. +Especially, make() creates +a CtMethod or CtConstructor object +from the given source text. + +

    For example, this program: + +

      +CtClass point = ClassPool.getDefault().get("Point");
+CtMethod m = CtNewMethod.make(
+                 "public int xmove(int dx) { x += dx; }",
+                 point);
+point.addMethod(m);
+
    + +

    adds a public method xmove() to class Point. +In this example, x is a int field in +the class Point. + +

    The source text passed to make() can refer to +$proceed if the target object and the target method name +are also given to make(). For example, + +

      +CtClass point = ClassPool.getDefault().get("Point");
+CtMethod m = CtNewMethod.make(
+                 "public int ymove(int dy) { $proceed(0, dy); }",
+                 point, "this", "move");
+
    + +

    this program creates a method ymove() defined below: + +

      +public int ymove(int dy) { this.move(0, dy); }
+
    + +

    Note that $proceed has been replaced with +this.move. + +

    Javassist also allows the users to create a new field. + +

      +CtClass point = ClassPool.getDefault().get("Point");
+CtField f = new CtField(CtClass.intType, "z", point);
+point.addField(f);
+
    + +

    This program adds a field named z to class +Point. + +

    If the initial value of the added field must be specified, +the program shown above must be modified into: + +

      +CtClass point = ClassPool.getDefault().get("Point");
+CtField f = new CtField(CtClass.intType, "z", point);
+point.addField(f, "0");    // initial value is 0.
+
    + +

    Now, the method addField() 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 (;). + +


    + +

    5.4 Limitations

    + +

    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: + +

  • The .class notation is not supported. Use the +method Class.forName(). +In regular +Java, an expression Point.class means a Class +object representing the Point class. This notation is +not available. + +

  • Array initializers, a comma-separated list of expressions +enclosed by braces { and }, are not +supported. + +

  • Inner classes or anonymous classes are not supported. + +

  • switch statements are not supported yet. + +

  • Labeled continue and break statements +are not supported. + +

  • The finally clause following +try and catch clauses is not supported. + +

  • 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. + +

  • The users are recommended to use # as the separator +between a class name and a static method or field name. +For example, in regular Java, + +
      javassist.CtClass.intType.getName()
    + +

    calls a method getName() on +the object indicated by the static field intType +in javassist.CtClass. In Javassist, the users can +write the expression shown above but they are recommended to +write: + +

      javassist.CtClass#intType.getName()
    + +

    so that the compiler can quickly parse the expression. + + +


    + +    Previous page + +

    +Java(TM) is a trademark of Sun Microsystems, Inc.
    +Copyright (C) 2000-2003 by Shigeru Chiba, All rights reserved. + + -- cgit v1.2.3