added the description of insertAt() in CtBehavior.

git-svn-id: http://anonsvn.jboss.org/repos/javassist/trunk@65 30ef5769-5b8d-40dd-aea6-55b5d6557bb3

4 files changed, 70 insertions, 456 deletions

diff --git a/src/main/javassist/CtBehavior.java b/src/main/javassist/CtBehavior.java
index 7824dbe1..018b0c52 100644
--- a/src/main/javassist/CtBehavior.java
+++ b/src/main/javassist/CtBehavior.java
@@ -21,7 +21,9 @@ import javassist.compiler.CompileError;
 import javassist.expr.ExprEditor;
 
 /**
- * <code>CtBehavior</code> is the abstract super class of
+ * <code>CtBehavior</code> represents a method, a constructor,
+ * or a static constructor (class initializer). 
+ * It is the abstract super class of
  * <code>CtMethod</code> and <code>CtConstructor</code>.
  */
 public abstract class CtBehavior extends CtMember {
@@ -40,7 +42,7 @@ public abstract class CtBehavior extends CtMember {
     }
 
     /**
-     * Returns the MethodInfo representing this member in the
+     * Returns the MethodInfo representing this method/constructor in the
      * class file.
      */
     public MethodInfo getMethodInfo() {
@@ -54,7 +56,7 @@ public abstract class CtBehavior extends CtMember {
     public MethodInfo getMethodInfo2() { return methodInfo; }
 
     /**
-     * Obtains the modifiers of the member.
+     * Obtains the modifiers of the method/constructor.
      *
      * @return          modifiers encoded with
      *                  <code>javassist.Modifier</code>.
@@ -65,7 +67,11 @@ public abstract class CtBehavior extends CtMember {
     }
 
     /**
-     * Sets the encoded modifiers of the member.
+     * Sets the encoded modifiers of the method/constructor.
+     *
+     * <p>Changing the modifiers may cause a problem.
+     * For example, if a non-static method is changed to static,
+     * the method will be rejected by the bytecode verifier.
      *
      * @see Modifier
      */
@@ -75,14 +81,7 @@ public abstract class CtBehavior extends CtMember {
     }
 
     /**
-     * Obtains the name of this member.
-     *
-     * @see CtConstructor#getName()
-     */
-    public abstract String getName();
-
-    /**
-     * Obtains parameter types of this member.
+     * Obtains parameter types of this method/constructor.
      */
     public CtClass[] getParameterTypes() throws NotFoundException {
         return Descriptor.getParameterTypes(methodInfo.getDescriptor(),
@@ -99,16 +98,17 @@ public abstract class CtBehavior extends CtMember {
 
     /**
      * Returns the character string representing the parameter types
-     * and the return type.  If two members have the same parameter types
+     * and the return type.  If two methods/constructors have
+     * the same parameter types
      * and the return type, <code>getSignature()</code> returns the
-     * same string.
+     * same string (the return type of constructors is <code>void</code>).
      */
     public String getSignature() {
         return methodInfo.getDescriptor();
     }
 
     /**
-     * Obtains exceptions that this member may throw.
+     * Obtains exceptions that this method/constructor may throw.
      */
     public CtClass[] getExceptionTypes() throws NotFoundException {
         String[] exceptions;
@@ -122,7 +122,7 @@ public abstract class CtBehavior extends CtMember {
     }
 
     /**
-     * Sets exceptions that this member may throw.
+     * Sets exceptions that this method/constructor may throw.
      */
     public void setExceptionTypes(CtClass[] types) throws NotFoundException {
         declaringClass.checkModify();
@@ -150,11 +150,11 @@ public abstract class CtBehavior extends CtMember {
     public abstract boolean isEmpty();
 
     /**
-     * Sets a member body.
+     * Sets a method/constructor body.
      *
-     * @param src       the source code representing the member body.
+     * @param src       the source code representing the body.
      *                  It must be a single statement or block.
-     *                  If it is <code>null</code>, the substituted member
+     *                  If it is <code>null</code>, the substituted
      *                  body does nothing except returning zero or null.
      */
     public void setBody(String src) throws CannotCompileException {
@@ -162,11 +162,11 @@ public abstract class CtBehavior extends CtMember {
     }
 
     /**
-     * Sets a member body.
+     * Sets a method/constructor body.
      *
-     * @param src       the source code representing the member body.
+     * @param src       the source code representing the body.
      *                  It must be a single statement or block.
-     *                  If it is <code>null</code>, the substituted member
+     *                  If it is <code>null</code>, the substituted
      *                  body does nothing except returning zero or null.
      * @param delegateObj       the source text specifying the object
      *                          that is called on by <code>$proceed()</code>.
@@ -250,7 +250,7 @@ public abstract class CtBehavior extends CtMember {
     }
 
     /**
-     * Declares to use <code>$cflow</code> for this member;
+     * Declares to use <code>$cflow</code> for this method/constructor.
      * If <code>$cflow</code> is used, the class files modified
      * with Javassist requires a support class
      * <code>javassist.runtime.Cflow</code> at runtime
@@ -298,7 +298,7 @@ public abstract class CtBehavior extends CtMember {
     }
 
     /**
-     * Modifies the member body.
+     * Modifies the method/constructor body.
      *
      * @param converter         specifies how to modify.
      */
@@ -311,7 +311,7 @@ public abstract class CtBehavior extends CtMember {
     }
 
     /**
-     * Modifies the member body.
+     * Modifies the method/constructor body.
      *
      * @param editor            specifies how to modify.
      */
@@ -330,8 +330,18 @@ public abstract class CtBehavior extends CtMember {
     /**
      * Inserts bytecode at the beginning of the body.
      *
+     * <p>If this object represents a constructor,
+     * the bytecode is inserted before
+     * a constructor in the super class or this class is called.
+     * Therefore, the inserted bytecode is subject to constraints described
+     * in Section 4.8.2 of The Java Virtual Machine Specification (2nd ed).
+     * For example, it cannot access instance fields or methods
+     * although it can access static fields and methods.
+     * Use <code>insertBeforeBody()</code> in <code>CtConstructor</code>.
+     *
      * @param src       the source code representing the inserted bytecode.
      *                  It must be a single statement or block.
+     * @see CtConstructor#insertBeforeBody(String)
      */
     public void insertBefore(String src) throws CannotCompileException {
         declaringClass.checkModify();
@@ -674,12 +684,21 @@ public abstract class CtBehavior extends CtMember {
     }
 
     /**
-     * Inserts bytecode at the specified line in the body.  It is equivalent
-     * to insertAt(lineNum, true, src).
+     * Inserts bytecode at the specified line in the body.
+     * It is equivalent to:
+     *
+     * <br><code>insertAt(lineNum, true, src)</code>
+     *
+     * <br>See this method as well.
      *
-     * @param lineNum   the line number.
+     * @param lineNum   the line number.  The bytecode is inserted at the
+     *                  beginning of the code at the line specified by this
+     *                  line number.
      * @param src       the source code representing the inserted bytecode.
      *                  It must be a single statement or block.
+     * @return      the line number at which the bytecode has been inserted.
+     *
+     * @see CtBehavior#insertAt(int,boolean,String)
      */
     public int insertAt(int lineNum, String src)
         throws CannotCompileException
@@ -690,13 +709,24 @@ public abstract class CtBehavior extends CtMember {
     /**
      * Inserts bytecode at the specified line in the body.
      *
-     * @param lineNum   the line number.
+     * <p>If there is not
+     * a statement at the specified line, the bytecode might be inserted
+     * at the line including the first statement after that line specified.
+     * For example, if there is only a closing brace at that line, the
+     * bytecode would be inserted at another line below.
+     * To know exactly where the bytecode will be inserted, call with
+     * <code>modify</code> set to <code>false</code>. 
+     *
+     * @param lineNum   the line number.  The bytecode is inserted at the
+     *                  beginning of the code at the line specified by this
+     *                  line number.
      * @param modify    if false, this method does not insert the bytecode.
      *                  It instead only returns the line number at which
      *                  the bytecode would be inserted.
      * @param src       the source code representing the inserted bytecode.
      *                  It must be a single statement or block.
      *                  If modify is false, the value of src can be null.
+     * @return      the line number at which the bytecode has been inserted.
      */
     public int insertAt(int lineNum, boolean modify, String src)
         throws CannotCompileException
diff --git a/src/main/javassist/CtConstructor.java b/src/main/javassist/CtConstructor.java
index 25113889..849f8553 100644
--- a/src/main/javassist/CtConstructor.java
+++ b/src/main/javassist/CtConstructor.java
@@ -18,12 +18,6 @@ package javassist;
 import javassist.bytecode.*;
 import javassist.compiler.Javac;
 import javassist.compiler.CompileError;
-import javassist.expr.ExprEditor;
-
-/* Some methods do nothing except calling the super's method.
- * They might seem redundant but they are necessary so that javadoc
- * includes the description of those methods in the page of this class.
- */
 
 /**
  * An instance of CtConstructor represents a constructor.
@@ -31,6 +25,9 @@ import javassist.expr.ExprEditor;
  * (class initializer).  To distinguish a constructor and a class
  * initializer, call <code>isClassInitializer()</code>.
  *
+ * <p>See the super class <code>CtBehavior</code> as well since
+ * a number of useful methods are in <code>CtBehavior</code>.
+ *
  * @see CtClass#getDeclaredConstructors()
  * @see CtClass#getClassInitializer()
  * @see CtNewConstructor
@@ -160,14 +157,6 @@ public final class CtConstructor extends CtBehavior {
     }
 
     /**
-     * Returns the MethodInfo representing the constructor in the
-     * class file.
-     */
-    public MethodInfo getMethodInfo() {
-        return super.getMethodInfo();
-    }
-
-    /**
      * Returns true if this object represents a constructor.
      */
     public boolean isConstructor() {
@@ -182,26 +171,6 @@ public final class CtConstructor extends CtBehavior {
     }
 
     /**
-     * Obtains the encoded modifiers of the constructor.
-     *
-     * @return          modifiers encoded with
-     *                  <code>javassist.Modifier</code>.
-     * @see Modifier
-     */
-    public int getModifiers() {
-        return super.getModifiers();
-    }
-
-    /**
-     * Sets the encoded modifiers of the constructor.
-     *
-     * @see Modifier
-     */
-    public void setModifiers(int mod) {
-        super.setModifiers(mod);
-    }
-
-    /**
      * Obtains the name of this constructor.
      * It is the same as the simple name of the class declaring this
      * constructor.  If this object represents a class initializer,
@@ -215,45 +184,6 @@ public final class CtConstructor extends CtBehavior {
     }
 
     /**
-     * Returns the class that declares this constructor.
-     */
-    public CtClass getDeclaringClass() {
-        return super.getDeclaringClass();
-    }
-
-    /**
-     * Obtains parameter types of this constructor.
-     */
-    public CtClass[] getParameterTypes() throws NotFoundException {
-        return super.getParameterTypes();
-    }
-
-    /**
-     * Returns the character string representing the parameter types.
-     * If two constructors have the same parameter types,
-     * <code>getSignature()</code> returns the same string.
-     */
-    public String getSignature() {
-        return super.getSignature();
-    }
-
-    /**
-     * Obtains exceptions that this constructor may throw.
-     */
-    public CtClass[] getExceptionTypes() throws NotFoundException {
-        return super.getExceptionTypes();
-    }
-
-    /**
-     * Sets exceptions that this constructor may throw.
-     */
-    public void setExceptionTypes(CtClass[] types)
-        throws NotFoundException
-    {
-        super.setExceptionTypes(types);
-    }
-
-    /**
      * Returns true if the constructor is the default one.
      */
     public boolean isEmpty() {
@@ -317,86 +247,6 @@ public final class CtConstructor extends CtBehavior {
     }
 
     /**
-     * Obtains an attribute with the given name.
-     * If that attribute is not found in the class file, this
-     * method returns null.
-     *
-     * @param name              attribute name
-     */
-    public byte[] getAttribute(String name) {
-        return super.getAttribute(name);
-    }
-
-    /**
-     * Adds an attribute. The attribute is saved in the class file.
-     *
-     * @param name      attribute name
-     * @param data      attribute value
-     */
-    public void setAttribute(String name, byte[] data) {
-        super.setAttribute(name, data);
-    }
-
-    /**
-     * Declares to use <code>$cflow</code> for this constructor.
-     * If <code>$cflow</code> is used, the class files modified
-     * with Javassist requires a support class
-     * <code>javassist.runtime.Cflow</code> at runtime
-     * (other Javassist classes are not required at runtime).
-     *
-     * <p>Every <code>$cflow</code> variable is given a unique name.
-     * For example, if the given name is <code>"Point.paint"</code>,
-     * then the variable is indicated by <code>$cflow(Point.paint)</code>.
-     *
-     * @param name      <code>$cflow</code> name.  It can include
-     *                  alphabets, numbers, <code>_</code>,
-     *                  <code>$</code>, and <code>.</code> (dot).
-     *
-     * @see javassist.runtime.Cflow
-     */
-    public void useCflow(String name) throws CannotCompileException {
-        super.useCflow(name);
-    }
-
-    /**
-     * Modifies the constructor body.
-     *
-     * @param converter         specifies how to modify.
-     */
-    public void instrument(CodeConverter converter)
-        throws CannotCompileException
-    {
-        super.instrument(converter);
-    }
-
-    /**
-     * Modifies the constructor body.
-     *
-     * @param editor            specifies how to modify.
-     */
-    public void instrument(ExprEditor editor)
-        throws CannotCompileException
-    {
-        super.instrument(editor);
-    }
-
-    /**
-     * Inserts bytecode at the beginning of the constructor body.
-     * Since the bytecode is inserted before a constructor in the super
-     * class or this class is called, the bytecode is subject
-     * to constraints described
-     * in Section 4.8.2 of The Java Virtual Machine Specification (2nd ed).
-     * For example, it cannot access instance members although it can access
-     * static members.
-     *
-     * @param src       the source code representing the inserted bytecode.
-     *                  It must be a single statement or block.
-     */
-    public void insertBefore(String src) throws CannotCompileException {
-        super.insertBefore(src);
-    }
-
-    /**
      * Inserts bytecode just after another constructor in the super class
      * or this class is called.
      * It does not work if this object represents a class initializer.
@@ -434,50 +284,4 @@ public final class CtConstructor extends CtBehavior {
             throw new CannotCompileException(e);
         }
     }
-
-    /**
-     * Inserts bytecode at the end of the constructor body.
-     * The bytecode is inserted just before every return insturction.
-     * It is not executed when an exception is thrown.
-     *
-     * @param src       the source code representing the inserted bytecode.
-     *                  It must be a single statement or block.
-     */
-    public void insertAfter(String src)
-        throws CannotCompileException
-    {
-        super.insertAfter(src);
-    }
-
-    /**
-     * Inserts bytecode at the end of the constructor body.
-     * The bytecode is inserted just before every return insturction.
-     *
-     * @param src       the source code representing the inserted bytecode.
-     *                  It must be a single statement or block.
-     * @param asFinally         true if the inserted bytecode is executed
-     *                  not only when the transfer normally returns
-     *                  but also when an exception is thrown.
-     */
-    public void insertAfter(String src, boolean asFinally)
-        throws CannotCompileException
-    {
-        super.insertAfter(src, asFinally);
-    }
-
-    /**
-     * Adds a catch clause that handles an exception thrown in the
-     * constructor body.
-     * The catch clause must end with a return or throw statement.
-     *
-     * @param src       the source code representing the catch clause.
-     *                  It must be a single statement or block.
-     * @param exceptionType     the type of the exception handled by the
-     *                          catch clause.
-     */
-    public void addCatch(String src, CtClass exceptionType)
-        throws CannotCompileException
-    {
-        super.addCatch(src, exceptionType);
-    }
 }
diff --git a/src/main/javassist/CtMember.java b/src/main/javassist/CtMember.java
index 013437d7..9610a02e 100644
--- a/src/main/javassist/CtMember.java
+++ b/src/main/javassist/CtMember.java
@@ -67,6 +67,11 @@ public abstract class CtMember {
 
     /**
      * Obtains the name of the member.
+     *
+     * <p>As for constructor names, see <code>getName()</code>
+     * in <code>CtConstructor</code>.
+     *
+     * @see CtConstructor#getName()
      */
     public abstract String getName();
 
diff --git a/src/main/javassist/CtMethod.java b/src/main/javassist/CtMethod.java
index 035a3b9e..64634c39 100644
--- a/src/main/javassist/CtMethod.java
+++ b/src/main/javassist/CtMethod.java
@@ -16,16 +16,13 @@
 package javassist;
 
 import javassist.bytecode.*;
-import javassist.expr.ExprEditor;
-
-/* Some methods do nothing except calling the super's method.
- * They might seem redundant but they are necessary so that javadoc
- * includes the description of those methods in the page of this class.
- */
 
 /**
  * An instance of <code>CtMethod</code> represents a method.
  *
+ * <p>See the super class <code>CtBehavior</code> since
+ * a number of useful methods are in <code>CtBehavior</code>.
+ *
  * @see CtClass#getDeclaredMethods()
  * @see CtNewMethod
  */
@@ -189,37 +186,6 @@ public final class CtMethod extends CtBehavior {
     }
 
     /**
-     * Returns the MethodInfo representing the method in the class file.
-     */
-    public MethodInfo getMethodInfo() {
-        return super.getMethodInfo();
-    }
-
-    /**
-     * Obtains the modifiers of the method.
-     *
-     * @return          modifiers encoded with
-     *                  <code>javassist.Modifier</code>.
-     * @see Modifier
-     */
-    public int getModifiers() {
-        return super.getModifiers();
-    }
-
-    /**
-     * Sets the encoded modifiers of the method.
-     *
-     * <p>Changing the modifiers may cause a problem.
-     * For example, if a non-static method is changed to static,
-     * the method will be rejected by the bytecode verifier.
-     *
-     * @see Modifier
-     */
-    public void setModifiers(int mod) {
-        super.setModifiers(mod);
-    }
-
-    /**
      * Obtains the name of this method.
      */
     public String getName() {
@@ -235,20 +201,6 @@ public final class CtMethod extends CtBehavior {
     }
 
     /**
-     * Returns the class that declares this method.
-     */
-    public CtClass getDeclaringClass() {
-        return super.getDeclaringClass();
-    }
-
-    /**
-     * Obtains parameter types of this method.
-     */
-    public CtClass[] getParameterTypes() throws NotFoundException {
-        return super.getParameterTypes();
-    }
-
-    /**
      * Obtains the type of the returned value.
      */
     public CtClass getReturnType() throws NotFoundException {
@@ -256,32 +208,6 @@ public final class CtMethod extends CtBehavior {
     }
 
     /**
-     * Returns the character string representing the parameter types
-     * and the return type.  If two methods have the same parameter types
-     * and the return type, <code>getSignature()</code> returns the
-     * same string.
-     */
-    public String getSignature() {
-        return super.getSignature();
-    }
-
-    /**
-     * Obtains exceptions that this method may throw.
-     */
-    public CtClass[] getExceptionTypes() throws NotFoundException {
-        return super.getExceptionTypes();
-    }
-
-    /**
-     * Sets exceptions that this method may throw.
-     *
-     * @param types     exception types (or null)
-     */
-    public void setExceptionTypes(CtClass[] types) throws NotFoundException {
-        super.setExceptionTypes(types);
-    }
-
-    /**
      * Returns true if the method body is empty, that is, <code>{}</code>.
      * It also returns true if the method is an abstract method.
      */
@@ -300,37 +226,6 @@ public final class CtMethod extends CtBehavior {
     }
 
     /**
-     * Sets a method body.
-     *
-     * @param src       the source code representing the method body.
-     *                  It must be a single statement or block.
-     *                  If it is <code>null</code>, the substituted method
-     *                  body does nothing except returning zero or null.
-     */
-    public void setBody(String src) throws CannotCompileException {
-        super.setBody(src);
-    }
-
-    /**
-     * Sets a method body.
-     *
-     * @param src       the source code representing the method body.
-     *                  It must be a single statement or block.
-     *                  If it is <code>null</code>, the substituted method
-     *                  body does nothing except returning zero or null.
-     * @param delegateObj       the source text specifying the object
-     *                          that is called on by <code>$proceed()</code>.
-     * @param delegateMethod    the name of the method
-     *                          that is called by <code>$proceed()</code>.
-     */
-    public void setBody(String src,
-                        String delegateObj, String delegateMethod)
-        throws CannotCompileException
-    {
-        super.setBody(src, delegateObj, delegateMethod);
-    }
-
-    /**
      * Copies a method body from another method.
      * If this method is abstract, the abstract modifier is removed
      * after the method body is copied.
@@ -389,126 +284,6 @@ public final class CtMethod extends CtBehavior {
                                   & ~AccessFlag.ABSTRACT);
     }
 
-    /**
-     * Obtains an attribute with the given name.
-     * If that attribute is not found in the class file, this
-     * method returns null.
-     *
-     * @param name              attribute name
-     */
-    public byte[] getAttribute(String name) {
-        return super.getAttribute(name);
-    }
-
-    /**
-     * Adds an attribute. The attribute is saved in the class file.
-     *
-     * @param name      attribute name
-     * @param data      attribute value
-     */
-    public void setAttribute(String name, byte[] data) {
-        super.setAttribute(name, data);
-    }
-
-    /**
-     * Declares to use <code>$cflow</code> for this method.
-     * If <code>$cflow</code> is used, the class files modified
-     * with Javassist requires a support class
-     * <code>javassist.runtime.Cflow</code> at runtime
-     * (other Javassist classes are not required at runtime).
-     *
-     * <p>Every <code>$cflow</code> variable is given a unique name.
-     * For example, if the given name is <code>"Point.paint"</code>,
-     * then the variable is indicated by <code>$cflow(Point.paint)</code>.
-     *
-     * @param name      <code>$cflow</code> name.  It can include
-     *                  alphabets, numbers, <code>_</code>,
-     *                  <code>$</code>, and <code>.</code> (dot).
-     *
-     * @see javassist.runtime.Cflow
-     */
-    public void useCflow(String name) throws CannotCompileException {
-        super.useCflow(name);
-    }
-
-    /**
-     * Modifies the method body.
-     *
-     * @param converter         specifies how to modify.
-     */
-    public void instrument(CodeConverter converter)
-        throws CannotCompileException
-    {
-        super.instrument(converter);
-    }
-
-    /**
-     * Modifies the method body.
-     *
-     * @param editor            specifies how to modify.
-     */
-    public void instrument(ExprEditor editor)
-        throws CannotCompileException
-    {
-        super.instrument(editor);
-    }
-
-    /**
-     * Inserts bytecode at the beginning of the method body.
-     *
-     * @param src       the source code representing the inserted bytecode.
-     *                  It must be a single statement or block.
-     */
-    public void insertBefore(String src) throws CannotCompileException {
-        super.insertBefore(src);
-    }
-
-    /**
-     * Inserts bytecode at the end of the method body.
-     * The bytecode is inserted just before every return insturction.
-     * It is not executed when an exception is thrown.
-     *
-     * @param src       the source code representing the inserted bytecode.
-     *                  It must be a single statement or block.
-     */
-    public void insertAfter(String src)
-        throws CannotCompileException
-    {
-        super.insertAfter(src);
-    }
-
-    /**
-     * Inserts bytecode at the end of the method body.
-     * The bytecode is inserted just before every return insturction.
-     *
-     * @param src       the source code representing the inserted bytecode.
-     *                  It must be a single statement or block.
-     * @param asFinally         true if the inserted bytecode is executed
-     *                  not only when the transfer normally returns
-     *                  but also when an exception is thrown.
-     */
-    public void insertAfter(String src, boolean asFinally)
-        throws CannotCompileException
-    {
-        super.insertAfter(src, asFinally);
-    }
-
-    /**
-     * Adds a catch clause that handles an exception thrown in the
-     * method body.
-     * The catch clause must end with a return or throw statement.
-     *
-     * @param src       the source code representing the catch clause.
-     *                  It must be a single statement or block.
-     * @param exceptionType     the type of the exception handled by the
-     *                          catch clause.
-     */
-    public void addCatch(String src, CtClass exceptionType)
-        throws CannotCompileException
-    {
-        super.addCatch(src, exceptionType);
-    }
-
     // inner classes
 
     /**