From fe4d1a1b0ddcd6941ab3087732680abe277e9404 Mon Sep 17 00:00:00 2001 From: chiba Date: Tue, 11 May 2004 02:47:05 +0000 Subject: Updated the tutorial git-svn-id: http://anonsvn.jboss.org/repos/javassist/trunk@100 30ef5769-5b8d-40dd-aea6-55b5d6557bb3 --- tutorial/tutorial.html | 393 ++++++++++++++++++++++++++----------------------- 1 file changed, 209 insertions(+), 184 deletions(-) diff --git a/tutorial/tutorial.html b/tutorial/tutorial.html index 65267f04..b3c779ae 100644 --- a/tutorial/tutorial.html +++ b/tutorial/tutorial.html @@ -20,7 +20,7 @@ Shigeru Chiba @@ -43,7 +43,7 @@ following program is a very simple example: ClassPool pool = ClassPool.getDefault(); CtClass cc = pool.get("test.Rectangle"); cc.setSuperclass(pool.get("test.Point")); -pool.writeFile("test.Rectangle"); // or simply, cc.writeFile() +cc.writeFile("test.Rectangle");

This program first obtains a ClassPool object, @@ -57,65 +57,53 @@ to a file or an output stream.

The ClassPool object is used to maintain one-to-one mapping between classes and CtClass objects. Javassist never allows two distinct CtClass objects to represent -the same class. This is a crucial feature to consistent program -transformaiton. If you need, however, you can deal with multiple -instances of ClassPool at the same time. To create a new -instance of ClassPool, write the following code: +the same class unless two independent ClassPool are created. +This is a significant feature for consistent program +transformaiton. To create multiple +instances of ClassPool, write the following code:

-

ClassPool.getDefault() is just a singleton factory -method provided for convenience. +

This creates a ClassPool object that behaves as the +default ClassPool returned by +ClassPool.getDefault() does. +ClassPool.getDefault() is a singleton factory method +provided for convenience. + +

If you have two ClassPool objects, then you can +obtain, from each ClassPool, a distinct +CtClass object representing the same class file. You can +differently modify these CtClass objects to generate +different versions of the class.

To modify the definition of a class, the users must first obtain a reference to the CtClass object representing that class. -ClassPool.get() is used for this purpose. -In the case of the program above, the CtClass object -representing a class test.Rectangle is obtained from -the ClassPool object -and it is assigned -to a variable cc. Then it is modified so that -the superclass of test.Rectangle is changed into -a class test.Point. -This change is reflected on the original class file when -ClassPool.writeFile() is finally called. - -

Note that writeFile() is a method declared in not -CtClass but ClassPool. -If this method is called, the ClassPool -finds a CtClass object specified with a class name -among the objects that the ClassPool contains. -Then it translates that CtClass object into a class file -and writes it on a local disk. - -

There is also writeFile() defined in CtClass. -Thus, the last line in the program above can be rewritten into: - -

- -

This method is a convenient method for invoking writeFile() -in ClassPool with the name of the class represented by -cc. - -

Javassist also provides a method for directly obtaining the -modified bytecode. To do this, call write(): +get() in ClassPool is used for this purpose. +In the case of the program shown at the beginning, the +CtClass object representing a class +test.Rectangle is obtained from the +ClassPool object and it is assigned to a variable +cc. Then it is modified so that the superclass of +test.Rectangle is changed into a class +test.Point. This change is reflected on the original +class file when writeFile() in CtClass() is +finally called. + +

writeFile() translates the CtClass 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 toBytecode():

-

The contents of the class file for test.Rectangle are -assigned to a variable b in the form of byte array. -writeFile() also internally calls write() -to obtain the byte array written in a class file. -

The default ClassPool returned by a static method ClassPool.getDefault() -searches the same path as the underlying JVM (Java virtual machine). +searches the same path that the underlying JVM (Java virtual machine) has. The users can expand this class search path if needed. For example, the following code adds a directory /usr/local/javalib @@ -131,15 +119,16 @@ a URL:

-

This program adds "http://www.foo.com:80/java/" to the class search +

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 com.foo. +package org.javassist. -

You can directly give a byte array to a ClassPool object +

Furthermore, you can directly give a byte array +to a ClassPool object and construct a CtClass object from that array. To do this, use ByteArrayClassPath. For example, @@ -153,15 +142,13 @@ CtClass cc = cp.get(name);

The obtained CtClass object represents a class defined by the class file specified by b. +The ClassPool reads a class file from the given +ByteArrayClassPath if get() is called +and the class name given to get() is equal to +one specified by name. -

Since ClassPath is an interface, the users can define -a new class implementing this interface and they can add an instance -of that class so that a class file is obtained from a non-standard resource. - -

If you want to directly construct a CtClass object -from a class file but you do not know the fully-qualified name -of the class, then -you can use makeClass() in CtClass: +

If you do not know the fully-qualified name of the class, then you +can use makeClass() in ClassPool: