diff options
| author | Shigeru Chiba <chiba@javassist.org> | 2015-05-23 02:41:30 +0900 |
|---|---|---|
| committer | Shigeru Chiba <chiba@javassist.org> | 2015-05-23 02:41:30 +0900 |
| commit | 2c35b1080745871c3200753e905f25b748bc0053 (patch) | |
| tree | 2de786b9e848f351b3feea060bceb12cb4c6a6bc /tutorial/tutorial.html | |
| parent | 29040740206ef778b2029e38656570f302dcff3a (diff) | |
| download | javassist-2c35b1080745871c3200753e905f25b748bc0053.tar.gz javassist-2c35b1080745871c3200753e905f25b748bc0053.zip | |
Initial commit
Diffstat (limited to 'tutorial/tutorial.html')
| -rw-r--r-- | tutorial/tutorial.html | 1105 |
1 files changed, 0 insertions, 1105 deletions
diff --git a/tutorial/tutorial.html b/tutorial/tutorial.html deleted file mode 100644 index b8110390..00000000 --- a/tutorial/tutorial.html +++ /dev/null @@ -1,1105 +0,0 @@ -<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> - -<b> -<font size="+3"> -Getting Started with Javassist -</font> - -<p><font size="+2"> -Shigeru Chiba -</font> -</b> - -<p><div align="right"><a href="tutorial2.html">Next page</a></div> - -<ul>1. <a href="#read">Reading and writing bytecode</a> -<br>2. <a href="#pool">ClassPool</a> -<br>3. <a href="#load">Class loader</a> -<br>4. <a href="tutorial2.html#intro">Introspection and customization</a> -<br>5. <a href="tutorial3.html#intro">Bytecode level API</a> -<br>6. <a href="tutorial3.html#generics">Generics</a> -<br>7. <a href="tutorial3.html#varargs">Varargs</a> -<br>8. <a href="tutorial3.html#j2me">J2ME</a> -<br>9. <a href="tutorial3.html#boxing">Boxing/Unboxing</a> -<br>10. <a href="tutorial3.html#debug">Debug</a> -</ul> - -<p><br> - -<a name="read"> -<h2>1. Reading and writing bytecode</h2> - -<p>Javassist is a class library for dealing with Java bytecode. -Java bytecode is stored in a binary file called a class file. -Each class file contains one Java class or interface. - -<p>The class <code>Javassist.CtClass</code> is an abstract -representation of a class file. A <code>CtClass</code> (compile-time -class) object is a handle for dealing with a class file. The -following program is a very simple example: - -<ul><pre> -ClassPool pool = ClassPool.getDefault(); -CtClass cc = pool.get("test.Rectangle"); -cc.setSuperclass(pool.get("test.Point")); -cc.writeFile(); -</pre></ul> - -<p>This program first obtains a <code>ClassPool</code> object, which -controls bytecode modification with Javassist. The -<code>ClassPool</code> object is a container of <code>CtClass</code> -object representing a class file. It reads a class file on demand for -constructing a <code>CtClass</code> object and records the -constructed object for responding later accesses. - -To modify the definition of a class, the users must first obtain -from a <code>ClassPool</code> object -a reference to a <code>CtClass</code> object representing that class. -<code>get()</code> in <code>ClassPool</code> is used for this purpose. -In the case of the program shown above, the -<code>CtClass</code> object representing a class -<code>test.Rectangle</code> is obtained from the -<code>ClassPool</code> object and it is assigned to a variable -<code>cc</code>. -The <code>ClassPool</code> object returned by <code>getDefault()</code> -searches the default system search path. - -<p>From the implementation viewpoint, <code>ClassPool</code> is a hash -table of <code>CtClass</code> objects, which uses the class names as -keys. <code>get()</code> in <code>ClassPool</code> searches this hash -table to find a <code>CtClass</code> object associated with the -specified key. If such a <code>CtClass</code> object is not found, -<code>get()</code> reads a class file to construct a new -<code>CtClass</code> object, which is recorded in the hash table and -then returned as the resulting value of <code>get()</code>. - -<p>The <code>CtClass</code> object obtained from a <code>ClassPool</code> -object can be modified -(<a href="tutorial2.html#intro">details of how to modify -a <code>CtClass</code></a> will be presented later). -In the example above, it is modified so that the superclass of -<code>test.Rectangle</code> is changed into a class -<code>test.Point</code>. This change is reflected on the original -class file when <code>writeFile()</code> in <code>CtClass()</code> is -finally called. - -<p><code>writeFile()</code> translates the <code>CtClass</code> object -into a class file and writes it on a local disk. -Javassist also provides a method for directly obtaining the -modified bytecode. To obtain the bytecode, call <code>toBytecode()</code>: - -<ul><pre> -byte[] b = cc.toBytecode(); -</pre></ul> - -<p>You can directly load the <code>CtClass</code> as well: - -<ul><pre> -Class clazz = cc.toClass(); -</pre></ul> - -<p><code>toClass()</code> requests the context class loader for the current -thread to load the class file represented by the <code>CtClass</code>. It -returns a <code>java.lang.Class</code> object representing the loaded class. -For more details, please see <a href="#toclass">this section below</a>. - -<a name="def"> -<h4>Defining a new class</h4> - -<p>To define a new class from scratch, <code>makeClass()</code> -must be called on a <code>ClassPool</code>. - -<ul><pre> -ClassPool pool = ClassPool.getDefault(); -CtClass cc = pool.makeClass("Point"); -</pre></ul> - -<p>This program defines a class <code>Point</code> -including no members. -Member methods of <code>Point</code> can be created with -factory methods declared in <code>CtNewMethod</code> and -appended to <code>Point</code> with <code>addMethod()</code> -in <code>CtClass</code>. - -<p><code>makeClass()</code> cannot create a new interface; -<code>makeInterface()</code> in <code>ClassPool</code> can do. -Member methods in an interface can be created with -<code>abstractMethod()</code> in <code>CtNewMethod</code>. -Note that an interface method is an abstract method. - -<a name="frozenclasses"> -<h4>Frozen classes</h4></a> - -<p>If a <code>CtClass</code> object is converted into a class file by -<code>writeFile()</code>, <code>toClass()</code>, or -<code>toBytecode()</code>, Javassist freezes that <code>CtClass</code> -object. Further modifications of that <code>CtClass</code> object are -not permitted. This is for warning the developers when they attempt -to modify a class file that has been already loaded since the JVM does -not allow reloading a class. - -<p>A frozen <code>CtClass</code> can be defrost so that -modifications of the class definition will be permitted. For example, - -<ul><pre> -CtClasss cc = ...; - : -cc.writeFile(); -cc.defrost(); -cc.setSuperclass(...); // OK since the class is not frozen. -</pre></ul> - -<p>After <code>defrost()</code> is called, the <code>CtClass</code> -object can be modified again. - -<p>If <code>ClassPool.doPruning</code> is set to <code>true</code>, -then Javassist prunes the data structure contained -in a <code>CtClass</code> object -when Javassist freezes that object. -To reduce memory -consumption, pruning discards unnecessary attributes -(<code>attribute_info</code> structures) in that object. -For example, <code>Code_attribute</code> structures (method bodies) -are discarded. -Thus, after a -<code>CtClass</code> object is pruned, the bytecode of a method is not -accessible except method names, signatures, and annotations. -The pruned <code>CtClass</code> object cannot be defrost again. -The default value of <code>ClassPool.doPruning</code> is <code>false</code>. - -<p>To disallow pruning a particular <code>CtClass</code>, -<code>stopPruning()</code> must be called on that object in advance: - -<ul><pre> -CtClasss cc = ...; -cc.stopPruning(true); - : -cc.writeFile(); // convert to a class file. -// cc is not pruned. -</pre></ul> - -<p>The <code>CtClass</code> object <code>cc</code> is not pruned. -Thus it can be defrost after <code>writeFile()</code> is called. - -<ul><b>Note:</b> -While debugging, you might want to temporarily stop pruning and freezing -and write a modified class file to a disk drive. -<code>debugWriteFile()</code> is a convenient method -for that purpose. It stops pruning, writes a class file, defrosts it, -and turns pruning on again (if it was initially on). -</ul> - - - -<h4>Class search path</h4> - -<p>The default <code>ClassPool</code> returned -by a static method <code>ClassPool.getDefault()</code> -searches the same path that the underlying JVM (Java virtual machine) has. -<em>If a program is running on a web application server such as JBoss and Tomcat, -the <code>ClassPool</code> object may not be able to find user classes</em> -since such a web application server uses multiple class loaders as well as -the system class loader. In that case, an additional class path must be -registered to the <code>ClassPool</code>. Suppose that <code>pool</code> -refers to a <code>ClassPool</code> object: - -<ul><pre> -pool.insertClassPath(new ClassClassPath(this.getClass())); -</pre></ul> - -<p> -This statement registers the class path that was used for loading -the class of the object that <code>this</code> refers to. -You can use any <code>Class</code> object as an argument instead of -<code>this.getClass()</code>. The class path used for loading the -class represented by that <code>Class</code> object is registered. - -<p> -You can register a directory name as the class search path. -For example, the following code adds a directory -<code>/usr/local/javalib</code> -to the search path: - -<ul><pre> -ClassPool pool = ClassPool.getDefault(); -pool.insertClassPath("/usr/local/javalib"); -</pre></ul> - -<p>The search path that the users can add is not only a directory but also -a URL: - -<ul><pre> -ClassPool pool = ClassPool.getDefault(); -ClassPath cp = new URLClassPath("www.javassist.org", 80, "/java/", "org.javassist."); -pool.insertClassPath(cp); -</pre></ul> - -<p>This program adds "http://www.javassist.org:80/java/" to the class search -path. This URL is used only for searching classes belonging to a -package <code>org.javassist</code>. For example, to load a class -<code>org.javassist.test.Main</code>, its class file will be obtained from: - -<ul><pre>http://www.javassist.org:80/java/org/javassist/test/Main.class -</pre></ul> - -<p>Furthermore, you can directly give a byte array -to a <code>ClassPool</code> object -and construct a <code>CtClass</code> object from that array. To do this, -use <code>ByteArrayClassPath</code>. For example, - -<ul><pre> -ClassPool cp = ClassPool.getDefault(); -byte[] b = <em>a byte array</em>; -String name = <em>class name</em>; -cp.insertClassPath(new ByteArrayClassPath(name, b)); -CtClass cc = cp.get(name); -</pre></ul> - -<p>The obtained <code>CtClass</code> object represents -a class defined by the class file specified by <code>b</code>. -The <code>ClassPool</code> reads a class file from the given -<code>ByteArrayClassPath</code> if <code>get()</code> is called -and the class name given to <code>get()</code> is equal to -one specified by <code>name</code>. - -<p>If you do not know the fully-qualified name of the class, then you -can use <code>makeClass()</code> in <code>ClassPool</code>: - -<ul><pre> -ClassPool cp = ClassPool.getDefault(); -InputStream ins = <em>an input stream for reading a class file</em>; -CtClass cc = cp.makeClass(ins); -</pre></ul> - -<p><code>makeClass()</code> returns the <code>CtClass</code> object -constructed from the given input stream. You can use -<code>makeClass()</code> for eagerly feeding class files to -the <code>ClassPool</code> object. This might improve performance -if the search path includes a large jar file. Since -a <code>ClassPool</code> object reads a class file on demand, -it might repeatedly search the whole jar file for every class file. -<code>makeClass()</code> can be used for optimizing this search. -The <code>CtClass</code> constructed by <code>makeClass()</code> -is kept in the <code>ClassPool</code> object and the class file is never -read again. - -<p>The users can extend the class search path. They can define a new -class implementing <code>ClassPath</code> interface and give an -instance of that class to <code>insertClassPath()</code> in -<code>ClassPool</code>. This allows a non-standard resource to be -included in the search path. - -<p><br> - -<a name="pool"> -<h2>2. ClassPool</h2> - -<p> -A <code>ClassPool</code> object is a container of <code>CtClass</code> -objects. Once a <code>CtClass</code> object is created, it is -recorded in a <code>ClassPool</code> for ever. This is because a -compiler may need to access the <code>CtClass</code> object later when -it compiles source code that refers to the class represented by that -<code>CtClass</code>. - -<p> -For example, suppose that a new method <code>getter()</code> is added -to a <code>CtClass</code> object representing <code>Point</code> -class. Later, the program attempts to compile source code including a -method call to <code>getter()</code> in <code>Point</code> and use the -compiled code as the body of a method, which will be added to another -class <code>Line</code>. If the <code>CtClass</code> object representing -<code>Point</code> is lost, the compiler cannot compile the method call -to <code>getter()</code>. Note that the original class definition does -not include <code>getter()</code>. Therefore, to correctly compile -such a method call, the <code>ClassPool</code> -must contain all the instances of <code>CtClass</code> all the time of -program execution. - -<a name="avoidmemory"> -<h4>Avoid out of memory</h4> -</a> - -<p> -This specification of <code>ClassPool</code> may cause huge memory -consumption if the number of <code>CtClass</code> objects becomes -amazingly large (this rarely happens since Javassist tries to reduce -memory consumption in <a href="#frozenclasses">various ways</a>). -To avoid this problem, you -can explicitly remove an unnecessary <code>CtClass</code> object from -the <code>ClassPool</code>. If you call <code>detach()</code> on a -<code>CtClass</code> object, then that <code>CtClass</code> object is -removed from the <code>ClassPool</code>. For example, - -<ul><pre> -CtClass cc = ... ; -cc.writeFile(); -cc.detach(); -</pre></ul> - -<p>You must not call any method on that -<code>CtClass</code> object after <code>detach()</code> is called. -However, you can call <code>get()</code> on <code>ClassPool</code> -to make a new instance of <code>CtClass</code> representing -the same class. If you call <code>get()</code>, the <code>ClassPool</code> -reads a class file again and newly creates a <code>CtClass</code> -object, which is returned by <code>get()</code>. - -<p> -Another idea is to occasionally replace a <code>ClassPool</code> with -a new one and discard the old one. If an old <code>ClassPool</code> -is garbage collected, the <code>CtClass</code> objects included in -that <code>ClassPool</code> are also garbage collected. -To create a new instance of <code>ClassPool</code>, execute the following -code snippet: - -<ul><pre> -ClassPool cp = new ClassPool(true); -// if needed, append an extra search path by appendClassPath() -</pre></ul> - -<p>This creates a <code>ClassPool</code> object that behaves as the -default <code>ClassPool</code> returned by -<code>ClassPool.getDefault()</code> does. -Note that <code>ClassPool.getDefault()</code> is a singleton factory method -provided for convenience. It creates a <code>ClassPool</code> object in -the same way shown above although it keeps a single instance of -<code>ClassPool</code> and reuses it. -A <code>ClassPool</code> object returned by <code>getDefault()</code> -does not have a special role. <code>getDefault()</code> is a convenience -method. - -<p>Note that <code>new ClassPool(true)</code> is a convenient constructor, -which constructs a <code>ClassPool</code> object and appends the system -search path to it. Calling that constructor is -equivalent to the following code: - -<ul><pre> -ClassPool cp = new ClassPool(); -cp.appendSystemPath(); // or append another path by appendClassPath() -</pre></ul> - -<h4>Cascaded ClassPools</h4> - -<p> -<em>If a program is running on a web application server,</em> -creating multiple instances of <code>ClassPool</code> might be necessary; -an instance of <code>ClassPool</code> should be created -for each class loader (i.e. container). -The program should create a <code>ClassPool</code> object by not calling -<code>getDefault()</code> but a constructor of <code>ClassPool</code>. - -<p> -Multiple <code>ClassPool</code> objects can be cascaded like -<code>java.lang.ClassLoader</code>. For example, - -<ul><pre> -ClassPool parent = ClassPool.getDefault(); -ClassPool child = new ClassPool(parent); -child.insertClassPath("./classes"); -</pre></ul> - -<p> -If <code>child.get()</code> is called, the child <code>ClassPool</code> -first delegates to the parent <code>ClassPool</code>. If the parent -<code>ClassPool</code> fails to find a class file, then the child -<code>ClassPool</code> attempts to find a class file -under the <code>./classes</code> directory. - -<p> -If <code>child.childFirstLookup</code> is true, the child -<code>ClassPool</code> attempts to find a class file before delegating -to the parent <code>ClassPool</code>. For example, - -<ul><pre> -ClassPool parent = ClassPool.getDefault(); -ClassPool child = new ClassPool(parent); -child.appendSystemPath(); // the same class path as the default one. -child.childFirstLookup = true; // changes the behavior of the child. -</pre></ul> - -<h4>Changing a class name for defining a new class</h4> - -<p>A new class can be defined as a copy of an existing class. -The program below does that: - -<ul><pre> -ClassPool pool = ClassPool.getDefault(); -CtClass cc = pool.get("Point"); -cc.setName("Pair"); -</pre></ul> - -<p>This program first obtains the <code>CtClass</code> object for -class <code>Point</code>. Then it calls <code>setName()</code> to -give a new name <code>Pair</code> to that <code>CtClass</code> object. -After this call, all occurrences of the class name in the class -definition represented by that <code>CtClass</code> object are changed -from <code>Point</code> to <code>Pair</code>. The other part of the -class definition does not change. - -<p>Note that <code>setName()</code> in <code>CtClass</code> changes a -record in the <code>ClassPool</code> object. From the implementation -viewpoint, a <code>ClassPool</code> object is a hash table of -<code>CtClass</code> objects. <code>setName()</code> changes -the key associated to the <code>CtClass</code> object in the hash -table. The key is changed from the original class name to the new -class name. - -<p>Therefore, if <code>get("Point")</code> is later called on the -<code>ClassPool</code> object again, then it never returns the -<code>CtClass</code> object that the variable <code>cc</code> refers to. -The <code>ClassPool</code> object reads -a class file -<code>Point.class</code> again and it constructs a new <code>CtClass</code> -object for class <code>Point</code>. -This is because the <code>CtClass</code> object associated with the name -<code>Point</code> does not exist any more. -See the followings: - -<ul><pre> -ClassPool pool = ClassPool.getDefault(); -CtClass cc = pool.get("Point"); -CtClass cc1 = pool.get("Point"); // cc1 is identical to cc. -cc.setName("Pair"); -CtClass cc2 = pool.get("Pair"); // cc2 is identical to cc. -CtClass cc3 = pool.get("Point"); // cc3 is not identical to cc. -</pre></ul> - -<p><code>cc1</code> and <code>cc2</code> refer to the same instance of -<code>CtClass</code> that <code>cc</code> does whereas -<code>cc3</code> does not. Note that, after -<code>cc.setName("Pair")</code> is executed, the <code>CtClass</code> -object that <code>cc</code> and <code>cc1</code> refer to represents -the <code>Pair</code> class. - -<p>The <code>ClassPool</code> object is used to maintain one-to-one -mapping between classes and <code>CtClass</code> objects. Javassist -never allows two distinct <code>CtClass</code> objects to represent -the same class unless two independent <code>ClassPool</code> are created. -This is a significant feature for consistent program -transformation. - -<p>To create another copy of the default instance of -<code>ClassPool</code>, which is returned by -<code>ClassPool.getDefault()</code>, execute the following code -snippet (this code was already <a href="#avoidmemory">shown above</a>): - -<ul><pre> -ClassPool cp = new ClassPool(true); -</pre></ul> - -<p>If you have two <code>ClassPool</code> objects, then you can -obtain, from each <code>ClassPool</code>, a distinct -<code>CtClass</code> object representing the same class file. You can -differently modify these <code>CtClass</code> objects to generate -different versions of the class. - -<h4>Renaming a frozen class for defining a new class</h4> - -<p>Once a <code>CtClass</code> object is converted into a class file -by <code>writeFile()</code> or <code>toBytecode()</code>, Javassist -rejects further modifications of that <code>CtClass</code> object. -Hence, after the <code>CtClass</code> object representing <code>Point</code> -class is converted into a class file, you cannot define <code>Pair</code> -class as a copy of <code>Point</code> since executing <code>setName()</code> -on <code>Point</code> is rejected. -The following code snippet is wrong: - -<ul><pre> -ClassPool pool = ClassPool.getDefault(); -CtClass cc = pool.get("Point"); -cc.writeFile(); -cc.setName("Pair"); // wrong since writeFile() has been called. -</pre></ul> - -<p>To avoid this restriction, you should call <code>getAndRename()</code> -in <code>ClassPool</code>. For example, - -<ul><pre> -ClassPool pool = ClassPool.getDefault(); -CtClass cc = pool.get("Point"); -cc.writeFile(); -CtClass cc2 = pool.getAndRename("Point", "Pair"); -</pre></ul> - -<p>If <code>getAndRename()</code> is called, the <code>ClassPool</code> -first reads <code>Point.class</code> for creating a new <code>CtClass</code> -object representing <code>Point</code> class. However, it renames that -<code>CtClass</code> object from <code>Point</code> to <code>Pair</code> before -it records that <code>CtClass</code> object in a hash table. -Thus <code>getAndRename()</code> -can be executed after <code>writeFile()</code> or <code>toBytecode()</code> -is called on the the <code>CtClass</code> object representing <code>Point</code> -class. - -<p><br> - -<a name="load"> -<h2>3. Class loader</h2> - -<p>If what classes must be modified is known in advance, -the easiest way for modifying the classes is as follows: - -<ul><li>1. Get a <code>CtClass</code> object by calling - <code>ClassPool.get()</code>, - <li>2. Modify it, and - <li>3. Call <code>writeFile()</code> or <code>toBytecode()</code> - on that <code>CtClass</code> object to obtain a modified class file. -</ul> - -<p>If whether a class is modified or not is determined at load time, -the users must make Javassist collaborate with a class loader. -Javassist can be used with a class loader so that bytecode can be -modified at load time. The users of Javassist can define their own -version of class loader but they can also use a class loader provided -by Javassist. - - -<p><br> - -<a name="toclass"> -<h3>3.1 The <code>toClass</code> method in <code>CtClass</code></h3> -</a> - -<p>The <code>CtClass</code> provides a convenience method -<code>toClass()</code>, which requests the context class loader for -the current thread to load the class represented by the <code>CtClass</code> -object. To call this method, the caller must have appropriate permission; -otherwise, a <code>SecurityException</code> may be thrown. - -<p>The following program shows how to use <code>toClass()</code>: - -<ul><pre> -public class Hello { - public void say() { - System.out.println("Hello"); - } -} - -public class Test { - public static void main(String[] args) throws Exception { - ClassPool cp = ClassPool.getDefault(); - CtClass cc = cp.get("Hello"); - CtMethod m = cc.getDeclaredMethod("say"); - m.insertBefore("{ System.out.println(\"Hello.say():\"); }"); - Class c = cc.toClass(); - Hello h = (Hello)c.newInstance(); - h.say(); - } -} -</pre></ul> - -<p><code>Test.main()</code> inserts a call to <code>println()</code> -in the method body of <code>say()</code> in <code>Hello</code>. Then -it constructs an instance of the modified <code>Hello</code> class -and calls <code>say()</code> on that instance. - -<p>Note that the program above depends on the fact that the -<code>Hello</code> class is never loaded before <code>toClass()</code> -is invoked. If not, the JVM would load the original -<code>Hello</code> class before <code>toClass()</code> requests to -load the modified <code>Hello</code> class. Hence loading the -modified <code>Hello</code> class would be failed -(<code>LinkageError</code> is thrown). For example, if -<code>main()</code> in <code>Test</code> is something like this: - -<ul><pre> -public static void main(String[] args) throws Exception { - Hello orig = new Hello(); - ClassPool cp = ClassPool.getDefault(); - CtClass cc = cp.get("Hello"); - : -} -</pre></ul> - -<p>then the original <code>Hello</code> class is loaded at the first -line of <code>main</code> and the call to <code>toClass()</code> -throws an exception since the class loader cannot load two different -versions of the <code>Hello</code> class at the same time. - -<p><em>If the program is running on some application server such as -JBoss and Tomcat,</em> the context class loader used by -<code>toClass()</code> might be inappropriate. In this case, you -would see an unexpected <code>ClassCastException</code>. To avoid -this exception, you must explicitly give an appropriate class loader -to <code>toClass()</code>. For example, if <code>bean</code> is your -session bean object, then the following code: - -<ul><pre>CtClass cc = ...; -Class c = cc.toClass(bean.getClass().getClassLoader()); -</pre></ul> - -<p>would work. You should give <code>toClass()</code> the class loader -that has loaded your program (in the above example, the class of -the <code>bean</code> object). - -<p><code>toClass()</code> is provided for convenience. If you need -more complex functionality, you should write your own class loader. - -<p><br> - -<h3>3.2 Class loading in Java</h3> - -<p>In Java, multiple class loaders can coexist and -each class loader creates its own name space. -Different class loaders can load different class files with the -same class name. The loaded two classes are regarded as different -ones. This feature enables us to run multiple application programs -on a single JVM even if these programs include different classes -with the same name. - -<ul> -<b>Note:</b> The JVM does not allow dynamically reloading a class. -Once a class loader loads a class, it cannot reload a modified -version of that class during runtime. Thus, you cannot alter -the definition of a class after the JVM loads it. -However, the JPDA (Java Platform Debugger Architecture) provides -limited ability for reloading a class. -See <a href="#hotswap">Section 3.6</a>. -</ul> - -<p>If the same class file is loaded by two distinct class loaders, -the JVM makes two distinct classes with the same name and definition. -The two classes are regarded as different ones. -Since the two classes are not identical, an instance of one class is -not assignable to a variable of the other class. The cast operation -between the two classes fails -and throws a <em><code>ClassCastException</code></em>. - -<p>For example, the following code snippet throws an exception: - -<ul><pre> -MyClassLoader myLoader = new MyClassLoader(); -Class clazz = myLoader.loadClass("Box"); -Object obj = clazz.newInstance(); -Box b = (Box)obj; // this always throws ClassCastException. -</pre></ul> - -<p> -The <code>Box</code> class is loaded by two class loaders. -Suppose that a class loader CL loads a class including this code snippet. -Since this code snippet refers to <code>MyClassLoader</code>, -<code>Class</code>, <code>Object</code>, and <code>Box</code>, -CL also loads these classes (unless it delegates to another class loader). -Hence the type of the variable <code>b</code> is the <code>Box</code> -class loaded by CL. -On the other hand, <code>myLoader</code> also loads the <code>Box</code> -class. The object <code>obj</code> is an instance of -the <code>Box</code> class loaded by <code>myLoader</code>. -Therefore, the last statement always throws a -<code>ClassCastException</code> since the class of <code>obj</code> is -a different verison of the <code>Box</code> class from one used as the -type of the variable <code>b</code>. - -<p>Multiple class loaders form a tree structure. -Each class loader except the bootstrap loader has a -parent class loader, which has normally loaded the class of that child -class loader. Since the request to load a class can be delegated along this -hierarchy of class loaders, a class may be loaded by a class loader that -you do not request the class loading. -Therefore, the class loader that has been requested to load a class C -may be different from the loader that actually loads the class C. -For distinction, we call the former loader <em>the initiator of C</em> -and we call the latter loader <em>the real loader of C</em>. - -<p> -Furthermore, if a class loader CL requested to load a class C -(the initiator of C) delegates -to the parent class loader PL, then the class loader CL is never requested -to load any classes referred to in the definition of the class C. -CL is not the initiator of those classes. -Instead, the parent class loader PL becomes their initiators -and it is requested to load them. -<em>The classes that the definition of a class C referes to are loaded by -the real loader of C.</em> - -<p>To understand this behavior, let's consider the following example. - -<ul><pre> -public class Point { // loaded by PL - private int x, y; - public int getX() { return x; } - : -} - -public class Box { // the initiator is L but the real loader is PL - private Point upperLeft, size; - public int getBaseX() { return upperLeft.x; } - : -} - -public class Window { // loaded by a class loader L - private Box box; - public int getBaseX() { return box.getBaseX(); } -}</pre></ul> - -<p>Suppose that a class <code>Window</code> is loaded by a class loader L. -Both the initiator and the real loader of <code>Window</code> are L. -Since the definition of <code>Window</code> refers to <code>Box</code>, -the JVM will request L to load <code>Box</code>. -Here, suppose that L delegates this task to the parent class loader PL. -The initiator of <code>Box</code> is L but the real loader is PL. -In this case, the initiator of <code>Point</code> is not L but PL -since it is the same as the real loader of <code>Box</code>. -Thus L is never requested to load <code>Point</code>. - -<p>Next, let's consider a slightly modified example. - -<ul><pre> -public class Point { - private int x, y; - public int getX() { return x; } - : -} - -public class Box { // the initiator is L but the real loader is PL - private Point upperLeft, size; - public Point getSize() { return size; } - : -} - -public class Window { // loaded by a class loader L - private Box box; - public boolean widthIs(int w) { - Point p = box.getSize(); - return w == p.getX(); - } -}</pre></ul> - -<p>Now, the definition of <code>Window</code> also refers to -<code>Point</code>. In this case, the class loader L must -also delegate to PL if it is requested to load <code>Point</code>. -<em>You must avoid having two class loaders doubly load the same -class.</em> One of the two loaders must delegate to -the other. - -<p> -If L does not delegate to PL when <code>Point</code> -is loaded, <code>widthIs()</code> would throw a ClassCastException. -Since the real loader of <code>Box</code> is PL, -<code>Point</code> referred to in <code>Box</code> is also loaded by PL. -Therefore, the resulting value of <code>getSize()</code> -is an instance of <code>Point</code> loaded by PL -whereas the type of the variable <code>p</code> in <code>widthIs()</code> -is <code>Point</code> loaded by L. -The JVM regards them as distinct types and thus it throws an exception -because of type mismatch. - -<p>This behavior is somewhat inconvenient but necessary. -If the following statement: - -<ul><pre> -Point p = box.getSize(); -</pre></ul> - -<p>did not throw an exception, -then the programmer of <code>Window</code> could break the encapsulation -of <code>Point</code> objects. -For example, the field <code>x</code> -is private in <code>Point</code> loaded by PL. -However, the <code>Window</code> class could -directly access the value of <code>x</code> -if L loads <code>Point</code> with the following definition: - -<ul><pre> -public class Point { - public int x, y; // not private - public int getX() { return x; } - : -} -</pre></ul> - -<p> -For more details of class loaders in Java, the following paper would -be helpful: - -<ul>Sheng Liang and Gilad Bracha, -"Dynamic Class Loading in the Java Virtual Machine", -<br><i>ACM OOPSLA'98</i>, pp.36-44, 1998.</ul> - -<p><br> - -<h3>3.3 Using <code>javassist.Loader</code></h3> - -<p>Javassist provides a class loader -<code>javassist.Loader</code>. This class loader uses a -<code>javassist.ClassPool</code> object for reading a class file. - -<p>For example, <code>javassist.Loader</code> can be used for loading -a particular class modified with Javassist. - -<ul><pre> -import javassist.*; -import test.Rectangle; - -public class Main { - public static void main(String[] args) throws Throwable { - ClassPool pool = ClassPool.getDefault(); - Loader cl = new Loader(pool); - - CtClass ct = pool.get("test.Rectangle"); - ct.setSuperclass(pool.get("test.Point")); - - Class c = cl.loadClass("test.Rectangle"); - Object rect = c.newInstance(); - : - } -} -</pre></ul> - -<p>This program modifies a class <code>test.Rectangle</code>. The -superclass of <code>test.Rectangle</code> is set to a -<code>test.Point</code> class. Then this program loads the modified -class, and creates a new instance of the -<code>test.Rectangle</code> class. - -<p>If the users want to modify a class on demand when it is loaded, -the users can add an event listener to a <code>javassist.Loader</code>. -The added event listener is -notified when the class loader loads a class. -The event-listener class must implement the following interface: - -<ul><pre>public interface Translator { - public void start(ClassPool pool) - throws NotFoundException, CannotCompileException; - public void onLoad(ClassPool pool, String classname) - throws NotFoundException, CannotCompileException; -}</pre></ul> - -<p>The method <code>start()</code> is called when this event listener -is added to a <code>javassist.Loader</code> object by -<code>addTranslator()</code> in <code>javassist.Loader</code>. The -method <code>onLoad()</code> is called before -<code>javassist.Loader</code> loads a class. <code>onLoad()</code> -can modify the definition of the loaded class. - -<p>For example, the following event listener changes all classes -to public classes just before they are loaded. - -<ul><pre>public class MyTranslator implements Translator { - void start(ClassPool pool) - throws NotFoundException, CannotCompileException {} - void onLoad(ClassPool pool, String classname) - throws NotFoundException, CannotCompileException - { - CtClass cc = pool.get(classname); - cc.setModifiers(Modifier.PUBLIC); - } -}</pre></ul> - -<p>Note that <code>onLoad()</code> does not have to call -<code>toBytecode()</code> or <code>writeFile()</code> since -<code>javassist.Loader</code> calls these methods to obtain a class -file. - -<p>To run an application class <code>MyApp</code> with a -<code>MyTranslator</code> object, write a main class as following: - -<ul><pre> -import javassist.*; - -public class Main2 { - public static void main(String[] args) throws Throwable { - Translator t = new MyTranslator(); - ClassPool pool = ClassPool.getDefault(); - Loader cl = new Loader(); - cl.addTranslator(pool, t); - cl.run("MyApp", args); - } -} -</pre></ul> - -<p>To run this program, do: - -<ul><pre> -% java Main2 <i>arg1</i> <i>arg2</i>... -</pre></ul> - -<p>The class <code>MyApp</code> and the other application classes -are translated by <code>MyTranslator</code>. - -<p>Note that <em>application</em> classes like <code>MyApp</code> cannot -access the <em>loader</em> classes such as <code>Main2</code>, -<code>MyTranslator</code>, and <code>ClassPool</code> because they -are loaded by different loaders. The application classes are loaded -by <code>javassist.Loader</code> whereas the loader classes such as -<code>Main2</code> are by the default Java class loader. - -<p><code>javassist.Loader</code> searches for classes in a different -order from <code>java.lang.ClassLoader</code>. -<code>ClassLoader</code> first delegates the loading operations to -the parent class loader and then attempts to load the classes -only if the parent class loader cannot find them. -On the other hand, -<code>javassist.Loader</code> attempts -to load the classes before delegating to the parent class loader. -It delegates only if: - -<ul><li>the classes are not found by calling <code>get()</code> on -a <code>ClassPool</code> object, or - -<p><li>the classes have been specified by using -<code>delegateLoadingOf()</code> -to be loaded by the parent class loader. -</ul> - -<p>This search order allows loading modified classes by Javassist. -However, it delegates to the parent class loader if it fails -to find modified classes for some reason. Once a class is loaded by -the parent class loader, the other classes referred to in that class will be -also loaded by the parent class loader and thus they are never modified. -Recall that all the classes referred to in a class C are loaded by the -real loader of C. -<em>If your program fails to load a modified class,</em> you should -make sure whether all the classes using that class have been loaded by -<code>javassist.Loader</code>. - -<p><br> - -<h3>3.4 Writing a class loader</h3> - -<p>A simple class loader using Javassist is as follows: - -<ul><pre>import javassist.*; - -public class SampleLoader extends ClassLoader { - /* Call MyApp.main(). - */ - public static void main(String[] args) throws Throwable { - SampleLoader s = new SampleLoader(); - Class c = s.loadClass("MyApp"); - c.getDeclaredMethod("main", new Class[] { String[].class }) - .invoke(null, new Object[] { args }); - } - - private ClassPool pool; - - public SampleLoader() throws NotFoundException { - pool = new ClassPool(); - pool.insertClassPath("./class"); // <em>MyApp.class must be there.</em> - } - - /* Finds a specified class. - * The bytecode for that class can be modified. - */ - protected Class findClass(String name) throws ClassNotFoundException { - try { - CtClass cc = pool.get(name); - // <em>modify the CtClass object here</em> - byte[] b = cc.toBytecode(); - return defineClass(name, b, 0, b.length); - } catch (NotFoundException e) { - throw new ClassNotFoundException(); - } catch (IOException e) { - throw new ClassNotFoundException(); - } catch (CannotCompileException e) { - throw new ClassNotFoundException(); - } - } -}</pre></ul> - -<p>The class <code>MyApp</code> is an application program. -To execute this program, first put the class file under the -<code>./class</code> directory, which must <em>not</em> be included -in the class search path. Otherwise, <code>MyApp.class</code> would -be loaded by the default system class loader, which is the parent -loader of <code>SampleLoader</code>. -The directory name <code>./class</code> is specified by -<code>insertClassPath()</code> in the constructor. -You can choose a different name instead of <code>./class</code> if you want. -Then do as follows: - -<ul><code>% java SampleLoader</code></ul> - -<p>The class loader loads the class <code>MyApp</code> -(<code>./class/MyApp.class</code>) and calls -<code>MyApp.main()</code> with the command line parameters. - -<p>This is the simplest way of using Javassist. However, if you write -a more complex class loader, you may need detailed knowledge of -Java's class loading mechanism. For example, the program above puts the -<code>MyApp</code> class in a name space separated from the name space -that the class <code>SampleLoader</code> belongs to because the two -classes are loaded by different class loaders. -Hence, the -<code>MyApp</code> class cannot directly access the class -<code>SampleLoader</code>. - -<p><br> - -<h3>3.5 Modifying a system class</h3> - -<p>The system classes like <code>java.lang.String</code> cannot be -loaded by a class loader other than the system class loader. -Therefore, <code>SampleLoader</code> or <code>javassist.Loader</code> -shown above cannot modify the system classes at loading time. - -<p>If your application needs to do that, the system classes must be -<em>statically</em> modified. For example, the following program -adds a new field <code>hiddenValue</code> to <code>java.lang.String</code>: - -<ul><pre>ClassPool pool = ClassPool.getDefault(); -CtClass cc = pool.get("java.lang.String"); -CtField f = new CtField(CtClass.intType, "hiddenValue", cc); -f.setModifiers(Modifier.PUBLIC); -cc.addField(f); -cc.writeFile(".");</pre></ul> - -<p>This program produces a file <code>"./java/lang/String.class"</code>. - -<p>To run your program <code>MyApp</code> -with this modified <code>String</code> class, do as follows: - -<ul><pre> -% java -Xbootclasspath/p:. MyApp <i>arg1</i> <i>arg2</i>... -</pre></ul> - -<p>Suppose that the definition of <code>MyApp</code> is as follows: - -<ul><pre>public class MyApp { - public static void main(String[] args) throws Exception { - System.out.println(String.class.getField("hiddenValue").getName()); - } -}</pre></ul> - -<p>If the modified <code>String</code> class is correctly loaded, -<code>MyApp</code> prints <code>hiddenValue</code>. - -<p><i>Note: Applications that use this technique for the purpose of -overriding a system class in <code>rt.jar</code> should not be -deployed as doing so would contravene the Java 2 Runtime Environment -binary code license.</i> - -<p><br> - -<a name="hotswap"> -<h3>3.6 Reloading a class at runtime</h3></a> - -<p>If the JVM is launched with the JPDA (Java Platform Debugger -Architecture) enabled, a class is dynamically reloadable. After the -JVM loads a class, the old version of the class definition can be -unloaded and a new one can be reloaded again. That is, the definition -of that class can be dynamically modified during runtime. However, -the new class definition must be somewhat compatible to the old one. -<em>The JVM does not allow schema changes between the two versions.</em> -They have the same set of methods and fields. - -<p>Javassist provides a convenient class for reloading a class at runtime. -For more information, see the API documentation of -<code>javassist.tools.HotSwapper</code>. - -<p><br> - -<a href="tutorial2.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> |